# 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`.