Motor: Usa LLM (Anthropic)
1. Qué hace
Haces una pregunta libre sobre un panel ("¿qué cliente creció más?") y la IA responde solo con base en el snapshot ya materializado — cada afirmación viene acompañada de citas verificables a los datos que la sustentan.
2. ¿Determinista o LLM?
Híbrido: LLM + verificación determinista. El LLM redacta la respuesta, pero quien decide
si la respuesta tiene respaldo es código puro. Cada widget enviado recibe un id [W1], [W2]… y
cada fila un sub-id [W1.r3]; el LLM está obligado a citar esos ids, y verificarCitacoes
comprueba cada cita contra el índice de lo que realmente viajó en el prompt — no contra el
texto que escribió el modelo.
Modelo: el mismo selector de Text-to-SQL. La verificación de las citas es determinista (código puro), separada de la redacción hecha por el LLM.
3. Datos enviados y egress
- Se envía el snapshot del panel (filas por widget), siempre dentro de un fence
<dados>, con los nombres de columna y los valores tratados como dato no confiable. - Ninguna query corre en el datalake para responder — el análisis es sobre el snapshot ya materializado (costo cero de datos).
- La cantidad de filas por widget respeta la política de egress: tope de hasta 50 filas, o, con el envío de filas desactivado, ninguna fila cruda — solo un resumen estadístico por columna (conteo, mín/máx/suma para las numéricas; nº de distintos para las categóricas).
- Un widget que es muestra se marca como tal en el prompt (la IA tiene prohibido afirmar totales/ rankings sobre una muestra).
4. Privacidad y retención
- La IA lee la misma vista segura de la pantalla: RLS del miembro y enmascaramiento de PII aplicados
antes de armar el contexto (
secureViewForSession/secureRows). Lo que la IA ve nunca es más de lo que ve quien pregunta. - La pregunta se guarda en el registro de auditoría (preguntas sobre el panel), con una marca cuando fue rechazada o
tuvo evidencia débil. El uso/costo va en
ai.usage. - Los filtros activos de la pantalla vuelven reflejados desde el lado determinista (nunca desde el LLM), y
lo que el LLM dice haber considerado se compara con los filtros reales (
divergencia).
5. Tokens, costo y presupuesto
- El mismo ledger reserva→liquidación y el mismo tope mensual del resto de la IA (ver presupuesto).
- La respuesta trae el costo real formateado (
custoBrlFormatado, p. ej.: "R$ 0,03") — incluso cuando la respuesta se convierte en negativa después de la llamada (gastó, lo reporta).
6. Cómo activarla, quién puede usarla y cómo desactivarla
POST /api/ai/dashboard-insights (con question) pasa por: rate limit 10/60 s por
workspace (fail-closed) → workspace (401) → entitlement aiNarrative (Pro, 403) →
la verificación de acceso y la verificación de capacidad insights de IA. Apagado general:
con el envío a proveedores desactivado, la respuesta cae en el resultado honesto (sin inventar evidencia).
7. Negativas
Tres formas de negativa — la respuesta sin respaldo no sale como hecho:
fora_do_contexto— una pregunta que no toca ningún término del panel: se rechaza antes de gastar tokens (costo cero).sem_evidencia— el LLM respondió, pero ninguna cita coincide con el dato: se convierte en negativa; el costo real se liquida.ia_indisponivel— sin proveedor/error: fallback honesto, citas vacías, nunca evidencia fingida.evidenciaFraca— cuando la mayoría de las citas es mala, la respuesta sale con aviso; solo las citas que coinciden cuentan como evidencia.
8. Limitaciones y ausencia de causalidad
- Responde sobre el snapshot — si el panel está desactualizado, la respuesta refleja el dato antiguo (la fecha de la última actualización va en el prompt y la IA tiene la instrucción de no tratarla como "hoy").
- No afirma causa y efecto: cita lo que muestran los datos; una correlación vista en el panel no se convierte en "X causó Y".
- Sobre una muestra, tiene prohibido afirmar total/suma/"mayor"/"menor"/"todos".
9. Cómo validar
- Una cita falsificada no pasa: incluye en una celda un texto como "[W9.r9]"; comprueba que no se convierte en una cita válida (la verificación usa el índice de lo que viajó, no el texto del modelo).
- Negativa sin evidencia: haz una pregunta que el panel no sustenta y confirma que la respuesta sale como negativa, no como hecho.
- Vista segura: confirma que una fila filtrada por RLS/PII no aparece en la respuesta.
- Egress mínimo: con el envío de filas desactivado, comprueba que solo el resumen estadístico viaja a la IA.
- Costo visible: la respuesta trae el costo formateado; compáralo con el evento
ai.usageen el registro de auditoría del workspace.