Sistema de análise de dados com IA

O sistema tem três camadas e o LLM só toca nas pontas. Na entrada, ele interpreta a pergunta. Na saída, ele narra o resultado. O meio, escolher métrica, montar consulta, executar, calcular, é determinístico. Essa fronteira é a decisão estruturante: tudo que precisa ser reprodutível ficou fora do modelo.

No centro está um dicionário semântico versionado em Git: cada métrica com fórmula, grão, dimensões permitidas, joins canônicos, sinônimos e marcação de coluna sensível. A pergunta passa por um retrieval sobre esse dicionário, embeddings de tabelas, colunas e valores de baixa cardinalidade, para que Sul case com a dimensão de região sem que o schema inteiro entre no contexto. Só o subconjunto relevante vai para o prompt; o bloco fixo de instruções fica em cache, o que segura o custo de token por turno.

Na execução, o limite mora no banco, não no prompt. Réplica read-only, role do usuário com RLS, statement_timeout e LIMIT injetado pelo compilador. Aprovada na validação estática, a consulta ainda passa por um EXPLAIN na réplica: se a estimativa de linhas do planejador estourar o orçamento, ela não é bloqueada, vira job em fila e volta por notificação. O cache de resultado é particionado por permissão: a chave é o hash do SQL canonicalizado mais o conjunto de roles e policies do usuário mais o watermark da última carga. Sem identidade na chave, cache e RLS se anulam, o mesmo SQL devolveria a um usuário as linhas materializadas com a permissão de outro. O porquê não é outra pergunta ao modelo: é uma rotina de decomposição de variância em DuckDB sobre o result set, separando efeito de mix e efeito de taxa. No fim, um verificador confere cada número do texto contra o conjunto de valores permitidos, células do result set mais as saídas da rotina analítica, com tolerância de arredondamento e unidade declarada. Número fora desse conjunto trava a resposta antes de ela chegar à tela.

A primeira coisa construída não foi o prompt: foram 120 perguntas de teste escritas à mão sobre um modelo de dados fictício de varejo, cada uma com o SQL gold correspondente, e uma suíte que compara result sets, não strings. Sem régua, mexer em prompt vira troca de opinião. Depois veio o dicionário semântico, tabela por tabela. Ele existe justamente para obrigar que a definição de receita líquida seja decidida por quem é dono da métrica; no protótipo, essa decisão foi modelada explicitamente em YAML, fórmula, grão, exclusões, sinônimos. O prompt foi a última peça a nascer.

O protótipo inicial fazia o óbvio: mandava o schema e pedia SQL. Funcionava na demonstração e falhava fora do roteiro dela. Fan-out em join um-para-muitos inflava receita sem erro visível, e a mesma pergunta reformulada produzia SQL diferente com número diferente. Trocar SQL livre por IR tipada foi a virada do projeto. A partir dali, join errado deixou de ser problema de prompt e virou bug de compilador, com teste de regressão, correção e diff.

O segundo ponto difícil foi o multi-turno. O porquê precisa herdar região e trimestre da pergunta anterior sem arrastar o resto do contexto junto. O estado virou uma pilha de filtros explícita, renderizada na tela, que o usuário pode soltar item a item. Segurança e auditoria entraram antes de qualquer apresentação, porque retrofitar RLS depois é reescrever a camada de execução, e a chave de cache só ganhou a role do usuário quando um teste com dois perfis fictícios de escopos diferentes recebeu o mesmo número: bug de cache, não de RLS. O plano de ação ficou por último; é o único lugar onde o modelo escreve texto longo, e mesmo lá cada item carrega a consulta que o sustenta.