From 01e6beef26a963f90815f517b6af216a1a5da0bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Pedro=20Toledo?= Date: Thu, 8 Jan 2026 22:18:24 -0300 Subject: [PATCH] docs: adiciona breakdown de tasks para Athena --- docs/tasks/athena_implementation_tasks.md | 128 ++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 docs/tasks/athena_implementation_tasks.md diff --git a/docs/tasks/athena_implementation_tasks.md b/docs/tasks/athena_implementation_tasks.md new file mode 100644 index 0000000..a466074 --- /dev/null +++ b/docs/tasks/athena_implementation_tasks.md @@ -0,0 +1,128 @@ +# 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`.