Skip to main content
Glama
deenesjakoruzh
khaosans

Operator ETL

by khaosans
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

{"type": "text"}# Operador ETL

Ingesta de datos agéntica para solicitudes FOIA y comentarios públicos — almacén de datos determinista en medallón, orquestación con LangGraph, superficie de herramientas MCP, plano de políticas PII.

CI Release License

Python y SQL deciden qué datos existen. Los agentes orquestan dentro de límites tipados. Las pruebas demuestran los invariantes — no se necesita clave API de LLM para la demo MVP.

Construido para agencias gubernamentales y organismos regulados que deben recibir comentarios públicos, detectar PII antes de la publicación, poner en cuarentena filas incorrectas y producir información defendible (cada número verificado contra el almacén).

Documentación

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

Empieza aquí

Enlace

Verlo en acción

Tour visual (capturas de pantalla)

Primera ejecución

INICIO RÁPIDO — ./scripts/verify.sh

Aprende lo que creamos

Conceptos · Patrones · Aplicar · Riesgos

Para quién es

Personas

UI del producto (posterior)

PRODUCT-UX — ESPECIFICADO, no esta demo

Related MCP server: MES Document MCP

Verificar en un comando

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

Instala uv si falta, sincroniza dependencias, ejecuta la puerta de validación completa. El éxito termina con OPERATOR_ETL_VERIFY=PASS.

Esperado: 51 pruebas pytest aprobadas, demo FOIA imprime status=complete y silver=10. Conjunto completo de capturas: docs/TOUR.md.

Panel de control gubernamental / FOIA

Pestaña de demostración de pedidos

Información del grafo ETL de plantilla

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

¿Ya tienes uv? make e2e · Detalles: docs/QUICKSTART.md · Paso a paso: docs/WALKTHROUGH.md

Instantáneas publicadas son etiquetas git (no cada fusión). Después de que exista un lanzamiento: GitHub Releases (ruedas), ghcr.io/khaosans/operator-etl:<version>, GitHub Packages operator-etl. Proceso: docs/VERSIONING.md. La wiki siempre sigue 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 separa el ETL determinista de los agentes acotados. La PII nunca llega a herramientas sin restricciones; el crítico rechaza números de información que no estén en oro; bronce te da un registro de auditoría inmutable.

Inmersión profunda: docs/WHY.md · Flujo de trabajo de la agencia: docs/FOIA-Public-Comments-Guide.md

Cómo funciona — tres planos

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

Plano

Rol

Datos

Bronce (inmutable) → plata (validado) → oro (marts SQL) + cuarentena. Python y SQL ejecutan; sin LLM en filas sin procesar.

Política

Escaneo de PII, bóveda cifrada, cierre ante fallo antes de la información. La bóveda nunca se expone a través de MCP.

Control

Pipeline LangGraph, herramientas MCP en lista blanca, crítico verifica cada número en el borrador de información.

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

¿Por qué no darle el almacén al chatbot?

Confianza y prueba

Pregunta

Respuesta

¿Funciona localmente?

make e2e — OKF validar, 51 pruebas pytest, demo FOIA en almacén nuevo

¿Qué prueba el CI?

La misma puerta en cada push (insignia arriba)

¿Qué no se prueba en CI?

Despliegue en vivo en GCP, PII con Presidio, información generada por LLM — ver auditoría honesta

Matriz de prueba: docs/FOUNDATIONS.md · Auditoría completa: docs/FINAL-REVIEW.md

Lo que acabas de probar

Métrica

Esperado

Comentarios de muestra

12 (expedientes EPA/FCC)

Plata (válido)

10

En cuarentena

2

Estado del grafo

complete

Crítico

pass

Detalles: okf/models/mvp-demo.md

Compensaciones de ingeniería

Decisión

Elegimos

Beneficio

Costo

Cuándo cambiar

Almacén local

DuckDB

Prueba sin infraestructura en un portátil

No multiinquilino

Etapa L3 BigQuery — SCALING.md

Detección de PII

MVP con Regex

Simple, comprobable, sin dependencias de ML

Omite nombres, direcciones

Presidio para producción

Generación de información

Plantilla + crítico

Sin clave API; determinista

Menos flexibilidad narrativa

Nodo LLM cuando la agencia lo apruebe

Acceso a datos del agente

Lista blanca MCP (3 herramientas)

Mínimo privilegio

Sin exploración SQL ad-hoc

No relajar para FOIA en producción

Fallos de calidad

Cierre ante fallo

KPI confiables

Bloquea información hasta que se corrija

Evitar pancartas de advertencia y mostrar

Matriz de prueba completa: docs/FOUNDATIONS.md

Para quién es esto

Rol

Empieza aquí

Oficial FOIA

Guía FOIA → TOUR · PERSONAS

Ingeniero de datos

PRIMEROS PASOS → ESCALADO

Arquitecto / revisor

POR QUÉ → FUNDAMENTOS → make e2e

Agente de IA (MCP)

AGENTS.md · operator-etl-mcp

Escalera de adopción

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]

Nivel

Acción

Documento

0 — Probar

make e2e

TUTORIAL

1 — Ejecutar localmente

MCP, panel de control

PRIMEROS PASOS

2 — Extender

Nueva fuente CSV

extender-nueva-fuente

3 — Puesta en escena GCP

Terraform + Cloud Run

ESCALADO

4 — Producción

Presidio, HITL, BQ en vivo, UX del producto

REVISIÓN FINAL · PRODUCT-UX

Comandos comunes

Comando

Acción

./scripts/verify.sh

Primera ejecución — instala uv si es necesario + puerta de validación completa

make verify

Igual que verify.sh

make e2e

Puerta de validación MVP completa (OKF + pruebas + demo FOIA)

make demo

Solo demo FOIA

make test

pytest (51 pruebas)

uv run etl-graph --source public_comments

Pipeline agéntico FOIA

uv run etl dashboard

Streamlit — Pestañas de Gobierno y Pedidos

uv run operator-etl-mcp

Servidor MCP para agentes Cursor

make share

Regenerar paquete de intercambio PDF

Ejecuta make help para todos los objetivos.

Arquitectura

Plano

Paquete

Estado

Datos

operator_etl/

IMPLEMENTADO

Control

operator_etl_graph/

IMPLEMENTADO

Política

operator_etl_policy/

IMPLEMENTADO

MCP

operator_etl_mcp/

IMPLEMENTADO

GCP

operator_etl_gcp/ + infra/

PARCIAL

Matriz viva: okf/models/implementation-status.md

Límites del alcance

Esta demo prueba: Pipeline FOIA local · Escaneo de PII · Límite MCP · Calidad de cierre ante fallo · 51 pruebas + CI

No incluido: Presidio de producción · Adaptador Regulations.gov · E2E GCP/BQ en vivo · UX de oficial de producción (responsiva, streaming, UI generativa) — docs/PRODUCT-UX.md

La UI de la demo es Streamlit. La UX del producto está ESPECIFICADA, no es este MVP.

Antes de afirmaciones de producción: Lista de verificación previa a la escala de REVISIÓN FINAL

Doc

Por qué abrirlo

Wiki (GitHub Pages)

Wiki humano buscable — empieza aquí

docs/TOUR.md

Capturas de pantalla de verify, CLI, Streamlit

docs/PERSONAS.md

Para quién es la demo

docs/PRODUCT-UX.md

Backlog de UI del producto (ESPECIFICADO)

docs/QUICKSTART.md

Primera ejecución — ./scripts/verify.sh

docs/CONCEPTS.md

Problema, lo que construimos, por qué es útil

docs/PATTERNS.md

Medallion, planes, critic — Inglés + citas

docs/APPLY.md

Otras fuentes de datos — mantén planes, cambia el esquema

docs/RISKS.md

Riesgos residuales después de un verify verde

docs/NIST.md

AI RMF / 600-1 / SP 800-122 — alineación, no certificación

docs/MODELS.md

Tarjetas de modelo y cuándo usar (Ollama vs OpenAI)

docs/GETTING-STARTED.md

Instalación, MCP, variables de entorno

docs/WALKTHROUGH.md

Prueba paso a paso

docs/DASHBOARD.md

Streamlit Gov / Pedidos

docs/LLM.md

Instala Ollama / insights compatibles con OpenAI

docs/SCALING.md

DuckDB → GCP

docs/FOUNDATIONS.md

Citas + matriz de prueba

docs/TESTING.md

Qué prueba cada test

docs/README.md

Índice completo por persona

También: HOW-IT-WORKS · WHY · documento técnico

Compartir y presentar

Código abierto: https://github.com/khaosans/operator-etl — clona y ejecuta make e2e.

Para entrevistas, LinkedIn o propuestas, adjunta los PDFs de docs/share/ (resumen de una página, documento técnico, diapositivas):

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

Contribución · Licencia · Seguridad

Licenciado bajo Apache License 2.0. Los datos de muestra son sintéticos — no confirmes registros FOIA reales.

Las Issues y PRs son bienvenidos.

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