canonic

canonic

La capa de contexto que permite a los agentes de IA consultar tus datos correctamente.

Apunta canonic a tu base de datos y construye el contexto que un agente necesita para responder preguntas sobre datos con precisión: definiciones, relaciones, significado empresarial y las salvaguardas que evitan respuestas erróneas con confianza. Mantiene ese contexto actualizado a medida que tus datos cambian, y nunca toca tu almacén más allá de leerlo.

📖 Documentación completa: https://docs.getcanonic.app

El problema

Un agente de IA conectado directamente a tu almacén ve tablas y columnas, no significado. No sabe que revenue vive en orders.amount pero excluye reembolsos, o que "cliente activo" tiene una definición específica acordada por tu equipo de finanzas. Así que adivina. El acceso al esquema hace que un agente sea fluido. No lo hace correcto.

Salida real, capturada de una ejecución en vivo contra el ejemplo de ecommerce:

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

Este total incluye dos pedidos reembolsados ($260), un número confiado y bien formateado que se desvía en un 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" }]
  }
}

canonic resuelve "ingresos" a su definición canónica, compila la salvaguarda en el SQL tanto si alguien la pide como si no, y devuelve el número correcto con el razonamiento adjunto.

canonic no es una herramienta de BI ni una interfaz de chat: es la capa que alimenta las herramientas que ya tienes (un panel de BI, un agente, un cuaderno) con respuestas correctas y gobernadas.

Qué hace canonic

• Definiciones canónicas, aplicadas. Un agente pide una métrica por nombre. canonic la resuelve a la definición acordada y compila el SQL. Salvaguardas como mandatory_filter, required_dimension, restrict_source y min_trust forman parte del contrato, por lo que una advertencia documentada no puede omitirse silenciosamente. Contratos y salvaguardas
• La agregación correcta, no solo SQL válido. Medidas semiaditivas (instantáneas de MRR), ratios recalculados al nivel solicitado, recuentos distintos y percentiles reciben cada uno su propia estrategia de compilación, y las uniones que expandirían una tabla de hechos se detectan. ¿Varias rutas de unión válidas? Tú eliges una con via, canonic no adivina. Compilador
• Las respuestas llevan su confianza. Cada resultado incluye una banda de metadatos: la definición resuelta, salvaguardas activadas, frescura, filas finales vs. provisionales, y un nivel de confianza (trusted, provisional, caution) con las razones detrás. Las aserciones controlan la CI, y los resultados confirmados como incorrectos reducen la confianza de una métrica. Confianza y aserciones
• Rechazar y preguntar. Las preguntas ambiguas o inseguras devuelven una razón estructurada (ambiguous_join_path, guardrail_block, ...) sobre la que el agente puede actuar, nunca una suposición. Códigos de error
• El contexto se construye solo. La ingesta redacta semántica desde tu esquema en vivo, un manifiesto de dbt o un modelo de Apache Ossie, y aprende del uso de Looker y Metabase, páginas de Notion y documentación web. Cada cambio es un diff revisable (canonic review, canonic apply), se señala la deriva, y se propone eliminar referencias a cosas que desaparecieron. Ingesta
• Conocimiento empresarial para agentes. Definiciones, políticas y advertencias viven como páginas Markdown. Los agentes las buscan, las leen con definiciones renderizadas en vivo, y reciben las advertencias relevantes adjuntas a una respuesta. Capa de conocimiento
• Gobernanza integrada. Alcance por inquilino, control de acceso basado en roles, enmascaramiento de columnas, y OAuth 2.1 / OIDC para el servidor MCP, incluida la aserción de identidad para agentes que actúan en nombre de un usuario. Inquilinato y control de acceso
• Tu almacén, solo lectura. Postgres, Redshift, MySQL, Snowflake, Databricks, ClickHouse, SQLite y DuckDB (incluidos archivos CSV y Parquet). Conectores
• Medible. Un registro de eventos local alimenta canonic audit y canonic status, y un banco de pruebas de precisión (canonic assert, canonic eval baseline) convierte "confiable" en algo que puedes verificar. Instrumentación

Cómo 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

Una pregunta sigue un camino determinista: resolver la métrica, compilar SQL contra la definición canónica, aplicar salvaguardas, ejecutarlo en solo lectura, adjuntar la banda de metadatos. No interviene ningún LLM en el momento de la respuesta.

Qué recibe un agente

Salida real (resumida) de canonic --json query --metrics gross_revenue en el ejemplo 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)"]
    }
  }
}

El agente ve qué definición respondió, qué reglas dieron forma al SQL, y por qué el número es solo provisional, para poder advertir sobre la respuesta en lugar de presentarla como definitiva.

Las tres capas

El contexto de canonic vive en tres superficies versionadas: archivos simples en tu repositorio git, revisados como código.

Capa	Archivo	Responde	Propiedad
Semántica	semantics/**/*.yaml	"¿Cómo consulto esto de forma segura?"	mantenimiento automático
Conocimiento	knowledge/**/*.md	"¿Qué significa esto para el negocio?"	mantenimiento automático
Contratos	contracts/**/*.yaml	"¿Qué definición es canónica y qué debe cumplir la respuesta?"	propiedad humana

Cambios en cómo se ejecuta el SQL → semántica. Un humano lo necesita para confiar en la respuesta → conocimiento. Gobierna qué definición es autoritativa → contratos. Consulta Conceptos: las tres capas.

Inicio rápido

canonic requiere Python 3.13 o superior (uv lo descarga por ti).

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

La ruta más rápida usa conectores locales, sin servidor, sin red. Apunta a un archivo SQLite .db o DuckDB .duckdb/CSV/Parquet:

canonic setup

El asistente nombra tu proyecto, conecta una fuente, configura opcionalmente un LLM, redacta tu semántica desde el esquema en vivo, luego ejecuta una consulta real y muestra la respuesta con su frescura y definición. Una base de datos basada en servidor o un proveedor de LLM necesita una credencial en una variable de entorno (o una referencia file:) antes de ejecutar canonic setup, porque canonic nunca almacena secretos en canonic.yaml directamente.

Ahora tienes una capa de contexto funcional versionada en tu repositorio:

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

Instalación aislada de red y ruedas sin conexión: Instalación.

Conecta tu agente (MCP)

canonic expone sus herramientas a través de un servidor MCP local y bajo demanda, verificado con Claude Code, Cursor y Codex:

canonic mcp start

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

Los clientes lanzados por GUI (Claude Desktop, Cursor) no cargan tu perfil de shell, así que pasa las credenciales de conexión a través del campo env de la configuración, no export.

Consulta Conectando tu agente para despliegue remoto y empresarial (--transport http, tokens portadores por cliente) y la referencia de herramientas. Para ver el enmascaramiento, el control run_sql y el alcance por inquilino aplicados a una identidad real, scripts/local_idp ejecuta el ejemplo de marketplace detrás de un Keycloak local: tutorial.

Proyectos de ejemplo

examples/ incluye siete proyectos listos para ejecutar, cada uno con una guía:

Ejemplo	Backend	Muestra
jaffle-shop	DuckDB	manifiesto dbt con modelos MetricFlow como evidencia
ecommerce	Postgres	el ciclo completo: salvaguardas, finalidad, evidencia de Notion y dbt, observabilidad
rental	SQLite	expansión entre hechos y una salvaguarda de manejo de NULL, sin configuración necesaria
saas-analytics	DuckDB	cada tipo de enlace de métrica, todos los tipos de salvaguarda, finalidad, aserciones
dutch-railway	DuckDB	una cadena de dimensiones geográficas y métricas de ratio
marketplace	SQLite	alcance por inquilino, control de acceso basado en roles y enmascaramiento de columnas
ossie-retail	SQLite	contexto inicializado desde un modelo Apache Ossie

En qué puedes confiar

• Solo lectura. canonic nunca muta tu almacén.
• Solo propuesta, rechazar y preguntar. Cada cambio es un diff revisable; las respuestas ambiguas o inseguras reciben una razón estructurada, no una suposición.
• Sin LLM en la ruta de respuesta. Las consultas se compilan de forma determinista. Un LLM es opcional y solo redacta contexto durante la configuración, con cuatro proveedores compatibles (Anthropic, OpenAI, cualquier endpoint compatible con OpenAI, GitHub Copilot), consulta Configurando un LLM.
• Local primero y capaz de operar aislado de red. Ejecuta todo en tu máquina; nada tiene que salir de tu red.

Para desarrolladores

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/

• Estructura. canonic/ es el paquete (compilador, conectores, contratos, ingesta, conocimiento, servidor MCP, confianza, instrumentación), tests/ lo refleja, examples/ contiene los proyectos de ejemplo.
• Puntos de extensión. Los conectores se registran con el ConnectorFactory por capacidad (introspect_schema, run_read_only_sql, extract_definitions, extract_evidence), y las credenciales de corta duración se conectan a través del CredentialProviderRegistry.
• Contrato estable. El contrato de servicio está versionado (la herramienta MCP contract_info, CONTRACT_CHANGELOG.md), y tests/golden/ fija el SQL compilado y los números ejecutados para los ejemplos.
• Contribuciones. Conventional Commits, el flujo de trabajo de la suite dorada y el proceso de cambio de contrato están en CONTRIBUTING.md.

Documentación

• Inicio rápido: primera respuesta en minutos.
• Conceptos: las tres capas, el compilador, los contratos, el inquilinato.
• Referencia de CLI: cada comando, flag por flag.
• Integración MCP / agente: conexión de canonic a Claude Code, Cursor, Codex o cualquier cliente MCP.
• Guías: los siete proyectos de ejemplo y los tutoriales de almacenes.
• Referencia: códigos de error y el esquema completo de configuración canonic.yaml.

Licencia

Business Source License 1.1. Gratuita para uso no comercial, personal, de evaluación, educativo y de desarrollo. El uso comercial requiere una licencia separada. La versión licenciada se convierte a Apache 2.0 el 17 de julio de 2030.