The problem
An AI agent connected straight to your warehouse sees tables and columns, not meaning. It doesn’t know thatrevenue lives in orders.amount but excludes refunds, that “active customer” has a specific definition your finance team agreed on, or that summing a daily balance across a week is nonsense. So it guesses. A confidently-wrong answer is the worst kind of wrong: a confident, well-formatted, incorrect number that looks right.
Schema access makes an agent fluent. It doesn’t make it correct.
Why you need a context layer
Real output, captured from a live run against the ecommerce example, not hand-written: ❌ Without canonic (the guess):What canonic does
canonic sits between your data and your agents as a context layer: an auto-built, auto-maintained, version-controlled description of what your data means and how to query it safely.- Canonical definitions, enforced. An agent asks for a metric by name. canonic resolves it to the one agreed definition and compiles the SQL. Guardrails such as
mandatory_filter,required_dimension,restrict_sourceandmin_trustare part of the contract, so a documented caveat can’t be silently skipped. Contracts and guardrails - The right aggregation, not just valid SQL. Semi-additive measures (MRR snapshots), ratios recomputed at the requested grain, distinct counts, percentiles and running totals each get their own compilation strategy, and joins that would fan out a fact table are caught. Several valid join paths? You pick one with
via, canonic doesn’t guess. Compiler - Answers carry their trust. Every result ships a metadata band: the resolved definition, guardrails fired, freshness, final vs. provisional rows, and a trust tier (
trusted,provisional,caution) with the reasons behind it. Assertions gate CI, and confirmed-wrong outcomes lower a metric’s trust. Trust and assertions - Refuse and ask. Ambiguous or unsafe questions come back as a structured reason (
ambiguous_join_path,guardrail_block, …) the agent can act on, never as a guess. Error codes - The context builds itself. Ingest drafts semantics from your live schema, a dbt manifest or an Apache Ossie model, and learns from Looker and Metabase usage, Notion pages and web docs. Every change is a reviewable diff (
canonic review,canonic apply), drift is flagged, and references to things that disappeared are proposed for removal. Ingestion - Business knowledge for agents. Definitions, policies and caveats live as Markdown pages. Agents search them, read them with live-rendered definitions, and get the relevant caveats attached to an answer. Knowledge layer
- Governance built in. Tenant scoping, role-based access, column masking, and OAuth 2.1 / OIDC for the MCP server, including identity assertion for agents acting on behalf of a user. Tenancy and access control
- Your warehouse, read-only. Postgres, Redshift, MySQL, Snowflake, Databricks, ClickHouse, SQLite and DuckDB (including CSV and Parquet files). Connectors
- Measurable. A local event log feeds
canonic auditandcanonic status, and an accuracy harness (canonic assert,canonic eval baseline) turns “trustworthy” into something you can check. Instrumentation
How it works
What an agent gets back
Real output, abridged, fromcanonic --json query --metrics gross_revenue in the saas-analytics example:
provisional, so it can caveat the answer instead of presenting it as settled.
Why canonic, not something else
For a side-by-side with dbt MetricFlow, Cube, LookML and Apache Ossie, see canonic and other tools.
What makes it different in one line: canonic builds the context for you, keeps it honest, and refuses to lie when it isn’t sure.
canonic is not a BI tool and not a chat interface: it’s the layer that feeds the tools you already have (a BI dashboard, an agent, a notebook) correct, governed answers. If you want a place to explore data visually, or a standalone chatbot, canonic isn’t that. It’s the plumbing underneath one.
The three layers
canonic’s context lives in three committed surfaces: plain files in your git repo, reviewed like code. Each answers a different question.
The split rule:
- Changes how the SQL runs → semantics.
- A human needs it to trust the answer → knowledge.
- Governs which definition is authoritative or what an answer must satisfy → contracts.
Example projects
examples/ ships seven ready-to-run projects, each with a guide. Source for all of them is in the repository.
What you can rely on
- Read-only. canonic never mutates your warehouse. It reads, it never writes back.
- Propose-only. It never silently edits your context: every change is a reviewable diff anchored to evidence.
- Refuse-and-ask. Ambiguous or unsafe? It returns a structured reason, not a guess.
- No LLM in the answer path. Queries compile deterministically: the same question always produces the same SQL. An LLM only helps draft context, never compute an answer.
- Local-first & air-gapped-capable. Run entirely on your machine with a local model and local embeddings. Nothing has to leave your network.
- Measurable. A local event log tracks accuracy, freshness, and answer quality, so “trustworthy” is something you can check, not just claim.
Installation
Install the canonic CLI via uv, pip, or Docker.
Quickstart
Get your first answer in minutes with a local SQLite or DuckDB file.
Concepts
The three layers, the compiler, contracts and tenancy.
Connect your agent
Wire canonic into Claude Code, Cursor, Codex or any MCP client.
Guides
Seven ready-to-run example projects and the warehouse walkthroughs.