From 0fb9e067d39f55b35953585cb73ac9f1b726be28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Pedro=20Toledo?= Date: Thu, 8 Jan 2026 22:11:34 -0300 Subject: [PATCH] docs: adiciona feature de governanca e roteamento inteligente (Athena) --- ...ATURE_GOVERNANCA_ROTEAMENTO_APRENDIZADO.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 docs/FEATURE_GOVERNANCA_ROTEAMENTO_APRENDIZADO.md diff --git a/docs/FEATURE_GOVERNANCA_ROTEAMENTO_APRENDIZADO.md b/docs/FEATURE_GOVERNANCA_ROTEAMENTO_APRENDIZADO.md new file mode 100644 index 0000000..bee8d8a --- /dev/null +++ b/docs/FEATURE_GOVERNANCA_ROTEAMENTO_APRENDIZADO.md @@ -0,0 +1,64 @@ +# Feature: Sistema de Governança Cognitiva e Roteamento Adaptativo (Athena) + +## 1. Visão Geral +Esta feature propõe a implementação de uma arquitetura robusta de **Governança, Roteamento Inteligente e Aprendizado Contínuo** para o sistema "Antigravity Brain" (Minions da ITGuys). O objetivo é resolver os problemas de controle de custos ("custo da autonomia"), segurança (toxicidade/jailbreak) e gestão de conhecimento (alucinação vs. ignorância) identificados nos documentos de referência. + +A estratégia integra os conceitos de "Defesa em Profundidade" e "Roteamento Semântico em Camadas" diretamente na infraestrutura existente baseada em CrewAI, Qdrant e Neo4j. + +## 2. Arquitetura Lógica: O Protocolo "Athena" + +A arquitetura será dividida em três camadas sequenciais de processamento: + +### Camada 1: O Gateway de Defesa (Athena Guard & Router) +Esta é a "porta da frente" do sistema. Nenhuma `Crew` complexa é instanciada aqui. +* **Responsabilidade:** Segurança, Filtragem de Ruído e Despacho de Departamento. +* **Componentes:** + 1. **Filtro de Segurança (Guardrail):** Implementação do **Llama Guard 3 (8B ou 1B)** (rodando via Ollama ou API) para interceptar toxicidade, injeção de prompt e jailbreaks antes que consumam recursos caros. + 2. **Verificação de Domínio (OOD):** Uso de **Qdrant Zero-Shot Classification**. Se a consulta não tiver similaridade mínima (ex: > 0.75) com os vetores de escopo de nenhuma equipe, ela é rejeitada como "Fora do Domínio" (Out of Domain). + 3. **Roteamento Global:** Se segura e pertinente, a consulta é classificada para a Crew correta (ex: `infra_crew`, `sales_crew`, `hr_crew`) usando similaridade semântica. + +### Camada 2: O Gerente Tático (Crew Manager) +Uma vez dentro da equipe correta, a decisão de *como* resolver o problema é tomada. +* **Responsabilidade:** Decisão de Estratégia de Recuperação (RAG). +* **Lógica de Decisão:** + * **Consulta Fática/Entidade (ex: "Status do servidor X"):** Aciona **GraphRAG** (Neo4j) para precisão estrutural. + * **Consulta Semântica/Processo (ex: "Como configuro VPN?"):** Aciona **VectorRAG** (Qdrant) para busca de documentos. + * **Consulta Criativa/Lógica (ex: "Crie um script Python"):** **Sem RAG**. Usa apenas a capacidade do LLM e ferramentas de código. +* **Prevenção de Alucinação:** Se a busca (RAG) retornar dados de baixa confiança (< 0.6), o Gerente DEVE optar por não responder ou escalar, em vez de inventar. + +### Camada 3: Ciclo de Assimilação (The Learning Loop) +Transforma falhas em ativos. +* **Conceito:** Uma "Lacuna de Conhecimento" não é um erro fatal, é um pedido de atualização. +* **Fluxo:** + 1. Agente identifica falta de informação (`knowledge_gap_detected = True`). + 2. O sistema registra um **"Ticket de Assimilação"** (log estruturado em json/banco). + 3. **Curadoria Humana:** Um Especialista (SME) revisa tickets agrupados e fornece a resposta/documento. + 4. **Ingestão Automática:** O sistema ingere o novo conteúdo no Qdrant/Neo4j e avisa que agora sabe a resposta. + +## 3. Plano de Implementação Técnica + +### Fase 1: Fundação do Gateway (Router & Guard) +1. **Novo Fluxo Principal (`src/main_flow.py`):** Criar um Flow CrewAI (`AntigravityFlow`) que atua como orquestrador mestre, substituindo ou envolvendo o `src/router.py` atual. +2. **Integração Llama Guard:** Adicionar ferramenta/passo de verificação de segurança no início do fluxo. +3. **Índice de Roteamento no Qdrant:** Criar uma coleção separada (`routing_index`) populada com "frases canônicas" (missão/escopo) de cada uma das 27 personas/crews existentes. + +### Fase 2: Inteligência das Crews (Managers) +1. **Refatoração de Crew Definitions (`src/crews/definitions.py`):** + * Atualizar os agentes "Managers" (ex: Arthur Mendes, The Architect) com instruções explícitas de **"RAG Decision Making"**. + * Instrução de System Prompt: *"Antes de responder, avalie se você precisa de dados externos. Se a pergunta for sobre processos internos, use a tool `search_knowledge_base`. Se for código genérico, NÃO use."* +2. **Integração Neo4j:** Garantir que as tools de busca diferenciem busca vetorial (Qdrant) de busca de grafos (Neo4j) e que os agentes saibam quando usar qual. + +### Fase 3: Pipeline de Assimilação +1. **Ferramenta de Sinalização:** Criar uma `GapSignalTool` que os agentes podem chamar quando não encontram informações. +2. **Logs de Lacuna:** Definir estrutura de armazenamento para essas sinalizações (arquivo JSON na pasta `.gemini/knowledge_gaps/` ou banco de dados). +3. **Workflow de Ingestão:** Criar um script ou fluxo auxiliar que lê correções humanas e atualiza a base. + +## 4. Impacto e Benefícios +* **Redução de Custos:** Perguntas tóxicas ou irrelevantes são bloqueadas "barato" (modelos locais/pequenos) antes de chamar LLMs caros (GPT-4/Gemini Pro). +* **Segurança da Marca:** Mitigação ativa de respostas nocivas ou comprometedoras. +* **Evolução Constante:** O sistema deixa de ser estático e passa a aprender com o uso real, preenchendo buracos na sua base de conhecimento automaticamente. + +## 5. Próximos Passos (Para Execução) +1. **Criar Task:** Criar tarefa em `docs/tasks/implementacao_guardrails_roteamento.md` detalhando os passos técnicos. +2. **Setup Qdrant:** Script para popular o índice de roteamento com as descrições dos agentes atuais (`docs/AGENT_CATALOG.md`). +3. **Codificação:** Iniciar implementação do `AntigravityFlow`.