canonic

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

GitHub
2
Prueba este MCPPatrocinado

Documentación

canonic

CI PyPI License

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 de datos con precisión: definiciones, relaciones, significado de negocio 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

Los nombres de paquetes e imágenes a continuación muestran la forma de cada canal de instalación; los nombres exactos se confirman por versión.

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 comercio electrónico:

$ 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 ya sea que alguien la haya solicitado o 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.

Las tres capas

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

CapaArchivoRespondePropiedad
Semánticasemantics/**/*.yaml"¿Cómo consulto esto de forma segura?"mantenimiento automático
Conocimientoknowledge/**/*.md"¿Qué significa esto para el negocio?"mantenimiento automático
Contratoscontracts/**/*.yaml"¿Qué definición es canónica y qué debe cumplir la respuesta?"propiedad humana

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

Instalación

uv (máquinas de desarrollo, principal):

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

pip (alternativa para entornos sin uv):

pip install canonic

Docker (CI, sin interfaz, aislado):

docker pull ghcr.io/mischuh/canonic:latest

Verifica con canonic --version. Instalación aislada y ruedas sin conexión: consulta Instalación.

Inicio rápido

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

canonic setup

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

El asistente nombra tu proyecto, conecta una fuente, opcionalmente configura 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. Postgres o un proveedor de LLM necesitan una credencial en una variable de entorno antes de ejecutar canonic setup (canonic nunca almacena secretos en canonic.yaml directamente).

¿No tienes una base de datos a mano? examples/ incluye 5 proyectos de ejemplo listos para ejecutar (dbt Jaffle Shop, comercio electrónico, alquiler de vehículos, análisis SaaS, ferrocarril holandés), consulta las guías.

Ahora tienes una capa de contexto funcional comprometida 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

Conecta tu agente (MCP)

canonic expone sus capacidades 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 obtienen tu perfil de shell, así que pasa las credenciales de conexión a través del campo env de la configuración, no export. Cada herramienta que produce respuestas de las 11 registradas (query, run_sql, search_knowledge, ...) devuelve una banda de metadatos: definición resuelta, salvaguardas activadas, frescura, trust_score. Ante la ambigüedad, el agente recibe una razón estructurada, no una suposición.

Consulta Conectando tu agente para implementación remota/empresarial (--transport http, tokens de portador por cliente) y la referencia de herramientas.

En qué puedes confiar

  • Solo lectura. canonic nunca muta tu almacén.
  • Solo propuesta, rechaza y pregunta. 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 funcionar aislado. Ejecuta completamente en tu máquina; nada tiene que salir de tu red.

Documentación

Licencia

Licencia de Código Fuente Comercial 1.1.