Arquitectura
BI generativo sobre una capa semántica gobernada
Un usuario hace una pregunta de negocio y recibe un tablero en segundos. La IA interpreta y elige; las definiciones, los joins y el SQL son determinísticos y auditables.
IA (Claude)DeterminísticoConfianza / controlDatos
Principios
01
La IA elige y combina; no calcula
El modelo devuelve un QueryPlan tipado (métricas, dimensiones, filtros). Nunca escribe SQL ni números.
02
La lógica vive en la capa semántica
Cocientes de sumas, hectáreas contadas una vez, estándar obligatorio: reglas en YAML versionado, no en prompts.
03
SQL determinístico
Mismo plan → mismo SQL, byte a byte. Solo joins declarados. Snapshot tests en CI.
04
Mejor un “no sé” que un número malo
Si falta una métrica, rechaza y ofrece lo más cercano. Las brechas conocidas están declaradas.
05
Cada número es trazable
Definición, plan, SQL, tablas de origen, filas de muestra, fecha de corte y versión semántica.
06
Las evaluaciones son producto
Set dorado puntuado por etapa; CI bloquea si baja la precisión. Nunca se usa como few-shot.
Niveles de confianza de cada respuesta
| Nivel | Cuándo | Qué ve el usuario |
|---|---|---|
| Verificado | Coincide con una consulta verificada; solo se completan parámetros. | Dueño y fecha de verificación. Costo de IA: 0. |
| Gobernado | QueryPlan sobre métricas definidas que pasó todas las validaciones. | Linaje completo y advertencias de los chequeos. |
| Exploratorio | SQL libre detrás de un flag (apagado en la demo pública). | SQL expandido y aviso de revisar. |
| Sin respuesta | Fuera de alcance, ambigua tras una aclaración o validación fallida. | Explicación simple y métricas más cercanas. |
Stack
| Capa | Demo | Producción |
|---|---|---|
| Web | Next.js 15 · Recharts · Leaflet | Vercel |
| API | FastAPI · Pydantic · sqlglot | Cloud Run (min 0) |
| Datos analíticos | DuckDB (read-only) | Postgres + PostGIS (Neon), app_reader |
| Datos crudos | JSONL (Mongo-shaped) | MongoDB Atlas |
| LLM | Claude Haiku 5.5 (router) · Sonnet 5.5 (planner) | Igual; el modelo se elige por costo con las evals |
| CI | GitHub Actions | Lint, tests, linter semántico, evals con gates |
Patrones de casos en producción
| Patrón | Fuente | Acá |
|---|---|---|
| El LLM descompone en métricas + dimensiones; un motor genera el SQL | dbt Labs (2023, 2026) | QueryPlan + compilador |
| La precisión depende de la capa semántica más que del modelo | Cube (2026) | Modelo como config; comparado en evals |
| Workspaces + agente de intención + poda del catálogo | Uber QueryGPT | Router por workspace |
| Activos de confianza: consultas verificadas parametrizadas | Databricks Genie | Nivel Verificado |
| Los benchmarks evalúan pero nunca alimentan el contexto | Databricks Genie | Test de disjunción en CI |