Learn

This section is for a smart beginner: you know what a spreadsheet is, you have heard of large language models, and you want to know how this engine turns a folder of business files into a report you can check, and why it is built the way it is.

Everything here follows one example from start to finish: examples/coffee-roaster, a small specialty roaster’s first half of 2026. It has 4 files: a sales workbook with 6,260 order rows, a wholesale price list (PDF), an email from a hotel customer, and the owner’s operations notes (Word). Revenue fell −17.9%N30 from March to April. By the end of the section you will know where that number came from, why the engine believes the hotel’s email explains it, and how you could prove it wrong.

The whole job on one screen

This is one real run of the engine on the example, stage by stage: files go in, a verified report comes out. The rail follows the run’s own event log; press a stage, or Play.

One real run · examples/coffee-roaster · scripted planner, no LLM

1. Files
2. Profile
3. Metric
4. SQL
5. Evidence
6. Verify
7. Report

Play

01 Files INGEST

File	Kind	Read as
email-0412.eml	email	headers and body
ops-notes.docx	document	text, by section and page
price-list.pdf	document	text, by section and page
sales-2026.xlsx	table	sheets, split into table regions

02 Profile PROFILE

Tables

3

Document sections

9

Data-quality issues

3

Every column gets a role and a type before anything is measured; the issues go into the report.

03 Metric METRICS_DRAFT

revenue = sum of amount, per month · USD · assumed

Drafted in plain words and YAML, confirmed or assumed, then compiled to SQL:

SELECT strftime("date", '%Y-%m') AS period, sum("amount") AS value
FROM "t_t1"

04 SQL MEASURE · DETECT · DECOMPOSE

Revenue, 2026-03	$44,100 N12
Revenue, 2026-04	$36,200 N11
Change	−$7,900 N29
Change, percent	−17.9% N30
By channel: wholesale	−$8,500 N144
Wholesale's share of the change	108% N147

05 Evidence INDEX_DOCS · WEB_CONTEXT · EXPLAIN · DECIDE

• After the new price list we are pausing our standing order while we compare suppliers. D1 email-0412.eml · Purchasing, Hotel Group · Standing order · document supported
• Wholesale prices increase 12% from 15 March 2026. D7 price-list.pdf · p.2 · correlated
• Specialty coffee roasters typically see refunds of 1–2% of sales. W1 external · coffee-benchmarks.example · a benchmark page from this run's offline web fixture, compared with the run's own numbers, never in place of them

06 Verify VERIFY

• V1 placeholders ran 19 times · pass
• V2 recompute ran 101 times · pass
• V3 re-derive ran 3 times · pass
• V4 definitions ran 18 times · pass
• V5 citations ran 73 times · pass
• V6 causal ran 18 times · 2 caught
• V7 grounding ran 2 times · pass
• V8 external ran 18 times · pass

101 numbers recomputed, 0 mismatched · 6 citations checked · 2 claims dropped, 2 downgraded

07 Report RENDER

Revenue fell after March, driven by wholesale (a change of −$7,900).

#1 action of 2 · medium confidence Offer wholesale accounts a volume-tier discount to win back paused standing orders: +$3,995 N350 to +$7,191 N351 , next quarter.

Checked later against: revenue >= $44,100 by 2026-09-30

Every stage, with what went in and what came out

Each card is one stage of the job, with the real numbers of that run. Open any of them for a guide: the problem the stage solves, a diagram you can step through, the ideas behind it in plain words, and a command to try it yourself.

Read the files

1. Stage 1 Ingestion & profiling in 4 files out 3 tables (6,260 order rows), 9 document sections, 2 data-quality issues
2. Stage 2 Metric layer in 8 columns of Orders out 5 metric definitions, each one SQL query
3. Stage 3 Analysis in 6 months of revenue out −17.9% (N30), split by channel and by price, volume and mix

Find the why

1. Stage 4 Retrieval in “wholesale price increase standing order paused” out the hotel's email at BM25 #3, vector #3
2. Stage 5 Web lane in a query with a customer's name and a number in it out 2 terms cut; 1 page kept, 1 quarantined, 1 refused
3. Stage 6 The planner (agent) in a finding and 8 fixed tools out 5 tool calls, a structured draft with {{N…}} placeholders

Check and show

1. Stage 7 The verifier (V1–V8) in the draft report out 101 numbers recomputed, 0 mismatched; 2 claims dropped, 2 reworded or downgraded
2. Stage 8 Report & fact IDs in 101 facts out the headline −17.9%, with N30 next to it

Under every stage

1. Stage 9 Model router & free providers in one model on two free endpoints out groq 429 → cerebras 200; repeats from the cache
2. Stage 10 Security in a poisoned email, a forum page, a metadata URL out quarantined, quarantined, refused; every fact unchanged

Two rules hold in every stage, and most of the design follows from them:

1. The model never does arithmetic. Every number in a report is computed by SQL in DuckDB or by a small deterministic function, and carries a fact ID such as N30. A language model may only refer to numbers, through placeholders like {{N30}}.
2. Text from your files is data, never instructions. Documents, emails, cells and web pages are read only by a quarantined extractor that has no tools. Nothing it reads can make the engine act.

How to read this section

• New to all of it? Read the stages in order: Ingestion & profiling first, Security last.
• Want to run it? Start with the tutorial Analyse your first file. Every tutorial runs offline, with no model and no API key.
• Want the exact rules? Each guide links to its reference page under How it works.
• Met a word you don’t know? The glossary explains every term used here.

About the numbers on these pages

Nothing on these pages is typed by hand. The numbers, fact IDs, SQL, quotes, retrieval ranks, verifier counts and terminal output come from real runs of the engine on the example, recorded by apps/docs/scripts/learn-data.ts into docs/assets/learn/learn.json. A test reruns the engine and fails if the file no longer matches.

The runs are offline and deterministic: a scripted planner stands in for the language model (it replays the decisions a model would make, including some deliberate mistakes, so the verifier has something to catch), documents are embedded with an offline hash embedder, and the web lane reads a fixed set of pages. With a real model the wording changes; the numbers don’t, because no model computes them.

Facts on this page

Fact	Value	What it is	How it was computed	Verified
N30	−17.9%	I5 trend_break.v1 revenue 2026-04:change_pct	pct_change ( N11N12 )	recomputed