Read the brief
Six blocks in a fixed order: the answer, what happens and when, why it happens and which agent caused it, what could go wrong, what to watch, and what the whole thing rests on.
How the brief is builtHow it works
Files in, a working company out
There are six moves between the folder on your desktop and a brief you could hand to a board. None of them is hidden, all of them are editable, and every number that reaches the simulation carries a note saying where it came from.
Build a twinWhat the engine computes
The simulation is arithmetic. It runs with no API key at all.
Most tools stop at the summary. This one keeps going until the summary has people in it.
A parser that reads your profit and loss and tells you what it says has done a tenth of the job. The other nine tenths is turning those figures into actors with objectives, running them against each other for a year, and doing it enough times that you can see the shape of the answer rather than one line through the middle of it.
The arc
Six moves, in this order, every time
Each one is a separate step with its own screen. You can stop after any of them, look at what it produced, change it, and carry on.
01
Read the files
CSV, Excel, Word, text and markdown are read directly. A PDF is read if it has a text layer, and you are told plainly when it does not rather than being handed an empty result. Every file is split into chunks and kept, because a number with no line behind it is a guess wearing a suit.
02
Pull out facts
Rules go first and they go every time. They read tables by their column headings and prose by the shapes numbers take in business writing. Each fact carries the source, the chunk, the quote and how it was found. A language model runs second, only over chunks the rules read nothing from, and everything it returns is marked separately.
03
Build the graph
Facts about the same thing are merged on a normalised version of its name, with every spelling kept as an alias. Customers, suppliers, competitors, departments, products, salespeople and partners become nodes with sizes and edges. Importance is share of its own type, so the largest account is a percentage of the customer list rather than an opinion.
04
Generate the agents
Nine classes, always all nine. Each agent gets objectives with weights, constraints it cannot break, the slice of the world it can see, the things it is blind to, a personality, relationships with a trust number, and whatever history the record gave it.
05
Fill the ledger
Every number the simulation runs on lands in one table with its origin and a band around it. Read from a document with the line quoted, worked out from something that was, estimated by a model, typed by you, or an industry starting point. They are never blended into a single confident figure.
06
Run the year
Two hundred replications of your scenario and two hundred of the same company doing nothing, on the same seeds, each drawing its own parameters from the bands. What comes back is a median with a tenth and a ninetieth, a list of what the agents did and how often, and a brief.
Step one
What to put in, and what each thing buys you
You do not need all of it. A profit and loss and a customer list is enough to get a twin that is worth arguing with, and the overview tells you what is missing in the order it is worth fixing.
The readiness score on the overview is not a gamified progress bar. It is the share of the assumption ledger that is standing on something you uploaded rather than on an industry starting point.
- A profit and loss or statement summary gives revenue, gross margin and the cost base
- A customer list gives named accounts, concentration, contract end dates and the segment split
- Reviews or survey exports give satisfaction, scored from the wording rather than asserted
- A supplier or vendor file gives cost share and how much of it sits with one name
- An org chart or payroll summary gives departments, headcount and what each one holds up
- Contracts give the share of revenue that cannot reprice this month
- Strategy notes and board papers give the things that never make it into a spreadsheet
Step two
Rules read the file. A model only reads the leftovers
The rule pass knows what a column called MRR, ARR, contract value, renewal, NPS or headcount means, and it knows the shapes a number takes in a sentence written by a finance person. It runs on every source, every time, and it needs no key and no network.
The language model pass is second and optional. It is shown only the chunks the rules produced nothing from, it is capped per run, and it is told to return no number that is not in the text. What it does return is written with its own marker and a lower confidence, so the ledger can show you the difference at a glance.
That order matters more than it sounds. It means the cheap, deterministic, inspectable path owns the numbers that matter, and the expensive, probabilistic one is left with the prose nobody could parse.
Step four
Nine classes, whether or not your files mention them
What a file becomes
From a column in a spreadsheet to something that acts
| What you upload | What it becomes in the graph | What that changes in the run |
|---|---|---|
| Customer list with revenue per account | Named accounts with a share of the list, plus three behavioural segments cut by size | Named accounts decide one at a time at renewal. Losing one is a month with a hole in it rather than a slope. |
| Contract end dates | A contract clock on each named account | A price rise reaches an account when its term ends, not when you send the letter. |
| Reviews, ratings or survey exports | A satisfaction score and per account sentiment | Satisfaction moves churn and word of mouth, and it recovers more slowly than it falls. |
| Supplier or vendor spend | Suppliers with a cost share and a concentration number | A supplier increase lands on the share of cost that is actually theirs, then management decides how much to pass on. |
| Org chart or payroll summary | Departments with headcount, cost, and weights on capacity, quality and selling | Eliminating one removes its cost and the thing it was quietly holding up. |
| Competitor file or market research | Competitors with a price index, a strength and a reaction | They match part of your move, late, and once. |
| Nothing at all for a class | An inferred node, marked as inferred | The class still acts, and the ledger tells you that its numbers are industry starting points. |
Every row here is reversible. Open the graph, correct a name, merge two nodes the resolver split, delete one it invented, and rebuild.
Step six
What one simulated month actually does
The engine walks the same nine stages in the same order every month of every replication. Nothing here is a curve somebody drew.
- 1
Your decision lands
Any lever whose start month is this month is applied. Price moves, people arrive or go, a supplier changes, a build begins.
- 2
The company answers back
Effects already running tick on, and then your own executives act if their numbers have crossed their own thresholds. This is the part a spreadsheet does not have.
- 3
Competitors resolve what they decided earlier
A match committed three months ago lands now, at the size it was committed at.
- 4
Suppliers drift
Ordinary input cost movement, small and noisy, on top of anything a lever did.
- 5
Customers churn and new ones arrive
Segments move as mass. Named accounts decide one at a time, when their contract comes up.
- 6
Sales capacity is worked out
Ramping reps age, attainment is measured against quota, and a rep who has been behind for a quarter may leave.
- 7
The books are closed
Revenue, cost of goods, operating cost, operating profit, then cash.
- 8
The people react
Utilisation sets strain, strain sets quality, quality sets satisfaction, morale follows workload and pay, attrition follows morale.
- 9
The watchers check their thresholds
Regulator, investor and partners stay silent unless a line has been crossed, and then they do not stay silent.
The run
Fast enough that the follow up question is free
400
Simulations in a standard run
Two hundred of the scenario, two hundred of doing nothing, on the same seeds
0.1s
Typical time for that run
Measured on the machine this was built on, twelve months, about forty agents
20
Metrics recorded every month
Each with a median, a tenth and a ninetieth across the replications
9
Stages inside every simulated month
In the same order, every replication
The output
One answer is a line. Hundreds of answers is a shape
After the run
What you can do with an answer
A single run is the start of the conversation, not the end of it. Everything below works off the same twin, the same ledger and the same seeds.
Sweep the lever
Take the one number you were arguing about, run it across a range with the whole Monte Carlo behind every point, and get a curve with a best point on it.
How sweeps workCompare the options
Several scenarios against one baseline on one set of seeds, so the differences between them are decisions rather than noise.
Why one baseline mattersAttack the assumptions
Move each load bearing number to the ends of its own band, one at a time, and see how far the answer travels. Then go and replace the one that moved it most.
The ledgerInterrogate the twin
Ask a question and get the rows from the graph, the ledger and the runs that bear on it, with what was used listed underneath.
How Ask worksEdit anything and re-run
Rewrite an agent's objectives, correct a node, lock an assumption to your own number. The seed is kept, so the same question tomorrow gives the same answer.
The agentsWhere this stops
The parts that are honestly weak
A simulation that only shows you its strengths is a sales tool. These are the places to be careful, and they are the same places a good analyst would poke first.
None of this is fixed by running more replications. More replications narrow the sampling noise, not the assumption error, and the second is nearly always the larger of the two.
- Elasticity is the most load bearing number in the model, and unless you have run a real price test it is an industry starting point
- A twin built from a thin record is mostly industry priors, and the confidence score is exactly that number rather than a badge
- The model knows your market only through what you uploaded about it, so it will not tell you what your market does next year
- Behaviour below department level is not modelled, so a scenario about one team's workflow is out of scope today
- Nothing in the system learns from how your last decision actually turned out
The practical questions
How long does the whole thing take the first time?
The reading and extraction depend on how much you upload. The graph, the agents and the ledger are built in one pass after that, and running a scenario on the result takes about a tenth of a second for a twelve month horizon with around forty agents.
The slow part is you deciding whether the ledger is right, which is the part worth spending time on.
Can I correct something the extractor got wrong?
Yes, at every level. Facts show the quote they came from. Nodes can be renamed, merged or deleted. Agents can have their objectives, constraints and personality rewritten. Assumptions can be typed over, and a row you type over is locked so a rebuild does not undo it.
Does the simulation call a language model?
No. The engine is arithmetic from end to end and gives the same answer for the same seed. A model is used in three places, all optional: reading prose the rules could not parse, rewriting a finished brief into better English, and answering questions in Ask.
No number reaches the simulation from a model without passing through the ledger first, where it is labelled as an estimate and given a wider band than anything read from a document.
What if I have no customer list?
The twin falls back to three behavioural segments, price led, mainstream and anchored, and to a concentration assumption. Both show up in the ledger as defaults. A scenario about losing your largest customer will then use the assumed concentration and will say so in the event, which is worth reading before you believe the number.
Where does any of this run?
Inside your own WordPress install. Files are kept in a folder outside the media library that is not served over the web, and deleting a source deletes its chunks and its facts with it.
Start with one decision and one file
Or look at the worked example first. It is an invented contract manufacturer called Harborline Components, with one customer at eighteen percent of revenue, a single sourced billet and a price it has not moved since 2023.