# PRD - Product Requirements Document
## Agente de IA para Classificação de Transações Bancárias

### 1. Visão Geral
Este documento define os requisitos para o desenvolvimento de um Agente de Inteligência Artificial especializado na classificação de transações bancárias. O sistema operará exclusivamente via API, consumindo dados já tratados e utilizando técnicas de RAG (Retrieval-Augmented Generation) para sugerir classificações com base em histórico prévio, priorizando eficiência em ambientes com restrição de hardware (CPU-only).

### 2. Objetivos do Produto
- **Classificação Inteligente:** Categorizar transações com base na descrição, utilizando similaridade (RAG) e inferência de modelo local.
- **Eficiência de Recurso:** Operar com baixo consumo de RAM e exclusivamente em CPU.
- **Desacoplamento:** Interação exclusiva via API, sem interface direta com usuário final.
- **Autonomia:** Processamento assíncrono sem bloqueio aguardando feedback humano imediato.

### 3. Escopo
#### 3.1 Incluso
- Integração via API para recebimento de dados de transações (já parseados).
- Busca de transações similares em base vetorial (RAG).
- Motor de inferência utilizando LLM Local (Llama 3).
- Cálculo de taxa de acerto e confiança.
- Mecanismo de feedback diferido (Human-in-the-loop passivo).

#### 3.2 Não Incluso
- Leitura ou parsing de arquivos (OFX, CSV, PDF, Excel).
- OCR ou extração de dados de imagens.
- Interface de usuário direta para o agente (o agente é um backend service).
- Bloqueio de execução por espera humana.

### 4. Funcionalidades Principais

#### 4.1 Interface de Entrada
- O agente expõe endpoints para receber objetos JSON contendo estritamente:
    - `idTransacao` (varchar 1000): Identificador único da transação na origem.
    - `dataEntrada` (date): Data de competência da transação.
    - `descricao` (varchar 500): Texto descritivo da transação bancária.
    - `tipoOperacao` (varchar 500): Indicador de entrada/saída (ex: 'C'/'D', 'Crédito'/'Débito').
    - `tipoTransacao` (varchar 500): Método da transação (ex: 'pix', 'pagamento', 'boleto', 'débito').
    - `titulo` (varchar 500): Título amigável da transação (ex: "Pix Enviado", "Boleto Pago").
- **Nota:** O campo de Valor foi removido para evitar vieses. O modelo usará a descrição combinada com os tipos e título para categorização.

#### 4.2 Motor de Classificação (Core AI - RAG + LLM Local)
- **Estratégia:**
    1. **Embedding:** Gera vetor da descrição usando `BGE-small`.
    2. **Retrieval (Qdrant):** Busca 3-5 transações similares confirmadas.
    3. **Context Injection:** Injeta os exemplos no prompt do Llama 3.2 1B.
    4. **Inference (PydanticAI):** Modelo classifica e PydanticAI valida se a categoria existe no Enum permitido.
    5. **Output:** Retorna classificação validada.
- **Resources:** Otimizado para rodar localmente limitando uso de RAM.

#### 4.3 Métricas e Observabilidade
- **Monitoramento Lógico (AgentOps):** Uso do **Langfuse** (self-hosted) para rastreamento (tracing) passo a passo de cada inferência. (Integração com Zabbix via Webhooks/API desejável, mas não obrigatória nesta fase).
- **Monitoramento de Infraestrutura:** Uso de **Zabbix Agent** para monitoramento de CPU/RAM/IO do host e containers.
- **Feedback Loop:** O sistema deve registrar feedback de usuário como "Scores" no trace do Langfuse para avaliação de qualidade.

### 5. Requisitos Não Funcionais
- **Hardware:** Execução exclusiva em CPU. Mínimo consumo de RAM plausível.
- **Privacidade:** Dados processados localmente. Sem envio para APIs externas (OpenAI/Anthropic).
- **Latência:** Foco em throughput, aceitável latência de inferência local desde que não trave a aplicação chamadora.

### 6. Stack Tecnológica Definida
- **Linguagem:** Python (Versão travada: 3.12.1).
- **Framework:** FastAPI (Exposição) + **PydanticAI** (Validação estrita e Orquestração).
- **Observabilidade:** **Langfuse** (Tracing) + **Prometheus/Grafana** (Métricas).
- **LLM:** **Llama 3.2 1B Instruct** Local (GGUF Q4).
    - **Otimização:** Modelo extremamente leve (< 1GB RAM) rodando via `llama-cpp-python` ou `ollama`.
- **Base de Dados e RAG:**
    - **Relacional:** PostgreSQL.
    - **Vetorial (RAG):** **Qdrant**. Configurado com `on_disk: true` e quantização escalar para economia de RAM.
    - **Embeddings:** `BGE-small-en-v1.5` ou similar (FastEmbed) para geração rápida em CPU.

6. **Learning (RAG + Fine-tuning):** 
    - **Curto Prazo:** Correções atualizam o índice do Qdrant (RAG imediato).
    - **Médio Prazo (Ciclo MLOps):** Transações acumuladas disparam pipeline de treino LoRA. O novo adaptador é salvo, versionado e submetido a benchmark antes de ser ativado.

### 7. MLOps e Versionamento (Critical)
O sistema deve garantir a reprodutibilidade e métrica de evolução dos modelos.
- **Model Registry Local:**
    - Estrutura de pastas padronizada: `models/v{VERSION_ID}/`.
    - Cada versão deve conter: `adapter.gguf`, `training_metrics.json` e `benchmark_report.json`.
- **Benchmarking Comparativo:**
    - Aparato de teste que executa o "Golden Dataset" contra a Versão Atual (N) e a Versão Candidata (N+1).
    - **Critérios de Aprovação:** A nova versão só substitui a anterior se `Accuracy >= Previous_Accuracy` e `Latency <= Threshold`.

### 8. Fluxo de Execução
1. **Trigger:** Aplicação externa envia transação via API para o Agente.
2. **Retrieval:** Agente busca no VectorDB as "Top-K" transações mais parecidas semanticamente com a atual.
3. **Inference:** Prompt montado com a Transação Atual + Exemplos Recuperados é enviado ao Llama 3 Local.
4. **Result:** Agente retorna a classificação sugerida + Score de Confiança.
5. **Human Review (Assíncrono):** Através da aplicação principal, o usuário valida.
6. **Learning:** Integração com pipeline de MLOps descrito acima.

### 9. Próximos Passos
- [ ] Definir a versão exata do Llama 3.2 1B e método de quantização.
- [ ] Configurar container Zabbix Agent.
- [ ] Modelar pipeline de exportação de dados para Fine-tuning futuro.