Grane

Управляемая аналитика и контролируемое исследование для ИИ-агентов.

Подключите свою базу данных, определите важные бизнес-метрики и предоставьте любому MCP-совместимому агенту управляемый доступ к этим определениям — плюс разрешенное исследование всего остального.

Self-hosted. Детерминированно. Семантически-ориентированный, но не только семантический.

Ваш ИИ умеет писать SQL. Это не значит, что он знает, что означает «Выручка». Grane сообщает ему, какие числа являются авторитетными, а какие выводы — исследовательскими.

Что делает Grane

ИИ-агенты уже умеют писать SQL. Но ваша база данных не знает утвержденных определений компании для «Выручки», MRR, «Активных клиентов» или ARPU — и позволять LLM выдумывать их приводит к правдоподобным, но неверным числам.

Grane находится между вашей базой данных и вашими агентами:

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

• Агент рассуждает. Grane обеспечивает истину — и маркирует исследование. Агенты отправляют семантические запросы («выручка по странам за прошлый месяц»); Grane разрешает утвержденные определения, планирует соединения, компилирует SQL и выполняет его только на чтение. Разрешенные необработанные колонки хранилища могут быть запрошены как raw_dimensions / raw_metrics без написания SQL.

• Безопасность от фан-аута. Grane знает кардинальность связей и зерно метрик. Меры через соединения one_to_many предварительно агрегируются детерминированно; запросы, которые молча умножают строки, отклоняются — включая исследовательские.

• Отказ — это функция доверия. Запросите метрику, которая не определена, и Grane вернет структурированный ответ undefined_metric с предложениями — он никогда не выдумывает бизнес-логику. Необработанные колонки разрешены только тогда, когда исследование включено и колонка не исключена.

• Три уровня доверия. governed (только утвержденные определения), mixed (утвержденные метрики плюс необработанные поля), exploratory (необработанные данные хранилища). Агенты не должны представлять исследование как утвержденную бизнес-истину.

• Никакого LLM внутри. Grane — это детерминированная инфраструктура. Никаких API-ключей, никакой размещенной плоскости данных, ничего не покидает вашу среду.

Related MCP server: FastAPI Database MCP Server

Подключите ChatGPT, Claude, Gemini или любого MCP-агента

Grane не требует ваших API-ключей OpenAI, Anthropic или Google. Вы используете свою собственную подписку на агента или API-ключ на стороне чата; Grane находится посередине и отвечает на управляемые аналитические запросы через 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

Настройка в три шага:

1. База данных — укажите grane.yml на Postgres с пользователем только для чтения; определите метрики в YAML; запустите grane validate.

2. Grane MCP — запустите grane serve (HTTP) или позвольте агенту запустить grane serve --stdio (локальные десктопные клиенты).

3. Агент — зарегистрируйте Grane с помощью grane mcp connect <client> (Claude, Cursor, Gemini, VS Code, ChatGPT, Windsurf, Claude Code или универсальный), затем задавайте вопросы в чате.

Полное руководство: docs/connect-an-agent.md

Справочник по MCP-инструментам: docs/mcp-setup.md

Подключения к хранилищам: docs/warehouses.md

Быстрый старт (с примером базы данных)

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

Установка

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

Команда CLI по-прежнему grane. Требуется Node 20+. Драйверы хранилищ, отличные от Postgres, не устанавливаются с CLI — добавьте только тот, который вы используете (см. «Хранилища» ниже). Это позволяет глобальной установке быть свободной от ненужных предупреждений об устаревании SDK.

Хранилища

Установите connection.type в grane.yml. Postgres и Redshift используют встроенный драйвер pg. Для других движков нужен один дополнительный пакет:

Примеры подключения: docs/warehouses.md

Быстрый старт (ваша собственная база данных)

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

Используйте пользователя базы данных только для чтения. Grane также оборачивает каждый запрос в транзакцию READ ONLY с таймаутом выполнения, но база данных остается окончательной границей безопасности.

Определение метрик

Конфигурация — это код: YAML-файлы, проверяемые в пул-реквестах, версионируемые в Git, редактируемые вами или вашим кодирующим агентом.

# 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 проверяет каждую ссылку на соответствие живой схеме, проверяет типы и обнаруживает небезопасный фан-аут до того, как агент выполнит запрос.

Поверхность MCP

Четыре инструмента, которые трудно использовать неправильно:

Агенты отправляют аналитическое намерение, а не 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
}

Каждый результат несет уровень доверия и происхождение:

{
  "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"
  }
}

См. docs/connect-an-agent.md для ChatGPT, Claude, Gemini, Cursor и grane mcp connect. См. docs/mcp-setup.md для справки по MCP-инструментам и форматам конфигурационных файлов.

Контракт доверия

Grane — семантически-ориентированный, но не только семантический. Компания не должна моделировать все свое хранилище, прежде чем агенты смогут проводить исследования. Определите «Выручку», MRR, «Клиентов»; позвольте агентам исследовать discount_code или device_type, когда политика разрешает. Grane по-прежнему компилирует SQL — агенты никогда не получают неограниченный SQL по умолчанию.

Включите исследование в grane.yml:

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

Установите enabled: false, чтобы отклонять каждую необработанную колонку. Исключенные колонки никогда не запрашиваются. Учетные данные базы данных, используемые Grane, должны оставаться только для чтения.

Когда необработанное поле многократно полезно:

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

Когда Grane возвращает trust: governed, он гарантирует, что каждая метрика и измерение были явно определены в семантической модели, каждое соединение было известно и безопасно по кардинальности, никакая бизнес-логика не была выдумана LLM, SQL проверяем, и точные версии определений идентифицированы. Если Grane не может безопасно разрешить запрошенное значение, он отказывается вместо этого.

Чем Grane не является

Никаких дашбордов, конструктора графиков, встроенного чат-бота, размещенной плоскости данных, обязательного API-ключа LLM. Агенты владеют представлением; Grane владеет аналитической истиной — и всегда говорит, какие числа управляемые, а какие исследовательские.

Разработка

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 поддерживает Postgres. Интерфейс коннектора откроется для других баз данных (MySQL, ClickHouse, DuckDB, Snowflake, ...) по мере появления спроса.

Лицензия

Apache-2.0