canonic

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

GitHub
2
Experimente este MCPPatrocinado

Documentação

canonic

CI PyPI License

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 proteções 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

Os nomes de pacotes e imagens abaixo mostram a forma de cada canal de instalação; os nomes exatos são confirmados por versão.

O problema

Um agente de IA conectado diretamente ao seu warehouse enxerga 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 e-commerce:

$ 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 proteção no SQL independentemente de alguém ter pedido ou não, 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á tem (um dashboard de BI, um agente, um notebook) com respostas corretas e governadas.

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.

CamadaArquivoRespondePropriedade
Semânticasemantics/**/*.yaml"Como consulto isso com segurança?"mantida automaticamente
Conhecimentoknowledge/**/*.md"O que isso significa para o negócio?"mantida automaticamente
Contratoscontracts/**/*.yaml"Qual definição é canônica, e o que a resposta deve obedecer?"de 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.

Instalação

uv (máquinas de desenvolvimento, principal):

uvx canonic --version        # ephemeral, no install step
uv tool install canonic      # persistent, global command

pip (alternativa para ambientes sem uv):

pip install canonic

Docker (CI, headless, air-gapped):

docker pull ghcr.io/mischuh/canonic:latest

Verifique com canonic --version. Instalação air-gapped e wheels offline: veja Instalação.

Início rápido

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

canonic setup

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

O assistente nomeia seu projeto, conecta uma fonte, opcionalmente configura um LLM, rascunha sua semântica a partir do schema ao vivo, então executa uma consulta real e mostra a resposta com sua atualidade e definição. Postgres ou um provedor de LLM precisam de uma credencial em uma variável de ambiente antes de você executar canonic setup (o canonic nunca armazena segredos em canonic.yaml diretamente).

Não tem um banco de dados à mão? examples/ inclui 5 projetos de exemplo prontos para executar (dbt Jaffle Shop, e-commerce, aluguel de veículos, análise SaaS, ferrovia holandesa), veja os guias.

Agora você 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

Conecte seu agente (MCP)

O canonic expõe suas capacidades 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 as credenciais de conexão pelo campo env da configuração, não por export. Cada ferramenta que produz respostas entre as 11 registradas (query, run_sql, search_knowledge, ...) retorna uma faixa de metadados: definição resolvida, proteções acionadas, atualidade, trust_score. Em caso de ambiguidade, o agente recebe um motivo estruturado, não um palpite.

Veja Conectando seu agente para implantação remota/empresarial (--transport http, tokens bearer por cliente) e a referência de ferramentas.

No que você pode confiar

  • Somente leitura. O canonic nunca modifica seu warehouse.
  • Somente proposta, recusa e pergunta. 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 compatível com air-gapped. Execute inteiramente na sua máquina; nada precisa sair da sua rede.

Documentação

Licença

Business Source License 1.1.