Skip to main content
Glama
deenesjakoruzh
khaosans

Operator ETL

by khaosans
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Operator ETL

Агентный приём данных для FOIA и публичных комментариев — детерминированное хранилище-медальон, оркестрация LangGraph, инструментальная поверхность MCP, плоскость политик PII.

CI Release License

Python и SQL решают, какие данные существуют. Агенты оркестрируют в типизированных границах. Тесты доказывают инварианты — для MVP-демонстрации не требуется ключ API LLM.

Создано для государственных органов и регулируемых организаций, которым необходимо принимать публичные комментарии, обнаруживать PII перед публикацией, помещать некорректные строки в карантин и получать обоснованные выводы (каждое число верифицировано по хранилищу).

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

Вики (доступен поиск): https://khaosans.github.io/operator-etl/

Начните здесь

Ссылка

Посмотрите в работе

Визуальный обзор (скриншоты)

Первый запуск

QUICKSTART — ./scripts/verify.sh

Узнайте, что мы создали

Концепции · Паттерны · Применение · Риски

Для кого это

Персонажи

Пользовательский интерфейс (позже)

PRODUCT-UX — СПЕЦИФИЦИРОВАНО, не эта демо-версия

Related MCP server: MES Document MCP

Проверить одной командой

git clone https://github.com/khaosans/operator-etl.git
cd operator-etl
./scripts/verify.sh

Устанавливает uv, если отсутствует, синхронизирует зависимости, запускает полный шлюз проверки. Успешное завершение выводит OPERATOR_ETL_VERIFY=PASS.

Ожидается: 51 тест pytest, демо FOIA выводит status=complete и silver=10. Полный набор скриншотов: docs/TOUR.md.

Панель управления Gov / FOIA

Вкладка «Orders» демо

Вывод шаблона etl-graph

flowchart LR
  Verify[verify.sh] --> UV[uv sync]
  UV --> E2E[e2e gate]
  E2E --> Pass[OPERATOR_ETL_VERIFY=PASS]

Уже есть uv? make e2e · Подробности: docs/QUICKSTART.md · Пошагово: docs/WALKTHROUGH.md

Опубликованные снимки — это git-теги (не каждый merge). После выхода релиза: GitHub Releases (wheels), ghcr.io/khaosans/operator-etl:<version>, GitHub Packages operator-etl. Процесс: docs/VERSIONING.md. В вики всегда отслеживается master.

flowchart LR
  subgraph problem [The usual demo]
    A[Chatbot + SQL] --> W[(Warehouse)]
    A --> M[Memo with KPIs]
  end

  subgraph fail [Three failures]
    F1[PII in context]
    F2[Hallucinated counts]
    F3[No replay audit]
  end

  M --> fail

Operator ETL разделяет детерминированный ETL и ограниченных агентов. PII никогда не попадает в неограниченные инструменты; критик отклоняет числа выводов, которых нет в gold; bronze даёт неизменяемый аудиторский след.

Подробно: docs/WHY.md · Рабочий процесс для агентств: docs/FOIA-Public-Comments-Guide.md

Как это работает — три плоскости

flowchart TB
  subgraph data [Data plane]
    direction TB
    CSV[CSV intake] --> Bronze[bronze_raw]
    Bronze --> Silver[silver validated]
    Bronze --> Quarantine[quarantine]
    Silver --> Gold[gold SQL marts]
  end

  subgraph policy [Policy plane]
    PII[PII scan + vault]
    Bronze --> PII
  end

  subgraph control [Control plane]
    Graph[LangGraph]
    MCP[MCP allowlist]
    Critic[critic]
    Graph --> MCP --> Gold
    Graph --> Critic --> Insight[verified insight]
  end

Плоскость

Роль

Данные

Bronze (неизменяемый) → silver (проверенный) → gold (SQL-витрины) + карантин. Python и SQL выполняют; LLM не работает с сырыми строками.

Политики

Сканирование PII, зашифрованное хранилище, отказоустойчивость до вывода. Хранилище никогда не раскрывается через MCP.

Управление

Конвейер LangGraph, инструменты MPC из белого списка, критик проверяет каждое число в черновике вывода.

Подробности: docs/HOW-IT-WORKS.md · okf/models/three-planes.md

Зачем отдавать чат-боту ваше хранилище?

Доверие и доказательство

Вопрос

Ответ

Работает ли локально?

make e2e — OKF-валидация, 51 тест pytest, демо FOIA на свежем хранилище

Что доказывает CI?

Тот же шлюз на каждом push (значок выше)

Что не доказано в CI?

Развёртывание на GCP, Presidio PII, выводы, сгенерированные LLM — см. честный аудит

Матрица доказательств: docs/FOUNDATIONS.md · Полный аудит: docs/FINAL-REVIEW.md

Что вы только что доказали

Метрика

Ожидаемое значение

Образцы комментариев

12 (реестры EPA/FCC)

Silver (валидные)

10

В карантине

2

Статус графа

complete

Критик

пройдено

Подробности: okf/models/mvp-demo.md

Инженерные компромиссы

Решение

Мы выбрали

Преимущество

Цена

Когда менять

Локальное хранилище

DuckDB

Доказательство без инфраструктуры на ноутбуке

Не многопользовательский

Стадия L3 BigQuery — SCALING.md

Обнаружение PII

Regex MVP

Просто, тестируемо, без ML-зависимостей

Пропускает имена, адреса

Presidio для продакшена

Генерация выводов

Шаблон + критик

Нет ключа API; детерминировано

Меньше гибкости повествования

Узел LLM, когда агентство одобрит

Доступ агентов к данным

MCP-белый список (3 инструмента)

Минимальные привилегии

Нет ad-hoc SQL-исследований

Не ослаблять для продакшена FOIA

Отказы по качеству

Закрытие с ошибкой

Доверенные KPI

Блокирует выводы до исправления

Избегать баннеров предупреждений «warn-and-show»

Полная матрица доказательств: docs/FOUNDATIONS.md

Для кого это

Роль

Начните здесь

Сотрудник FOIA

Руководство FOIA → ОБЗОР · ПЕРСОНАЖИ

Инженер данных

НАЧАЛО РАБОТЫ → МАСШТАБИРОВАНИЕ

Архитектор / рецензент

ЗАЧЕМ → ОСНОВЫ → make e2e

AI-агент (MCP)

AGENTS.md · operator-etl-mcp

Лестница внедрения

flowchart LR
  L0[L0 Prove make e2e] --> L1[L1 Run locally]
  L1 --> L2[L2 Extend source]
  L2 --> L3[L3 GCP staging]
  L3 --> L4[L4 Production HITL]

Уровень

Действие

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

0 — Доказать

make e2e

ПОШАГОВО

1 — Запустить локально

MCP, панель управления

НАЧАЛО РАБОТЫ

2 — Расширить

Новый источник CSV

extend-new-source

3 — GCP-стенд

Terraform + Cloud Run

МАСШТАБИРОВАНИЕ

4 — Продакшен

Presidio, HITL, живой BQ, UX продукта

ФИНАЛЬНЫЙ ОБЗОР · PRODUCT-UX

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

Команда

Действие

./scripts/verify.sh

Первый запуск — установка uv (если нужно) + полный шлюз проверки

make verify

То же, что verify.sh

make e2e

Полный шлюз MVP (OKF + тесты + демо FOIA)

make demo

Только демо FOIA

make test

pytest (51 тест)

uv run etl-graph --source public_comments

Агентный конвейер FOIA

uv run etl dashboard

Streamlit — вкладки «Gov» и «Orders»

uv run operator-etl-mcp

MCP-сервер для агентов Cursor

make share

Пересобрать PDF-пакет для распространения

Запустите make help для всех целей.

Архитектура

Плоскость

Пакет

Статус

Данные

operator_etl/

РЕАЛИЗОВАНО

Управление

operator_etl_graph/

РЕАЛИЗОВАНО

Политики

operator_etl_policy/

РЕАЛИЗОВАНО

MCP

operator_etl_mcp/

РЕАЛИЗОВАНО

GCP

operator_etl_gcp/ + infra/

ЧАСТИЧНО

Актуальная матрица: okf/models/implementation-status.md

Границы охвата

Эта демоверсия доказывает: Локальный конвейер FOIA · Сканирование PII · Граница MCP · Отказоустойчивость по качеству · 51 тест + CI

Не включено: Продакшен Presidio · Адаптер Regulations.gov · живой E2E GCP/BQ · продакшен UX для сотрудников (адаптивный, потоковый, современный UI) — docs/PRODUCT-UX.md

Пользовательский интерфейс демо — Streamlit. Продуктовый UX СПЕЦИФИЦИРОВАН, не является частью этого MVP.

Перед заявлениями о продакшене: Чек-лист предмасштабирования FINAL-REVIEW

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

Документ

Зачем открывать

Wiki (GitHub Pages)

Поисковая человеческая вики — начинайте здесь

docs/TOUR.md

Скриншоты verify, CLI, Streamlit

docs/PERSONAS.md

Для кого демо

docs/PRODUCT-UX.md

Бэклог UI продукта (SPECIFIED)

docs/QUICKSTART.md

Первый запуск — ./scripts/verify.sh

docs/CONCEPTS.md

Проблема, что мы построили, почему это полезно

docs/PATTERNS.md

Медальон, плоскости, критик — английский + цитаты

docs/APPLY.md

Другие источники данных — сохраняйте плоскости, меняйте схему

docs/RISKS.md

Остаточные риски после зелёного verify

docs/NIST.md

AI RMF / 600-1 / SP 800-122 — согласование, не сертификация

docs/MODELS.md

Карточки моделей и когда использовать (Ollama vs OpenAI)

docs/GETTING-STARTED.md

Установка, MCP, переменные окружения

docs/WALKTHROUGH.md

Пошаговое доказательство

docs/DASHBOARD.md

Streamlit Gov / Orders

docs/LLM.md

Установка Ollama / OpenAI-совместимые инсайты

docs/SCALING.md

DuckDB → GCP

docs/FOUNDATIONS.md

Цитаты + матрица доказательств

docs/TESTING.md

Что доказывает каждый тест

docs/README.md

Полный указатель по персонам

Также: HOW-IT-WORKS · WHY · white paper

Делитесь и представляйте

Открытый исходный код: https://github.com/khaosans/operator-etl — клонируйте и запустите make e2e.

Для собеседований, LinkedIn или предложений прикрепляйте PDF из docs/share/ (одностраничник, white paper, слайды):

make share   # regenerates docs/share/latest/ after e2e

Участие · Лицензия · Безопасность

Лицензировано по Apache License 2.0. Примеры данных синтетические — не фиксируйте реальные записи FOIA.

Приветствуются Issues и PR.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MetaGraph-MCP

    midsane
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables enterprise AI agents to query governed data lineage, PII-aware schema documentation, and semantic metadata from SQL logs via MCP, with role-based access and vector search.
    MIT
  • dst by get-dst

    dstofficial

    get-dst
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents to query governed data warehouses through plain language, returning grounded answers with SQL, confidence grades, and signed receipts while enforcing access, testing, and audit controls.
    15
    Apache 2.0