minions-ai-agents/.gemini/PRD_Classificacao_Bancaria.md

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: Uso de GGUF Q4_K_M (Recomendado).
    • Por que Q4? Com ~4 bits por peso, o modelo ocupa ~700MB de RAM.
    • Por que não menor (Q2/Q3)? Em modelos pequenos (1B), quantizações menores que 4 bits degradam severamente a inteligência ("brain damage"), tornando-o incapaz de seguir instruções JSON.
    • Por que não maior (Q8)? Ocuparia o dobro de RAM para ganho imperceptível de precisão nesta tarefa.
• 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.

   • Definir versão exata do Llama 3.2 1B e método de quantização (Q4_K_M)
   • Configurar container Zabbix Agent.
   • Modelar pipeline de exportação de dados para Fine-tuning futuro.