Pergunte a um chatbot “qual promoção devemos intensificar?” e ele responde em um fôlego: escolhe o número que parece melhor, afirma com confiança e para. Mas ele pode nunca verificar quantos dados sustentam aquele número. Uma promoção que parece ótima com 10 pedidos é muito menos convincente do que uma que se sai bem com 1.000 pedidos. Um analista sênior trabalha mais devagar de propósito: reformula a pergunta, forma hipótese, escreve a consulta e confere se há dados suficientes antes de falar com um executivo. Este tutorial mostra como colocar essa disciplina em código.
O que você vai construir
Um pequeno toolkit em Python que empurra uma pergunta por seis estágios em vez de um único prompt: entendimento de negócio, geração de hipóteses, planejamento de SQL, validação, resumo executivo e recomendações. O código funciona com a API da Anthropic ou da OpenAI — você traz a sua chave — e roda as mesmas seis etapas sobre qualquer tabela.
✅ O que você ganha
- Um analista que checa o tamanho da amostra antes de concluir qualquer coisa.
- Raciocínio rastreável: cada conclusão vem de uma consulta SQL que você pode inspecionar.
- Independência de provedor: o mesmo código roda com Claude ou GPT trocando uma variável.
- Um padrão reutilizável: os mesmos seis métodos valem para a próxima tabela que você apontar.
⚠️ O que você não ganha
- Não substitui um analista humano — a validação é uma regra em código, não julgamento de negócio.
- Não trata limpeza de dados nem modelagem estatística avançada.
- Os prompts são específicos para o formato JSON; você precisará ajustá-los para domínios muito diferentes.
A armadilha central: o “número bonito”
O exemplo do tutorial usa uma tabela com 29 pedidos e quatro promoções. Um GROUP BY simples ordenado por média de unidades coloca a promoção 4 no topo com média 8,00 — mas ela tem exatamente 1 pedido por trás. Uma resposta “em um fôlego” recomendaria a promoção 4 pela força de um único pedido. É essa armadilha que o pipeline inteiro é construído para capturar.
Os seis estágios, em ordem
1. Entendimento de negócio
O primeiro estágio reformula a pergunta em termos que a tabela pode de fato responder, nomeia o “grão” dos dados (o que cada linha representa) e lista limitações — tamanho de amostra, cobertura de datas, dimensões ausentes. No exemplo, o modelo sinalizou a amostra pequena antes de rodar uma única consulta.
2. Geração de hipóteses
O segundo estágio propõe hipóteses específicas e testáveis usando apenas as colunas existentes. Repare que a hipótese testada não é uma média crua: pergunta se o líder de volume vence o segundo colocado por uma margem real.
3. Planejamento de SQL
O terceiro estágio transforma a hipótese em consulta DuckDB. O prompt pede explicitamente um COUNT(*) nomeado n_orders ao lado de qualquer métrica agrupada, porque o tamanho do grupo é o que a validação confere em seguida.
4. Validação
O quarto estágio executa a consulta e checa n_orders contra um limite mínimo de suporte (no exemplo, 3). É o único estágio que é código puro, sem chamada ao modelo — porque a checagem precisa ser imposta, não sugerida.
5. Resumo executivo
O quinto estágio escreve o resumo, instruído a deixar qualquer linha de baixa confiança fora da afirmação principal.
6. Recomendações
O sexto estágio propõe ações, com a mesma regra: nenhuma recomendação pode se apoiar em dados de baixa confiança ou fatos que o resumo não sustentou. Se a evidência é fraca, o correto é recomendar mais análise.
O porquê de cada decisão
Um detalhe importante é o wrapper de LLM: ele recebe o provedor explicitamente e chama o método correspondente, escondendo os formatos de resposta de cada API atrás de um único complete(). Um helper separado extrai o JSON da resposta — tirando crases de bloco de código e fazendo fallback para o primeiro objeto válido. Isso torna o pipeline tolerante a erros de formatação comuns dos modelos sem deixar um JSON inválido passar silenciosamente.
Comparativo: um prompt vs. o pipeline
| Abordagem | Checa amostra | Rastreável | Imune a “número bonito” |
|---|---|---|---|
| Prompt único | Não | Não | Não |
| Pipeline de 6 estágios | Sim (validação) | Sim (SQL explícito) | Sim |
FAQ
Preciso de uma chave de API? Sim — o pipeline se recusa a rodar se você esquecer de colar uma chave real. Ele funciona com Anthropic ou OpenAI.
Preciso de um banco de dados? Não. O exemplo usa DuckDB, que roda SQL real sobre um DataFrame do Pandas sem servidor.
Funciona com outras tabelas? Sim — basta apontar o pipeline para outra tabela; os mesmos seis estágios rodam.
Qual é a peça mais importante? O estágio de validação, entre a consulta e o resumo. É ele que transforma um “palpite confiante” em uma resposta verificada.
O valor do pipeline não está na complexidade de cada etapa — reformular pergunta, escrever SQL e resumir tabela são coisas que um único prompt já faz razoavelmente bem. O valor está na validação entre a consulta e o resumo, checando o tamanho da amostra antes que qualquer coisa seja chamada de resposta.
Descubra mais sobre noticiAI
Assine para receber nossas notícias mais recentes por e-mail.
