# 📋 Plano de Implementação - APIs Agrupadas com Fallbacks

**Documento de Planejamento Estratégico**  
**Data**: Maio 2026  
**Scope**: Integração de 8+ APIs públicas em skills agrupadas com mecanismo de fallback  
**Objetivo**: Expandir capacidades de Akira mantendo resiliência e coesão de resposta

---

## 1. Executive Summary (Resumo Executivo)

Este documento descreve a estratégia de integração de múltiplas APIs públicas no sistema Akira, transformando-as em **skills agrupadas** com **mecanismo de fallback automático**. Em vez de uma skill por API, cada domínio (clima, entretenimento, arte, etc.) terá uma skill que tenta múltiplas fontes de dados.

**Benefícios**:
- ✅ Maior resiliência (se uma API cai, tenta a próxima)
- ✅ Resposta mais rica (combina dados de múltiplas fontes)
- ✅ Melhor UX (usuário recebe sempre algo válido)
- ✅ Escalável (fácil adicionar mais fallbacks)

**Timeline Estimado**: 6-8 horas de implementação total

---

## 2. Análise de APIs e Agrupamento por Domínio

### 2.1 Domínio: Informações Gerais

#### A. Weather API (Clima)
**Endpoint**: `https://wttr.in/{location}?format=j1` (ou similar)
**Response**: JSON com temp, umidade, vento, previsão
**Latência Típica**: 200-500ms
**Limite**: Sem limite explícito
**Integração Akira**: 
- Primary: Web search (análise em tempo real)
- Fallback 1: Weather Data API
- Fallback 2: wttr.in (sem autenticação)

**Casos de Uso**:
```
"qual é o clima em Lisboa?"
"vai chover hoje?"
"quanto graus em São Paulo?"
```

**Estrutura de Resposta Esperada**:
```json
{
  "location": "Lisboa, Portugal",
  "temperature": "22°C",
  "condition": "Parcialmente nublado",
  "humidity": "65%",
  "wind_speed": "12 km/h",
  "forecast": [
    {"day": "Hoje", "high": "24°C", "low": "18°C", "condition": "Ensolarado"}
  ]
}
```

**Tratamento de Erro**:
- Se ambas falharem, mensagem neutra: "Não consegui dados de clima agora, tente depois"

---

#### B. Advice Slip API (Dicas/Conselhos)
**Endpoint**: `https://api.adviceslip.com/advice`
**Response**: `{"slip_id": 123, "advice": "...texto..."}`
**Latência Típica**: 100-300ms
**Limite**: ~500 requests/dia (verificar)
**Integração Akira**: 
- Primary: Advice Slip API
- Fallback 1: Cached quotes (local)

**Casos de Uso**:
```
"me dá uma dica"
"preciso de conselho"
"me inspira"
```

---

### 2.2 Domínio: Entretenimento

#### A. Joke API (Piadas)
**Endpoint**: `https://v2.jokeapi.dev/joke/Any`
**Response**: JSON com setup + delivery ou single joke
**Latência**: 50-200ms
**Integração**:
- Primary: Joke API v2
- Fallback: Local joke library (hardcoded)

**Casos de Uso**:
```
"me conta uma piada"
"humor, eu preciso"
"piada de programador"
```

---

#### B. Genrenator API (Gêneros Musicais)
**Endpoint**: `https://binaryjazz.us/genrenator/api.php?type=genre`
**Response**: String simples com gênero música
**Latência**: 100-400ms

**Casos de Uso Avançados**:
```
"que tipo de música você gosta?"
"me recomenda um gênero"
"cria um gênero aleatório"
```

---

#### C. Quote API (Citações)
**Endpoint**: `https://api.quotable.io/random`
**Response**: JSON com quote, author, tags
**Integração**:
- Primary: Quotable API
- Fallback: Local quotes database

---

### 2.3 Domínio: Criatividade & Arte

#### A. Museum API (Museu Metropolitano)
**Endpoint**: `https://collectionapi.metmuseum.org/public/collection/v1/search?q={query}`
**Response**: Artwork metadata com image URLs
**Features**:
- 470K+ obras de arte
- Busca por keyword
- Imagens de alta resolução
- Sem API key necessário

**Casos de Uso**:
```
"mostra uma obra de arte sobre natureza"
"busca uma pintura renascentista"
"qual é a obra mais famosa do Monet?"
```

**Estrutura**:
```json
{
  "objectID": 12345,
  "title": "Starry Night",
  "artistDisplayName": "Vincent van Gogh",
  "objectDate": "1889",
  "primaryImage": "https://...",
  "medium": "Oil on canvas"
}
```

---

#### B. Pollinations AI (Geração de Imagens - Fallback)
**Endpoint**: `https://image.pollinations.ai/prompt/{prompt}`
**Response**: Direct image binary (PNG)
**Casos de Uso**:
```
"gera uma imagem de um gato cósmico"
"cria uma imagem cyberpunk"
```

**Integração com Akira**:
- Primary: Flux (via CellCog)
- Fallback: Pollinations AI
- Error Handling: Se ambas falharem, retorna descrição textual

---

### 2.4 Domínio: Música (NOVO - Detalhado)

#### A. Spotify API (Recomendações)
**Requer**: OAuth (um pouco complexo, optional)
**Alternativa**: Last.fm API (simpler)

#### B. Genius API (Letras)
**Endpoint**: `https://api.genius.com/searches?q={song}`
**Features**: Busca músicas, artistas, letras
**API Key**: Necessário (gratuito)

#### C. Jikan API (Anime OST)
**Endpoint**: `https://api.jikan.moe/v4/anime/{id}`
**Features**: OST de animes
**Casos de Uso**: "Qual música toca em Naruto?"

---

## 3. Arquitetura de Skill Agrupada com Fallback

### 3.1 Padrão de Implementação

```
BaseSkill
├── Primary Provider (implementação preferida)
├── Fallback Chain (fallbacks ordenadas)
├── Cache Layer (respostas em cache)
├── Error Handling (tratamento gracioso)
└── Response Formatting (unificar resposta)
```

### 3.2 Pseudo-código Genérico

```python
class WeatherSkill(BaseSkill):
    """Weather com fallbacks"""
    
    def execute(self, location: str):
        # 1. Tenta web search (tem em contexto)
        try:
            result = self.web_search(f"weather {location}")
            if result:
                return self.format_response("websearch", result)
        except Exception as e:
            logger.info(f"Web search falhou: {e}")
        
        # 2. Fallback 1: Weather API
        try:
            result = self.weather_api(location)
            if result:
                return self.format_response("weather_api", result)
        except Exception as e:
            logger.info(f"Weather API falhou: {e}")
        
        # 3. Fallback 2: wttr.in
        try:
            result = requests.get(f"https://wttr.in/{location}?format=j1")
            if result.status_code == 200:
                return self.format_response("wttr", result.json())
        except Exception as e:
            logger.info(f"wttr.in falhou: {e}")
        
        # 4. Erro final
        return {
            "erro": True,
            "mensagem": f"Não consegui encontrar clima de {location}",
            "sugestao": "Tenta com nome de cidade mais comum"
        }
    
    def format_response(self, provider, data):
        """Formata resposta independente da fonte"""
        return {
            "provider": provider,
            "location": data.get("location"),
            "temperature": data.get("temp"),
            # ... etc
        }
```

### 3.3 Integração em Skills Registry

```python
# skills_registry.py

SKILLS_MAP = {
    "weather": WeatherSkill(),           # Agrupa: web search + Weather API
    "entertain": EntertainmentSkill(),   # Agrupa: Jokes + Advice + Quotes
    "art": ArtSkill(),                   # Agrupa: Museum + Pollinations
    "music": MusicSkill(),               # Agrupa: Genius + Jikan + Genrenator
}
```

---

## 4. Especificação de Cada Skill Agrupada

### 4.1 Skill: `get_weather`

**Purpose**: Retornar informações de clima com fallbacks automáticos

**Parâmetros**:
```
location: str (obrigatório) - "Lisboa", "São Paulo", etc
unit: str (opcional) - "celsius" (default) ou "fahrenheit"
include_forecast: bool (opcional) - true para previsão
```

**Fallback Chain**:
1. Web search (se tiver contexto web)
2. Weather Data API
3. wttr.in JSON
4. Mensagem de erro

**Response Format**:
```json
{
  "sucesso": true,
  "provider": "weather_api",
  "dados": {
    "local": "Lisboa, Portugal",
    "temperatura_atual": "22°C",
    "condicao": "Parcialmente nublado",
    "humidade": "65%",
    "vento": "12 km/h",
    "sensacao_termica": "20°C",
    "previsao": [
      {
        "dia": "Hoje",
        "maxima": "24°C",
        "minima": "18°C",
        "condicao": "Ensolarado",
        "probabilidade_chuva": "10%"
      }
    ]
  },
  "timestamp": "2026-05-05T14:30:00Z"
}
```

---

### 4.2 Skill: `get_entertainment`

**Purpose**: Piadas, dicas, citações em uma resposta unificada

**Parâmetros**:
```
tipo: str (opcional) - "joke", "advice", "quote", ou "random" (default)
idioma: str (opcional) - "pt-BR", "en-US"
tema: str (opcional) - "programming", "life", etc
```

**Fallback Chain**:
1. API primária (Joke, Advice, Quote API)
2. Cache local (last 100 jokes)
3. Resposta fixa de fallback

**Response Format**:
```json
{
  "sucesso": true,
  "tipo": "joke",
  "conteudo": {
    "setup": "Por que o programador saiu de casa?",
    "punchline": "Porque o router não tinha sinal!",
    "categoria": "programming",
    "source": "jokeapi_v2"
  },
  "alternativas": [
    {
      "tipo": "quote",
      "texto": "Code is poetry written for computers"
    }
  ]
}
```

---

### 4.3 Skill: `get_art`

**Purpose**: Retornar obras de arte ou gerar imagens criativas

**Parâmetros**:
```
tipo: str - "search" (buscar museu) ou "generate" (criar imagem)
query: str - termo de busca
estilo: str (optional para generate) - "cyberpunk", "renaissance", etc
```

**Fallback Chain para Search**:
1. Met Museum API
2. Wikiart API (se implementado)
3. Descrição textual fallback

**Fallback Chain para Generate**:
1. Flux (via CellCog)
2. Pollinations AI
3. Descrição em ASCII art

**Response Format**:
```json
{
  "sucesso": true,
  "tipo": "search",
  "obras": [
    {
      "titulo": "Starry Night",
      "artista": "Vincent van Gogh",
      "ano": 1889,
      "tecnica": "Oil on canvas",
      "imagem_url": "https://...",
      "museo": "Museum of Modern Art",
      "descricao": "Uma noite estrelada em Arles..."
    }
  ],
  "total_encontradas": 42
}
```

---

### 4.4 Skill: `get_music` (NOVO)

**Purpose**: Informações musicais, recomendações, análise de gêneros

**Parâmetros**:
```
tipo: str - "genre", "recommendation", "lyrics", "analysis"
artista: str (opcional)
musica: str (opcional)
mood: str (opcional) - "happy", "sad", "energetic", etc
```

**Sub-Skills Internos**:

#### 4.4.1 Music Genre Generator
- **Endpoint**: Genrenator API
- **Response**: Gênero aleatório + descrição
- **Usar para**: "Que tipo de música você gosta?"

#### 4.4.2 Lyrics Finder
- **Endpoint**: Genius API
- **Response**: Letra + informações da música
- **Usar para**: "Qual é a letra de..."

#### 4.4.3 Anime OST Finder
- **Endpoint**: Jikan API
- **Response**: Lista de OSTs de anime
- **Usar para**: "Qual música toca em...?"

#### 4.4.4 Music Recommendation
- **Logic**: Combina Genrenator + análise de padrão
- **Response**: Recomendação personalizada

**Response Format - Genre**:
```json
{
  "sucesso": true,
  "tipo": "genre",
  "genero": "Synthwave Noir",
  "descricao": "Combinação de synthwave com elementos noir",
  "artistas_exemplos": ["Carpenter Brut", "Perturbator"],
  "instrumentos": ["sintetizador", "bateria eletrônica"],
  "mood": ["dark", "energetic", "nostalgic"]
}
```

**Response Format - Lyrics**:
```json
{
  "sucesso": true,
  "tipo": "lyrics",
  "musica": {
    "titulo": "Bohemian Rhapsody",
    "artista": "Queen",
    "ano": 1975,
    "album": "A Night at the Opera",
    "letra": "[LETRA COMPLETA]",
    "fonte": "genius_api"
  }
}
```

---

## 5. Tratamento de Erros e Resiliência

### 5.1 Estratégia de Error Handling

```python
class SkillError(Exception):
    """Tipos de erro em skills"""
    pass

class APITimeoutError(SkillError):
    """Timeout em chamada de API"""
    pass

class APIRateLimitError(SkillError):
    """Rate limit atingido"""
    pass

class DataValidationError(SkillError):
    """Dados inválidos retornados"""
    pass

# Em cada skill:
def execute_with_retry(fn, max_retries=2, backoff=1.0):
    for attempt in range(max_retries):
        try:
            return fn()
        except APITimeoutError:
            if attempt < max_retries - 1:
                time.sleep(backoff * (2 ** attempt))
                continue
            return fallback_response()
        except APIRateLimitError:
            logger.warning("Rate limit atingido, usando cache")
            return get_cached_response()
        except Exception as e:
            logger.error(f"Erro inesperado: {e}")
            return fallback_response()
```

### 5.2 Logging Estruturado

```
Level: DEBUG - "Tentando Provider A"
Level: INFO  - "Provider A falhou, tentando Provider B"
Level: WARN  - "Todos providers falharam, retornando fallback"
Level: ERROR - "Erro crítico: {erro}"
```

---

## 6. Implementação Passo a Passo

### 6.1 Estrutura de Arquivos

```
AKIRA-SOFTEDGE/modules/
├── skills/
│   ├── __init__.py
│   ├── base_skill.py          (✨ NOVO - classe base)
│   ├── weather_skill.py       (✨ NOVO - com fallbacks)
│   ├── entertainment_skill.py (✨ NOVO - piadas+dicas+quotes)
│   ├── art_skill.py           (✨ NOVO - museu+geração)
│   └── music_skill.py         (✨ NOVO - gêneros+letras+OST)
├── skills_library.py          (existente - atualizar)
├── skills_registry.py         (existente - integrar novas)
└── api_integrations/          (✨ NOVO)
    ├── __init__.py
    ├── weather_providers.py   (wttr.in, Weather API)
    ├── entertainment_providers.py
    ├── art_providers.py       (Met Museum, Pollinations)
    └── music_providers.py     (Genius, Jikan, Genrenator)
```

### 6.2 Fases de Implementação

**Fase 1 - Setup Base (1-2h)**
- Criar `base_skill.py` com framework
- Criar `api_integrations/` package
- Atualizar `skills_registry.py`

**Fase 2 - Skills Rápidas (1-2h)**
- Weather Skill (web search + fallbacks)
- Entertainment Skill (piadas + dicas)
- Art Skill (museu API)

**Fase 3 - Music Skill Avançada (2-3h)**
- Genrenator integration
- Genius API integration
- Jikan API integration
- Recomendação inteligente

**Fase 4 - Testes & Deploy (1h)**
- Testes unitários
- Testes de fallback
- Deploy em Railway

---

## 7. Considerações Técnicas

### 7.1 Rate Limiting & Quotas

| API | Limite | Estratégia |
|-----|--------|-----------|
| Met Museum | Ilimitado | Direct calls OK |
| Genius | 10k/hr | Cache responses |
| Jikan | 60/min | Add delay entre calls |
| Genrenator | Ilimitado | Direct calls OK |
| Weather API | ~500/dia | Cache 1h |
| Joke API | Ilimitado | Direct calls OK |
| Advice | ~500/dia | Cache responses |

### 7.2 Caching Strategy

```python
# Cache com TTL
CACHE_CONFIG = {
    "weather": {"ttl": 3600, "max_size": 100},      # 1h
    "art": {"ttl": 86400, "max_size": 500},         # 24h
    "music_genres": {"ttl": 604800, "max_size": 50}, # 7 dias
    "jokes": {"ttl": 86400, "max_size": 100}        # 24h
}
```

### 7.3 Resposta Unificada

Todas as skills seguem este padrão:
```json
{
  "sucesso": boolean,
  "tipo": "skill_type",
  "dados": {...},
  "provider": "qual API foi usada",
  "cache_hit": boolean,
  "erro_message": "se houver erro",
  "timestamp": "ISO8601"
}
```

---

## 8. Testes

### 8.1 Unit Tests

```python
def test_weather_primary_provider():
    """Web search deve ser tentado primeiro"""
    pass

def test_weather_fallback_chain():
    """Se primary falha, tenta fallbacks"""
    pass

def test_entertainment_caching():
    """Piadas devem ser cacheadas"""
    pass

def test_music_genre_generation():
    """Genrenator deve gerar gênero válido"""
    pass

def test_art_museum_search():
    """Met Museum deve retornar obras válidas"""
    pass
```

### 8.2 Integration Tests

```python
def test_full_pipeline():
    """User message -> Skill execution -> Response"""
    pass

def test_fallback_on_timeout():
    """Quando API demora >2s, usa fallback"""
    pass
```

---

## 9. Roadmap Futuro

- [ ] Integrar Spotify API (recomendações avançadas)
- [ ] Implementar playlist generation
- [ ] Add Last.fm para scrobbling
- [ ] Lyrics search com mais fontes
- [ ] AI music analysis (mood detection)
- [ ] Real-time trending music

---

## 10. Conclusão

Este plano estabelece a base para um sistema robusto, resiliente e escalável de integração de APIs públicas no Akira. O mecanismo de fallback garante que o usuário sempre receba uma resposta válida, enquanto o agrupamento em skills mantém o sistema organizado e manutenível.

**Timeline Total Estimado**: 6-8 horas  
**Complexidade**: Média-Alta  
**Risco**: Baixo (todas APIs públicas e estáveis)  
**ROI**: Alto (40+ novos casos de uso)

---

**Próximo Passo**: Executar implementação seguindo fases descritas acima.