MVP 2 — AI Insights — Auditoria de Precisão¶

Atualizado: 2026-05-18 Status: decisão aprovada para backlog executável Owner operacional: api; apoio platform, web

Decisão¶

AI Insights passa a ter auditoria de precisão baseada em snapshot financeiro determinístico, evidence manifest e versão de template. O modelo de linguagem não calcula fatos, riscos, saúde financeira, metas, comparativos nem custos. A API calcula esses elementos, valida evidências e usa o GPT apenas para explicar o resultado em linguagem clara.

O insight continua sendo account-wide, mas cada item retornado declara sua dimensão (transactions, budgets, goals, credit_cards, cashflow) para que Dashboard, Transações, Orçamentos, Metas, Cartões e /insights renderizem somente o contexto relevante de cada superfície.

Princípios¶

A API é a fonte factual: totais, comparações, riscos, metas, compromissos, custos e qualidade dos dados devem ser calculados antes do prompt.
O GPT explica, resume e prioriza; ele não soma linhas, não infere saúde financeira e não decide risco sem campos determinísticos no snapshot.
Cada afirmação renderizável deve apontar para evidências existentes no snapshot ou no manifest persistido.
Preview e dossiê de auditoria não chamam GPT para manter custo baixo.
Prompt bruto não deve ser persistido como artefato de produto em produção. Auditoria usa snapshot sanitizado, resposta estruturada, manifest e versão de template.
Snapshots auditáveis têm retenção curta, entram no registry LGPD e devem ser removidos na deleção total da conta.

Modelo de run¶

Criar AIInsightRun como store proprio de execucao, separado de AIInsight (store exibivel) e LLMAuditLog (auditoria de custo/tokens).

Campos minimos:

Campo	Uso
`id`	identificador do run/preview
`user_id`	dono do dado, registrado no registry LGPD
`ai_insight_id`	nullable no preview; preenchido quando gerar insight
`status`	`previewed`, `generated`, `cached`, `rejected`, `blocked`, `failed`, `purged`
`period_type`, `period_start`, `period_end`, `period_label`	recorte auditado
`snapshot_schema_version`	ex.: `financial_insight_snapshot.v2`
`snapshot_hash`	hash do snapshot sanitizado usado na decisao
`previous_snapshot_hash`	hash estruturado anterior, quando existir
`prompt_template_version`	versao do template usado na geracao
`model`	modelo configurado quando houver chamada GPT
`tokens_in`, `tokens_out`, `tokens_total`	custo tecnico do LLM
`cost_usd`	custo estimado ou real da chamada
`data_quality`	flags de ausencia/baixa confiabilidade de dados
`rejection_reasons`	validacoes que impediram persistencia exibivel
`truncation_flags`	campos truncados antes de prompt/resposta
`created_at`, `expires_at`, `purged_at`	governanca de retencao

O snapshot persistido deve ser sanitizado. Pode guardar valores financeiros, datas, categorias, status e descricoes truncadas, mas nao deve guardar nome, email, telefone, documento, external_id, ids internos reais desnecessarios nem observacoes livres longas.

Evidence manifest¶

Cada run deve persistir um manifest de evidencias derivado do snapshot:

{
  "snapshot_hash": "sha256:...",
  "template_version": "financial-insight.v2.2026-05-18",
  "evidence": {
    "dimensions.transactions.current_period.paid.expense_total": {
      "label": "Despesas pagas no periodo",
      "value": "21125.00",
      "currency": "BRL"
    },
    "dimensions.goals.car.required_monthly_pace": {
      "label": "Ritmo mensal necessario da meta",
      "value": "850.00",
      "currency": "BRL"
    }
  },
  "data_quality": {
    "has_transactions": true,
    "missing_comparison_periods": []
  }
}

O validador deve rejeitar ou marcar como rejected respostas que citem fatos sem evidencia compatível. Exemplo: um item de goals nao pode usar apenas dimensions.transactions.current_period.paid.expense_total para afirmar que uma meta esta em risco.

Preview sem GPT¶

Auditoria inicial sera backend-only por endpoint admin e CLI.

Endpoint alvo:

POST /admin/ai/insights/preview
Content-Type: application/json

{
  "user_id": "uuid",
  "period_type": "monthly",
  "anchor_date": "2026-05-18"
}

Resposta esperada:

{
  "run_id": "uuid",
  "snapshot_hash": "sha256:...",
  "snapshot": {},
  "comparisons": {},
  "risks": [],
  "evidence_manifest": {},
  "data_quality": {},
  "llm_called": false,
  "cost_usd": "0.00000000"
}

Regras:

preview nao consome quota diaria;
preview nao chama LLM;
preview cria AIInsightRun com status=previewed;
usuario comum nao acessa endpoint admin;
preview pode ser exportado em dossie JSON/HTML local via CLI.

Geracao com preview_run_id¶

Endpoint alvo:

POST /ai/insights/generate
Content-Type: application/json

{
  "period_type": "monthly",
  "anchor_date": "2026-05-18",
  "preview_run_id": "uuid"
}

Se preview_run_id for informado, a geracao deve usar o mesmo snapshot_hash. Se o snapshot atual divergir, a API deve bloquear ou recriar o preview explicitamente para evitar auditar um conjunto de fatos e gerar outro.

Cache/idempotencia deve preferir snapshot_hash: se o snapshot e o template nao mudaram, retornar insight existente sem nova chamada GPT.

Dossie de auditoria¶

CLI alvo:

flask ai export-insight-dossier \
  --user-id <uuid> \
  --period-type monthly \
  --anchor-date 2026-05-18 \
  --format json

O dossie deve conter:

metadados do run;
snapshot sanitizado;
evidence manifest;
riscos/saude/metas deterministicas;
resposta estruturada do modelo quando houver;
validacoes, rejeicoes e truncamentos;
custo/tokens vinculados a LLMAuditLog;
marcadores de retencao e expurgo.

HTML local e somente ferramenta operacional; nao e produto final. O Admin Front End fica como fase 2, bloqueado ate API/CLI provarem que a auditoria manual virou rotina.

Saude financeira, riscos e metas¶

Calcular deterministicamente na API:

risco de orcamento por categoria e geral;
risco de cartao por fatura, vencimento, fechamento e comprometimento;
vencidos e pendentes separados de gastos pagos;
saldo e compromissos futuros;
metas com progresso total, prazo, valor restante, ritmo necessario e ritmo observado.

Regra de produto: recorte semanal ou mensal isolado nao pode afirmar que uma meta esta boa ou ruim sem considerar progresso total, prazo e ritmo necessario. Quando os dados nao sustentarem conclusao, data_quality deve sinalizar insuficiencia.

Governanca de custo¶

Preview e dossie nao chamam GPT.
Geracao respeita orcamento diario/mensal em USD configuravel.
Circuit breaker bloqueia chamada GPT ao atingir orcamento, mas ainda permite preview/dossie.
LLMAuditLog ou agregacao derivada e a fonte de verdade de custo.
Logs e metricas devem mostrar custo por run, tokens, cache hit, bloqueio por budget e custo acumulado por janela.

LGPD e retencao¶

AIInsightRun e snapshots auditaveis entram no registry LGPD como dados financeiros derivados e artefatos de auditoria de IA.

Politica padrao:

retencao de snapshots auditaveis por 30 dias;
exportabilidade em pacote de dados do titular enquanto existirem;
delecao total da conta remove runs, snapshots, manifests e dossies vinculados;
LLMAuditLog pode manter agregados tecnicos necessarios, desde que sem PII, sem prompt bruto e sem snapshot financeiro reidentificavel.

Observabilidade¶

Metricas minimas:

ai_insight_runs_total{status,period_type};
ai_insight_cost_usd_total{model,period_type};
ai_insight_tokens_total{model,period_type,direction};
ai_insight_rejections_total{reason};
ai_insight_truncations_total{field};
ai_insight_data_quality_total{flag};
ai_insight_purges_total{status};
ai_insight_budget_block_total{window}.

Alertas minimos:

custo diario/mensal acima do orcamento;
rejeicao alta de respostas;
truncamento frequente;
falha de expurgo;
degradacao de qualidade de dados.

Logs estruturados devem incluir run_id, snapshot_hash, periodo, status, tokens e custo, sem PII e sem prompt bruto.

Backlog executavel¶

Repo	Issue	Escopo
auraxis-platform	#695	documentacao e backlog de auditoria
auraxis-api	#1310	`AIInsightRun` e dossie auditavel com retencao LGPD
auraxis-api	#1311	preview e export de dossie backend-only
auraxis-api	#1312	saude financeira, riscos e metas deterministicas
auraxis-api	#1313	governanca de custo e circuit breaker
auraxis-api	#1314	observabilidade de runs, evidencias, rejeicoes e expurgo
auraxis-web	#884	Admin Front End fase 2, bloqueado