Grane

Analítica gobernada y exploración controlada para agentes de IA.

Conecta tu base de datos, define las métricas de negocio que importan y dale a cualquier agente compatible con MCP acceso gobernado a esas definiciones, además de exploración con permisos sobre todo lo demás.

Autohospedado. Determinista. Semántico primero, no solo semántico.

Tu IA puede escribir SQL. Eso no significa que sepa qué significa Ingresos. Grane le dice qué números son autoritativos y qué conclusiones son exploratorias.

Qué hace Grane

Los agentes de IA ya pueden escribir SQL. Pero tu base de datos no conoce las definiciones aprobadas de tu empresa de Ingresos, MRR, Cliente Activo o ARPU, y dejar que un LLM las invente produce números incorrectos con apariencia plausible.

Grane se sitúa entre tu base de datos y tus agentes:

Claude / ChatGPT / Cursor / internal agents
                 |
                 |  MCP
                 v
              GRANE          metrics, dimensions, relationships,
                 |           deterministic compiler, validation,
                 |  SQL      join/grain safety, provenance
                 v
           Your Postgres

• El agente razona. Grane impone la verdad y etiqueta la exploración. Los agentes envían solicitudes semánticas («ingresos por país el mes pasado»); Grane resuelve las definiciones aprobadas, planifica los joins, compila el SQL y lo ejecuta en modo solo lectura. Las columnas permitidas del almacén en bruto se pueden solicitar como raw_dimensions / raw_metrics sin escribir SQL.

• Seguridad de fan-out. Grane conoce la cardinalidad de las relaciones y el grano de las métricas. Las medidas a través de joins one_to_many se pre-agregan de forma determinista; las consultas que multiplicarían filas silenciosamente se rechazan, incluidas las exploratorias.

• El rechazo es una característica de confianza. Si pides una métrica que no está definida, Grane devuelve una respuesta estructurada undefined_metric con sugerencias; nunca inventa lógica de negocio. Las columnas en bruto solo se permiten cuando la exploración está habilitada y la columna no está excluida.

• Tres niveles de confianza. governed (solo definiciones aprobadas), mixed (métricas aprobadas más campos en bruto), exploratory (datos en bruto del almacén). Los agentes no deben presentar la exploración como verdad empresarial aprobada.

• Sin LLM interno. Grane es infraestructura determinista. Sin claves de API, sin plano de datos alojado, nada sale de tu entorno.

Related MCP server: FastAPI Database MCP Server

Conecta ChatGPT, Claude, Gemini o cualquier agente MCP

Grane no necesita tus claves de API de OpenAI, Anthropic o Google. Usas tu propia suscripción o clave de API de agente en el lado del chat; Grane se sitúa en el medio y responde consultas de analítica gobernada a través de MCP.

Your agent (ChatGPT / Claude / Gemini / Cursor)  — your LLM keys
        |
        | MCP
        v
Grane  — no LLM keys; metrics + SQL compiler
        |
        | read-only SQL
        v
Your Postgres  — DATABASE_URL

Configuración en tres pasos:

1. Base de datos — apunta grane.yml a Postgres con un usuario de solo lectura; define métricas en YAML; ejecuta grane validate.

2. Grane MCP — ejecuta grane serve (HTTP) o deja que el agente lance grane serve --stdio (clientes de escritorio locales).

3. Agente — registra Grane con grane mcp connect <client> (Claude, Cursor, Gemini, VS Code, ChatGPT, Windsurf, Claude Code o genérico) y luego haz preguntas en el chat.

Guía completa: docs/connect-an-agent.md

Referencia de herramientas MCP: docs/mcp-setup.md

Conexiones de almacén: docs/warehouses.md

Inicio rápido (con la base de datos de ejemplo)

npm install -g grane-analytics @duckdb/node-api
git clone https://github.com/Nareik33L/grane.git
cd grane

# DuckDB (no Docker): seeded shop data in example/analytics-duckdb
grane -p example/analytics-duckdb validate
grane -p example/analytics-duckdb query revenue -d country --last 30d

# Or Postgres:
docker compose -f example/docker-compose.yml up -d --wait
grane -p example/analytics validate
grane -p example/analytics query revenue --dimension country --last last_month
grane -p example/analytics query revenue --raw-dimension customers.name --last 30d
grane -p example/analytics mcp doctor --offline --skip-mcp
grane -p example/analytics mcp print-config generic
grane -p example/analytics serve
# MCP  http://localhost:8080/mcp

Instalación

npm install -g grane-analytics
# or: npx grane-analytics --help

El comando CLI sigue siendo grane. Requiere Node 20+. Los controladores de almacén que no sean Postgres no se instalan con el CLI; añade solo el que uses (consulta Almacenes más abajo). Eso mantiene una instalación global libre de advertencias de obsolescencia de SDK no relacionadas.

Almacenes

Establece connection.type en grane.yml. Postgres y Redshift usan el controlador pg incluido. Otros motores necesitan un paquete adicional:

Ejemplos de conexión: docs/warehouses.md

Inicio rápido (tu propia base de datos)

grane init                 # scaffolds grane.yml, metrics.yml, dimensions.yml, relationships.yml
export DATABASE_URL=postgres://readonly_user:...@host:5432/db
grane discover             # introspect tables, columns, FKs; infer relationships
# ... define entities, metrics, dimensions, relationships ...
grane validate             # the "type checker for analytics"
grane query revenue -d country --last 30d
grane serve                # or: grane serve --stdio

Usa un usuario de base de datos de solo lectura. Grane también envuelve cada consulta en una transacción READ ONLY con un tiempo de espera de declaración, pero la base de datos sigue siendo el límite de seguridad final.

Definición de métricas

La configuración es código: archivos YAML, revisados en pull requests, versionados en Git, editados por ti o por tu agente de codificación.

# entities: the business objects metrics are counted at (their grain)
entities:
  order:
    table: orders
    primary_key: id

# metrics.yml
metrics:
  revenue:
    description: Net revenue from completed orders
    owner: finance
    entity: order
    type: sum                       # sum | count | count_distinct | avg | min | max | ratio
    sql: ${orders.net_amount}
    time_dimension: ${orders.completed_at}
    unit: GBP
    status: approved                # experimental | approved | deprecated
    synonyms: [sales, net sales]
    filters:
      orders.status: completed

# dimensions.yml
dimensions:
  country:
    entity: customer
    sql: ${customers.country}

# relationships.yml — cardinality powers the join-safety checks
relationships:
  orders_to_customers:
    from: orders.customer_id
    to: customers.id
    type: many_to_one

grane validate comprueba cada referencia contra el esquema en vivo, verifica los tipos y detecta fan-out inseguro antes de que un agente ejecute una consulta.

La superficie MCP

Cuatro herramientas, deliberadamente difíciles de usar mal:

Los agentes envían intención analítica, no SQL:

{
  "metrics": ["revenue"],
  "dimensions": ["country"],
  "raw_dimensions": ["orders.discount_code"],
  "filters": [{ "field": "customer_type", "operator": "=", "value": "business" }],
  "time": { "from": "2026-07-01", "to": "2026-07-31", "grain": "month" },
  "order": [{ "field": "revenue", "direction": "desc" }],
  "limit": 100
}

Cada resultado lleva un nivel de confianza y procedencia:

{
  "trust": "mixed",
  "governed": ["revenue"],
  "ungoverned": ["orders.discount_code"],
  "warning": "orders.discount_code is not defined in the Grane semantic model",
  "provenance": {
    "query_id": "q_1faea438cc34",
    "trust": "mixed",
    "query_model": "v1",
    "metrics": { "revenue": { "definition_version": "a82cf1d3" } },
    "generated_sql": "SELECT ...",
    "executed_at": "2026-08-25T12:00:00Z"
  }
}

Consulta docs/connect-an-agent.md para ChatGPT, Claude, Gemini, Cursor y grane mcp connect. Consulta docs/mcp-setup.md para la referencia de herramientas MCP y los formatos de archivo de configuración.

El contrato de confianza

Grane es semántico primero, no solo semántico. Una empresa no debería tener que modelar todo su almacén antes de que los agentes puedan investigar. Define Ingresos, MRR, Clientes; deja que los agentes exploren discount_code o device_type cuando la política lo permita. Grane sigue compilando el SQL; los agentes nunca obtienen SQL sin restricciones por defecto.

Habilita la exploración en grane.yml:

exploration:
  enabled: true
  schemas:
    - public
  exclude:
    - users.password_hash
    - customers.ssn

Establece enabled: false para rechazar toda columna en bruto. Las columnas excluidas nunca se pueden consultar. Las credenciales de base de datos utilizadas por Grane deben permanecer de solo lectura.

Cuando un campo en bruto es útil repetidamente:

grane usage                          # orders.discount_code used in 47 analyses
grane promote orders.discount_code   # writes a governed dimension to dimensions.yml

Cuando Grane devuelve trust: governed, garantiza que cada métrica y dimensión fue definida explícitamente en el modelo semántico, cada join era conocido y seguro en cuanto a cardinalidad, ninguna lógica de negocio fue inventada por un LLM, el SQL es inspeccionable y se identifican las versiones exactas de las definiciones. Si Grane no puede resolver de forma segura el significado solicitado, se niega en su lugar.

Lo que Grane no es

Sin paneles, sin constructor de gráficos, sin chatbot integrado, sin plano de datos alojado, sin clave de API LLM requerida. Los agentes son dueños de la presentación; Grane es dueño de la verdad analítica, y siempre dice qué números están gobernados y cuáles son exploratorios.

Desarrollo

npm install
npm run test:unit                                        # no database needed
docker compose -f example/docker-compose.yml up -d --wait
npm test                                                 # unit + integration

V0.1 soporta Postgres. La interfaz de conectores se abrirá a otras bases de datos (MySQL, ClickHouse, DuckDB, Snowflake, ...) según aparezca la demanda.

Licencia

Apache-2.0