Motor: Usa LLM (Anthropic) + validación determinística
1. Qué hace
Describes lo que quieres ("una medida de ticket promedio", "un gráfico de ventas por región", "un panel de seguimiento comercial") y la IA propone un artefacto estructurado — medida, visual o esqueleto de dashboard — listo para que lo revises y confirmes.
2. ¿Determinístico o LLM?
Híbrido: el LLM propone, el código valida. El texto del artefacto viene del LLM, pero el campo
validacao siempre lo completan los validadores determinísticos reales del producto — los
mismos del editor: validación de medida, typecheck de fórmula, compilación del modelo a SQL, la
allowlist de visuales y la validación de SQL libre.
Sin proveedor en dev/preview → artefacto mock determinístico, que pasa por los mismos validadores (la validación es ley incluso en el mock). En producción sin proveedor → 503.
3. Datos enviados y egress
- Va tu descripción (en un fence como
<dados id="pedido">), el modelo del dashboard y el catálogo físico sin PII (mismo grounding que el asistente), todo dentro de fences. - No van filas de datos — solo estructura (esquema/modelo).
- Cuando el datalake está configurado, el SQL propuesto pasa por un dry-run real para validarse — esto se ejecuta en el datalake, no en el LLM.
4. Privacidad y retención
- PII fuera del prompt (exclusión en el origen, como en text-to-SQL).
- El registro de auditoría generación asistida por IA registra el pedido, el tipo y si salió como borrador;
ai.usageregistra tokens/costo.
5. Tokens, costo y presupuesto
- Mismo ledger de reserva→liquidación, por llamada (feature
ai_generate), y mismo tope mensual. - La autocorrección cuenta como una segunda llamada: el costo de ambas se suma en
custoBrlTotal.
6. Cómo activarlo, quién puede usarlo y cómo desactivarlo
POST /api/ai/generate: rate limit 10/60 s por workspace (fail-closed) → workspace (401)
→ entitlement aiNarrative (Pro, 403) → la verificación de workspace activo → generación.
Con el envío a proveedores desactivado, el resultado es determinístico y nada sale de la plataforma.
7. Rechazos y borrador
- La IA NUNCA publica. La confirmación es siempre un paso humano, mediante las actions existentes
(
addMeasureAction/addWidgetAction/updateWidgetAction/saveModelAction). - Validación reprobada → se autocorrige una vez con los errores (en portugués); si persiste, el
artefacto sale como BORRADOR (
validacao.ok = false) con los errores a la vista — el error nunca se oculta. - Tope alcanzado → 429 con mensaje, sin gastar.
8. Limitaciones y ausencia de causalidad
- El artefacto es una propuesta: la fórmula/SQL puede ser sintácticamente válida y aun así no ser lo que querías. Revísala antes de confirmar.
- La IA solo genera visuales de datos de la allowlist (no genera elementos de diseño como texto/ imagen/botón).
- No interpreta causalidad en los datos; propone estructura, no conclusiones.
9. Cómo validar
- La validación es determinística: pide una medida o un visual y verifica que el campo
validacaode la respuesta refleje los mismos validadores del editor — nunca una "aprobación" basada solo en el texto del LLM. - Nada se publica solo: confirma que la ruta devuelve el artefacto +
validacao, y que la escritura solo ocurre en la action tras la confirmación humana. - Borrador honesto: pide algo imposible y verifica
rascunho: truecon los errores listados. - Dry-run real: con el datalake configurado, un SQL inválido se reprueba en el dry-run, no en el LLM.