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: 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.

7. 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 (RAG + Fine-tuning):
   • Curto Prazo: Correções atualizam o índice do Qdrant (RAG imediato).
   • Médio Prazo: Transações confirmadas compõem dataset para Fine-tuning (LoRA) periódico do modelo Llama 3.2. Isso "ensina" os padrões ao modelo, reduzindo a dependência de contextos longos e aumentando a velocidade.

8. 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.