minions-ai-agents/docs/FEATURE_GOVERNANCA_ROTEAMENTO_APRENDIZADO.md

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.