Agente de Classificação Bancária (RAG + Llama 3.2)

Branch: iris-classificacao-bancaria

Este projeto implementa um Agente de IA especializado na classificação de transações bancárias via API. Ele utiliza uma arquitetura RAG (Retrieval-Augmented Generation) com modelos locais otimizados para execução em CPU.

🎯 Objetivo

Classificar transações financeiras (ex: Pix, TED, Boletos) em categorias contábeis padronizadas, utilizando descrições históricas e aprendizado por similaridade.

🏗 Arquitetura

O sistema é construído sobre três pilares principais:

1. FastAPI (Python 3.12): Exposição da API REST de alta performance.
2. Qdrant (Vector DB): Busca de transações similares ("few-shot learning" dinâmico).
3. Llama 3.2 1B (GGUF): LLM Local quantizado (Q4_K_M) para inferência final.

Stack Tecnológica

• Runtime: Python 3.12
• IA Framework: PydanticAI (Validação e Orquestração)
• Database: Qdrant (Vetorial)
• Monitoramento: Logs Estruturados (Zabbix Ready)

🚀 Como Rodar

Pré-requisitos

• Docker & Docker Compose
• Python 3.12+ (Opcional, para rodar sem Docker)

1. Configuração

Copie o arquivo de exemplo e ajuste as variáveis (se necessário):

cp .env.example .env

2. Executando com Docker (Recomendado)

O comando abaixo sobe a API e o Banco Vetorial:

docker-compose up --build

A API estará disponível em: http://localhost:8000/docs

3. Executando Localmente (Dev)

Se preferir rodar o Python diretamente:

1. Suba apenas as dependências (Qdrant):

   docker-compose up qdrant -d
   

2. Instale as libs:

   pip install -r requirements.txt
   

3. Rode a API:

   uvicorn src.main:app --reload
   

📁 Estrutura do Projeto

.
├── src/
│   ├── main.py           # Entrypoint da API
│   ├── config.py         # Configurações centralizadas
│   ├── core/             # Lógica do LLM e Vector Store
│   ├── models/           # Schemas Pydantic (Input/Output)
│   └── services/         # Regras de Negócio
├── docker-compose.yml    # Orquestração de Containers
├── requirements.txt      # Dependências Python
└── scripts/              # Utilitários de MLOps

🧠 pipeline RAG (Resumo)

1. Input: Recebe JSON da transação (descricao, valor ignorado, tipo).
2. Retrieval: Busca 5 exemplos similares no Qdrant.
3. Inference: Llama 3.2 analisa a transação atual + exemplos.
4. Validation: PydanticAI garante que a categoria retornada existe.
5. Feedback: Transações validadas alimentam o treino futuro.