Agente de Inteligência Artificial para instrução de Processo para Registro de Importação
Status do Projeto: Concluído (Entregue e em evolução contínua)
Desenvolvimento de um agente de Inteligência Artificial capaz de elaborar a instrução de registro aduaneiro com as informações pertinentes do material que relacione: Part-Number, classificação fiscal, fabricante, origem do fabricante com endereço completo, gerando a informação da descrição do material, de forma que permita a receita federal entender o que é o produto e não gere dúvidas sobre o item o e não acarrete penalidades e/ou multas sobre o material declarado.
O projeto foi feito seguindo o método Ágil SCRUM, dividindo o trabalho em sprints de 21 dias, com reuniões diáras, revisões e retrospectivas ao final.
| Sprint | User Story | Status | Prioridade |
|---|---|---|---|
| 1 | Como analista fiscal, quero enviar um Partnumber ao sistema para receber informações detalhadas do produto. | CONCLUÍDA | ▲ Alta |
| 2 | Como analista fiscal, quero enviar um PDF com pedidos de compras para que o sistema extraia os Part Numbers automaticamente... | CONCLUÍDA | ▲ Alta |
| 2 | Como analista fiscal, quero que o sistema atribua automaticamente NCM e alíquota aos itens extraídos, para acelerar o processo de importação. | CONCLUÍDA | ▲ Alta |
| 2 | Como usuário, quero acessar o status da minha requisição de classificação | CONCLUÍDA | = Média |
| 3 | Como usuário, quero autenticar no sistema para acessar minhas operações com segurança. | CONCLUÍDA | ▲ Alta |
| 3 | Como usuário autenticado, quero exportar minhas operações para Excel, para usá-las no registro oficial de importação. | CONCLUÍDA | = Média |
| 3 | Como usuário autenticado, quero acessar o histórico de minhas operações para reaproveitar informações em importações futuras. | CONCLUÍDA | = Média |
| Sprint | Prazo | Status | Documentação | Entrega |
|---|---|---|---|---|
| Kick Off | 25/08/2025 | Concluído | - | - |
| Sprint 1 | 28/09/2025 | Concluído | sprint1 | video |
| Sprint 2 | 26/10/2025 | Concluído | sprint2 | video |
| Sprint 3 | 23/11/2025 | Concluído | sprint3 | video |
| Feira de Soluções | 04/12/2025 | Não iniciado | feira | - |
| Cliente | Período/Curso | Professor M2 | Professora P2 | Contato Cliente |
|---|---|---|---|---|
| Creonice Honório - Empresa TecSys | 4º Análise e Desenvolvimento de Sistemas | Giuliano Bertoti | Juliana Pasquini | creonice@tecsysbrasil.com.br |
Arquitetura orientada a eventos e altamente desacoplada, mantendo foco em experiência do usuário, confiabilidade e integração transparente com IA. . Cada componente possui responsabilidades bem definidas e se comunica através de APIs REST, WebSockets e um broker de mensagens via Redis, conforme detalhado nos documentos de arquitetura.
Para detalhes da implementação: Documento da Arquitetura
Abaixo você encontra os links para a documentação específica de cada serviço.
🔹 Nexa API
O Nexa-api é o orquestrador central da aplicação. Construído em Python com Flask, ele atua como o API Gateway, gerenciando todas as requisições do cliente, a lógica de negócio principal e a comunicação assíncrona com os outros serviços.
Principais Responsabilidades:
- Endpoints REST: Expõe os endpoints para o frontend, incluindo
/upload-pdfpara o envio de documentos e/classify-partnumberpara classificações individuais. - Orquestração Assíncrona: Utiliza Celery e Redis para enfileirar tarefas pesadas (como o parsing de PDFs e as chamadas para a IA), mantendo a API sempre responsiva.
- Comunicação em Tempo Real: Gerencia a comunicação via WebSocket (Socket.IO) com o frontend para enviar atualizações de progresso em tempo real.
- Persistência de Dados: É o único serviço com responsabilidade de escrita no banco de dados relacional (PostgreSQL), onde armazena os resultados finais das classificações.
- Validação e Segurança: Valida os dados de entrada (usando Pydantic) e lida com a lógica de autenticação e autorização de usuários.
Tecnologias-chave: Python, Flask, Celery, Redis, Socket.IO, SQLAlchemy, Docker.
O Nexa-AI-Agents é o cérebro de IA do sistema. Este serviço especializado, também em Python, é totalmente focado em executar as tarefas de inteligência artificial. Ele opera de forma independente, recebendo solicitações do Nexa-api e retornando resultados sem conhecer a lógica de negócio principal.
Principais Responsabilidades:
- Processamento de IA: Executa os modelos de linguagem para gerar descrições técnicas e classificar NCMs.
- Retrieval-Augmented Generation (RAG): Utiliza um banco de dados vetorial (ChromaDB) para buscar informações contextuais e semanticamente similares, aumentando a precisão e a qualidade das respostas geradas pela IA.
- Publicação de Progresso: Comunica-se de forma assíncrona com o
Nexa-api, publicando atualizações de progresso em um canal Redis (Pub/Sub). - Serviço Agnóstico: Não possui estado e não se conecta diretamente a outros componentes, exceto o Redis e o ChromaDB, garantindo seu total desacoplamento.
Tecnologias-chave: Python, Flask, Ollama, ChromaDB, Redis, smol-agents, Docker.
O Nexa-frontend é a interface do cliente da aplicação. Desenvolvida com React e TypeScript, esta Single-Page Application (SPA) foi projetada para oferecer uma experiência de usuário moderna, reativa e em tempo real.
Principais Responsabilidades:
- Interação com o Usuário: Fornece as telas para upload de documentos, entrada manual de Part Numbers e visualização de resultados.
- Comunicação com a API: Realiza chamadas para a
Nexa-apivia HTTP REST para iniciar os processos de classificação. - Atualizações em Tempo Real: Estabelece uma conexão WebSocket com a API para receber e exibir o progresso das tarefas sem a necessidade de recarregar a página.
- Gerenciamento de Estado: Controla o estado da interface, garantindo que os dados exibidos sejam consistentes e atualizados.
Tecnologias-chave: React, TypeScript, Vite, Socket.IO-client, CSS/Sass, Tailwind.
- Python 3.11+ (para backend e IA)
- Servidor Ollama rodando o modelo
qwen2.5:14b - Node.js 18+ e npm (para frontend)
- Redis (pode ser local ou via Docker)
- Docker e Docker Compose (opcional, para facilitar a execução)
git clone https://github.com/Titus-System/Nexa.git
cd Nexacd Nexa-api
python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
cp .env.example .env
# Edite o .env conforme necessário
python run.pyOu Usando Docker Compose (opcional)
cd Nexa-api
docker compose up -d --buildO backend estará disponível em http://localhost:5000.
cd ../Nexa-AI-Agents
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edite o .env conforme necessário
docker compose up --build -d
# Rodar o banco de dados vetorial
python database/create.py
# Inicia o banco de dados vetorial
python run.pyO serviço estará disponível em http://localhost:5001.
cd ../Nexa-frontend
npm install
npm run devO frontend estará disponível em http://localhost:5173.
- Certifique-se de que o Redis está rodando (
localhost:6379por padrão). - Ajuste as variáveis de ambiente nos arquivos
.envde cada módulo conforme necessário. - Para produção, utilize Gunicorn no backend e configure variáveis de ambiente seguras.
| Membro | Função | Github | |
|---|---|---|---|
| Pedro Garcia | Product Owner |
|
|
| Julia Soares | Scrum Master |
|
|
| Eduardo Ribeiro | Dev Team |
|
|
| Wesley Gonçalves | Dev Team |
|
|