Agentic Analytics Engine

Ask a question about a built-in warehouse or an uploaded CSV/Parquet file. The engine compiles the question into a typed analytical contract, executes that contract locally over DuckDB, verifies the result, and shows the data and SQL behind every published number.

https://github.com/user-attachments/assets/d1730a84-6861-4254-97d6-ccab0758a5d4

Live demo: agentic-analytics-engine.onrender.com

A model never executes SQL and never calculates a published value. On the upload path a model may propose a typed interpretation of an ambiguous question; local code then validates that proposal against the schema, compiles the SQL, runs it, and re-checks every figure. The multi-task warehouse path may also use models to propose findings and judge semantic support, and deterministic arithmetic, evidence checks and policy gates can still withhold them.

How a question becomes an answer

flowchart LR
  Q[Question] --> R{Can local rules resolve it?}
  R -->|yes| C[Typed query contract]
  R -->|ambiguous| P[Governed AI planner]
  P --> V[Local contract validation]
  V --> C
  R -->|unsafe or unmappable| X[Clear refusal]
  C --> D[DuckDB through MCP]
  D --> G[Coverage and numeric verification]
  G --> O[Answer, table, chart and provenance]

The rule resolver returns one of five states: EXACT, AMBIGUOUS, UNRESOLVED, UNSUPPORTED, UNSAFE. Only AMBIGUOUS can reach a planner, and only for the four issues a model can plausibly settle from wording: an unclear column role, competing measure candidates, competing dimension candidates, and an unbound filter. Everything else refuses with a reason and makes no provider request.

Period ambiguity is deliberately excluded from that set. A signup date beside annual revenue cannot establish which column is the business clock for the measure, so the engine asks the session owner instead of guessing.

Both paths hold to the same four properties:

• Operations, measures, groupings, filters, periods, rankings and result shape are all validated before any SQL is composed.

• The engine owns the SQL, the read-only guard, metric definitions, statistics, chart specification and arithmetic checks.

• A published claim needs cited cells, numeric support, evidence support and question relevance. A breakdown is described as complete only where coverage was measured.

• Reports link each number to its snapshot, cited cells, generated SQL and accepted contract.

Full detail in architecture, the architecture atlas, and limitations.

Related MCP server: mcp-data-lens

Ways to run an analysis

Governed Analysis is the default. It resolves straightforward questions locally at no model cost and consults a planner only for an eligible ambiguity. The route taken is recorded by the server rather than inferred by the UI.

Two audit paths are available where the deployment enables them:

Comparison does not rank planners. It reports whether the accepted contracts, coverage and outputs agree, and names the differing contract fields where they do not.

Upload analytics

• CSV and Parquet only, one file per anonymous capability-based session.

• The public deployment applies file, column, row, rate and concurrency limits. Sessions and their DuckDB data expire; they provide isolation rather than user accounts.

• Column roles are inferred conservatively. Unsupported questions and incomplete results refuse rather than silently dropping a filter, grouping or period.

• A cloud planner receives the question, schema information and allowed aggregate labels, never unaggregated rows. A near-unique text column is withheld from grouping, because group labels can reach the planner.

When the data cannot settle a column's role

Some numeric columns are structurally ambiguous: a value between 18 and 65 could be an ordered quantity such as age or a numeric key such as a store number. The engine marks this as a close call.

For an ambiguous upload field the session owner may confirm quantity or category. That confirmation is scoped to the session, validated server-side, revisioned to reject stale browser tabs, recorded in the planning audit, and pinned when a run starts. It never rewrites a completed run's evidence. Confirming a quantity permits an average but not an automatic total, because additivity is a separate fact the engine still does not know. Rationale in ADR 0007.

Run locally

make bootstrap  # create the environment, install Python and npm dependencies
make data       # generate the deterministic demo warehouse
make dev        # build and serve http://127.0.0.1:8000 in fake-provider mode
make verify     # lint, types, both test suites and recordings

Development commands pin AAE_PROVIDER_MODE=fake and need no credential. The browser suite refuses to run unless the target is a loopback address whose health endpoint reports provider_mode: fake. It checks the host as well as the mode, because the deployment also runs in fake mode: provider_mode selects the ungoverned provider, while the paid path is gated separately on an enabled flag, a credential and a reachable usage ledger. Deployments are exercised by the hosted sweep in web/hosted/, which has its own gate.

Cloud development requires explicit intent and can bill a real account:

AAE_CONFIRM_PAID_LOCAL_RUN=1 make dev-cloud

Stack and boundaries

The website speaks MCP in-process, so it makes no network hop for tools. /mcp is a separately guarded Streamable HTTP transport for external callers, and it answers 503 when no Host allow-list is configured, which is how the public deployment runs.

Verification evidence

CI publishes the test count for the exact commit it checks, and reconciles every discovered browser test, declared skip and retry across Chromium, Firefox and WebKit, so no count is frozen here.

The production audit on 6 October 2026 checked f98b890:

• all ten CI jobs passed, including Docker and the three browser engines;

• the credential-free API acceptance script passed 60 checks;

• the hosted browser sweep passed 156 of 156 width, theme and state cells and made no upload, analysis, comparison or provider request;

• one separately authorised Compare canary passed 41 checks and cost $0.000158.

On 7 October, a credential-free follow-up ran the same 156-cell browser matrix against the current deployed commit b5a24b5. It made no upload, analysis, comparison or provider request.

These are engineering checks. They are not a claim of universal dataset coverage or WCAG conformance. See the production audit, historical release evidence and limitations. The documentation map separates current operating material from historical evidence.

Repository map

src/agentic_analytics/
  analytics/       contracts, semantic inference, execution and presentation
  api/             FastAPI, SSE, sessions, uploads and admission
  graph/           workflow state and orchestration
  llm/             fake, local and governed cloud-provider adapters
  mcp_layer/       analytical MCP tools, resources and client transport
  verification/    arithmetic, claim-shape, evidence and chart safety
  warehouse/       DuckDB lifecycle, metrics, SQL guard and session capability
web/               React application, report workspace and browser tests
docs/              ADRs, architecture, evidence, deployment notes and limits

Limits

• No causal claims, forecasts, arbitrary joins, or business semantics absent from the data. Schema inference is conservative, and a role confirmation records a user-supplied interpretation rather than a fact derived from values.

• The scripted provider validates engine behaviour, not real-model planning quality. Paid live-model checks are documented separately and deliberately few.

• A session capability provides isolation, not authentication, and application rate limits are not a provider billing guarantee.

Complete list in limitations. MIT licensed.