# 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):
```bash
cp .env.example .env
```

### 2. Executando com Docker (Recomendado)
O comando abaixo sobe a API e o Banco Vetorial:
```bash
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):**
   ```bash
   docker-compose up qdrant -d
   ```

2. **Instale as libs:**
   ```bash
   pip install -r requirements.txt
   ```

3. **Rode a API:**
   ```bash
   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.