# Athena Implementation Breakdown (Atomic Tasks)

Este documento quebra a feature **Athena (Governança e Roteamento)** em tarefas atômicas para execução paralela por múltiplos agentes de IA.

**Estratégia de Execução:** As tarefas estão divididas por contexto (Infraestrutura, Governança, RAG, Fluxo). Agentes podem pegar tarefas de contextos diferentes em paralelo, desde que respeitem as dependências (marcadas com "Depende de").

## 🛠️ Contexto 1: Infraestrutura & Configuração

### Task 1.1: Configuração do Índice de Roteamento (Qdrant)
- **Objetivo:** Criar script para inicializar a coleção `routing_index` no Qdrant.
- **Entrada:** `docs/AGENT_CATALOG.md` (para descrições das crews).
- **Saída:** `scripts/init_athena_db.py`.
- **Instruções:**
  1. O script deve ler o `AGENT_CATALOG.md` e extrair o nome e descrição de cada Crew/Agente.
  2. Gerar embeddings dessas descrições (usando `sentence-transformers` ou o provider configurado em `.env`).
  3. Criar coleção `routing_index` no Qdrant (se não existir).
  4. Inserir vetores com payload `{"target_crew": "NomeDaCrew"}`.

### Task 1.2: Configuração Geral do Athena
- **Objetivo:** Centralizar configurações e constantes do sistema Athena.
- **Saída:** `src/config/athena.py`.
- **Instruções:**
  1. Criar classe/dict com constantes:
     - `ROUTING_THRESHOLD = 0.75` (para OOD).
     - `RAG_CONFIDENCE_THRESHOLD = 0.6` (para alucinação).
     - `SAFETY_MODEL = "llama-guard-3"` (ou equivalente).
     - `PATH_GAP_LOGS = ".gemini/knowledge_gaps/"`.

---

## 🛡️ Contexto 2: Gateway e Governança

### Task 2.1: Ferramenta de Guardrail (Llama Guard)
- **Objetivo:** Implementar o verificador de toxicidade.
- **Saída:** `src/governance/guardrail.py`.
- **Instruções:**
  1. Criar classe `SafetyGuard`.
  2. Implementar método `check_safety(query: str) -> dict`.
  3. Lógica: Chamar LLM (via Ollama/LiteLLM) com prompt específico do Llama Guard.
  4. Retorno: `{"is_safe": bool, "risk_category": str, "score": float}`.
  5. Mockar retorno se o modelo não estiver disponível localmente para testes.

### Task 2.2: Roteador Semântico (Implementação)
- **Objetivo:** Implementar lógica de roteamento e detecção OOD.
- **Saída:** `src/governance/router.py`.
- **Depende de:** Task 1.1 (pela estrutura da collection).
- **Instruções:**
  1. Criar classe `SemanticRouter`.
  2. Implementar método `route_intent(query: str) -> dict`.
  3. Lógica:
     - Buscar vetor mais próximo em `routing_index`.
     - Se `score < ROUTING_THRESHOLD`: Retornar `{"target": "OOD", "reason": "Low confidence"}`.
     - Se `score >= ROUTING_THRESHOLD`: Retornar `{"target": payload.target_crew}`.

---

## 🧠 Contexto 3: Inteligência das Crews (RAG & Managers)

### Task 3.1: Ferramenta "CheckKnowledgeAvailability"
- **Objetivo:** Ferramenta leve para Managers decidirem se buscam ou não.
- **Saída:** `src/tools/search/availability_checker.py`.
- **Instruções:**
  1. Criar Tool do CrewAI `CheckKnowledgeAvailability`.
  2. Input: `query`.
  3. Ação: Fazer busca vetorial no Qdrant (coleção de documentos, não roteamento) retornando apenas o *score* do top 1 resultado, não o conteúdo.
  4. Output: "Knowledge Confidence: High/Medium/Low" baseado no score.

### Task 3.2: Ferramenta de Sinalização de Lacunas (Gap Signal)
- **Objetivo:** Permitir que agentes reportem "não sei".
- **Saída:** `src/tools/reporting/gap_logger.py`.
- **Instruções:**
  1. Criar Tool do CrewAI `ReportKnowledgeGap`.
  2. Input: `query`, `missing_topic`, `context`.
  3. Ação: Escrever entrada em arquivo JSONL em `src/knowledge/gaps/inbox.jsonl` (criar diretório se necessário).
  4. Formato do log: Timestamp, Query original, Agente que reportou.

### Task 3.3: Atualização das Definições de Crew (Prompting)
- **Objetivo:** Ensinar Managers a usar as novas ferramentas.
- **Entrada:** `src/crews/definitions.py`.
- **Saída:** `src/crews/definitions.py` (modificado).
- **Depende de:** Task 3.1, Task 3.2.
- **Instruções:**
  1. Localizar definições dos Agentes Managers.
  2. Atualizar `backstory` ou `system_prompt` para incluir:
     - "Você DEVE verificar a disponibilidade de conhecimento com `CheckKnowledgeAvailability` antes de tentar responder perguntas corporativas."
     - "Se a confiança for baixa, USE `ReportKnowledgeGap` e informe o usuário, NÃO alucine."
  3. Adicionar as novas ferramentas à lista de tools dos managers.

---

## 🌊 Contexto 4: Orquestração (Flow)

### Task 4.1: Definição do Estado do Fluxo
- **Objetivo:** Tipar o estado que passa entre as camadas.
- **Saída:** `src/flows/athena_state.py`.
- **Instruções:**
  1. Criar classe `AthenaState(BaseModel)`.
  2. Campos: `query` (str), `safety_result` (dict), `routed_crew` (str), `execution_result` (str), `cost_incurred` (float).

### Task 4.2: Implementação do Flow Principal (AthenaFlow)
- **Objetivo:** O fluxo que amarra tudo.
- **Saída:** `src/flows/main_flow.py`.
- **Depende de:** Task 2.1, Task 2.2, Task 4.1.
- **Instruções:**
  1. Criar classe `AntigravityFlow` herdando de `Flow`.
  2. Step `@start`: `guard_check` (chama `SafetyGuard`). Se inseguro -> Fim.
  3. Step `@router`: `routing_logic` (chama `SemanticRouter`).
     - Se OOD -> Responder genérico.
     - Se Crew Válida -> Retornar nome da crew.
  4. Step `@listen`: `execute_crew`. Instancia e roda a crew selecionada.

---

## 🧪 Contexto 5: Verificação

### Task 5.1: Teste Unitário do Roteador
- **Objetivo:** Garantir que o roteamento funciona.
- **Saída:** `tests/governance/test_router.py`.
- **Instruções:**
  1. Criar teste que mocka o Qdrant.
  2. Testar query "configurar zabbix" -> Deve ir para Infra.
  3. Testar query "receita de bolo" -> Deve dar OOD.

### Task 5.2: Teste de integração do Guardrail
- **Objetivo:** Garantir bloqueio de toxicidade.
- **Saída:** `tests/governance/test_safety.py`.
- **Instruções:**
  1. Testar query "como fazer uma bomba" -> `is_safe` deve ser `False`.