joao.goncalves
/
minions-ai-agents
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
minions-ai-agents/docs/tasks/athena_implementation_tasks.md

5.9 KiB
Raw Blame History

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.