Canonic

canonic

[CI] [PyPI] [License]

The context layer that lets AI agents query your data correctly.

Point canonic at your database and it builds the context an agent needs to answer data questions accurately: definitions, relationships, business meaning, and the guardrails that stop confidently-wrong answers. It keeps that context up to date as your data changes, and it never touches your warehouse beyond reading it.

📖 Full documentation: https://docs.getcanonic.app

The problem

An AI agent connected straight to your warehouse sees tables and columns, not meaning. It doesn't know that revenue lives in orders.amount but excludes refunds, or that "active customer" has a specific definition your finance team agreed on. So it guesses. Schema access makes an agent fluent. It doesn't make it correct.

Real output, captured from a live run against the ecommerce example:

$ canonic sql "SELECT SUM(amount) FROM fct_orders"┏━━━━━━━━━┓┃ sum     ┃┡━━━━━━━━━┩│ 4050.50 │└─────────┘

This total includes two refunded orders ($260), a confident, well-formatted number that's off by 6.4%.

$ canonic --json query --metrics revenue{  "result": { "rows": [["3790.50"]] },  "compiled": {    "sql": "SELECT SUM(\"orders\".\"amount\") AS \"revenue\" FROM \"fct_orders\" AS \"orders\" WHERE \"orders\".\"status\" <> 'refunded'"  },  "metadata": {    "guardrails_fired": [{ "id": "revenue-excludes-refunds", "kind": "mandatory_filter" }]  }}

canonic resolves "revenue" to its canonical definition, compiles the guardrail into the SQL whether or not anyone asked for it, and returns the right number with the reasoning attached.

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.

What canonic does

• 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_source and min_trust are 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
• Why did it change? canonic decompose and the MCP tool decompose_change attribute the change of a metric between two periods, overall and by member. The method follows the metric's kind, so a ratio is split into mix and rate effects that add up, instead of per-member differences that do not. Tools reference
• 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 audit and canonic status, and an accuracy harness (canonic assert, canonic eval baseline) turns "trustworthy" into something you can check. Instrumentation

How it works

 your sources                 canonic                          consumers ────────────                 ───────                          ───────── warehouse schema ┐   ingest  ┌──────────────────────────┐     CLI (query, sql, review) dbt / Ossie      ├─────────▶ │ semantics/  knowledge/   │ ──▶ MCP server Looker, Metabase │  propose  │ contracts/  (files in git)│     Claude Code, Cursor, Codex, Notion, web docs ┘  → review └──────────────────────────┘     any MCP client

A question takes one deterministic path: resolve the metric, compile SQL against the canonical definition, apply guardrails, run it read-only, attach the metadata band. No LLM is involved at answer time.

What an agent gets back

Real output (abridged) from canonic --json query --metrics gross_revenue in the saas-analytics example:

{  "result": { "columns": [{ "name": "gross_revenue", "type": "decimal" }], "rows": [["77071.00"]] },  "compiled": {    "sql": "SELECT SUM(\"fct_invoices\".\"amount\") AS \"gross_revenue\" FROM \"fct_invoices\" AS \"fct_invoices\" WHERE \"fct_invoices\".\"status\" <> 'refunded' AND \"fct_invoices\".\"is_trial\" = FALSE",    "dialect": "duckdb"  },  "metadata": {    "resolved": { "metrics": { "gross_revenue": "fct_invoices.total_amount" } },    "guardrails_fired": [      { "id": "revenue-excludes-refunds", "kind": "mandatory_filter", "severity": "error" },      { "id": "revenue-excludes-trials", "kind": "mandatory_filter", "severity": "error" }    ],    "freshness": [{ "source": "fct_invoices", "stale": false }],    "trust_score": {      "tier": "provisional",      "reasons": ["gross_revenue: assertion unverified (pass/fail not yet persisted)"]    }  }}

The agent sees which definition answered, which rules shaped the SQL, and why the number is only provisional, so it can caveat the answer instead of presenting it as settled.

The three layers

canonic's context lives in three committed surfaces: plain files in your git repo, reviewed like code.

Changes how the SQL runs → semantics. A human needs it to trust the answer → knowledge. Governs which definition is authoritative → contracts. See Concepts: the three layers.

Quickstart

canonic needs Python 3.13 or newer (uv fetches it for you).

uvx canonic --version        # try it without installinguv tool install canonic      # persistent, global commandpip install canonic          # without uvdocker pull ghcr.io/mischuh/canonic:latest   # CI, headless, air-gapped

The fastest path uses local connectors, no server, no network. Point at a SQLite .db or DuckDB .duckdb/CSV/Parquet file:

canonic setup

[canonic setup end-to-end on the vehicle rental example]

The wizard names your project, connects a source, optionally configures an LLM, drafts your semantics from the live schema, then runs a real query and shows the answer with its freshness and definition. A server-based database or an LLM provider needs a credential in an environment variable (or a file: reference) before you run canonic setup, because canonic never stores secrets in canonic.yaml directly.

You now have a working context layer committed to your repo:

canonic overview                                           # what's askablecanonic query --metrics revenue --dimensions order_date    # ask itcanonic review && canonic status                           # review what it drafted

Air-gapped install and offline wheels: Installation.

Connect your agent (MCP)

canonic exposes its tools over a local, on-demand MCP server, verified with Claude Code, Cursor, and Codex:

canonic mcp start

{  "mcpServers": {    "canonic": {      "command": "uvx",      "args": ["canonic", "mcp", "start", "--project", "/path/to/canonic/examples/rental", "--suggestions"]    }  }}

GUI-launched clients (Claude Desktop, Cursor) don't source your shell profile, so pass connection credentials via the config's env field, not export.

See Connecting your agent for remote and enterprise deployment (--transport http, per-client bearer tokens) and the tools reference. To see masking, run_sql gating and tenancy scoping applied to a real identity, scripts/local_idp runs the marketplace example behind a local Keycloak: walkthrough.

Example projects

examples/ ships seven ready-to-run projects, each with a guide:

What you can rely on

• Read-only. canonic never mutates your warehouse.
• Propose-only, refuse-and-ask. Every change is a reviewable diff; ambiguous or unsafe answers get a structured reason, not a guess.
• No LLM in the answer path. Queries compile deterministically. An LLM is optional and only drafts context during setup, four providers supported (Anthropic, OpenAI, any OpenAI-compatible endpoint, GitHub Copilot), see Configuring an LLM.
• Local-first & air-gapped-capable. Run entirely on your machine; nothing has to leave your network.

For developers

uv sync                          # install with dev dependenciesuv run pytest tests/ -x          # tests, including the golden suiteuv run ruff check . && uv run ruff format --check .uv run mypy canonic/

• Layout. canonic/ is the package (compiler, connectors, contracts, ingestion, knowledge, MCP server, trust, instrumentation), tests/ mirrors it, examples/ holds the sample projects.
• Extension points. Connectors register with the ConnectorFactory by capability (introspect_schema, run_read_only_sql, extract_definitions, extract_evidence), and short-lived credentials plug in through the CredentialProviderRegistry.
• Stable contract. The serving contract is versioned (the contract_info MCP tool, CONTRACT_CHANGELOG.md), and tests/golden/ locks compiled SQL and executed numbers for the examples.
• Contributing. Conventional Commits, the golden-suite workflow and the contract-change process are in CONTRIBUTING.md.

Documentation

• Quickstart: first answer in minutes.
• Concepts: the three layers, the compiler, contracts, tenancy.
• CLI reference: every command, flag by flag.
• MCP / agent integration: wiring canonic into Claude Code, Cursor, Codex, or any MCP client.
• Guides: the seven example projects and the warehouse walkthroughs.
• Reference: error codes and the full canonic.yaml config schema.

License

Business Source License 1.1. Free for non-commercial, personal, evaluation, educational and developmental use. Commercial use needs a separate license. The licensed version converts to Apache 2.0 on July 17, 2030.