Use case: automated reports

The consulting deliverable is a report a client trusts: current numbers, defensible definitions, and the same thing every Monday without anyone assembling it by hand. This guide builds that pipeline end to end across the module slices: Conduit pulls today's numbers from live data with provenance, Warrant supplies the certified concept definitions those numbers are cited against, report generation freezes them into an as-of snapshot, a schedule renders it, Crucible benchmarks the quality, and the result is a reproducible PDF.

Prerequisites

• A workspace key with data:read, data:run, reports:write, reports:read, and runs:read, exported as $ELI_KEY. See Getting started.
• A configured data connector and at least one named query. See Data connectors & domain components.
• Some ingested, governed documents — a report over an empty KB is a report about an empty KB.

1 · Conduit — pull today's numbers, with provenance

A report's numbers should be live, not copied from a stale doc. Conduit runs governed named queries— reusable domain components bound onto entities — against live SQL or Snowflake. List what's available, then run one; every execution writes an append-only data_calls row and hands back a dataCallId — the [Dn] anchor you can cite later.

curl -s https://your-host/api/v1/data/queries \
  -H "Authorization: Bearer $ELI_KEY"

{
  "queries": [
    {
      "slug": "arr-by-segment",
      "title": "ARR by segment",
      "description": "Live annual recurring revenue grouped by customer segment. Bound to the ARR concept.",
      "connectorName": "warehouse-prod",
      "params": [ { "name": "as_of", "type": "string", "required": false, "description": "ISO date; defaults to today." } ]
    }
  ]
}

curl -s -X POST https://your-host/api/v1/data/queries/arr-by-segment/run \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"as_of":"2026-07-21"}}'

{
  "dataCallId": "01KY10CCCCCCCCCCCCCCCCCCCC",
  "connectorName": "warehouse-prod",
  "queryTitle": "ARR by segment",
  "columns": ["segment", "arr_usd"],
  "rows": [ { "segment": "Enterprise", "arr_usd": 4210000 }, { "segment": "Mid-market", "arr_usd": 1880000 } ],
  "rowCount": 2,
  "truncated": false,
  "durationMs": 63,
  "executedAt": "2026-07-21T07:00:03.412Z"
}

2 · Warrant — cite numbers against certified definitions

A number is only defensible if its definitionis. "ARR" means nothing in a client report unless everyone agrees what it counts. That agreement is a certified concept in Warrant — and because concepts are versioned, a report can cite the exact version of the definition in force when it was generated. The arr-by-segment query is bound to the ARR concept; when the report grounds that row, it references the concept at its current certified version. Confirm the definition is pinned before you schedule anything on top of it:

curl -s -X POST https://your-host/api/v1/entities/01KZARRCONCEPT00000000000/certify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"ARR = normalized annual recurring revenue, excludes one-time services. Signed off by Finance."}'

{ "authority": "certified", "lifecycleStatus": "published", "version": 5, "nextReviewAt": "2027-01-17T09:10:00.000Z" }

Now a claim in the report — "Enterprise ARR is $4.21M [D1] as defined by ARR v5 [S1]" — carries both a [Dn] live-data provenance anchor and an [Sn] citation to the governed definition at a specific version. Fuse both in one grounded call by asking with includeData: true:

curl -s -X POST https://your-host/api/v1/query \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"What is Enterprise ARR this quarter and how is ARR defined?","includeData":true}'

{
  "answer": "Enterprise ARR is $4.21M [D1], where ARR is normalized annual recurring revenue excluding one-time services [S1].",
  "claims": [
    { "text": "Enterprise ARR is $4.21M", "citations": ["D1"] },
    { "text": "ARR excludes one-time services", "citations": ["S1"] }
  ],
  "dataCalls": [ { "id": "D1", "dataCallId": "01KY10CCCCCCCCCCCCCCCCCCCC", "queryTitle": "ARR by segment", "executedAt": "2026-07-21T07:00:03.412Z" } ],
  "sources": [ { "id": "S1", "docId": "01KZARRDEF0000000000000000", "docTitle": "Metric definitions", "docPath": "finance/metric-definitions.md" } ],
  "policy": { "decision": "answer", "confidence": "high" }
}

3 · Generate the as-of snapshot

A report freezes the knowledge base as of a moment in time — coverage, KPIs, top entities, gaps, what to interview next — and persists it immutably. The numbers are stamped at generation, so a report you hand a client in July still reads the same in December, and re-rendering it is byte-for-byte identical because the layout version is stamped in.

curl -s -X POST https://your-host/api/v1/reports \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Acme — weekly revenue & coverage report"}'

{
  "id": "01KY13DDDDDDDDDDDDDDDDDDDD",
  "title": "Acme — weekly revenue & coverage report",
  "status": "generating",
  "layoutVersion": "report-v4",
  "sections": ["coverage", "kpis", "topEntities", "gaps", "interviewNext"],
  "generatedAt": "2026-07-21T07:00:10.000Z",
  "pdf": { "status": "queued", "url": null }
}

4 · Schedule it

Automation is the point. Put the generation call on a schedule and the Monday-morning report is rendered before anyone opens their inbox. The cron substrate — recurring jobs, drift checks, and alerting on the same durable queue that runs syncs — is covered in Scheduling, drift & alerts. A scheduled run does exactly what the manual POST /api/v1/reportsabove does, on a cadence, under the same key and scopes. Because Conduit re-runs the bound queries at generation time, each weekly snapshot captures that week's live numbers — while the certified definitions they cite stay pinned until Warrant deliberately bumps them.

5 · Crucible — benchmark the report's quality

A report a client relies on has to be right, and "right" must be measurable. The narrative sections are grounded answers, so the same evaluation framework that scores chat scores the report: build a golden set of the questions each section answers — "What is Enterprise ARR?", "Which segment grew fastest?" — and read faithfulness and abstention on a run. A regression here means a section would ship a wrong number; you catch it before the client does.

curl -s https://your-host/api/v1/evals/runs/01KZRUNA00000000000000000/metrics \
  -H "Authorization: Bearer $ELI_KEY"

{
  "runId": "01KZRUNA00000000000000000",
  "n": 30,
  "retrieval": { "recallAtK": 0.80, "ndcgAt10": 0.77 },
  "ragas": { "faithfulness": 0.93, "responseRelevancy": 0.86, "contextPrecision": 0.71 },
  "abstention": { "truthfulness": 0.66, "abstainRate": 0.10 }
}

Gate the schedule on it: a nightly benchmark run that dips below your faithfulness floor is an alert, not a silent bad report. Compare a prompt or retrieval change behind a two-gate significance test in Measure & compare before it touches a client-facing deliverable.

6 · Fetch the PDF

Once the render lands, pdf.status is ready and the PDF streams from its own endpoint under the same reports:read scope. Stream it straight to disk, attach it to an email, or drop the link in Slack:

curl -s https://your-host/api/v1/reports/01KY13DDDDDDDDDDDDDDDDDDDD \
  -H "Authorization: Bearer $ELI_KEY" | jq '{status, pdf: .pdf.status}'

{ "status": "ready", "pdf": "ready" }

curl -s https://your-host/api/v1/reports/01KY13DDDDDDDDDDDDDDDDDDDD/pdf \
  -H "Authorization: Bearer $ELI_KEY" \
  -o acme-weekly.pdf

The leverage

One schedule turns the live state of an engagement into a frozen, reproducible, benchmarked deliverable — with every number carrying its [Dn] query provenance and every definition its [Sn] concept version. Conduit keeps the numbers current, Warrant keeps the definitions defensible, Crucible keeps the quality measured, and the PDF is the artifact the client pays for. Nobody assembled it by hand, and anyone can trace any figure back to the exact query and definition behind it.