Learn
Add documents and emails as evidence
Run the example with the workbook alone, then with its price list, email and notes, and see what the documents change in the report.
Tutorial 3 of 5. About ten minutes, offline. Background: Retrieval and the verifier.
Numbers say what changed. Documents can say why. This tutorial shows the difference on the same data.
1. The workbook alone
Section titled “1. The workbook alone”Give the engine only the spreadsheet:
$ AA_DEMO_MODEL=scripted bun run aa analyze examples/coffee-roaster/sales-2026.xlsx --yes --embedder hash --today 2026-07-01 --currency USD
… (31 lines before)
Revenue fell after March, alongside wholesale (a change of −7,900).
Findings:
• Revenue fell after March, alongside wholesale
… (16 more lines) Replaced in the recording because they change on every run: stage durations, the job id (a timestamp), the report folder (the current folder).
The finding’s title says revenue fell “alongside” wholesale. With no document, the engine can show that the two moved together, not why. These are the finding’s claims, with their causal grades:
| Claim | Grade | Evidence |
|---|---|---|
| Revenue went from $44,100 in 2026-03 to $36,200 in 2026-04 (a change of −$7,900, −17.9%). It stood at $37,000 in 2026-06. | observed | the numbers |
| By channel, “wholesale” fell $8,500, more than the whole drop; “retail” rose $600. | observed | the numbers |
| By product, the price effect was $1,181.91, the volume effect −$1,911.07 and the mix effect −$7,170.84. | observed | the numbers |
| The drop coincided with the price increase. | correlated | the numbers |
The scripted planner still tried to write “caused by the price increase”; with nothing to cite, the verifier reworded it to “coincided with”.
2. Add the documents
Section titled “2. Add the documents”Put the price list (PDF), the hotel’s email (EML) and the operations notes (DOCX) next to the workbook. That is just the whole example folder:
AA_DEMO_MODEL=scripted bun run aa analyze examples/coffee-roaster --yes --embedder hash --today 2026-07-01 --currency USD$ AA_DEMO_MODEL=scripted bun run aa analyze examples/coffee-roaster --yes --embedder hash --today 2026-07-01 --currency USD
… (31 lines before)
Revenue fell after March, driven by wholesale (a change of −7,900).
Findings:
• Revenue fell after March, driven by wholesale
… (16 more lines) Replaced in the recording because they change on every run: stage durations, the job id (a timestamp), the report folder (the current folder).
Now it says “driven by” wholesale, and the claims gain evidence:
| Claim | Grade | Evidence |
|---|---|---|
| Revenue went from $44,100 in 2026-03 to $36,200 in 2026-04 (a change of −$7,900, −17.9%). It stood at $37,000 in 2026-06. | observed | the numbers |
| By channel, “wholesale” fell $8,500, more than the whole drop; “retail” rose $600. | observed | the numbers |
| By product, the price effect was $1,181.91, the volume effect −$1,911.07 and the mix effect −$7,170.84. | observed | the numbers |
| The hotel customer paused its standing order because of the new price list. | document_supported | email-0412.eml |
| The wholesale price increase took effect shortly before the drop. | correlated | price-list.pdf |
| The drop coincided with the price increase. | correlated | the numbers |
The email moved one claim to document_supported: the hotel wrote that it paused its standing order after the new price list, and the report quotes it exactly, with the file and the character span. The price list supports a weaker claim, correlated: prices went up shortly before the drop. The numbers did not change at all; they never come from documents.
3. What counts as evidence
Section titled “3. What counts as evidence”- Formats: PDF (with a text layer), Word (DOCX), email (EML, headers included), Markdown and plain text. Scanned PDFs can go through an optional Docling container.
- Put them in the same folder (or list them on the command line) as the data. Every file of a job is indexed.
- They are untrusted. A document can’t give instructions: it is screened, and only the quarantined extractor reads it. A document that tries is quarantined and listed in the report.
- Grades are earned. A cause needs a quote that says so; the verifier checks the quote exists in the file and that causal wording has a document behind it.
What you learned
Section titled “What you learned”- Without documents the report describes; with them it can explain, and says how strongly.
- Every causal claim cites an exact quote you can open.
- Documents add explanations, never numbers.
Next: Use it from Claude via MCP.