docs: adiciona breakdown de tasks para Athena
This commit is contained in:
parent
8dfd0eefa4
commit
01e6beef26
|
|
@ -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`.
|
||||||
Loading…
Reference in New Issue