79 lines
4.9 KiB
Markdown
79 lines
4.9 KiB
Markdown
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. |