Engine: Uses LLM (Anthropic)
1. What it does
You ask a free-form question about a dashboard ("which customer grew the most?") and the AI answers based only on the already materialized snapshot — each statement comes with verifiable citations pointing to the data that supports it.
2. Deterministic or LLM?
Hybrid: LLM + deterministic verification. The LLM writes the answer, but what decides
whether the answer is grounded is pure code. Each widget sent gets an id [W1], [W2]… and
each row a sub-id [W1.r3]; the LLM must cite these ids, and verificarCitacoes
checks each citation against the index of what actually traveled in the prompt — not against the
text the model wrote.
Model: same selector as Text-to-SQL. Citation verification is deterministic (pure code), separate from the writing done by the LLM.
3. Data sent and egress
- The dashboard snapshot is sent (rows per widget), always inside a fence
<dados>, with column names and values treated as untrusted data. - No query runs on the datalake to answer — the analysis is over the already materialized snapshot (zero data cost).
- The number of rows per widget follows the egress policy: a cap of up to 50 rows, or, with row sending turned off, no raw rows — only a statistical summary per column (count, min/max/sum for numeric columns; number of distinct values for categorical ones).
- A widget that is a sample is flagged as such in the prompt (the AI is forbidden from stating totals/ rankings over a sample).
4. Privacy and retention
- The AI reads the same secure view as the screen: the member's RLS and PII masking are applied
before building the context (
secureViewForSession/secureRows). What the AI sees is never more than what the person asking sees. - The question is recorded in the audit log (questions about the dashboard), flagged when it was refused or
had weak evidence. Usage/cost goes in
ai.usage. - The active filters on the screen are echoed back from the deterministic side (never from the LLM), and
what the LLM says it considered is checked against the real filters (
divergencia).
5. Tokens, cost and budget
- Same reservation→settlement ledger and same monthly cap as the rest of the AI (see budget).
- The answer includes the formatted real cost (
custoBrlFormatado, e.g. "R$ 0,03") — including when the answer becomes a refusal after the call (it spent, it reports).
6. How to turn it on, who can use it and how to turn it off
POST /api/ai/dashboard-insights (with question) goes through: rate limit 10/60 s per
workspace (fail-closed) → workspace (401) → entitlement aiNarrative (Pro, 403) →
the access check and the AI insights capability check. General shutdown:
with sending to providers turned off, the answer falls back to the honest result (no made-up evidence).
7. Refusals
Three forms of refusal — an ungrounded answer does not come out as fact:
fora_do_contexto— a question that touches no term of the dashboard: refused before spending tokens (zero cost).sem_evidencia— the LLM answered, but no citation checks out against the data: it becomes a refusal; the real cost is settled.ia_indisponivel— no provider/error: honest fallback, empty citations, never fake evidence.evidenciaFraca— when most citations are bad, the answer comes out with a warning; only the citations that check out count as evidence.
8. Limitations and absence of causality
- It answers about the snapshot — if the dashboard is out of date, the answer reflects the old data (the date of the last refresh goes into the prompt and the AI is instructed not to treat it as "today").
- It does not claim cause and effect: it cites what the data shows; a correlation seen on the dashboard does not become "X caused Y".
- Over a sample, it is forbidden from stating total/sum/"highest"/"lowest"/"all".
9. How to validate
- A forged citation does not pass: put a text like "[W9.r9]" in a cell; check that it does not become a valid citation (verification uses the index of what traveled, not the model's text).
- Refusal without evidence: ask a question the dashboard does not support and confirm that the answer comes out as a refusal, not as fact.
- Secure view: confirm that a row filtered by RLS/PII does not appear in the answer.
- Minimal egress: with row sending turned off, check that only the statistical summary travels to the AI.
- Visible cost: the answer includes the formatted cost; compare it with the
ai.usageevent in the workspace audit log.