Agente de Análise de Notas Fiscais

Este projeto implementa um agente de IA utilizando LangChain e Streamlit para permitir que usuários façam perguntas em linguagem natural sobre dados de notas fiscais contidos em arquivos CSV. O agente é capaz de descompactar, carregar e analisar os dados para fornecer respostas precisas.

Objetivo do Projeto

O objetivo principal é criar um agente de IA que possibilite aos usuários interagir com dados de notas fiscais (cabeçalho e itens) por meio de perguntas em linguagem natural. Em vez de análises manuais ou prompts diretos para LLMs genéricos, o agente automatiza a extração e a consulta de dados, fornecendo respostas baseadas nos CSVs fornecidos.

Funcionalidades

• Upload de Arquivo ZIP: Permite o upload de um arquivo ZIP contendo os CSVs de cabeçalho e itens das notas fiscais.

• Extração e Carregamento de Dados: Descompacta automaticamente o arquivo ZIP e carrega os dados dos CSVs (202401_NFs_Cabecalho.csv e 202401_NFs_Itens.csv) em DataFrames pandas.

• Agente de Análise de Dados: Utiliza um agente LangChain com o modelo Google Gemini Flash e uma ferramenta Python REPL para executar consultas nos DataFrames.

• Interação em Linguagem Natural: Os usuários podem fazer perguntas complexas sobre os dados, e o agente as traduzirá em operações Python para obter as respostas.

• Exibição do Pensamento do Agente: Um expander na interface do usuário permite visualizar o raciocínio do agente (código Python gerado e executado).

• Formatação Amigável de Respostas: As respostas são formatadas de maneira clara, incluindo contexto e formatação de valores monetários.

Como Usar o Agente

Pré-requisitos

Certifique-se de ter o uv (ou pip) instalado para gerenciar as dependências.

• Python 3.11 ou superior

• Chave de API do Google Gemini

Configuração da Chave de API

Você pode configurar sua chave de API do Google Gemini de duas maneiras:

1. Arquivo .env (para desenvolvimento local): Crie um arquivo .env na raiz do projeto com o seguinte conteúdo:

GOOGLE_API_KEY="SUA_CHAVE_AQUI"

2. Streamlit Secrets (para deploy): Crie um arquivo .streamlit/secrets.toml na raiz do projeto (se não existir) e adicione:

GOOGLE_API_KEY="SUA_CHAVE_AQUI"

Instalação

1. Clone o repositório:

git clone https://github.com/seu-usuario/seu-projeto.git cd seu-projeto

2. Instale as dependências usando uv:

uv sync

Ou usando pip:

pip install -r requirements.txt # Se você gerar um requirements.txt

Executando o Aplicativo

1. Inicie o aplicativo Streamlit:

streamlit run src/app.py

2. O aplicativo será aberto no seu navegador padrão.

Interagindo com o Agente

1. Faça o Upload do Arquivo: Na interface do Streamlit, clique em "Selecione o arquivo 202401_NFs.zip" e faça o upload do arquivo ZIP fornecido (geralmente localizado na pasta dados/). O arquivo ZIP deve conter 202401_NFs_Cabecalho.csv e 202401_NFs_Itens.csv.

2. Aguarde o Carregamento: O aplicativo irá descompactar e carregar os arquivos CSV. Você verá uma mensagem de sucesso quando os dados estiverem prontos.

3. Faça Suas Perguntas: No campo de chat na parte inferior, digite suas perguntas em linguagem natural sobre os dados das notas fiscais.

Exemplos de perguntas:

• "Qual é o fornecedor que teve maior montante recebido?"

• "Qual item teve maior volume entregue (em quantidade)?"

• "Qual o valor total das notas fiscais emitidas pela 'EMPRES BRASILEIRA DE CORREIOS E TELEGRAFOS'?"

• "Qual a média de valor unitário dos produtos vendidos pelo 'MINISTERIO DA SAUDE'?"

• "Qual a raiz quadrada da quantidade média de itens por nota fiscal?"

4. Visualize o Pensamento do Agente: Após fazer uma pergunta, um expander "Ver o Pensamento do Agente" aparecerá, mostrando o código Python que o agente gerou e executou para responder à sua pergunta.

5. Reiniciar Conversa: Use o botão "Reiniciar Conversa" para limpar o histórico do chat e recarregar os dados, se necessário.

Estrutura do Projeto

├── .env                  # Variáveis de ambiente (para chave de API)
├── .gitignore            # Arquivos e pastas a serem ignorados pelo Git
├── pyproject.toml        # Gerenciamento de dependências (uv)
├── dados/                # Pasta para os arquivos de dados
│   ├── perguntas.py      # Exemplo de perguntas (se houver)
│   ├── 202401_NFs_Cabecalho.csv # Exemplo de arquivo de cabeçalho (não incluído no repo, mas esperado no ZIP)
│   └── 202401_NFs_Itens.csv     # Exemplo de arquivo de itens (não incluído no repo, mas esperado no ZIP)
├── src/                  # Código fonte da aplicação
│   ├── app.py            # Aplicação Streamlit principal
│   ├── file_handler.py   # Lógica para manipulação de arquivos ZIP e CSV
│   └── agent_creator.py  # Lógica para inicialização do LLM e criação do agente
└── .streamlit/           # Configurações do Streamlit
    └── secrets.toml      # Secrets do Streamlit (para chave de API em deploy)

Dependências

As dependências são gerenciadas pelo uv e listadas em pyproject.toml:

• langchain

• langchain-community

• langchain-experimental

• langchain-google-genai

• pandas

• python-dotenv

• streamlit

Desenvolvimento

• src/app.py: Ponto de entrada da aplicação Streamlit. Gerencia a interface do usuário, upload de arquivos, exibição do chat e invocação do agente.

• src/file_handler.py: Contém a função extract_zip_and_load_csvs responsável por descompactar o arquivo ZIP e carregar os CSVs em DataFrames pandas.

• src/agent_creator.py: Contém as funções initialize_llm para configurar o modelo Google Gemini Flash e create_data_analysis_agent para configurar e retornar o agente LangChain com as ferramentas e o prompt personalizados.

Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests.

Licença

Este projeto está licenciado sob a licença MIT.