Documentation
What to upload
Thirteen kinds of source, and the part of the model each one switches on. You do not need all thirteen. Three good ones beat thirty scattered ones, and the app tells you which three are missing.
Files are stored outside the media library in a folder that is not served over the web. Deleting a source deletes the file, its chunks and its facts.
How a file becomes something the engine can use
Every upload takes the same path. The file is stored, text is pulled out of it, the text is cut into chunks that keep their headings, and rules read the chunks for facts. Tabular files keep their header row at the top of every chunk on purpose, so a chunk read on its own still says what its columns mean.
Rules run first and always. A language model, if one is configured, only sees chunks the rules read nothing from, and everything it returns is written with a lower confidence and labelled as an estimate in the ledger. No number reaches the simulation without an origin attached to it.
The kind you pick at upload time matters. It decides which reader runs, what subject type the facts get, and which part of the model they feed. If you are unsure, pick the closest one rather than other.
The thirteen kinds
| Kind | What it gives the model | What a good one looks like |
|---|---|---|
| Financial statements | Monthly revenue, gross margin, operating cost, cash and the starting point for every money figure in the simulation. Without it the whole model is running on industry priors scaled to nothing. | A profit and loss or management accounts. Prose works: revenue of 14.24 million, gross margin 31 percent, operating costs of 320,000 per month are all read as written. |
| Customer list | Segments, named accounts, concentration, contract end dates, account level satisfaction and the owner of each relationship. This is what makes lose the largest customer a real scenario rather than a subtraction. | One row per account with columns for name, revenue, segment, contract end, rating and owner. |
| Competitors | Competitor agents with strength, reaction speed and aggression. Without it the model invents them from industry priors and marks them inferred, because a market with no competitors in it is not a market. | A table of names with share or revenue, or a page of notes with one competitor per heading. |
| Customer reviews and feedback | A satisfaction reading and the recurring themes that become customer objectives: price, quality, support, speed, ease, features, relationship. Themes change how a segment reacts to a price move. | Exported review text, survey verbatims, or a column of comments next to a rating. |
| Contracts | Contract length, locked revenue share and renewal timing. This is the single biggest control on how fast a price rise actually reaches customers. | Word documents or a table with start and end dates. Terms stated in prose, such as a 24 month agreement, are picked up too. |
| Market research | Market growth, market share and the pool that new business is drawn from. Also scored for sentiment and themes. | Any analyst note, trade body figure or internal market memo with numbers in it. |
| Company strategy | Objectives for the executive agents, plus themes and sentiment. Strategy that names targets gives the executives lines to cross, which is usually where the interesting part of an answer comes from. | A board paper, a plan, an offsite output. Prose is fine. |
| Product information | Products as things with prices and costs, and a starting quality position relative to competitors. | A product list, a spec sheet, a catalogue export. |
| Pricing | List prices, discount practice and the price index the whole demand model moves around. | A price list, a rate card, or the discount policy as written. |
| Organisational structure | Departments with headcount, cost, and how much capacity and quality each one holds up. Required for the eliminate a department scenario to mean anything. | A headcount export with department, a payroll summary, or an org chart in a table. |
| Suppliers and vendors | Supplier agents, cost share and single sourcing risk. Without it a supplier cost rise is a margin haircut with no delivery consequence. | A vendor list with spend, or notes naming who supplies what. |
| Sales and pipeline | Salespeople as agents with quota, ramp and discount behaviour, plus new business rates. | A pipeline export, a quota sheet, or a rep list with territory and attainment. |
| Something else | Facts still get read and land in the graph and the ledger. They just do not get the specialist treatment the other twelve kinds get. | Anything that does not fit above. Board minutes, a customer email, a supplier letter. |
The readiness score weighs five of these most heavily: financials, customers, competitors, pricing and organisational structure. That is the shortest path out of the red.
The column headings the extractor recognises
Matching is case insensitive and matches on substrings, so Annual Revenue (USD) hits the revenue family. The first family that matches a column wins, so order your columns sensibly and avoid one heading that could answer to two families.
| Family | Headings it answers to | What it becomes |
|---|---|---|
| name | customer name, account name, company name, supplier name, vendor name, competitor, customer, account, client, company, supplier, vendor, employee, department, team, product, name | The subject of every fact in the row. A row with no name is skipped, so this column is the one to get right. |
| revenue | mrr, arr, monthly revenue, annual revenue, revenue, arpa, acv, contract value, billing, invoiced, spend, amount, sales, total | Account size, concentration, and the revenue split across segments. |
| price | unit price, list price, price, rate, fee | The price position the demand model moves around. |
| cost | cogs, cost of goods, unit cost, cost, salary, compensation, payroll, opex, expense | Unit cost, department cost, and cost per head. |
| qty | headcount, employees, people, fte, seats, licenses, units, quantity, qty, volume | Headcount for departments, units for products, seats for accounts. |
| date_end | renewal, renews, contract end, end date, expiry, expires, term end | When a named account next gets to make a decision, which sets the month a price move reaches them. |
| date_start | start date, signed, joined, hired, since, start | Tenure, which feeds loyalty and contract length. |
| segment | segment, tier, plan, category, type, industry, vertical, region, territory | The customer segments, each with its own price sensitivity and switching cost. |
| rating | nps, csat, rating, stars, score, satisfaction | Account level satisfaction, which feeds churn directly. |
| text | review, feedback, comment, notes, note, description, summary, verbatim | Sentiment and themes. |
| status | status, state, stage, health, churned, active | Whether an account is live, at risk or already gone. |
| share | market share, share, percent, % | Competitor strength and market position. |
| owner | owner, rep, salesperson, account manager, manager, reports to | Which salesperson carries the relationship, and the reporting line for departments. |
A table needs at least one of name, revenue or qty to be read as a table at all. Everything else is optional and adds detail.
A customer list that reads cleanly
This is the header row from the invented Harborline Components customer list that ships with the worked example. Every column hits a family, which is why that file produces named accounts with renewal dates, segments and owners rather than a list of names.
Customer,Segment,Annual revenue,Contract end,Rating,Owner,Status
Meridian Marine,OEM,2580000,2027-03-31,4.1,Dana Whitfield,Active
Corbell Aerospace,OEM,1940000,2026-11-30,3.4,Dana Whitfield,Active
Stratton Pumps,Industrial,1210000,2027-08-31,4.6,Rey Alvarado,ActiveNumbers can carry currency symbols, thousands separators, percent signs, a trailing k, m or b, or brackets for a negative. All of those are parsed. What cannot be parsed is a merged cell, a header two rows down, or a total row in the middle of the data.
File formats, and one honest limitation
What is read directly
- CSV and TSV, read as tables, with the header row kept on every chunk
- Plain text and markdown, read as prose, with headings kept
- JSON, flattened to key and value lines
- Word documents, if the server has the ZipArchive extension
- Excel workbooks, up to the first six sheets, also via ZipArchive
- PDF, if it has a text layer
The scanned PDF problem
A PDF made by printing to PDF has text in it and reads fine. A PDF made by a scanner is a picture of a page, and there is nothing in it to extract. When that happens the source is marked as needing text and carries a note saying it is probably a scan, with the suggestion to paste the numbers or upload the spreadsheet behind it.
This is deliberate. The alternative is a source that looks like it worked and contributed nothing, which is worse than a clear failure, because you would go on to read a brief built on less than you thought.
Size and count
The upload limit defaults to 25 MB per file and the accepted extensions default to csv, tsv, txt, md, json, docx, pdf and xlsx. Both are settings on a self hosted install. Files per twin is a plan limit. You can also paste text directly instead of uploading anything, which is the fastest way to add the three numbers a profit and loss would have given.
Files in, levers next
Once the record is in, the question is what you want to do to it. There are twenty four things you can change.