Motor: Usa LLM (Anthropic)
1. Qué hace
Describes en tu idioma lo que quieres ver ("facturación por mes del último año") y la IA propone una consulta SQL de solo lectura para tu datalake, con una explicación en tu idioma y una estimación de costo/bytes.
2. ¿Determinista o LLM?
LLM. El modelo se resuelve así:
- El proveedor del modelo lo configuramos nosotros en el entorno; nunca se te pide ninguna credencial de IA.
- Cuando no hay credencial directa, el acceso al modelo pasa por un gateway administrado
(
anthropic/claude-sonnet-5). - Sin ningún proveedor, en dev/preview cae en un generador mock determinista (heurística simple que relaciona términos de la pregunta con el schema). En producción, sin proveedor, la ruta responde 503 en lugar de fingir un resultado (guarda de producción).
3. Datos enviados y egress
Va al LLM, dentro de un fence de dato no confiable (<dados id="...">):
- El schema de tu catálogo — nombres de tablas y columnas de las capas silver y gold de tu workspace. Las columnas marcadas como PII se excluyen antes de armar el prompt — la IA ni siquiera sabe que existen.
- Tu pregunta, dentro de un fence como
<dados id="pergunta">. - En el camino semántico (cuando hay un modelo semántico publicado), va el modelo (ids de tablas/relaciones/medidas) en lugar de las columnas crudas.
No van filas de datos. El text-to-SQL envía solo estructura (schema/modelo), nunca el contenido de las tablas. Una guarda de workspace descarta cualquier tabla cuyo nombre no empiece con el prefijo de tu workspace, aunque el catálogo estuviera corrupto.
4. Privacidad y retención
- La PII del catálogo no sale (exclusión en el origen, antes de armar el prompt).
- Todo texto del cliente (pregunta, nombres de tabla) entra dentro de un fence y con los tokens de fence neutralizados — es la defensa contra el prompt injection (cubierta por una suite adversarial).
- El uso (modelo, tokens, costo en R$, resumen de egress: nº de tablas del schema, 0
filas) se guarda en el registro de auditoría con la acción
ai.usage, con alcance por workspace.
5. Tokens, costo y presupuesto
- Antes de la llamada, el producto reserva el presupuesto estimado (
ai.reserva) y solo entonces verifica el tope (patrón reserve-then-verify — la concurrencia no rompe el tope). Después de la llamada, liquida con el costo real (ai.usage+ai.reserva_liquidada). - Tope mensual por workspace (por defecto R$ 50/mes; sin tope cuando está en cero =
sin tope). Si se supera → la llamada se rechaza con un mensaje claro y se registra en
ai.blocked. - Guarda de costo de la propia consulta: estimación de bytes/costo mediante un dry-run real en el datalake, y la consulta se valida antes de ejecutarse.
- Detalles en Privacidad, envío externo, presupuesto y apagado.
6. Cómo activarla, quién puede usarla y cómo desactivarla
La ruta POST /api/ai/sql solo llama al proveedor después de pasar, en este orden:
- Rate limit 20 req/60 s por IP, fail-closed (caché administrada caída → deniega).
- Workspace obligatorio (401 sin workspace).
- Entitlement
aiNarrative— disponible a partir del plan Pro (403 por debajo). - Verificación de acceso: la verificación de workspace activo — la morosidad/suspensión bloquea (402/403).
- Verificación de capacidad de consulta en lenguaje natural — un interruptor de apagado independiente de la facturación.
Apagado general: el envío a proveedores de modelo se puede desactivar en el entorno; en ese estado no ocurre ninguna llamada a un LLM, aunque haya una credencial configurada — el text-to-SQL cae en el mock determinista y nada sale del producto.
7. Negativas
La IA no inventa:
- Ambigüedad (camino semántico): si un término de la pregunta coincide con ≥2 medidas/columnas, se niega antes de gastar tokens, listando las opciones ("¿cuál quisiste decir?").
- Ids inválidos (camino semántico): si la respuesta cita un identificador que no existe en el modelo publicado, la consulta se descarta (un SQL sin fundamento no sale) — el costo de los tokens ya gastados se liquida con honestidad.
- Tope alcanzado → 429 con mensaje, sin gastar.
8. Limitaciones y ausencia de causalidad
- Genera solo
SELECT(sin DML/DDL). Aun así, revísala antes de confiar: la IA puede equivocarse en el nombre de una columna/tabla — por eso hay autocorrección (un retry con el error real del datalake), pero no es una garantía. - La explicación describe lo que hace la consulta; no afirma relaciones de causa y efecto en tus datos.
- En el modo demo (sin proveedor), el SQL viene de una heurística simple — sirve para experimentar, no para producción.
9. Cómo validar
- Apagado: con el envío a proveedores desactivado, confirma que la respuesta viene del resultado determinista (la explicación dice "modo de demostración") y que no ocurre ninguna llamada externa.
- PII fuera del prompt: marca una columna como PII en el catálogo y comprueba que no aparece en el schema enviado a la IA.
- Anti-inyección: escribe en la pregunta un texto que intente "cerrar" el fence y darle órdenes a la IA, y confirma que lo trata como dato, no como instrucción.
- Negativa por ambigüedad/ids: con un modelo semántico publicado, haz una pregunta ambigua y comprueba la negativa (sin SQL).
- Presupuesto: verifica en el registro de auditoría del workspace los pares
ai.reserva/ai.reserva_liquidaday elai.usagecon costo.