Engine: Uses an LLM (Anthropic)
1. What it does
With one click, the AI reads the dashboard snapshot and produces an executive summary: headline, highlights, possible anomalies, and actionable recommendations — all in Portuguese.
2. Deterministic or LLM?
LLM. It's a generation with structured output: headline, highlights[], anomalies[],
recommendations[]. Same model selector as Text-to-SQL. With no provider
in dev/preview → a simple deterministic summary; in production with no provider → 503 (production
guard).
Note: the
anomaliessection here is LLM text about the snapshot, not the deterministic detector. Statistical anomaly detection is a separate capability — see Anomalies.
3. Data sent and egress
- The dashboard snapshot is sent per widget, inside a fence
<dados id="widget-N">. - No queries on the datalake (analysis runs on the snapshot; zero data cost).
- Same egress policy as Q&A: a row cap, sample marking, and with row sending turned off, only the statistical summary per column goes out (no raw rows).
- Each widget declares how many rows were sent, how many exist on the dashboard, and whether it's a sample — so the model doesn't claim a total while looking at 1,000 of 40,000 rows.
4. Privacy and retention
- Same safe view as Q&A (RLS + PII applied before the prompt).
- The dashboard insights audit log entry records the generation;
ai.usagerecords tokens/cost/ egress.
5. Tokens, cost, and budget
Same reservation→settlement ledger and monthly cap as the rest of the AI. See Privacy, external sending, budget, and shutdown.
6. How to turn it on, who can use it, and how to turn it off
POST /api/ai/dashboard-insights (without question): rate limit 10/60 s per workspace
(fail-closed) → workspace (401) → entitlement aiNarrative (Pro, 403) →
the active-workspace check → AI insights capability. Global shutdown:
sending to providers is turned off in the environment.
7. Refusals
- No data on the dashboard → doesn't call the LLM (nothing to analyze).
- Cap reached → 429 with a message, nothing spent.
- On a sample, it's forbidden to state a total/sum/ranking — it must say that the exact number requires aggregating in SQL.
8. Limitations and absence of causality
- The "anomalies" and "recommendations" are the LLM's reading, not a statistical test; treat them as hypotheses to investigate, not as proven facts.
- It doesn't establish causality: it describes what the numbers show; it doesn't claim that one thing caused another.
- It's based on the snapshot from the last refresh — it isn't real time.
9. How to validate
- Sample marking: materialize a dashboard with a truncated widget and check that the answer doesn't state a total while looking at a sample (it should say the exact number requires aggregating).
- Minimal egress: with row sending turned off, check that only the statistical summary travels to the AI.
- No provider: in dev without a key, check the deterministic summary; in production without a provider, check the 503 (production guard).
- Cost/usage: check the
ai.usageevent in the audit log and theproveniencia(model, prompt version, cost in BRL, opId) in the response.