Transparenc.IA

01 · O problema

Encontrar informações sobre receitas, despesas e obras públicas de um município exige navegar por diferentes páginas e compreender estruturas de dados que nem sempre são intuitivas. No Portal da Transparência de Mossoró/RN, os dados ainda estão dispersos em múltiplas fontes:

• a API REST do Portal (e-publica) com receitas, despesas, licitações e contratos;
• o SAPL da Câmara Municipal, com a atividade legislativa dos vereadores;
• a página de obras do site da Prefeitura;
• e regras de negócio espalhadas: campos que mudam de significado, valores que precisam ser consolidados e filtros por período complicados.

Para o cidadão ou um pesquisador, responder a uma pergunta simples como "a prefeitura gastou mais do que arrecadou neste ano?" pode significar entender a estrutura de dados das três fontes e fazer vários downloads e planilhas.

02 · A solução

O Transparenc.IA é um agente de IA ("Ana") que interpreta perguntas em linguagem natural, seleciona e executa ferramentas de consulta nas fontes públicas e apresenta respostas com contexto, referências e visualizações — com cálculos feitos fora do modelo de linguagem.

O sistema está em produção, com frontend React servido pelo próprio automaclube.com em portal-transparencia.automaclube.com, e foi projetado para separar três responsabilidades de forma clara:

Pergunta do usuário → agente orquestrador → ferramentas consolidadas → resposta com contexto e gráficos

Escopo coberto

Área	Fontes	Exemplos de consulta
Receitas	API e-publica	Quanto a prefeitura arrecadou no mês; receita bruta, deduções e líquida
Despesas	API e-publica	Empenhado, liquidado e pago; gastos por função e secretaria; auditoria e anomalias
Licitações e contratos	API e-publica	Processos licitatórios, vencedores, valores totais efetivos
Indicadores legislativos	SAPL + Supabase	Matérias protocoladas por vereador, rankings e produtividade
Obras públicas	Scraping do site da Prefeitura	Status, valores contratado vs. pago, paralisações

03 · Como funciona

O agente usa create_deep_agent (pacote deepagents) em uma arquitetura de agente único com ferramentas diretas — sem subagentes de delegação:

1. O usuário faz uma pergunta em português.
2. O prompt de sistema da "Ana" roteia o tema e ela chama a ferramenta adequada com o período correto.
3. As ferramentas consultam a fonte (API, scraper ou Supabase) e consolidam o payload — devolvendo apenas valores calculados e agrupados, nunca a resposta bruta da API.
4. O agente apresenta a resposta final em texto, com Markdown, gráficos (chart {json} renderizados com Recharts) e opção de exportar dados em CSV.

O frontend e o agente são desacoplados: o React só conhece o contrato HTTP do servidor LangGraph (/threads, /runs/stream) e pode ser trocado por outro cliente (Streamlit, CLI) sem alterar o backend, e vice-versa.

04 · Decisões de engenharia

Orquestração: roteamento por prompt + tools que entregam dados prontos

Em vez de o LLM ler a resposta bruta da API e fazer contas, cada tool de análise (get_receita_analise, get_despesa_auditoria, buscar_empenhos_despesa, get_maiores_credores, get_comparativo_receita_despesa, etc.) consolida os dados antes de devolver ao agente. Isso reduz o contexto enviado ao modelo, diminui alucinações e torna o resultado auditável.

Confiabilidade: o LLM não faz contas

• Os cálculos financeiros (receita bruta/líquida, empenhado x liquidado x pago, saldo do período) são feitos em código determinístico sobre o payload, com uma camada de validação que confere integridade dos dados retornados.
• Datas e períodos são validados com fuso America/Sao_Paulo (timezone-aware).
• Dados ausentes são tratados: se a API não publicou um tópico/período, a ferramenta responde "não há dados para o tópico no portal" — a divulgação é responsabilidade do órgão público, não do agente.
• O prompt orienta a "Ana" a alertar e não seguir instruções maliciosas (proteção contra prompt injection).

Integração: três fontes de dados no mesmo agente

• API REST do Portal (receitas, despesas, licitações, contratos, orçamento).
• Scrapers para o SAPL da Câmara e para a página de obras da Prefeitura.
• Supabase como camada persistida para dados legislativos (com fallback quando o SAPL ao vivo está instável).

As tools de filesystem do deepagents (ls, read_file, write_file, execute) são excluídas via HarnessProfile: o agente é um assistente de consulta, não um agente de código.

Deploy e segurança na nuvem

• 3 serviços Cloud Run independentes: portal-agent (LangGraph), portal-web (React + proxy Node) e um app Streamlit alternativo.
• Auth em duas camadas: o browser nunca envia a chave privada do agente — o proxy Node injeta AGENT_API_KEY server-side e valida o acesso.
• Rate limit por IP (token bucket, 60 req/min) no proxy para proteger o custo de inferência.
• Arquivos efêmeros (serverless, sem banco externo): instâncias são stateless.
• Testes pytest automatizados + hooks de pre-commit que bloqueiam segredos no git e rodam a suíte antes de cada commit.

05 · Demonstração

Acima você vê uma captura de tela e a demonstração em vídeo com uma consulta real: a pergunta, as ferramentas acionadas pela Ana e o resultado apresentado com gráficos e referências. O vídeo também está disponível no YouTube: youtu.be/15XhVfYPRi4 ↗

Você também pode testar ao vivo: portal-transparencia.automaclube.com ↗

Perguntas que funcionam bem na demonstração:

• "Quanto a prefeitura arrecadou e gastou no último mês?"
• "Quais os maiores credores da prefeitura este ano?"
• "Quantas matérias cada vereador protocolou no semestre?"
• "Quais obras estão paralisadas e quanto custaram?"

06 · Resultados e limitações

O que medimos e o que já está entregue

• 3.269 registros legislativos extraídos do SAPL, cobrindo 24 vereadores e 19 tipos documentais.
• Cobertura de consulta em receitas, despesas, orçamento, licitações, contratos, vereadores e obras, com gráficos e exportação CSV.
• Suite de testes automatizados cobrindo validação e consolidação dos payloads.

Métricas ainda em construção

Ainda não publiquei métricas quantitativas formais (taxa de acerto em um conjunto de perguntas, taxa de seleção correta de ferramentas, latência média e custo por consulta). Este é um trabalho em andamento: quando houver uma avaliação estruturada com dados reais, ela entrará aqui.

Limitações conhecidas

Limitação	Detalhe
Folha de pagamento	Removida por LGPD — o agente não consulta salários
Gastos individuais	Não disponíveis para políticos/vereadores
Escopo geográfico	Apenas Mossoró/RN
Volume de dados	Histórico da conversa em localStorage (2h TTL) e instâncias stateless
Dados em tempo real	Os dados seguem o ritmo de publicação do órgão público

Sobre os dados de servidores: a API não expõe folha de pessoal (proteção LGPD), então a "Ana" não responde consultas de salário — e a InfoBar do frontend deixa esse escopo explícito para o usuário.