Selo
- Motor: Usa LLM (Anthropic)
- Maturidade: Preview
- Medição: NOT_MEASURED (qualidade/latência de IA real em produção)
1. O que faz
Você faz uma pergunta livre sobre um painel ("qual cliente mais cresceu?") e a IA responde apenas com base no snapshot já materializado — cada afirmação vem acompanhada de citações verificáveis para os dados que a sustentam.
2. Determinístico ou LLM?
Híbrido: LLM + verificação determinística. O LLM redige a resposta, mas quem decide
se a resposta tem lastro é código puro. Cada widget enviado ganha um id [W1], [W2]… e
cada linha um sub-id [W1.r3]; o LLM é obrigado a citar esses ids, e verificarCitacoes
confere cada citação contra o índice do que realmente viajou no prompt — não contra o
texto que o modelo escreveu.
Modelo: mesmo seletor do Text-to-SQL. A verificação das citações é determinística (código puro), separada da redação feita pelo LLM.
3. Dados enviados e egress
- Vai o snapshot do painel (linhas por widget), sempre dentro de fence
<dados>, com os nomes de coluna e valores tratados como dado não confiável. - Nenhuma query roda no datalake para responder — a análise é sobre o snapshot já materializado (custo zero de dados).
- A quantidade de linhas por widget respeita a política de egress: teto de até 50 linhas, ou, com o envio de linhas desligado, nenhuma linha crua — só um resumo estatístico por coluna (contagem, min/max/soma para numéricas; nº de distintos para categóricas).
- Widget que é amostra é marcado como tal no prompt (a IA é proibida de afirmar total/ ranking sobre amostra).
4. Privacidade e retenção
- A IA lê a mesma visão segura da tela: RLS do membro e mascaramento de PII aplicados
antes de montar o contexto (
secureViewForSession/secureRows). O que a IA vê nunca é mais do que quem perguntou vê. - A pergunta é registrada no registro de auditoria (perguntas sobre o painel), com marca quando foi recusada ou
teve evidência fraca. O uso/custo vai em
ai.usage. - Os filtros ativos da tela voltam ecoados do lado determinístico (nunca do LLM), e o
que o LLM diz ter considerado é conferido contra os filtros reais (
divergencia).
5. Tokens, custo e orçamento
- Mesmo ledger reserva→liquidação e mesmo teto mensal do resto da IA (ver orçamento).
- A resposta traz o custo real formatado (
custoBrlFormatado, ex.: "R$ 0,03") — inclusive quando a resposta vira recusa depois da chamada (gastou, reporta).
6. Como ligar, quem pode usar e como desligar
POST /api/ai/dashboard-insights (com question) passa por: rate limit 10/60 s por
workspace (fail-closed) → workspace (401) → entitlement aiNarrative (Pro, 403) →
A verificação de acesso e a verificação de capacidade insights de IA. Desligamento geral
com o envio a provedores desligado, a resposta cai no resultado honesto (sem inventar evidência).
7. Recusas
Três formas de recusa — a resposta sem lastro não sai como fato:
fora_do_contexto— pergunta que não toca nenhum termo do painel: recusa antes de gastar token (custo zero).sem_evidencia— o LLM respondeu, mas nenhuma citação confere contra o dado: vira recusa; o custo real é liquidado.ia_indisponivel— sem provider/erro: fallback honesto, citações vazias, nunca evidência fingida.evidenciaFraca— quando a maioria das citações é ruim, a resposta sai com aviso; só as citações que conferem entram como evidência.
8. Limitações e ausência de causalidade
- Responde sobre o snapshot — se o painel está desatualizado, a resposta reflete o dado antigo (a data do último refresh vai no prompt e a IA é instruída a não tratar como "hoje").
- Não afirma causa e efeito: cita o que os dados mostram; correlação vista no painel não vira "X causou Y".
- Sobre amostra, é proibida de afirmar total/soma/"maior"/"menor"/"todos".
9. Como validar
- Citação forjada não passa: inclua numa célula um texto como "[W9.r9]"; confira que ele não vira citação válida (a verificação usa o índice do que viajou, não o texto do modelo).
- Recusa sem evidência: faça uma pergunta que o painel não sustenta e confirme que a resposta sai como recusa, não como fato.
- Visão segura: confirme que uma linha filtrada por RLS/PII não aparece na resposta.
- Egress mínimo: com o envio de linhas desligado, confira que só o resumo estatístico viaja para a IA.
- Custo visível: a resposta traz o custo formatado; confronte com o evento
ai.usageno registro de auditoria do workspace.