Nodal Analytics

Agent skills for building governed analytics context, planning data questions, and verifying the answers.

Analytics agents can write valid SQL and still give the wrong answer. They need the definitions an experienced analyst carries around: what a metric means, which table is canonical, which filters are mandatory, where joins fan out, and when a result should be escalated instead of trusted.

Nodal turns that knowledge into reviewable context and reusable agent workflows. An analyst remains the authority: the agent drafts choices where it finds uncertainty; the analyst chooses the correct interpretation, then the agent verifies, records, and evaluates the context.

Who Nodal is for today

Nodal is currently best suited to teams that already have:

• a queryable analytics warehouse or database;
• an analyst or other domain expert who owns business definitions; and
• a supported local agent that can receive approved, read-only access to the warehouse.

The person operating this open-source package should be comfortable working in a local agent project and coordinating data access. They do not need to write Python, and the domain expert who confirms definitions does not need to know dbt or use a command line. dbt, historical query access, and BI dashboards improve the evidence available to Nodal, but they are not all required.

Large organizations are in scope. Nodal is designed to roll out one analytics domain at a time: establish the domain's definitions, failure cases, and eval seeds; verify that its governed answers work; then expand to the next domain. This creates a reviewable governance boundary at every step instead of requiring a company-wide semantic migration before the first result.

Nodal is not yet optimized for organizations without a warehouse or technical data owner. We are interested in extending it both upstream to more complex enterprise environments and downstream to earlier-stage teams, while keeping the current domain-by-domain validation model.

Two ways to start

• Use your own stack. Start with one bounded business domain where a domain expert can confirm the definitions. Prove the workflow there before adding another domain.
• Look at an example company. See Shorelane Commerce, a fictional company with a public warehouse and deliberately ambiguous revenue definitions.

Let your agent guide installation

If you already use an AI coding agent, paste this prompt into a project where you want to evaluate Nodal:

Help me understand and set up Nodal Analytics for this project. Read
https://github.com/nodal-data/nodal-context/blob/main/docs/agent-guide.md
first. Explain what will change, choose only one supported installation method,
and ask before installing anything or editing configuration. Then walk me
through it one step at a time.

Where your data flows: nowhere new

Nodal's open-source package is a set of skills—instructions and local scripts that run inside your own agent, on your own machine. There is no Nodal service in the loop:

• No data reaches Nodal. Schema, query results, query history, dashboard captures, and the generated context all stay on your machine and in repositories you control. The package makes no network calls to Nodal and contains no telemetry.
• No credentials reach Nodal. Warehouse access happens through an MCP server you configure and authenticate yourself, using a read-only identity.
• Your existing agent agreement is the only data flow. Whatever your agent reads while answering a question is processed by the model provider behind your agent host—for example, Anthropic when you run on Claude Code—exactly as in any other use of that agent. Nodal adds no new data recipient.

What you need before the first interview

Nodal never handles warehouse credentials or sees your data. Connect your agent to the warehouse through an approved MCP server using a read-only identity.

For the best initial context build, prepare:

• A domain expert. An analyst or other owner must confirm definitions. Nodal does not silently promote generated documentation to truth.
• Read-only warehouse access. The connection must support SELECT and metadata inspection. Nodal does not run DDL, DML, grants, or procedures.
• Historical query-log visibility. Full Stage 0 discovery needs access to query history across the relevant people, BI service accounts, and workloads.
• Your dbt project, if you use dbt. A local sibling checkout is recommended so the interview can draft from real models, tests, and metric definitions.

The workflows

The skills are small and composable. Use one directly, or let the agent route to the appropriate workflow.

Build and maintain context

• setup-nodal configures project-local context sources, read-only warehouse capabilities, and optional browser access.
• context-interview interviews an analyst to build or improve an Analytics Context Format (ACF) repository.
• analyst-handoff captures critical domain knowledge when an analyst changes roles or transfers ownership.

Ask and verify

• analytics-plan translates a business question into a reviewable plan before any SQL runs.
• verify-result checks executed SQL and results against the approved plan for metric, filter, grain, join, and time fidelity.
• challenge-result gives a completed answer a skeptical second review when the user questions it or asks for another take.
• dashboard-verify reads a named BI dashboard in the user's local browser, capturing both values and active filters for reconciliation.

Why these skills exist

1. The agent knows the schema but not the business

Warehouses encode what can be queried, not what the company means by “active customer,” “revenue,” or “conversion.” Nodal interviews the people who own those definitions and stores the result in files the team can review by pull request.

2. Auto-generated context repeats existing ambiguity

Raw schemas, prior SQL, and BI metadata are useful evidence, but they are not authority. Nodal uses schema, dbt, dashboards, and query history to create drafts and surface conflicts. A human decides which interpretation is correct.

3. A successful query is not a verified answer

SQL can execute successfully at the wrong grain, omit a mandatory filter, use a noncanonical metric, or fan out through a join. analytics-plan makes intent explicit before execution; verify-result checks whether the query and result actually satisfy that intent afterward.

License

Apache-2.0. The format and the interview-built context are yours to keep.