# 🚀 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](#overview)
2. [Casos de Uso](#casos-de-uso)
3. [Como Usar em BotCore](#botcore)
4. [Como Usar em API](#api)
5. [Monitoramento](#monitoramento)
6. [Troubleshooting](#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

```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

```typescript
// 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()`

```python
# 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

```python
# 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

```python
# 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

```python
# 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

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

---

## Configuração

### Environment Variables (Opcional)

```bash
# 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:

```python
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 ✅