Skip to content

Automatic translation — the Portuguese version is the reference. View in Portuguese

Updated on 2026-10-03

Report narrative — the "AI Analyst"

The executive text the AI writes in every scheduled report — what goes to the model, how much it costs, when it refuses, and why it never invents a change.

On this page (10)

Engine: Uses an LLM (Anthropic)


Where it is on screen

In AI → Reports, click New report. The AI narrative step is the second of five; once the report is created, Run now generates it right away. The step-by-step guide with every label is in Reports screens.

1. What it does

When a scheduled report is generated, the AI writes the executive narrative of the results: headline, summary, highlights (with change vs. the previous period), anomalies, and recommendations — in an executive or technical tone, in Portuguese.

2. Deterministic or LLM?

LLM, with structured output. It's the same generation triggered both by the screen and by the reports cron — that's why the budget ledger lives inside it, covering every caller.

With no provider in dev/preview → a deterministic mock narrative (it summarizes the numbers without inventing anything). In production with no model provider, the call fails with an explicit error instead of simulating. If the call fails, it falls back to the same mock narrative and the reserved budget is released.

3. Data sent and egress

  • What's sent is the results of the report's queries (current rows and rows from the previous period), inside a fence <dados>, subject to the egress policy (a cap of 50 rows per query, or a statistical summary when row sending is turned off).
  • Also sent is the free-form business context the customer wrote in the report — fenced as <dados id="contexto-do-negocio"> and treated as data, never as an instruction.
  • The report name and the period label are sent with fence tokens neutralized.

4. Privacy and retention

  • The report is the main product; the narrative is an add-on. The data the AI sees is the same data already materialized for the report.
  • Usage/cost goes to ai.usage; the report run stores the input and output tokens (the input total includes cache) for history.

5. Tokens, cost, and budget

  • Same reservation→settlement ledger and monthly AI spending cap.
  • If the cap is exceeded, the report is NOT aborted — the data goes out normally; only the narrative falls back to the deterministic summary and says why there was no AI.
  • Prompt caching: the analyst's rules are stable between runs (only the tone changes, between 2 values) and are reread at ~0.1× the price.

6. How to turn it on, who can use it, and how to turn it off

  • Available starting on the Growth plan. The full matrix is in Plans (5).
  • With sending to providers turned off, the narrative is deterministic and nothing leaves the platform.
  • In the cron, each run goes through the same ledger/cap per workspace.

7. Refusals

  • No useful results (all queries empty/with errors) → doesn't call the LLM; the mock narrative summarizes what happened (including listing the failed queries as "anomalies").
  • Cap reached → mock narrative with a clear notice (blocked: true), zero cost.

8. Limitations and absence of causality

  • Non-negotiable rule in the prompt: use only numbers present in the data; never estimate, extrapolate, or invent. With no previous period in the data, deltaPct is null and the narrative states that there's no basis for comparison — it never invents a change.
  • It doesn't claim causality: it describes changes and highlights; it doesn't conclude that one thing caused another.
  • The quality of the text depends on the quality of the data; the narrative doesn't fix wrong data.

9. How to validate

  • Grounding without invention: generate a report with no previous period and check that the change appears as "no basis for comparison," never as an invented number.
  • Shutdown: with sending to providers turned off, confirm that the narrative becomes the deterministic summary and nothing leaves the product.
  • The cap doesn't take down the report: force the budget cap and check that the data goes out and only the narrative is replaced by the deterministic summary.
  • Customer context is data, not instruction: include in the business context a text that tries to change the rules and confirm that the AI ignores it.

Related links