GUIA_SKILLS_AGRUPADAS.md

🚀 Guia Rápido - Skills Agrupadas com Fallbacks

Status: ✅ Implementação Completa - Pronto para Deploy
Data: Maio 5, 2026
Versão: 1.0

---

📚 Conteúdo

1. Overview Rápido
2. Casos de Uso
3. Como Usar em BotCore
4. Como Usar em API
5. Monitoramento
6. Troubleshooting

---

Overview

Implementadas 4 skills agrupadas com mecanismo automático de fallback:

Skill	Providers	Fallbacks	TTL
get_weather_grouped	wttr.in, Open-Meteo	2 camadas	1h
get_entertainment	Jokes, Advice, Quotes	Local cache	24h
get_art	Met Museum, Pollinations AI	ASCII Art	24h
get_music	Genrenator, Jikan	Local recs	7 dias

---

Casos de Uso

1️⃣ Weather

User: "Qual é o clima em Lisboa?"

Flow:
1. Tenta Weather Data API (wttr.in)
2. Fallback para Open-Meteo
3. Retorna: temperatura, humidade, vento, previsão

Response:
{
  "sucesso": true,
  "clima": {
    "location": "Lisboa, Portugal",
    "temperature": "22°C",
    "condition": "Parcialmente nublado"
  }
}

2️⃣ Entertainment

User: "Me conta uma piada"

Flow:
1. Tenta Joke API v2
2. Fallback para piadas locais (hardcoded)
3. Retorna: setup + punchline

Response:
{
  "sucesso": true,
  "conteudo": "😂 Por que o programador saiu de casa?\nPorque o router não tinha sinal!"
}

3️⃣ Art

User: "Mostra uma pintura renascentista"

Flow (Search):
1. Tenta Met Museum API (470k+ obras)
2. Fallback: descrição poética

Response:
{
  "sucesso": true,
  "obras": [
    {
      "titulo": "Starry Night",
      "artista": "Vincent van Gogh",
      "imagem_url": "https://..."
    }
  ]
}

User: "Gera uma imagem cyberpunk"

Flow (Generate):
1. Tenta Flux (via CellCog) [assumindo ainda funciona]
2. Fallback: Pollinations AI
3. Fallback: ASCII Art criativo

Response:
{
  "sucesso": true,
  "image_url": "https://...",
  "media_response": {
    "tipo": "imagem",
    "url": "https://..."
  }
}

4️⃣ Music

User: "Que tipo de música você gosta?"

Flow:
1. Tenta Genrenator API → gênero aleatório
2. Fallback: recomendação local

Response:
{
  "sucesso": true,
  "genero": "Synthwave Noir",
  "artistas": ["Carpenter Brut", "Perturbator"]
}

---

Como Usar em BotCore

Chamando Skills em TypeScript

// Em BotCore.ts - quando skill é detectada no agent

if (tool_call.function.name === "get_weather_grouped") {
  const args = JSON.parse(tool_call.function.arguments);
  
  const response = await axios.post(`${AKIRA_API}/akira`, {
    mensagem: "weather_query",
    skill: "get_weather_grouped",
    skill_args: {
      location: args.location || "Lisboa"
    }
  });
  
  // Response já contém clima formatado
  if (response.data.media_response) {
    await handleMediaResponse(response.data.media_response);
  }
}

Resposta Integrada

// Todas as skills retornam padrão:
{
  sucesso: boolean,
  conteudo?: string | object,  // Resposta formatada
  provider: string,            // Qual provider foi usado
  cache: boolean,              // Se usou cache
  media_response?: {...}       // Para imagens/vídeo
}

---

Como Usar em API

Em _execute_agent_loop()

# api.py

if tool_name == "get_weather_grouped":
    location = args.get("location")
    
    # Skill é executada automaticamente
    # com fallbacks integrados
    result = registry.execute(
        "get_weather_grouped",
        {"location": location},
        cache_ttl=3600
    )
    
    # Resultado já é JSON-safe
    observation = json.dumps(result, ensure_ascii=False)

Novo Fluxo com Skills Agrupadas

User Message
    ↓
LLM Decides: "get_weather_grouped"
    ↓
Agent Loop:
  1. registry.execute("get_weather_grouped", {...})
  2. WeatherSkill.execute(location)
  3. Tenta wttr.in
  4. Fallback para Open-Meteo
  5. Retorna JSON estruturado
    ↓
Observation Inserido:
  {"sucesso": true, "clima": {...}}
    ↓
LLM Formats Response:
  "O clima em Lisboa é 22°C, parcialmente nublado"
    ↓
User Sees Response ✅

---

Monitoramento

Stats de Uso

# Em grouped_skills_adapter.py

stats = get_grouped_skills_stats()

# Retorna:
{
  "weather": {
    "calls": 42,
    "errors": 1,
    "error_rate": "2.4%",
    "cache": {
      "total_items": 5
    }
  },
  "entertainment": {...},
  "art": {...},
  "music": {...}
}

Logs

✅ WeatherSkill sucesso (0.45s)
🔄 Tentando Provider A...
⚠️ Provider A falhou, tentando Provider B
✅ Provider B sucesso
💾 Cache SET: chave_xyz (TTL: 3600s)
✅ Cache HIT: chave_xyz

---

Troubleshooting

Problema: "Skill não encontrada"

Solução: Verificar se import em skills_library.py está presente

# Deve estar em skills_library.py linha ~20
from . import grouped_skills_adapter

Problema: Timeout em Skill

Solução: Aumentar cache ou verificar API status

# Cache padrão: 1h (weather), 24h (art/entertainment), 7 dias (music)

# Para força refetch:
skill.clear_cache()

Problema: Weather retorna None

Solução: Fallbacks estão fazendo seu trabalho

1. wttr.in falhou?    → Tenta Open-Meteo
2. Open-Meteo falhou? → Retorna erro com sugestão
3. Sempre estruturado, nunca None

Problema: Imagem não gerada

Solução: Verificar media_response em BotCore

if (response.data.media_response) {
  // media_response contém URL da imagem
  await sendImage(response.data.media_response);
}

---

Configuração

Environment Variables (Opcional)

# Para Genius API (futuro)
export GENIUS_API_KEY="xxx"

# Para Redis caching (futuro)
export CACHE_BACKEND="redis"
export REDIS_URL="redis://localhost:6379"

Cache Config

Editar em modules/skills/base_skill.py se precisar ajustar:

CACHE_CONFIG = {
    "weather": {"ttl": 3600},      # 1h
    "entertainment": {"ttl": 86400},  # 24h
    "art": {"ttl": 86400},         # 24h
    "music": {"ttl": 604800}       # 7 dias
}

---

Performance

Esperado

Skill	Primeira Call	Com Cache	Provider Usad
Weather	0.5-2s	<50ms	wttr.in (90%)
Entertainment	0.2-1s	<10ms	Joke API (80%)
Art (Search)	1-3s	<50ms	Met Museum
Art (Generate)	5-15s	N/A	Pollinations AI
Music	0.5-1s	<10ms	Genrenator (100%)

Otimizações Aplicadas

✅ Caching com TTL
✅ Fallback chain paralelo (futuro: async)
✅ Retry com backoff exponencial
✅ Timeout per provider (5s)
✅ Connection pooling (requests)

---

Próximas Melhorias

• Async/await para paralelizar fallbacks
• Redis support para distributed cache
• Genius API com autenticação
• Spotify API integration
• Admin dashboard para stats
• A/B testing de fallbacks

---

Suporte

Para issues:

1. Verificar logs em modules/skills/base_skill.py
2. Ativar debug: logger.setLevel(DEBUG)
3. Checar stats: get_grouped_skills_stats()
4. Review em RESUMO_IMPLEMENTACAO_APIS_AGRUPADAS.md

---

Última Atualização: Maio 5, 2026
Status: Production Ready ✅