Skip to main content

​
The problem context solves

An agent with warehouse access can write SQL, but it can’t know that “revenue” excludes refunds, that dim_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. Two groups reached the same conclusion independently:
  • Anthropic’s data team: auto-generating metric definitions from raw tables and query logs “produced plausible-looking definitions that encoded the exact ambiguities we were trying to eliminate” — net-negative on evals vs. a smaller, human-curated layer.
  • MIT CISR: build the semantic layer top-down and incrementally, starting with priority data assets first — exactly the one-domain-at-a-time interview.
Nodal instead generates a draft with the model and has a human own the definition:
  1. 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.
  2. The analyst confirms. In the interview, the analyst corrects each definition. Their confirmation — not the extraction — is what Nodal trusts.
  3. 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-source nodal-context repo contains:

​
Next

Connect your database

The one prerequisite before the interview — read-only, and Nodal never sees it.

Build your context

Run the interview and generate your first domain.