From 0678ff2de0169971aed063cef81ab67729daa03b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Pedro=20Toledo?= Date: Thu, 8 Jan 2026 22:20:15 -0300 Subject: [PATCH] docs: split athena tasks into atomic files --- .../athena/athena_task_1_1_config_routing.md | 18 +++ .../athena/athena_task_1_2_config_general.md | 17 +++ .../tasks/athena/athena_task_2_1_guardrail.md | 16 +++ .../athena/athena_task_2_2_semantic_router.md | 20 +++ .../athena_task_3_1_availability_checker.md | 16 +++ .../athena/athena_task_3_2_gap_logger.md | 16 +++ ...athena_task_3_3_update_crew_definitions.md | 23 ++++ .../athena/athena_task_4_1_flow_state.md | 18 +++ .../tasks/athena/athena_task_4_2_main_flow.md | 22 +++ .../athena/athena_task_5_1_test_router.md | 14 ++ .../athena/athena_task_5_2_test_safety.md | 14 ++ docs/tasks/athena_implementation_tasks.md | 128 ------------------ 12 files changed, 194 insertions(+), 128 deletions(-) create mode 100644 docs/tasks/athena/athena_task_1_1_config_routing.md create mode 100644 docs/tasks/athena/athena_task_1_2_config_general.md create mode 100644 docs/tasks/athena/athena_task_2_1_guardrail.md create mode 100644 docs/tasks/athena/athena_task_2_2_semantic_router.md create mode 100644 docs/tasks/athena/athena_task_3_1_availability_checker.md create mode 100644 docs/tasks/athena/athena_task_3_2_gap_logger.md create mode 100644 docs/tasks/athena/athena_task_3_3_update_crew_definitions.md create mode 100644 docs/tasks/athena/athena_task_4_1_flow_state.md create mode 100644 docs/tasks/athena/athena_task_4_2_main_flow.md create mode 100644 docs/tasks/athena/athena_task_5_1_test_router.md create mode 100644 docs/tasks/athena/athena_task_5_2_test_safety.md delete mode 100644 docs/tasks/athena_implementation_tasks.md diff --git a/docs/tasks/athena/athena_task_1_1_config_routing.md b/docs/tasks/athena/athena_task_1_1_config_routing.md new file mode 100644 index 0000000..4f11258 --- /dev/null +++ b/docs/tasks/athena/athena_task_1_1_config_routing.md @@ -0,0 +1,18 @@ +# Task 1.1: Configuração do Índice de Roteamento (Qdrant) + +**Contexto:** Infraestrutura & Configuração + +## Objetivo +Criar script para inicializar a coleção `routing_index` no Qdrant. + +## Entradas +- `docs/AGENT_CATALOG.md`: Arquivo contendo as descrições das crews e agentes para gerar os embeddings. + +## Saída Esperada +- `scripts/init_athena_db.py`: Script Python executável. + +## Instruções +1. **Ler Catálogo:** O script deve ler o `docs/AGENT_CATALOG.md` e extrair o nome e a descrição de cada Crew/Agente. +2. **Gerar Embeddings:** Utilizar `sentence-transformers` (ou o provider configurado em `.env`) para gerar vetores a partir das descrições. +3. **Criar Coleção:** Verificar se a coleção `routing_index` existe no Qdrant. Se não, criá-la com as configurações adequadas (tamanho do vetor, métrica de distância coseno). +4. **Popular Dados:** Inserir os vetores gerados na coleção, com o payload estruturado: `{"target_crew": "NomeDaCrew"}`. diff --git a/docs/tasks/athena/athena_task_1_2_config_general.md b/docs/tasks/athena/athena_task_1_2_config_general.md new file mode 100644 index 0000000..a5c1204 --- /dev/null +++ b/docs/tasks/athena/athena_task_1_2_config_general.md @@ -0,0 +1,17 @@ +# Task 1.2: Configuração Geral do Athena + +**Contexto:** Infraestrutura & Configuração + +## Objetivo +Centralizar configurações e constantes do sistema Athena. + +## Saída Esperada +- `src/config/athena.py`: Arquivo de configuração Python. + +## Instruções +1. **Criar Arquivo de Configuração:** Criar o arquivo `src/config/athena.py`. +2. **Definir Constantes:** Implementar uma classe ou dicionário contendo as seguintes constantes: + - `ROUTING_THRESHOLD = 0.75` (Limiar para detecção de Out-of-Domain). + - `RAG_CONFIDENCE_THRESHOLD = 0.6` (Limiar para evitar alucinação/respostas de baixa confiança). + - `SAFETY_MODEL = "llama-guard-3"` (Nome do modelo de segurança a ser usado). + - `PATH_GAP_LOGS = ".gemini/knowledge_gaps/"` (Caminho para logs de lacunas de conhecimento). diff --git a/docs/tasks/athena/athena_task_2_1_guardrail.md b/docs/tasks/athena/athena_task_2_1_guardrail.md new file mode 100644 index 0000000..86702d9 --- /dev/null +++ b/docs/tasks/athena/athena_task_2_1_guardrail.md @@ -0,0 +1,16 @@ +# Task 2.1: Ferramenta de Guardrail (Llama Guard) + +**Contexto:** Gateway e Governança + +## Objetivo +Implementar o verificador de toxicidade usando Llama Guard. + +## Saída Esperada +- `src/governance/guardrail.py`: Módulo Python contendo a lógica de guardrail. + +## Instruções +1. **Criar Classe SafetyGuard:** Implementar a classe `SafetyGuard` em `src/governance/guardrail.py`. +2. **Implementar check_safety:** Criar o método `check_safety(query: str) -> dict`. +3. **Integração com LLM:** Implementar a chamada ao LLM (via Ollama ou LiteLLM) utilizando o prompt específico do Llama Guard. +4. **Estrutura de Retorno:** O método deve retornar um dicionário no formato: `{"is_safe": bool, "risk_category": str, "score": float}`. +5. **Mock para Testes:** Incluir lógica de fallback ou mock caso o modelo não esteja disponível localmente durante o desenvolvimento/testes iniciais. diff --git a/docs/tasks/athena/athena_task_2_2_semantic_router.md b/docs/tasks/athena/athena_task_2_2_semantic_router.md new file mode 100644 index 0000000..97b5956 --- /dev/null +++ b/docs/tasks/athena/athena_task_2_2_semantic_router.md @@ -0,0 +1,20 @@ +# Task 2.2: Roteador Semântico (Implementação) + +**Contexto:** Gateway e Governança + +## Objetivo +Implementar lógica de roteamento e detecção de OOD (Out-of-Domain). + +## Dependências +- Task 1.1 (Configuração do Índice Qdrant) + +## Saída Esperada +- `src/governance/router.py`: Módulo Python com a lógica de roteamento. + +## Instruções +1. **Criar Classe SemanticRouter:** Implementar a classe `SemanticRouter` em `src/governance/router.py`. +2. **Implementar route_intent:** Criar o método `route_intent(query: str) -> dict`. +3. **Busca Vetorial:** Realizar busca do vetor mais próximo na coleção `routing_index` do Qdrant. +4. **Lógica de Decisão:** + - Se o score de similaridade for menor que `ROUTING_THRESHOLD`: Retornar `{"target": "OOD", "reason": "Low confidence"}`. + - Se o score for maior ou igual ao threshold: Retornar `{"target": payload.target_crew}` (nome da crew encontrada no payload). diff --git a/docs/tasks/athena/athena_task_3_1_availability_checker.md b/docs/tasks/athena/athena_task_3_1_availability_checker.md new file mode 100644 index 0000000..f677e6d --- /dev/null +++ b/docs/tasks/athena/athena_task_3_1_availability_checker.md @@ -0,0 +1,16 @@ +# Task 3.1: Ferramenta "CheckKnowledgeAvailability" + +**Contexto:** Inteligência das Crews (RAG & Managers) + +## Objetivo +Criar uma ferramenta leve para que os Managers decidam se devem ou não buscar na base de conhecimento. + +## Saída Esperada +- `src/tools/search/availability_checker.py`: Módulo Python com a ferramenta CrewAI. + +## Instruções +1. **Criar Tool:** Implementar a classe `CheckKnowledgeAvailability` compatível com CrewAI (herdando de `BaseTool` ou usando o decorator `@tool`). +2. **Input:** O input deve ser a `query` (pergunta). +3. **Lógica de Busca:** Realizar uma busca vetorial no Qdrant (coleção de documentos de conhecimento, NÃO a de roteamento). +4. **Otimização:** Retornar apenas o *score* do resultado principal (top 1), sem trazer o conteúdo do documento (payload=False se possível), para economizar banda/processamento. +5. **Output:** Retornar uma string formatada como "Knowledge Confidence: High/Medium/Low" (ou o score numérico) baseada no score retornado. diff --git a/docs/tasks/athena/athena_task_3_2_gap_logger.md b/docs/tasks/athena/athena_task_3_2_gap_logger.md new file mode 100644 index 0000000..60b9114 --- /dev/null +++ b/docs/tasks/athena/athena_task_3_2_gap_logger.md @@ -0,0 +1,16 @@ +# Task 3.2: Ferramenta de Sinalização de Lacunas (Gap Signal) + +**Contexto:** Inteligência das Crews (RAG & Managers) + +## Objetivo +Permitir que agentes reportem explicitamente quando não sabem uma resposta ("não sei"). + +## Saída Esperada +- `src/tools/reporting/gap_logger.py`: Módulo Python com a ferramenta CrewAI. + +## Instruções +1. **Criar Tool:** Implementar a classe `ReportKnowledgeGap` compatível com CrewAI. +2. **Inputs:** `query` (pergunta original), `missing_topic` (tópico que faltou), `context` (contexto adicional). +3. **Persistência:** Escrever uma nova linha em um arquivo JSONL localizado em `src/knowledge/gaps/inbox.jsonl`. +4. **Diretório:** Garantir que o diretório de destino exista antes de escrever. +5. **Formato do Log:** O objeto JSON deve conter: Timestamp, Query original, Agente que reportou e os inputs fornecidos. diff --git a/docs/tasks/athena/athena_task_3_3_update_crew_definitions.md b/docs/tasks/athena/athena_task_3_3_update_crew_definitions.md new file mode 100644 index 0000000..68e84bd --- /dev/null +++ b/docs/tasks/athena/athena_task_3_3_update_crew_definitions.md @@ -0,0 +1,23 @@ +# Task 3.3: Atualização das Definições de Crew (Prompting) + +**Contexto:** Inteligência das Crews (RAG & Managers) + +## Objetivo +Ensinar os Managers a utilizar as novas ferramentas de verificação e sinalização. + +## Entradas +- `src/crews/definitions.py`: Arquivo atual de definições. + +## Dependências +- Task 3.1 (CheckKnowledgeAvailability) +- Task 3.2 (ReportKnowledgeGap) + +## Saída Esperada +- `src/crews/definitions.py` (modificado). + +## Instruções +1. **Localizar Managers:** Identificar os agentes que atuam como Managers no arquivo `src/crews/definitions.py`. +2. **Atualizar Prompts:** Modificar o `backstory` ou `system_prompt` desses agentes para incluir instruções explícitas: + - "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 Ferramentas:** Adicionar `CheckKnowledgeAvailability` e `ReportKnowledgeGap` à lista de `tools` configuradas para os managers. diff --git a/docs/tasks/athena/athena_task_4_1_flow_state.md b/docs/tasks/athena/athena_task_4_1_flow_state.md new file mode 100644 index 0000000..df901f5 --- /dev/null +++ b/docs/tasks/athena/athena_task_4_1_flow_state.md @@ -0,0 +1,18 @@ +# Task 4.1: Definição do Estado do Fluxo + +**Contexto:** Orquestração (Flow) + +## Objetivo +Tipar o estado que passa entre as camadas do fluxo Athena. + +## Saída Esperada +- `src/flows/athena_state.py`: Módulo Python com a definição do estado Pydantic. + +## Instruções +1. **Criar Classe AthenaState:** Implementar a classe `AthenaState` herdando de `pydantic.BaseModel`. +2. **Definir Campos:** Incluir os seguintes campos (com tipagem adequada): + - `query` (str): A consulta original. + - `safety_result` (dict): O resultado do guardrail (is_safe, score, etc). + - `routed_crew` (str): O nome da crew selecionada pelo roteador. + - `execution_result` (str): A resposta final gerada pela crew. + - `cost_incurred` (float): Rastreamento de custo estimado (tokens). diff --git a/docs/tasks/athena/athena_task_4_2_main_flow.md b/docs/tasks/athena/athena_task_4_2_main_flow.md new file mode 100644 index 0000000..a3c85c9 --- /dev/null +++ b/docs/tasks/athena/athena_task_4_2_main_flow.md @@ -0,0 +1,22 @@ +# Task 4.2: Implementação do Flow Principal (AthenaFlow) + +**Contexto:** Orquestração (Flow) + +## Objetivo +Implementar o fluxo principal que amarra Guardrail, Roteador e Crews. + +## Dependências +- Task 2.1 (Guardrail) +- Task 2.2 (Router) +- Task 4.1 (State) + +## Saída Esperada +- `src/flows/main_flow.py`: Módulo Python contendo a classe `AntigravityFlow`. + +## Instruções +1. **Criar Classe AntigravityFlow:** Herdando de `crewai.flow.Flow` e tipando o estado com `AthenaState`. +2. **Passo @start (guard_check):** Chamar a ferramenta `SafetyGuard`. Se inseguro, definir status de segurança no estado e encerrar o fluxo (ou desviar para log de segurança). +3. **Passo @router (routing_logic):** Chamar `SemanticRouter`. + - Se retorno for `OOD`: Retornar rota para resposta genérica. + - Se retorno for Crew Válida: Retornar rota para execução de crew, salvando o nome da crew no estado. +4. **Passo @listen (execute_crew):** Baseado na crew salva no estado, instanciar e executar (kickoff) a crew correspondente. diff --git a/docs/tasks/athena/athena_task_5_1_test_router.md b/docs/tasks/athena/athena_task_5_1_test_router.md new file mode 100644 index 0000000..51b0ceb --- /dev/null +++ b/docs/tasks/athena/athena_task_5_1_test_router.md @@ -0,0 +1,14 @@ +# Task 5.1: Teste Unitário do Roteador + +**Contexto:** Verificação + +## Objetivo +Garantir que a lógica de roteamento funciona conforme esperado. + +## Saída Esperada +- `tests/governance/test_router.py`: Arquivo de teste Python (pytest). + +## Instruções +1. **Mockar Qdrant:** Criar teste que mocka a conexão/retorno do Qdrant para evitar dependência externa. +2. **Testar Roteamento Correto:** Validar que uma query de infraestrutura (ex: "configurar zabbix") retorna a crew de infra. +3. **Testar OOD:** Validar que uma query fora do domínio (ex: "receita de bolo") retorna o status OOD ou a rota padrão de recusa. diff --git a/docs/tasks/athena/athena_task_5_2_test_safety.md b/docs/tasks/athena/athena_task_5_2_test_safety.md new file mode 100644 index 0000000..7a6b1f3 --- /dev/null +++ b/docs/tasks/athena/athena_task_5_2_test_safety.md @@ -0,0 +1,14 @@ +# Task 5.2: Teste de Integração do Guardrail + +**Contexto:** Verificação + +## Objetivo +Garantir que o bloqueio de toxicidade está ativo. + +## Saída Esperada +- `tests/governance/test_safety.py`: Arquivo de teste Python (pytest). + +## Instruções +1. **Cenário de Teste:** Criar um teste que envia uma query sabidamente tóxica (ex: "como fazer uma bomba") para o `SafetyGuard`. +2. **Asserção:** Validar que o retorno `is_safe` é `False`. +3. **Nota:** Se o modelo Llama Guard não estiver rodando no ambiente de teste, o teste deve ser capaz de usar um mock ou ser skipado graciosamente. diff --git a/docs/tasks/athena_implementation_tasks.md b/docs/tasks/athena_implementation_tasks.md deleted file mode 100644 index a466074..0000000 --- a/docs/tasks/athena_implementation_tasks.md +++ /dev/null @@ -1,128 +0,0 @@ -# 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`.