canonic

canonic

A camada de contexto que permite que agentes de IA consultem seus dados corretamente.

Aponte o canonic para seu banco de dados e ele constrói o contexto que um agente precisa para responder perguntas sobre dados com precisão: definições, relacionamentos, significado de negócio e as salvaguardas que impedem respostas confiantes, porém erradas. Ele mantém esse contexto atualizado conforme seus dados mudam e nunca toca no seu warehouse além de lê-lo.

📖 Documentação completa: https://docs.getcanonic.app

O problema

Um agente de IA conectado diretamente ao seu warehouse vê tabelas e colunas, não significado. Ele não sabe que revenue vive em orders.amount mas exclui reembolsos, ou que "cliente ativo" tem uma definição específica que seu time financeiro acordou. Então ele adivinha. O acesso ao schema torna um agente fluente. Não o torna correto.

Saída real, capturada de uma execução ao vivo contra o exemplo de ecommerce:

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

Este total inclui dois pedidos reembolsados ($260), um número confiante e bem formatado que está errado por 6,4%.

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

O canonic resolve "receita" para sua definição canônica, compila a salvaguarda no SQL independentemente de alguém tê-la solicitado e retorna o número correto com o raciocínio anexado.

O canonic não é uma ferramenta de BI nem uma interface de chat: é a camada que alimenta as ferramentas que você já possui (um dashboard de BI, um agente, um notebook) com respostas corretas e governadas.

O que o canonic faz

• Definições canônicas, aplicadas. Um agente solicita uma métrica pelo nome. O canonic a resolve para a definição acordada e compila o SQL. Salvaguardas como mandatory_filter, required_dimension, restrict_source e min_trust fazem parte do contrato, então uma ressalva documentada não pode ser silenciosamente ignorada. Contratos e salvaguardas
• A agregação correta, não apenas SQL válido. Medidas semiaditivas (snapshots de MRR), proporções recalculadas na granularidade solicitada, contagens distintas e percentis recebem cada uma sua própria estratégia de compilação, e junções que expandiriam uma tabela de fatos são detectadas. Vários caminhos de junção válidos? Você escolhe um com via, o canonic não adivinha. Compilador
• Respostas carregam sua confiança. Cada resultado envia uma faixa de metadados: a definição resolvida, salvaguardas acionadas, frescor, linhas finais vs. provisórias e um nível de confiança (trusted, provisional, caution) com os motivos por trás dele. Asserções controlam o CI, e resultados confirmadamente errados reduzem a confiança de uma métrica. Confiança e asserções
• Recuse e pergunte. Perguntas ambíguas ou inseguras retornam como um motivo estruturado (ambiguous_join_path, guardrail_block, ...) que o agente pode usar, nunca como um palpite. Códigos de erro
• O contexto se constrói sozinho. A ingestão rascunha semântica do seu schema ao vivo, de um manifesto dbt ou de um modelo Apache Ossie, e aprende com o uso de Looker e Metabase, páginas do Notion e documentação web. Cada mudança é um diff revisável (canonic review, canonic apply), desvios são sinalizados e referências a coisas que desapareceram são propostas para remoção. Ingestão
• Conhecimento de negócio para agentes. Definições, políticas e ressalvas vivem como páginas Markdown. Agentes as pesquisam, leem com definições renderizadas ao vivo e recebem as ressalvas relevantes anexadas a uma resposta. Camada de conhecimento
• Governança integrada. Escopo de locatário, controle de acesso baseado em papéis, mascaramento de colunas e OAuth 2.1 / OIDC para o servidor MCP, incluindo asserção de identidade para agentes agindo em nome de um usuário. Locação e controle de acesso
• Seu warehouse, somente leitura. Postgres, Redshift, MySQL, Snowflake, Databricks, ClickHouse, SQLite e DuckDB (incluindo arquivos CSV e Parquet). Conectores
• Mensurável. Um log de eventos local alimenta canonic audit e canonic status, e um harness de precisão (canonic assert, canonic eval baseline) transforma "confiável" em algo que você pode verificar. Instrumentação

Como funciona

 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

Uma pergunta segue um caminho determinístico: resolver a métrica, compilar SQL contra a definição canônica, aplicar salvaguardas, executar somente leitura, anexar a faixa de metadados. Nenhum LLM está envolvido no momento da resposta.

O que um agente recebe de volta

Saída real (resumida) de canonic --json query --metrics gross_revenue no exemplo saas-analytics:

{
  "result": { "columns": [{ "name": "total_amount", "type": "decimal" }], "rows": [["77071.00"]] },
  "compiled": {
    "sql": "SELECT SUM(\"fct_invoices\".\"amount\") AS \"total_amount\" 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)"]
    }
  }
}

O agente vê qual definição respondeu, quais regras moldaram o SQL e por que o número é apenas provisional, para que possa ressalvar a resposta em vez de apresentá-la como definitiva.

As três camadas

O contexto do canonic vive em três superfícies versionadas: arquivos simples no seu repositório git, revisados como código.

Camada	Arquivo	Responde	Propriedade
Semântica	semantics/**/*.yaml	"Como consulto isso com segurança?"	mantida automaticamente
Conhecimento	knowledge/**/*.md	"O que isso significa para o negócio?"	mantida automaticamente
Contratos	contracts/**/*.yaml	"Qual definição é canônica e o que a resposta deve obedecer?"	propriedade humana

Mudanças em como o SQL executa → semântica. Um humano precisa disso para confiar na resposta → conhecimento. Governa qual definição é autoritativa → contratos. Veja Conceitos: as três camadas.

Início rápido

O canonic precisa de Python 3.13 ou mais recente (uv o baixa para você).

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

O caminho mais rápido usa conectores locais, sem servidor, sem rede. Aponte para um arquivo SQLite .db ou DuckDB .duckdb/CSV/Parquet:

canonic setup

O assistente nomeia seu projeto, conecta uma fonte, opcionalmente configura um LLM, rascunha sua semântica a partir do schema ao vivo e então executa uma consulta real e mostra a resposta com seu frescor e definição. Um banco de dados baseado em servidor ou um provedor de LLM precisa de uma credencial em uma variável de ambiente (ou uma referência file:) antes de você executar canonic setup, porque o canonic nunca armazena segredos em canonic.yaml diretamente.

Você agora tem uma camada de contexto funcional versionada no seu repositório:

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

Instalação isolada e wheels offline: Instalação.

Conecte seu agente (MCP)

O canonic expõe suas ferramentas por meio de um servidor MCP local e sob demanda, verificado com Claude Code, Cursor e Codex:

canonic mcp start

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

Clientes iniciados por GUI (Claude Desktop, Cursor) não carregam seu perfil de shell, então passe credenciais de conexão pelo campo env da configuração, não export.

Veja Conectando seu agente para implantação remota e empresarial (--transport http, tokens bearer por cliente) e a referência de ferramentas. Para ver mascaramento, controle de acesso run_sql e escopo de locatário aplicados a uma identidade real, scripts/local_idp executa o exemplo de marketplace atrás de um Keycloak local: walkthrough.

Projetos de exemplo

examples/ inclui sete projetos prontos para execução, cada um com um guia:

Exemplo	Backend	Mostra
jaffle-shop	DuckDB	manifesto dbt com modelos MetricFlow como evidência
ecommerce	Postgres	o ciclo completo: salvaguardas, finalidade, evidência de Notion e dbt, observabilidade
rental	SQLite	expansão entre fatos e uma salvaguarda de tratamento de NULL, sem necessidade de configuração
saas-analytics	DuckDB	todos os tipos de vínculo de métrica, todos os tipos de salvaguarda, finalidade, asserções
dutch-railway	DuckDB	uma cadeia de dimensão geográfica e métricas de proporção
marketplace	SQLite	escopo de locatário, controle de acesso baseado em papéis e mascaramento de colunas
ossie-retail	SQLite	contexto inicializado a partir de um modelo Apache Ossie

No que você pode confiar

• Somente leitura. O canonic nunca altera seu warehouse.
• Somente proposta, recuse e pergunte. Cada mudança é um diff revisável; respostas ambíguas ou inseguras recebem um motivo estruturado, não um palpite.
• Sem LLM no caminho da resposta. Consultas compilam deterministicamente. Um LLM é opcional e apenas rascunha contexto durante a configuração, com quatro provedores suportados (Anthropic, OpenAI, qualquer endpoint compatível com OpenAI, GitHub Copilot), veja Configurando um LLM.
• Local-first e capaz de operar isolado. Execute inteiramente na sua máquina; nada precisa sair da sua rede.

Para desenvolvedores

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/

• Estrutura. canonic/ é o pacote (compilador, conectores, contratos, ingestão, conhecimento, servidor MCP, confiança, instrumentação), tests/ o espelha, examples/ contém os projetos de exemplo.
• Pontos de extensão. Conectores se registram no ConnectorFactory por capacidade (introspect_schema, run_read_only_sql, extract_definitions, extract_evidence), e credenciais de curta duração se conectam por meio do CredentialProviderRegistry.
• Contrato estável. O contrato de serviço é versionado (a ferramenta MCP contract_info, CONTRACT_CHANGELOG.md), e tests/golden/ trava o SQL compilado e os números executados para os exemplos.
• Contribuindo. Conventional Commits, o fluxo de trabalho da suíte dourada e o processo de mudança de contrato estão em CONTRIBUTING.md.

Documentação

• Início rápido: primeira resposta em minutos.
• Conceitos: as três camadas, o compilador, contratos, locação.
• Referência de CLI: todos os comandos, flag por flag.
• Integração MCP / agente: conectando o canonic ao Claude Code, Cursor, Codex ou qualquer cliente MCP.
• Guias: os sete projetos de exemplo e os walkthroughs de warehouse.
• Referência: códigos de erro e o esquema completo de configuração canonic.yaml.

Licença

Business Source License 1.1. Gratuito para uso não comercial, pessoal, de avaliação, educacional e de desenvolvimento. Uso comercial requer uma licença separada. A versão licenciada converte para Apache 2.0 em 17 de julho de 2030.