Agro Intelligence BR

01 · leitura rápida

Resumo para decidir se vale aprofundar.

Skill e pacote Python para consultas auditáveis em linguagem natural a estatísticas agropecuárias brasileiras (IBGE/SIDRA). Núcleo determinístico resolve códigos, executa, valida e compõe a resposta; recusa explícita fora do recorte validado.

02 · narrativa do percurso

O campo, a rota e o que foi aprendido.

Dados públicos são abundantes. Respostas confiáveis nem sempre.

O Brasil oferece uma quantidade enorme de dados públicos sobre a produção agropecuária. Encontrar um número, porém, é apenas uma parte do problema. Antes de transformá-lo em resposta, é preciso entender o que a fonte realmente mede, qual unidade está sendo usada, a que período e geografia o dado se refere e até onde aquela informação permite chegar.

O Agro Intelligence BR nasceu dessa preocupação: criar uma forma auditável de consultar estatísticas agropecuárias brasileiras em linguagem natural sem deixar que a flexibilidade de um modelo de IA substitua as regras necessárias para lidar com os dados.

Tipo: skill e pacote Python
Área: dados públicos, APIs, IA aplicada
Estado: v0.1.0
Fonte inicial: IBGE/SIDRA
Recorte validado: soja em grão, PAM 1612, quantidade produzida, Brasil e Unidades da Federação

O problema

Perguntar “quanto o Brasil produziu de soja em determinado ano?” parece simples.

Para um sistema, a pergunta envolve uma sequência de decisões: identificar a pesquisa correta, localizar códigos e classificações oficiais, resolver período e território, consultar a fonte, validar a resposta, interpretar unidades e só então comunicar o resultado.

Um modelo de linguagem é muito bom em compreender a intenção de uma pergunta. Isso não significa que deva decidir sozinho quais números utilizar ou preencher o que a fonte não respondeu.

Esse foi o problema central do projeto: como combinar uma interface flexível em linguagem natural com um processo de consulta que permaneça verificável?

A hipótese

Minha hipótese foi separar claramente as responsabilidades.

A IA poderia interpretar o que a pessoa quer saber e ajudar a apresentar o resultado. A obtenção e o tratamento dos dados, por outro lado, deveriam seguir um núcleo controlado, com contratos explícitos sobre o que o sistema sabe responder.

Em vez de começar pela ambição de “responder qualquer coisa sobre o agro”, escolhi um recorte pequeno o suficiente para ser validado com rigor.

A primeira versão cobre uma combinação específica: soja em grão, Pesquisa Agrícola Municipal 1612 do IBGE, quantidade produzida, Brasil e UFs.

A restrição é intencional. Antes de ampliar o território de perguntas, eu queria ter confiança no caminho percorrido por cada resposta.

Meu papel

Concebi o recorte do projeto, estruturei a arquitetura, desenvolvi o núcleo de consulta, organizei os contratos de capacidade e documentação e defini os mecanismos de evidência, validação e recusa.

Uma parte importante do trabalho não foi ensinar o sistema a responder mais. Foi ensinar o sistema a reconhecer quando não deveria responder.

Como funciona

O fluxo separa compreensão, execução e comunicação.

1. A pergunta chega em linguagem natural

O modelo interpreta a intenção e identifica os elementos necessários para a consulta.

2. O núcleo resolve a consulta

A camada determinística transforma essa intenção em parâmetros e códigos compatíveis com o contrato validado.

Ela é responsável por executar a consulta, validar os dados retornados, realizar as transformações permitidas e preparar o resultado.

3. A resposta é construída apenas com dados entregues pelo núcleo

O modelo não recebe liberdade para criar números ausentes.

Se o núcleo não forneceu determinado valor, ele não pode aparecer na resposta final.

4. A evidência acompanha a resposta

Quando necessário, é possível inspecionar os elementos que sustentaram o resultado, incluindo códigos oficiais, URLs consultadas, transformações realizadas e o payload bruto da fonte.

Isso permite sair de “a IA disse” para “é possível verificar como essa resposta foi produzida”.

Uma decisão importante: capacidade também é saber recusar

Sistemas de IA costumam ser avaliados pelo número de coisas que conseguem responder. Neste projeto, tratei a recusa como parte da qualidade.

O contrato v0.1 estabelece um domínio conhecido. Fora dele, o sistema deve explicar por que não pode fornecer uma resposta validada.

Isso inclui, por exemplo:

• previsão de safra;
• previsão de preços;
• recomendação de investimento;
• perguntas fora das culturas, métricas ou geografias já cobertas pelo contrato.

A resposta correta, nesses casos, pode ser reconhecer o limite.

Esse desenho evita transformar dados históricos oficiais em previsões ou recomendações que a fonte não sustenta.

Por que um núcleo determinístico?

O projeto parte de uma distinção que considero importante em sistemas com IA.

Compreender uma pergunta é diferente de provar uma resposta.

Modelos de linguagem ajudam muito na primeira tarefa. Para a segunda, em um domínio baseado em estatísticas oficiais, preferi usar código, contratos, validações e testes.

Isso cria uma divisão clara:

Modelo de IA

• interpreta a intenção;
• ajuda a estruturar a consulta;
• comunica o resultado.

Núcleo determinístico

• resolve códigos;
• consulta a fonte;
• valida os retornos;
• calcula apenas o que está previsto;
• produz os dados usados na resposta;
• mantém a trilha de evidência.

A IA amplia a usabilidade do sistema sem substituir a fonte nem o mecanismo que sustenta os números.

Tecnologias e ferramentas

O projeto combina:

• Python 3.11 ou superior;
• integração com IBGE/SIDRA;
• skill para agentes de IA;
• contratos de capacidade;
• exemplos estruturados de execução;
• documentação de arquitetura, evidência, proveniência, limitações e roadmap;
• testes automatizados com pytest.

A tecnologia é importante, mas não é o centro do projeto. O elemento principal é o contrato entre linguagem natural, código e fonte de dados.

Evidências e validação

A versão 0.1.0 passou por uma auditoria de prontidão antes de entrar no portfólio.

No estado verificado:

• 233 testes automatizados foram aprovados;
• a release v0.1.0 foi criada e verificada;
• o repositório público está sob licença MIT;
• exemplos JSON de execução estão disponíveis;
• documentação específica descreve arquitetura, capacidade, evidência, proveniência, limitações e roadmap;
• materiais internos de planejamento permaneceram fora do repositório público.

A evidência de funcionamento, portanto, não depende apenas de uma demonstração visual. O comportamento esperado está documentado e coberto por testes.

O que o projeto não pretende fazer

O Agro Intelligence BR ainda não é uma plataforma geral de inteligência agropecuária.

A versão atual não afirma suportar qualquer cultura, qualquer indicador ou qualquer tipo de análise disponível no SIDRA.

Também não é:

• ferramenta de previsão de safra;
• modelo de previsão de preços;
• sistema de recomendação financeira;
• substituto da interpretação especializada de estatísticas agropecuárias.

O contrato v0.1 é deliberadamente estreito.

Novas culturas, métricas, fontes e tipos de análise só devem ser incorporados quando tiverem seus próprios contratos semânticos e testes.

O que este projeto demonstra

Mais do que uma interface para consultar uma API, o Agro Intelligence BR representa uma maneira de pensar sistemas de IA conectados a dados.

Ele demonstra que é possível usar linguagem natural sem abrir mão de:

• escopo explícito;
• proveniência;
• validação;
• rastreabilidade;
• testes;
• e limites comunicados ao usuário.

A intenção não é fazer a IA parecer que sabe tudo.

É construir um sistema que consiga mostrar o que sabe, de onde veio e até onde aquela resposta pode ser sustentada.

Estado atual

A versão v0.1.0 está pública, documentada e testada.

O próximo desenvolvimento não é simplesmente aumentar o volume de respostas. A expansão depende da criação de novos contratos para culturas, indicadores, geografias, fontes ou operações adicionais.

A infraestrutura pode crescer. O princípio permanece o mesmo: nenhuma nova capacidade entra apenas porque tecnicamente é possível consultá-la.

Aprofundar

Ver código e documentação no GitHub

Documentação técnica sobre capacidade, evidência, proveniência e limitações disponível no repositório.

Versão pública: v0.1.0