canonic

canonic

AI エージェントがデータを正しく照会できるようにするコンテキストレイヤーです。

canonic をデータベースに接続すると、エージェントがデータに関する質問へ正確に答えるために必要なコンテキスト（定義、関係性、ビジネス上の意味、そして自信満々に誤った回答をするのを防ぐガードレール）を構築します。データの変更に合わせてコンテキストを最新の状態に保ち、読み取り以外の目的でデータウェアハウスにアクセスすることはありません。

📖 ドキュメント全文：https://docs.getcanonic.app

問題点

データウェアハウスに直接接続された AI エージェントに見えるのは、テーブルと列であり、意味ではありません。revenue が orders.amount にあるものの返金を除外していることや、「アクティブな顧客」に財務チームが合意した特定の定義があることを知りません。そのため、推測してしまいます。スキーマへのアクセスでエージェントは流暢になりますが、正確になるわけではありません。

EC サンプルを使った実行で記録された実際の出力：

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

この合計には返金済みの注文が 2 件（260 ドル）含まれており、自信に満ちた整った書式の数値ですが、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 は「revenue」を正式な定義に対応付け、誰も要求していなくてもガードレールを SQL に組み込み、根拠とともに正しい数値を返します。

canonic は BI ツールでもチャットインターフェースでもありません。BI ダッシュボード、エージェント、ノートブックなど、すでにお使いのツールに、ガバナンスの効いた正確な回答を提供するレイヤーです。

canonic の機能

• 正規の定義を適用します。 エージェントが名前を指定して指標を要求すると、canonic は合意済みの唯一の定義に解決し、SQL をコンパイルします。mandatory_filter、required_dimension、restrict_source、min_trust などのガードレールは契約に含まれるため、文書化された注意事項が黙って無視されることはありません。契約とガードレール
• 有効な SQL だけでなく、適切な集計を実現します。 準加法的な指標（MRR のスナップショット）、要求された粒度で再計算される比率、個別カウント、パーセンタイル、累積合計には、それぞれ専用のコンパイル戦略が適用され、ファクトテーブルの行数を膨らませる結合も検出されます。有効な結合経路が複数ある場合は、via で選択します。canonic が推測することはありません。コンパイラー
• 回答には信頼度が付与されます。 すべての結果には、解決された定義、適用されたガードレール、鮮度、確定行と暫定行、そしてその根拠を示す信頼度ティア（trusted、provisional、caution）を含むメタデータ帯が付属します。アサーションで CI を制御でき、誤りが確認された結果は指標の信頼度を下げます。信頼度とアサーション
• 変更の理由を把握できます。 canonic decompose と MCP ツール decompose_change は、全体およびメンバー別に、2 つの期間における指標の変化要因を特定します。この手法は指標の種類に応じており、比率はメンバーごとの変化を並べるのではなく、合計が一致する構成効果と率効果に分解されます。ツールリファレンス
• 拒否して確認を求めます。 曖昧な質問や安全でない質問には、エージェントが対処できる構造化された理由（ambiguous_join_path、guardrail_block など）を返し、推測で回答することはありません。エラーコード
• コンテキストが自動で構築されます。 ライブスキーマ、dbt マニフェスト、または Apache Ossie モデルから意味情報のドラフトを取り込み、Looker と Metabase の利用状況、Notion ページ、ウェブドキュメントから学習します。すべての変更はレビュー可能な差分（canonic review、canonic apply）として提示され、ドリフトはフラグ付けされ、存在しなくなった項目への参照は削除候補として提案されます。取り込み
• エージェント向けのビジネス知識。 定義、ポリシー、注意事項は Markdown ページに保存されます。エージェントはそれらを検索し、定義がライブレンダリングされた状態で読み取り、回答に関連する注意事項を添付して受け取れます。ナレッジレイヤー
• ガバナンスを標準搭載。 MCP サーバーでは、テナントのスコープ設定、ロールベースのアクセス制御、列のマスキング、OAuth 2.1 / OIDC に対応し、ユーザーに代わって動作するエージェントの本人性アサーションも含まれます。テナント管理とアクセス制御
• データウェアハウスは読み取り専用で接続します。 Postgres、Redshift、MySQL、Snowflake、Databricks、ClickHouse、SQLite、DuckDB に対応しています（CSV ファイルと Parquet ファイルを含む）。コネクター
• 測定可能です。 ローカルイベントログから canonic audit と canonic status を実行でき、精度ハーネス（canonic assert、canonic eval baseline）によって、「信頼できる」ことを検証可能にします。計測

仕組み

 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

質問は、指標の解決、正規の定義に基づく SQL のコンパイル、ガードレールの適用、読み取り専用での実行、メタデータ帯の付与という、決定論的な経路をたどります。回答時に LLM は関与しません。

エージェントが受け取る内容

saas-analytics のサンプルで canonic --json query --metrics gross_revenue を実行した場合の実際の出力（一部抜粋）：

{
  "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)"]
    }
  }
}

エージェントには、どの定義が回答に使われ、どのルールが SQL を形作ったか、そして数値が provisional にとどまる理由が示されるため、確定事項として提示するのではなく、注意事項を添えて回答できます。

3 つのレイヤー

canonic のコンテキストは、Git リポジトリ内のプレーンファイルという 3 つのコミット対象の領域に保存され、コードと同じようにレビューされます。

レイヤー	ファイル	答える質問	管理者
セマンティクス	semantics/**/*.yaml	「安全にクエリするにはどうすればよいですか？」	自動管理
ナレッジ	knowledge/**/*.md	「これはビジネスにとってどのような意味がありますか？」	自動管理
コントラクト	contracts/**/*.yaml	「どの定義が正規で、回答は何に従う必要がありますか？」	人間が管理

SQL の 実行方法 を変更するものはセマンティクスです。回答を 信頼する ために人間が必要とするものはナレッジです。どの定義を正とするかを規定するものはコントラクトです。概念：3 つのレイヤーを参照してください。

クイックスタート

canonic には Python 3.13 以降が必要です（uv が自動で取得します）。

uvx canonic --version        # try it without installing
uv tool install canonic      # persistent, global command
pip install canonic          # without uv
docker pull ghcr.io/mischuh/canonic:latest   # CI, headless, air-gapped

最も手早く始める方法は、サーバーもネットワークも不要なローカルコネクターを使うことです。SQLite の .db または DuckDB の .duckdb／CSV／Parquet ファイルを指定してください。

canonic setup

ウィザードでは、プロジェクト名を付け、データソースに接続し、必要に応じて LLM を設定します。その後、実際のスキーマからセマンティクスを作成し、実際のクエリを実行して、鮮度と定義を添えて回答を表示します。サーバーベースのデータベースや LLM プロバイダーを使う場合は、canonic setup の実行前に、環境変数または file: 参照で認証情報を設定する必要があります。canonic はシークレットを canonic.yaml に直接保存しないためです。

これで、リポジトリにコミットできるコンテキストレイヤーが整いました。

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

エアギャップ環境へのインストールとオフライン用ホイールについては、インストールを参照してください。

エージェントを接続する（MCP）

canonic は、オンデマンドのローカル MCP サーバーを介してツールを公開します。Claude Code、Cursor、Codex で検証済みです。

canonic mcp start

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

GUI から起動するクライアント（Claude Desktop、Cursor）はシェルのプロファイルを読み込まないため、接続に必要な認証情報は export ではなく、設定の env フィールドに渡してください。

リモート環境およびエンタープライズ環境へのデプロイ（--transport http、クライアントごとのベアラートークン）については、エージェントの接続とツールリファレンスを参照してください。実際の ID に対してマスキング、run_sql のゲーティング、テナントスコープがどのように適用されるかを確認するには、scripts/local_idpを使って、ローカルの Keycloak 上でマーケットプレイスの例を実行できます。手順を参照してください。

サンプルプロジェクト

examples/ には、すぐに実行できる7つのプロジェクトが含まれており、それぞれにガイドがあります。

サンプル	バックエンド	内容
jaffle-shop	DuckDB	MetricFlow モデルを根拠とする dbt マニフェスト
ecommerce	Postgres	ガードレール、確定性、Notion と dbt の根拠、可観測性を含む一連の流れ
rental	SQLite	ファクト間のファンアウトと NULL 処理のガードレール。セットアップは不要です
saas-analytics	DuckDB	すべてのメトリクスバインディング種別、すべてのガードレール種別、確定性、アサーション
dutch-railway	DuckDB	地理ディメンションの連鎖と比率メトリクス
marketplace	SQLite	テナントスコープ、ロールベースのアクセス制御、列のマスキング
ossie-retail	SQLite	Apache Ossie モデルから初期化されたコンテキスト
coffeehouse	DuckDB	dbt MetricFlow と canonic が同じ質問に回答します。個別カウント、平均、ガードレール

信頼できること

• 読み取り専用です。 canonic がデータウェアハウスを変更することはありません。
• 変更は提案のみ。拒否して確認を求めます。 すべての変更はレビュー可能な差分として提示されます。曖昧または安全でない回答には、推測ではなく、構造化された理由が返されます。
• 回答処理に LLM は使用しません。 クエリは決定論的にコンパイルされます。LLM は任意で、セットアップ中のコンテキストの 草案作成 のみに使用されます。対応プロバイダーは4種類です（Anthropic、OpenAI、OpenAI 互換の任意のエンドポイント、GitHub Copilot）。詳しくはLLM の設定をご覧ください。
• ローカル優先で、エアギャップ環境にも対応します。 すべてをお使いのマシン上で実行でき、ネットワーク外にデータを送る必要はありません。

開発者向け

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

• 構成。 canonic/ はパッケージ（コンパイラー、コネクター、コントラクト、取り込み、ナレッジ、MCP サーバー、信頼性、計装）です。tests/ はその構成を反映し、examples/ にはサンプルプロジェクトが含まれています。
• 拡張ポイント。 コネクターは機能（introspect_schema、run_read_only_sql、extract_definitions、extract_evidence）に応じて ConnectorFactory に登録します。短期間有効な認証情報は CredentialProviderRegistry を通じて組み込めます。
• 安定したコントラクト。 サービングコントラクトはバージョン管理されています（contract_info MCP ツール、CONTRACT_CHANGELOG.md）。また、tests/golden/ ではサンプルのコンパイル済み SQL と実行結果の数値を固定しています。
• コントリビューション。 Conventional Commits、ゴールデンスイートのワークフロー、コントラクト変更の手順については、CONTRIBUTING.mdをご覧ください。

ドキュメント

• クイックスタート：数分で最初の回答を得られます。
• 概念：3つのレイヤー、コンパイラー、コントラクト、テナンシーについて説明します。
• CLI リファレンス：すべてのコマンドとフラグを解説します。
• MCP／エージェント統合：canonic を Claude Code、Cursor、Codex、または任意の MCP クライアントに接続する方法を説明します。
• ガイド：7つのサンプルプロジェクトとデータウェアハウスの手順を紹介します。
• リファレンス：エラーコードと canonic.yaml の設定スキーマ全体を掲載しています。

ライセンス

Business Source License 1.1。非商用、個人利用、評価、教育、開発目的であれば無料で利用できます。商用利用には別途ライセンスが必要です。ライセンス対象のバージョンは、2030年7月17日に Apache 2.0 に切り替わります。