autobi-agent 0.3.1

Agent: text / field layout -> dashboard in selected BI on top of DWH DM layer

Auto_BI

Агент «запрос → дашборд» поверх DM-слоя DWH. Принимает запрос текстом, drag&drop-раскладкой полей витрин или авто-обзором витрины (детерминированный курируемый дашборд без LLM), уточняет детали только при реальных расхождениях с данными, честно предупреждает о не предусмотренных витриной паттернах (engine-aware Feasibility Advisor — вплоть до «это запрос на новую витрину»), строит дашборд в выбранной BI и возвращает ссылку.

Скоуп v1 (RU-рынок): ClickHouse (DM) + Apache Superset (BI). v2: Greengage/Greenplum + Yandex DataLens (self-hosted OSS-стенд). Универсальность — в швах (IR, адаптеры), не в имплементации. LLM: прямой Anthropic Messages API (по умолчанию — нужен только ANTHROPIC_API_KEY); локальный сервис GraceKelly — документированная опция (AUTO_BI_LLM_PROVIDER=gracekelly, см. USER_GUIDE §6).

Демо

Живое демо: https://juliome20-auto-bi-demo.hf.space — публичная песочница (Hugging Face Space, один контейнер ClickHouse + Superset + Auto_BI): выберите витрину, соберите авто-обзор и откройте готовый дашборд в Superset без логина. Работает детерминированный путь без LLM; полный текстовый цикл — на видео ниже. Данные синтетические, всё пересоздаётся при рестарте (холодный старт ~3 мин).

Живой цикл (сжаты только паузы ожидания LLM): запрос «средний чек по месяцам, Парето по магазинам, динамика количества» → агент уточняет неоднозначное «количество» (orders vs items) → превью спецификации с вердиктом Feasibility Advisor (CRITICAL: запрос сканирует 100% витрины в 20 млн строк — предложение сузить период) → сборка → готовый дашборд Superset на реальных данных ClickHouse: средний чек как производная метрика sum(revenue)/sum(orders) по месяцам, Парето — накопленная доля выручки по магазинам. Видео в лучшем качестве — docs/screenshots/demo.mp4.

Веб-UI: запрос → спецификация + Feasibility Advisor	Собранный дашборд (Superset)

Слева — естественно-языковой запрос, уточнения агента, превью спецификации (IR) и вердикты Feasibility Advisor (CRITICAL → заявка владельцу DM, WARN → правка спеки). Справа — собранный из той же спецификации дашборд Superset на реальных данных ClickHouse.

Статус

Phase 0–4 + бэклог адекватности дашбордов (B1–B4) закрыты. Работает end-to-end: текст/поля → spec → валидация → сборка дашборда. v1-стек (ClickHouse + Superset) и v2-стек (Greenplum/Greengage интроспекция + advisor; self-hosted DataLens-адаптер) live-проверены; web UI с двумя режимами ввода, итерациями, Feasibility Advisor, заявками владельцу DM и панелью наблюдаемости. Остаток — owner/стенд-зависимый (адаптеры Visiology/Luxms). История фаз и план — в docs/PLAN.md.

Чем отличается

Зрелого бесплатного инструмента «диалог → целый дашборд поверх DWH с выбором BI» нет ни в России, ни глобально (обзор с проверкой первоисточников — docs/MARKET.md). Три отличия от существующих NL→chart-решений:

• Grounding по конкретному DM, а не свободный чат — уточнения только при реальных расхождениях запроса с витриной; однозначный запрос → ноль вопросов.
• Дашборд целиком из BI-агностичного IR (layout, фильтры, N чартов) — а не один чарт по готовому датасету (отличие от DataLens «Нейроаналитик»). Один spec → Superset и DataLens.
• Engine-aware Feasibility Advisor — детерминированно сверяет запрос с физикой витрины (ключи сортировки/партиции, EXPLAIN) и прямо говорит «такой дашборд витриной не предусмотрен, вот evidence и заявка владельцу DM». Этого нет ни у одного конкурента.

flowchart LR
    Q["Запрос<br/>текст · поля"] --> G["GROUNDING<br/>по semantic model"]
    G --> C{"уточнения?"}
    C -->|да| G
    C -->|нет| S["DashboardSpec<br/>IR · валидируется по модели"]
    S --> SQL["SQL-guard<br/>sqlglot · EXPLAIN · LIMIT"]
    S -.->|вердикты| ADV["Feasibility Advisor<br/>engine-aware"]
    SQL --> A1["Superset adapter"]
    SQL --> A2["DataLens adapter"]
    A1 --> D[("Дашборд")]
    A2 --> D

Как пользоваться

Установка, команды CLI, web UI, конфигурация — docs/USER_GUIDE.md. Подключение новой витрины DWH за ≤ 1 ч — docs/ONBOARDING_DWH.md.

pip install autobi-agent                          # или pip install -e . из корня репозитория
auto_bi introspect --output semantic/model.yaml   # DWH -> черновик модели
auto_bi build "Выручка по магазинам за июнь 2026"  # текст -> дашборд
auto_bi build --auto dm.sales_daily                # витрина -> обзорный дашборд (без LLM)
auto_bi serve                                     # web UI на http://127.0.0.1:8200

Хотите увидеть весь конвейер за минуту, без стенда и без LLM — на синтетической витрине из репозитория:

uv run python scripts/demo_golden_path.py

Скрипт прогоняет детерминированную часть end-to-end: семантическая модель → курируемый обзорный дашборд → валидированный SQL по каждому чарту → вердикт Feasibility Advisor (включая dm_change_request — «витрина не предусматривает такой разрез, вот evidence»). Живым остаётся только финальный BUILD (HTTP к Superset/DataLens + EXPLAIN на стенде).

Документация

Файл	Что внутри
docs/USER_GUIDE.md	Руководство пользователя: установка, команды CLI, web UI, два режима ввода, advisor, наблюдаемость, конфигурация
docs/ONBOARDING_DWH.md	Подключение нового DWH за ≤ 1 ч: доступы, .env, интроспекция, обогащение, проверка (ClickHouse + Greenplum)
docs/ARCHITECTURE.md	Архитектура: скоуп, IR-first, семантическая модель с физическим слоем, агент, Feasibility Advisor, адаптеры, LLM-слой, решения D1–D10, риски
docs/DEPLOYMENT.md	Деплой в проде: workers=1, reverse-proxy/TLS, готовность, docker-compose, бэкап SQLite, ротация логов, чеклист секретов
CHANGELOG.md	История версий по Keep a Changelog — что вошло в каждый релиз
docs/PLAN.md	План: Phase 0–4, задачи, exit criteria; полезный продукт после Phase 2 (~2.5–3 мес FTE)
docs/MARKET.md	Рынок на 06.2026: RU (СУБД, BI, AI-фичи конкурентов, статус Superset) + глобальный контекст

Суть архитектуры в одном абзаце

LLM никогда не генерирует нативные форматы BI. Пайплайн: запрос (текст или раскладка полей) → grounding по семантической модели (model.yaml, включая физический слой движка) → уточнения при необходимости → DashboardSpec (BI-агностичный JSON, жёстко валидируется по модели) → SQL с проверкой (sqlglot/EXPLAIN/LIMIT) → детерминированный компилятор-адаптер строит дашборд через API выбранной BI. Параллельно детерминированный Feasibility Checker сверяет запрос с физикой витрины (ключи сортировки/партиции, размеры, EXPLAIN) — advisor прямо говорит, когда дашборд витриной не предусмотрен, и умеет оформить заявку владельцу DM. Один spec — N платформ.

Разработка

uv sync                                              # окружение из uv.lock (вкл. dev-инструменты)
uv run ruff check .                                  # линтер
uv run black --check auto_bi tests                   # формат
uv run --with duckdb pytest -q                       # тесты (integration-сьюты со стендом — deselected)
uv run --with duckdb --with pytest-cov pytest --cov=auto_bi --cov-report=term-missing   # покрытие
uv run python scripts/verify_live_clickhouse.py      # числа CH-путей на ЖИВОМ стенде (ratio/grain/yoy/compare-KPI/авто-обзор)

--with duckdb — эфемерная test-dep (проверяет numeric-корректность transform-SQL под postgres-семантикой окон; без неё те тесты importorskip). Те же шаги гоняет CI на push/PR (.github/workflows/ci.yml). Покрытие в бейдже выше генерируется самим CI на каждый push в main (.github/badges/coverage.json, из coverage report --format=total) — не статичное число. Superset-контрактный сьют (tests/test_superset_contract.py) + живой auto_bi build --auto дополнительно гоняются в CI отдельным job'ом (integration) на одноразовом docker-compose стенде ClickHouse+Superset; DataLens-сьют (tests/test_datalens_contract.py) остаётся Mac-only (self-hosted стенд, не докеризован). Job docker собирает образ на каждый PR (только сборка, ловит дрейф Dockerfile); на тег vX.Y.Z — .github/workflows/release.yml публикует образ в GHCR (ghcr.io/brownjuly2003-code/auto_bi) и создаёт GitHub Release из CHANGELOG.md.

License

MIT. See LICENSE.