Estado: Activo — actualizado 2025-10-07 15:28 CLT. Responsable: Equipo datos.

Trazabilidad, API y MCP

Esta página centraliza cómo navegar la trazabilidad extremo a extremo, consumirla vía API y aprovechar el router MCP público. Resume los artefactos, comandos y endpoints clave para mantener el catálogo actualizado y ofrecer permalinks estables para tablas y columnas.

1. Resumen ejecutivo

  • make schema-catalog genera todos los artefactos de trazabilidad (docs/schema_catalog.md, docs/lineage_paths.json, docs/schema_explorer.html).
  • /mcp entrega un API auto-descubrible con permalinks y lineage hasta RAW (/mcp/tables/{code}/lineage).
  • docs/schema_explorer.html es la UI online para navegar capas, dominios, métricas de calidad y relaciones.
  • tasks/export/resolve_code.py y los CSV (docs/schema_codes.csv, docs/column_codes.csv) permiten resolver códigos y construir permalinks desde scripts, MCP o LLMs.
  • Mantén todo alineado ejecutando make schema-catalog tras cambios de esquema y revisando diffs antes de publicar.

2. Flujo de datos y trazabilidad

  1. Capas: data_raw/ → bronze.* → staging/stg.* → silver.* → gold.* → pub.* → API/UI.
  2. Scripts ETL: viven en tasks/ (descargas y orquestación), etl/ (procesos programados) y SQL en etl/sql/ siguiendo prefijos (gold_*, silver_*, etc.).
  3. Lineage automático: tasks/export/lineage_trace_export.py resume rutas en docs/lineage_paths.json, usadas por el MCP y el explorer.
  4. Calidad: métricas null_frac, nn, nf, sample sizes y outliers se anotan en schema_graph.json.gz y aparecen como tooltips en la UI.

Comandos útiles

# Regenerar catálogo, lineage y explorer (usa $DATABASE_URL)
make schema-catalog

# Inspeccionar lineage crudo de una tabla gold
jq '.\"gold.funnel_stage_matrix\"' docs/lineage_paths.json

# Trazar un dato específico
psql "$DATABASE_URL" -c "SELECT * FROM gold.funnel_stage_matrix WHERE region_id=13 AND anio=2023;"
psql "$DATABASE_URL" -c "SELECT * FROM silver.policiales_region WHERE region_id=13 AND anio=2023;"

UI online

Sirve la carpeta docs/ (quarto preview docs o python -m http.server) y abre docs/schema_explorer.html. La URL soporta permalinks (?table=<code> o ?column=<table_code:column_code>) y muestra:

  • Dominio, capa y tipo de objeto.
  • Primary keys, foreign keys, unique constraints.
  • Métricas de calidad (null %, hist_min, hist_max, outliers).
  • Rutas de lineage hacia capas inferiores (tooltip y panel lateral).

3. API de catálogo y trazabilidad

Los endpoints FastAPI en ops/services/api publican vistas pub.*. Para explorar y validar:

  • Referencia rápida: docs/API_ENDPOINTS.md (contratos) y docs/API_STATUS_ROADMAP.md (estado).
  • Gibbs: usa uvicorn app:app --reload --port 8120 o make serve-api.
  • Cada vista se sustenta en tablas gold.* o publish.* incluidas en el explorer; cruza el permalink para auditar cambios.

Ejemplo de verificación

# Levanta el API
make serve-api

# Chequea un endpoint funnel
curl -s "http://localhost:8120/api/v1/funnel/region?region_id=13&anio=2023" | jq '.[0]'

Relaciona la respuesta con el permalink de gold.funnel_stage_matrix (docs/schema_explorer.html?table=a33678976933) para confirmar columnas y lineage.

4. Router MCP público

El router en illanes_api/routes/mcp.py expone un catálogo navegable por agentes MCP, Codex o LLMs. Se alimenta de los artefactos generados por make schema-catalog.

Endpoint Descripción Ejemplo
GET /mcp/status Metadata (generated_at, capas disponibles, recuentos). curl http://localhost:8120/mcp/status
GET /mcp/tables Lista filtrable (layer, domain, q, limit, offset). curl "http://localhost:8120/mcp/tables?layer=gold&domain=funnel"
GET /mcp/tables/{code} Detalle completo de tabla/columna (constraints, métricas, permalinks). curl http://localhost:8120/mcp/tables/a33678976933
GET /mcp/tables/{code}/lineage Paths completos hasta bronze y archivos RAW. curl http://localhost:8120/mcp/tables/a33678976933/lineage

Las respuestas incluyen:

  • permalink (schema_explorer.html?table=code).
  • Metadatos (layer, domain, kind, row_count, null_ratio).
  • Columnas con sus códigos (column_code), tipos y flags (is_primary_key, is_foreign_key).
  • lineage.paths: secuencia de tablas y scripts (etl/sql/<archivo>.sql, tasks/<ingesta>.py) para alcanzar el origen.

Mantención

  • Ejecuta pytest tests/backend/api/test_mcp_router.py tras cambios en el router.
  • Documenta nuevos dominios o capas en docs/DATA_CATALOG.md y docs/LINEAGE_GUIDE.md para que los agentes MCP los descubran.
  • Si añades columnas o tablas, vuelve a generar docs/schema_codes.csv y commitea los diffs.

6. Checklist de publicación

  1. Ejecuta make schema-catalog.
  2. Revisa git diff docs/schema_catalog.md docs/schema_explorer.html docs/lineage_paths.json.
  3. Corre pytest tests/backend/api/test_schema_permalinks.py tests/backend/api/test_mcp_router.py.
  4. Actualiza este documento si hay cambios de flujo o endpoints.
  5. Reconstruye el sitio (quarto render docs) antes de publicar.

7. Recursos relacionados

  • docs/LINEAGE_GUIDE.md: guía detallada de lineage y dominios.
  • docs/PERMALINKS.md: especificación de códigos y permalinks.
  • docs/DATA_CATALOG.md: catálogo maestro con capas y dominios.
  • docs/API_ENDPOINTS.md: contratos públicos del API.
  • docs/schema_explorer.html: vista interactiva con relaciones y métricas.

¿Necesitas extender la trazabilidad para un nuevo dominio? Duplica el patrón (etl/sql/<layer>_<dominio>_*.sql, usa prefijos consistentes) y agrega las rutas en los scripts/SQL correspondientes. Ejecuta nuevamente make schema-catalog para reflejarlo en el MCP, el explorer y los permalinks.