Skip to content

Start

What it is

A one-minute read on what agentic-analytics does, and what it refuses to do.

agentic-analytics reads a small or medium business’s own files — spreadsheets, CSV exports, PDFs, Word documents, emails — and writes a report: what changed, why it changed, where the data is wrong, and what to do next.

It is built around three refusals:

  1. The model never does arithmetic. Every number is a fact: the result of SQL run in DuckDB, or of a deterministic function, with its computation attached. Model-written text holds numbers only as {{N12}} placeholders that resolve to facts.
  2. No claim without a source. Every claim carries citations — the rows, cells, pages or URLs it rests on — and a causal grade: observed, correlated, document-supported.
  3. Nothing unverified ships. A verifier recomputes every number, re-derives the headline metrics another way, checks every citation and every causal word, and drops or downgrades what fails before report.json is written.

Below is one real run on the example business (scripted planner, no LLM): its stages, the facts it computed with their ids, the evidence it cited, the verifier’s checks and the top-ranked action. The README GIF is drawn from the same run data.

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

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

What it is not

Section titled “What it is not”
  • Not a dashboard or a BI tool: it answers “what changed and why”, once per period.
  • Not a chatbot over your files: follow-up questions are answered with verified claims only (aa ask).
  • Not a forecaster: v0.1 explains the past and proposes checks; it does not predict.