CELLCOG_SKILLS.md

# 🎯 CellCog Skills — Guia Completo

## Visão Geral

**CellCog** é a plataforma multi-modal nº1 para IA avançada. AKIRA-SOFTEDGE agora integra os seguintes skills:

---

## 📸 1. **generate_image** (PADRÃO)
**Gera imagens artísticas via CellCog → Fallback para Flux**

### Uso:
```
Desenha uma paisagem montanhosa ao pôr do sol
Cria uma imagem cyberpunk futurista
Imagina um castelo de gelo em Marte
```

### Parâmetros:
- `prompt` ⭐ **OBRIGATÓRIO**: Descrição da imagem
- `model`: Estilo (flux, anime, photo, 3d, illustration) — padrão: flux
- `aspect_ratio`: Proporção (1:1, 16:9, 9:16, 4:3, 3:4) — padrão: 1:1

### Exemplo:
```
"Desenha um astronauta em uma base lunar com modelo anime e proporção 16:9"
→ Gera imagem via CellCog (se disponível) ou Flux (fallback automático)
```

---

## 🎬 2. **generate_video** (PREMIUM)
**Gera vídeos cinematográficos via CellCog**

### Uso:
```
Faz um vídeo curto de um dragão voando sobre montanhas
Cria um filme de 30 segundos sobre tecnologia do futuro
Gera um vídeo de uma cidade submersa sob água
```

### Parâmetros:
- `prompt` ⭐ **OBRIGATÓRIO**: Descrição do vídeo
- `duration`: Duração em segundos (5-240) — padrão: 10
- `resolution`: Resolução (720p, 1080p, 4k) — padrão: 1080p

### Exemplo:
```
"Gera um vídeo de 15 segundos de um carro futurista em resolução 1080p"
→ Retorna URL do vídeo pronto para assistir/partilhar
```

### ⚠️ Requisitos:
- Chave CellCog configurada no `.env`
- Plano que inclua "Video Cog" (Pro ou superior)

---

## 🎙️ 3. **generate_audio** (PREMIUM)
**Gera áudio/voz sintetizada via CellCog**

### Uso:
```
Sintetiza este texto em voz masculina
Cria uma narração em português de Portugal
Gera um áudio da minha mensagem em voz robótica
```

### Parâmetros:
- `text` ⭐ **OBRIGATÓRIO**: Texto a converter
- `voice`: Tipo de voz (default, male, female, child, robotic) — padrão: default
- `language`: Idioma (pt-PT, pt-BR, en-US, en-GB, es-ES, fr-FR) — padrão: pt-PT

### Exemplo:
```
"Gera áudio deste texto em voz feminina em português do Brasil"
→ Retorna arquivo MP3 pronto para enviar
```

### ⚠️ Requisitos:
- Chave CellCog configurada
- Plano que inclua "Audio Cog" (Pro ou superior)

---

## 🔬 4. **research_advanced** (PREMIUM)
**Pesquisa profunda multi-fonte (#1 em DeepResearch Bench)**

### Uso:
```
Faz uma pesquisa profunda sobre inteligência artificial
Analisa em profundidade o impacto da IA no mercado de trabalho
Pesquisa tudo sobre energia renovável
```

### Parâmetros:
- `query` ⭐ **OBRIGATÓRIO**: Pergunta ou tópico
- `depth`: Profundidade (quick, medium, thorough) — padrão: medium

### Exemplo:
```
"Pesquisa em profundidade 'história da internet' com análise thorough"
→ Retorna findings detalhados com múltiplas fontes citadas
```

### Vantagens sobre web_search:
| Aspecto | web_search | research_advanced |
|--------|-----------|-------------------|
| **Profundidade** | Rápida | Profunda |
| **Fontes** | 5-10 | 50+ |
| **Análise** | Básica | Avançada |
| **Tempo** | ~5s | ~60s |
| **Melhor para** | Dúvidas rápidas | Relatórios/análises |

### ⚠️ Requisitos:
- Chave CellCog configurada
- Plano que inclua "Research Cog" (Pro ou superior)

---

## 📊 5. **analyze_data** (PREMIUM)
**Análise de dados com ML e estatísticas**

### Uso:
```
Analisa esta tabela de vendas
Que insights tem nestes dados de usuários?
Faz uma análise preditiva deste dataset
```

### Parâmetros:
- `csv_data` ⭐ **OBRIGATÓRIO**: Dados em formato CSV
- `analysis_type`: Tipo (exploratory, statistical, predictive) — padrão: exploratory

### Exemplo:
```
Usuário envia uma tabela Excel com vendas mensais
"Analisa isto com tipo predictive"
→ Retorna insights, gráficos, previsões e correlações
```

### Tipos de Análise:
- **exploratory**: Descobre padrões e outliers
- **statistical**: Testes de significância, correlações
- **predictive**: ML models para previsões futuras

### ⚠️ Requisitos:
- Chave CellCog configurada
- Plano que inclua "Data Cog" (Pro ou superior)

---

## 🎓 Outros Skills CellCog Disponíveis (Futuros)

Quando integrados, AKIRA terá acesso a:

### 📽️ **Slides/Apresentações**
- Gera decks de powerpoint automaticamente
- Skill: `generate_presentation`

### 📄 **Documentos**
- Cria PDFs, contratos, relatórios
- Skill: `generate_document`

### 💎 **3D Models**
- Gera modelos 3D (GLB para games/AR)
- Skill: `generate_3d_model`

### 🎨 **Branding**
- Cria identidades visuais completas
- Skill: `generate_brand_identity`

### 📚 **Tutoriais**
- Gera cursos e materiais educativos
- Skill: `generate_tutorial`

---

## ⚙️ Configuração

### 1️⃣ Obter Chave CellCog
```
1. Ir para https://cellcog.ai/
2. Criar conta (Plano Gratuito disponível)
3. Ir para Settings → API Keys
4. Copiar a chave
```

### 2️⃣ Adicionar ao .env
```bash
CELLCOG_API_KEY=sua_chave_aqui
CELLCOG_BASE_URL=https://api.cellcog.ai/v1
```

### 3️⃣ Testes Locais
```python
from modules.cellcog_integration import get_media_factory

media = get_media_factory()
result = media.generate_image(
    prompt="um gato futurista em neon",
    model="anime",
    aspect_ratio="1:1"
)
print(result)
```

---

## 🔄 Fallback Automático

Se `CELLCOG_API_KEY` não estiver configurada ou a API falhar:

| Skill | Fallback |
|-------|----------|
| `generate_image` | Pollinations Flux ✅ |
| `generate_video` | ❌ Não disponível |
| `generate_audio` | ❌ Não disponível |
| `research_advanced` | Volta para `web_search` |
| `analyze_data` | ❌ Não disponível |

---

## 💡 Exemplos Práticos

### Caso 1: Criar uma apresentação de negócios
```
Usuário: "Preciso de uma apresentação sobre IA para amanhã"
AKIRA: 
1. Executa research_advanced("inteligência artificial 2026")
2. Gera documento com dados
3. Cria presentation com slides
4. Envia link para baixar
```

### Caso 2: Analisar dados de vendas
```
Usuário: [Envia CSV com vendas]
Usuário: "Analisa estes dados e prevê vendas para junho"
AKIRA:
1. Executa analyze_data(csv, analysis_type="predictive")
2. Retorna gráficos e previsões
3. Identifica padrões de sazonalidade
```

### Caso 3: Criar assets visuais
```
Usuário: "Desenha um logo futurista em estilo 3D"
AKIRA:
1. Executa generate_image com model="3d"
2. Se falhar, fallback para Flux anime
3. Retorna imagem pronta para usar
```

---

## 📞 Suporte

- **Documentação CellCog**: https://docs.cellcog.ai/
- **API Reference**: https://api.cellcog.ai/docs
- **Planos**: https://cellcog.ai/pricing

---

**Última atualização**: Maio 2026  
**Status**: ✅ Integração Completa