65 lines
5.4 KiB
Markdown
65 lines
5.4 KiB
Markdown
# 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`.
|