The problem context solves
An agent with warehouse access can write SQL, but it can’t know that “revenue” excludes refunds, thatdim_customer is canonical and customers_raw is a staging table, or that every appointment
query should filter out no-shows. Those are decisions your analyst has already made. Without them,
the agent produces answers that look right and aren’t.
A context layer encodes those decisions in one place the agent reads before it queries:
definitions, canonical tables, standard filters, and known caveats.
ACF: the Analytics Context Format
Nodal’s context layer is ACF — an open format that is just Markdown + YAML, organized by business domain. It is readable by a human in a PR and by any agent at query time. ACF is Apache-2.0; the format and the interview that builds it are yours to keep.A context layer is one idea; ACF is one shape it can take. The Nodal eval harness reads ACF,
dbt models and docs, or raw markdown — so you can measure the value of context you already have,
then adopt ACF where it helps. You are never locked into the format.
Interview-built, not auto-generated
The defining choice in ACF is how the context is created. Most tools ingest your warehouse and query logs and auto-generate the definitions. Teams who measured that approach found it net-negative — it encodes the ambiguities you were trying to remove. Nodal instead generates a draft with the model and has a human own the definition:- Auto-extract a draft. Your schema and dbt models/docs seed a first draft, so the analyst starts from something real instead of a blank page.
- The analyst confirms. In the interview, the analyst corrects each definition. Their confirmation — not the extraction — is what Nodal trusts.
- Every confirmation is also an eval pair. Each disambiguation becomes labeled ground truth, so context and measurement grow together.
What’s in the repo
The open-sourcenodal-context repo contains:
| Path | What it is |
|---|---|
SPEC.md | The Analytics Context Format standard |
skills/context-interview/ | The interview skill that builds your context |
schemas/ | JSON Schemas that make the YAML CI-checkable |
template/ | The empty scaffold the interview fills in |
examples/ | A worked example in the ACF format |
eval_harness/ | The OSS eval runner and its contract |
.github/workflows/ | Validate context, detect drift, and run the eval delta on every PR |
Next
Connect a warehouse (MCP)
The one prerequisite before the interview — read-only, and Nodal never sees it.
Build your context
Run the interview and generate your first domain.