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.