Engine: Uses an LLM (Anthropic) + deterministic validation
1. What it does
You describe what you want ("an average ticket measure," "a chart of sales by region," "a sales tracking dashboard") and the AI proposes a structured artifact — a measure, a visual, or a dashboard skeleton — ready for you to review and confirm.
2. Deterministic or LLM?
Hybrid: the LLM proposes, the code validates. The artifact's text comes from the LLM, but the
validacao field is always filled in by the product's real deterministic validators — the
same ones the editor uses: measure validation, formula typecheck, model-to-SQL compilation, the
visuals allowlist, and free-form SQL validation.
With no provider in dev/preview → a deterministic mock artifact, which goes through the same validators (validation is law even in the mock). In production with no provider → 503.
3. Data sent and egress
- What's sent is your description (fenced as
<dados id="pedido">), the dashboard model, and the physical catalog without PII (same grounding as the wizard), all fenced. - No data rows are sent — only structure (schema/model).
- When the datalake is configured, the proposed SQL goes through a real dry-run for validation — this runs on the datalake, not on the LLM.
4. Privacy and retention
- PII is kept out of the prompt (excluded at the source, as in text-to-SQL).
- The AI-assisted generation audit log entry records the request, the type, and whether it came out as a draft;
ai.usagerecords tokens/cost.
5. Tokens, cost, and budget
- Same reservation→settlement ledger, per call (feature
ai_generate), and same monthly cap. - Self-correction counts as a second call: the cost of both is added up in
custoBrlTotal.
6. How to turn it on, who can use it, and how to turn it off
POST /api/ai/generate: rate limit 10/60 s per workspace (fail-closed) → workspace (401)
→ entitlement aiNarrative (Pro, 403) → the active-workspace check → generation.
With sending to providers turned off, the result is deterministic and nothing leaves the platform.
7. Refusals and drafts
- The AI NEVER publishes. Confirmation is always a human step, through the existing actions
(
addMeasureAction/addWidgetAction/updateWidgetAction/saveModelAction). - Validation failed → self-corrects once using the errors (in Portuguese); if it persists, the
artifact comes out as a DRAFT (
validacao.ok = false) with the errors on display — the error is never hidden. - Cap reached → 429 with a message, nothing spent.
8. Limitations and absence of causality
- The artifact is a proposal: the formula/SQL may be syntactically valid and still not be what you meant. Review it before confirming.
- The AI only generates data visuals from the allowlist (it doesn't generate layout elements such as text/ image/button).
- It doesn't interpret causality in the data; it proposes structure, not conclusions.
9. How to validate
- Validation is deterministic: ask for a measure or visual and check that the response's
validacaofield reflects the same validators as the editor — never an "approval" based only on the LLM's text. - Nothing publishes on its own: confirm that the route returns the artifact +
validacao, and that the write only happens in the action after human confirmation. - Honest draft: ask for something impossible and check for
rascunho: truewith the errors listed. - Real dry-run: with the datalake configured, invalid SQL fails in the dry-run, not in the LLM.