minions-ai-agents/docs/Especificação Técnica Agente IA Financeiro.md

Esta é a Especificação Técnica do Produto (Spec) detalhada para a construção do ecossistema de agentes IA locais. Este documento foi estruturado para ser fornecido a um agente desenvolvedor, descrevendo cada peça, requisito e etapa do processo.

---

Especificação Técnica: Ecossistema Multi-Agente Soberano de Classificação Financeira

1. Visão Geral do Sistema

O objetivo é construir uma infraestrutura local para execução de agentes de IA especializados, com foco inicial em um Agente de Classificação de Transações Bancárias. O sistema deve operar de forma soberana (100% offline/local), ser altamente escalável em termos de memória e possuir um ciclo de aprendizado contínuo (Flywheel de Dados).

2. Arquitetura de Hardware (Infraestrutura)

• Processador: Intel Xeon E5-2699 v3 (18 núcleos / 36 threads).
• Memória RAM: 128 GB DDR4 ECC.
• Armazenamento: SSD NVMe (Mínimo 50k IOPS).

3. Template de Memória Semântica (Qdrant)

Para suportar armazenamento indeterminado e segregação total entre clientes, o banco vetorial Qdrant deve seguir este template:

• Estratégia Multitenancy: Modelo Tiered Multitenancy usando particionamento por payload.

• Segregação: Cada vetor deve conter um campo tenant_id no payload com o parâmetro is_tenant=true para co-localização física de dados.

• Otimização de Armazenamento (Custo/RAM):

  • Configurar on_disk: true para vetores originais.

  • Habilitar Scalar Quantization (redução de 75% no uso de RAM com precisão \>99\\%).

  • Habilitar inline_storage: true na configuração HNSW para reduzir leituras de disco de 32 para 1 em cada busca.

• Embeddings: Utilizar o modelo BGE-small-en-v1.5 via runtime ONNX para geração de vetores em CPU em \<50ms.

4. A "Cola" Tecnológica (Backend e Orquestração)

• Linguagem: Python 3.11+.

• API Framework: FastAPI para exposição de endpoints REST compatíveis com JSON.

• Framework de Orquestração: LangGraph para gerenciar o estado cíclico e o fluxo de decisão (State Machine).

• Framework de Integridade: PydanticAI para definição de tipos, injeção de dependências e validação estrita das saídas do LLM.

5. Perfil do Agente: Classificador de Transações (Tiny Agent)

• Modelo de Inferência: Llama 3.2 1B Instruct (GGUF Q4).
• Função: Analisar descrições bancárias curtas e mapear para categorias pré-definidas (Ex: Comida, Transporte).
• Capacidades:

  • RAG Individual: Antes de classificar, o agente deve consultar o Qdrant em busca das 3 transações similares confirmadas do histórico do cliente.

  • Tool Use (MCP): O agente deve usar o Model Context Protocol (MCP) para acessar ferramentas de padronização de nomes de comerciantes ou calculadoras.

6. Governança e Amarras de Segurança

O sistema deve implementar uma defesa em três camadas :

1. Camada de Entrada (Guardrail): Uso do Llama Guard 3 1B para detectar injeções de prompt e roteamento semântico para verificar se a pergunta está no escopo financeiro.

2. Camada de Processamento (RBAC): Filtros obrigatórios de tenant_id injetados em todas as queries vetoriais para impedir vazamento de dados entre clientes.

3. Camada de Saída (Validação): Validação Pydantic para garantir que o modelo retorne apenas categorias existentes em um Enum específico.

7. Pipeline de Aprendizado (Data Flywheel)

Para tornar o agente progressivamente mais "esperto" no Xeon v3:

• Metodologia CLEAR (Confidence-based Evaluation): O sistema deve filtrar classificações com confiança \<85\\% para revisão humana.
• Fine-Tuning Local: Utilizar Intel Extension for PyTorch (IPEX) e a técnica LoRA para treinar adaptadores semanais baseados nas correções humanas.
• Evolução: Os adaptadores LoRA treinados devem ser carregados "on-the-fly" no Llama 3.2 1B sem reiniciar o serviço.

8. Etapas de Implementação (Roadmap para o Agente Construtor)

1. Fase 1 (Infra): Provisionar container Docker com Qdrant (configurado para disco/quantização) e servidor Ollama/llama-cpp-python.

2. Fase 2 (Memória): Criar pipeline de ingestão de transações históricas com metadados de tenant_id e unificação de embeddings.

3. Fase 3 (Agente): Implementar o grafo no LangGraph com nós de: (a) Triagem de Segurança, (b) Busca de Referência, (c) Classificação Pydantic e (d) Feedback Humano.

4. Fase 4 (Integração): Expor API via FastAPI e conectar a interface (Next.js recomendada para visualização de documentos lado a lado).

---

Instrução para o Agente Construtor: Inicie pelo provisionamento do banco Qdrant utilizando o arquivo compose.yaml para habilitar clusterização local e siga para a definição do schema Pydantic das transações financeiras.