joao.goncalves
/
minions-ai-agents
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
minions-ai-agents/.gemini/PRD_Classificacao_Bancaria.md

7.3 KiB
Raw Blame History

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.
  1. 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 Data Flywheel (Pipeline RAG Completo)

O pipeline RAG não serve apenas para inferência, mas é o motor de geração de dataset para o Agente.

  • Estrutura de Dados (Golden Dataset):

    • Todo feedback positivo (ou correção humana) é salvo na tabela training_examples.
    • Campos: input_text (Descrição + Metadados), output_json (Categoria Correta), source (Human/Auto), timestamp.

  • Ciclo de Vida do Dado:

    1. Ingestão: Transação chega via API.
    2. Busca & Inferência: Agente sugere classificação.
    3. Feedback: Aplicação confirma ou corrige a classificação.
    4. Persistência: O par {Input, Correct_Output} é salvo no PostgreSQL e indexado no Qdrant.
    5. Exportação: Script export_dataset.py gera arquivo JSONL formatado para LoRA (instruction, input, output) a partir apenas de exemplos validados.

  • Model Registry & Git Flow:

    • Todo novo treino gera um commit automático em uma branch isolada model-candidates/v{TIMESTAMP}.
    • O artefato (adapter.gguf) é salvo e preservado independente do resultado do benchmark.

  • Benchmarking e Promoção (Nível 1 - Manual):

    • O sistema roda o teste comparativo e anexa o relatório no Pull Request ou Issue.
    • Aprovação: Se aprovado pelo humano, faz merge para main e o deploy ocorre.
    • Reprovação: Se reprovado, a branch é mantida para análise histórica (não é descartada), mas o PR é fechado/ignorado.

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)
    • Modelar pipeline de exportação de dados para Fine-tuning futuro (Data Flywheel)
    • Configurar container Zabbix Agent.