Skip to main content
Glama
deenesjakoruzh
khaosans

Operator ETL

by khaosans
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Operator ETL

Agentische Datenerfassung für FOIA und öffentliche Kommentare — deterministisches Medaillon-Warehouse, LangGraph-Orchestrierung, MCP-Tool-Oberfläche, PII-Richtlinienebene.

CI Release License

Python und SQL entscheiden, welche Daten existieren. Agenten orchestrieren innerhalb typisierter Grenzen. Tests beweisen die Invarianten — kein LLM-API-Schlüssel für die MVP-Demo erforderlich.

Entwickelt für Regierungsbehörden und regulierte Stellen, die öffentliche Kommentare erfassen, PII vor der Veröffentlichung erkennen, fehlerhafte Zeilen unter Quarantäne stellen und verteidigungsfähige Erkenntnisse (jede Zahl gegen das Warehouse verifiziert) produzieren müssen.

Dokumentation

Wiki (durchsuchbar): https://khaosans.github.io/operator-etl/

Hier starten

Link

In Aktion sehen

Visuelle Tour (Screenshots)

Erster Start

QUICKSTART — ./scripts/verify.sh

Erfahren, was wir gebaut haben

Konzepte · Muster · Anwenden · Risiken

Für wen es gedacht ist

Personas

Produkt-UI (später)

PRODUCT-UX — SPEZIFIZIERT, nicht diese Demo

Related MCP server: MES Document MCP

Mit einem Befehl verifizieren

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

Installiert uv falls fehlend, synchronisiert Abhängigkeiten, führt das vollständige Proof-Gate aus. Erfolg endet mit OPERATOR_ETL_VERIFY=PASS.

Erwartet: 51 pytest bestehen, FOIA-Demo gibt status=complete und silver=10 aus. Vollständiges Screenshot-Set: docs/TOUR.md.

Gov / FOIA Dashboard

Orders Demo Tab

Template etl-graph Erkenntnis

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

Bereits uv installiert? make e2e · Details: docs/QUICKSTART.md · Schritt-für-Schritt: docs/WALKTHROUGH.md

Veröffentlichte Snapshots sind Git-Tags (nicht jeder Merge). Nachdem eine Veröffentlichung existiert: GitHub Releases (Wheels), ghcr.io/khaosans/operator-etl:<version>, GitHub Packages operator-etl. Prozess: docs/VERSIONING.md. Das Wiki folgt immer 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 trennt deterministisches ETL von begrenzten Agenten. PII erreicht nie uneingeschränkte Tools; der Kritiker lehzt Erkenntniszahlen ab, die nicht in gold sind; bronze gibt Ihnen eine unveränderliche Prüfspur.

Tiefergehend: docs/WHY.md · Behörden-Workflow: docs/FOIA-Public-Comments-Guide.md

So funktioniert es — drei Ebenen

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

Ebene

Rolle

Daten

Bronze (unveränderlich) → Silber (validiert) → Gold (SQL-Marts) + Quarantäne. Python und SQL führen aus; kein LLM auf Rohdaten.

Richtlinie

PII-Scan, verschlüsselter Tresor, fehlschlagen-schließen vor Erkenntnis. Tresor nie über MCP exponiert.

Steuerung

LangGraph-Pipeline, MCP-allowlistierte Tools, Kritiker verifiziert jede Zahl im Erkenntnisentwurf.

Details: docs/HOW-IT-WORKS.md · okf/models/three-planes.md

Warum dem Chatbot nicht Ihr Warehouse geben?

Vertrauen und Beweis

Frage

Antwort

Funktioniert es lokal?

make e2e — OKF validieren, 51 pytest, FOIA-Demo auf frischem Warehouse

Was beweist CI?

Gleiches Gate bei jedem Push (Badge oben)

Was wird nicht in CI bewiesen?

Live-GCP-Deploy, Presidio PII, LLM-generierte Erkenntnisse — siehe ehrliches Audit

Beweismatrix: docs/FOUNDATIONS.md · Vollständiges Audit: docs/FINAL-REVIEW.md

Was Sie gerade bewiesen haben

Metrik

Erwartet

Beispielkommentare

12 (EPA/FCC-Akten)

Silber (gültig)

10

Unter Quarantäne

2

Graph-Status

complete

Kritiker

bestanden

Details: okf/models/mvp-demo.md

Technische Abwägungen

Entscheidung

Wir wählten

Vorteil

Kosten

Wann ändern

Lokales Warehouse

DuckDB

Null-Infrastruktur-Beweis auf einem Laptop

Nicht mehrfachmandantenfähig

Stufe L3 BigQuery — SCALING.md

PII-Erkennung

Regex MVP

Einfach, testbar, keine ML-Abhängigkeiten

Übersieht Namen, Adressen

Presidio für Produktion

Erkenntnisgenerierung

Vorlage + Kritiker

Kein API-Schlüssel; deterministisch

Weniger narrative Flexibilität

LLM-Knoten, wenn Behörde zustimmt

Agentendatenzugriff

MCP-Allowlist (3 Tools)

Minimale Rechte

Keine Ad-hoc-SQL-Erkundung

Für Produktions-FOIA nicht lockern

Qualitätsfehler

Fehlschlagen-schließen

Vertrauenswürdige KPIs

Blockiert Erkenntnisse bis zur Behebung

Warn-und-Banner vermeiden

Vollständige Beweismatrix: docs/FOUNDATIONS.md

Für wen das gedacht ist

Rolle

Hier starten

FOIA-Beauftragter

FOIA-Leitfaden → TOUR · PERSONAS

Dateningenieur

GETTING-STARTED → SCALING

Architekt / Prüfer

WHY → FOUNDATIONS → make e2e

KI-Agent (MCP)

AGENTS.md · operator-etl-mcp

Übernahme-Leiter

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]

Ebene

Aktion

Dokument

0 — Beweisen

make e2e

WALKTHROUGH

1 — Lokal ausführen

MCP, Dashboard

GETTING-STARTED

2 — Erweitern

Neue CSV-Quelle

extend-new-source

3 — GCP-Staging

Terraform + Cloud Run

SCALING

4 — Produktion

Presidio, HITL, Live-BQ, Produkt-UI

FINAL-REVIEW · PRODUCT-UX

Häufige Befehle

Befehl

Aktion

./scripts/verify.sh

Erster Start — uv installieren falls nötig + vollständiges Proof-Gate

make verify

Wie verify.sh

make e2e

Vollständiges MVP-Proof-Gate (OKF + Tests + FOIA-Demo)

make demo

Nur FOIA-Demo

make test

pytest (51 Tests)

uv run etl-graph --source public_comments

FOIA-agentische Pipeline

uv run etl dashboard

Streamlit — Gov + Orders Tabs

uv run operator-etl-mcp

MCP-Server für Cursor-Agenten

make share

PDF-Share-Pack neu generieren

Führen Sie make help für alle Ziele aus.

Architektur

Ebene

Paket

Status

Daten

operator_etl/

IMPLEMENTIERT

Steuerung

operator_etl_graph/

IMPLEMENTIERT

Richtlinie

operator_etl_policy/

IMPLEMENTIERT

MCP

operator_etl_mcp/

IMPLEMENTIERT

GCP

operator_etl_gcp/ + infra/

TEILWEISE

Lebende Matrix: okf/models/implementation-status.md

Umfangsgrenzen

Diese Demo beweist: Lokale FOIA-Pipeline · PII-Scan · MCP-Grenze · fehlschlagen-schließen-Qualität · 51 Tests + CI

Nicht enthalten: Produktions-Presidio · Regulations.gov-Adapter · Live-GCP/BQ-E2E · Produktions-Beauftragter-UI (responsiv, Streaming, gen UI) — docs/PRODUCT-UX.md

Die Demo-UI ist Streamlit. Produkt-UI ist SPEZIFIZIERT, nicht dieser MVP.

Vor Produktionsbehauptungen: FINAL-REVIEW Pre-Scale-Checkliste

Dokumentation

Dokumentation

Warum öffnen

Wiki (GitHub Pages)

Durchsuchbares Human-Wiki – hier starten

docs/TOUR.md

Screenshots von verify, CLI, Streamlit

docs/PERSONAS.md

Für wen die Demo gedacht ist

docs/PRODUCT-UX.md

Product-UI-Backlog (SPEZIFIZIERT)

docs/QUICKSTART.md

Erster Start – ./scripts/verify.sh

docs/CONCEPTS.md

Problem, was wir gebaut haben, warum es nützlich ist

docs/PATTERNS.md

Medaillon, Ebenen, Kritiker – Englisch + Quellenangaben

docs/APPLY.md

Andere Datenquellen – Ebenen behalten, Schema ändern

docs/RISKS.md

Restrisiken nach einem grünen Verify

docs/NIST.md

AI RMF / 600-1 / SP 800-122 – Ausrichtung, nicht Zertifizierung

docs/MODELS.md

Modellkarten und Einsatzzeitpunkt (Ollama vs. OpenAI)

docs/GETTING-STARTED.md

Installation, MCP, Umgebungsvariablen

docs/WALKTHROUGH.md

Schritt-für-Schritt-Nachweis

docs/DASHBOARD.md

Streamlit Gov / Orders

docs/LLM.md

Installiere Ollama / OpenAI-kompatible Einblicke

docs/SCALING.md

DuckDB → GCP

docs/FOUNDATIONS.md

Quellenangaben + Beweismatrix

docs/TESTING.md

Was jeder Test beweist

docs/README.md

Vollständiger Index nach Persona

Auch: HOW-IT-WORKS · WHY · Whitepaper

Teilen und präsentieren

Open Source: https://github.com/khaosans/operator-etl – klonen und make e2e ausführen.

Für Vorstellungsgespräche, LinkedIn oder Vorschläge die PDFs aus docs/share/ (One-Pager, Whitepaper, Folien) anhängen:

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

Mitwirken · Lizenz · Sicherheit

Lizenziert unter der Apache License 2.0. Die Beispieldaten sind synthetisch – keine echten FOIA-Unterlagen einchecken.

Issues und PRs sind willkommen.

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