PLANO_IMPLEMENTACAO_APIS_AGRUPADAS.md

# 📋 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.