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. Recebe a descrição da transação.
  2. Consulta banco vetorial para encontrar transações passadas similares já classificadas (pelo agente ou humanos).
  3. LLM (Llama 3) analisa a descrição atual + exemplos recuperados (Contexto).
  4. Define a Categoria e Subcategoria.
• Resources: Otimizado para rodar localmente limitando uso de RAM.

4.3 Métricas e Feedback

• Dashboard de Métricas: Exposição de dados sobre taxa de acerto e confiança do modelo.
• Feedback Loop: O sistema deve permitir que uma aplicação externa envie a correção de uma classificação. Essa correção é salva no banco para refinar futuras buscas RAG.

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: A definir (LangChain ou implementação customizada leve).
• LLM: Llama 3 Local (via llama-cpp-python).
  • Otimização: Uso obrigatório de formato GGUF com Quantização (ex: Q4_K_M ou Q5_K_M) para reduzir uso de RAM (< 6GB) e latência.
• Base de Dados e RAG:
  • Relacional: PostgreSQL.
  • Vetorial (RAG): ChromaDB com estratégia de Ranking/Reranking. O retriever deve pré-filtrar ou ordenar candidatos não apenas por similaridade bruta, mas priorizando exemplos com alta confiança histórica para acelerar a convergência da resposta correta.

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: Se houve correção, a aplicação notifica o Agente/Banco para atualizar o "Golden Record" usado no RAG.

8. Próximos Passos

• Definir a versão exata do Llama 3 e método de quantização para CPU.
• Modelar o schema do banco de dados (Tabela de Transações vs Tabela de Embeddings).
• Configurar ambiente Python 3.12 travado.