Metadata-Version: 2.4
Name: ai-generator
Version: 0.2.0
Summary: Roteador de chamadas LLM por model:provider, multi-provider, com retorno consistente.
Author-email: Stamatios Stamou Jr <bushier.outsets.0c@icloud.com>
License: MIT
Keywords: llm,router,openai,gemini,anthropic,multi-provider
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Requires-Dist: requests>=2.28
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == "openai"
Provides-Extra: gemini
Requires-Dist: google-genai>=0.3; extra == "gemini"
Provides-Extra: claude
Requires-Dist: anthropic>=0.40; extra == "claude"
Provides-Extra: cerebras
Requires-Dist: cerebras-cloud-sdk>=1.0; extra == "cerebras"
Provides-Extra: all
Requires-Dist: openai>=1.30; extra == "all"
Requires-Dist: google-genai>=0.3; extra == "all"
Requires-Dist: anthropic>=0.40; extra == "all"
Requires-Dist: cerebras-cloud-sdk>=1.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# aigen

Roteador multi-provider para chamadas de IA com retorno consistente.

O caller escolhe explicitamente a key `model:provider`; o pacote instancia o
provider correspondente, executa a chamada e devolve um dataclass padronizado
com resposta, metadados técnicos e tokens reportados pelo provider.

Decisões de produto como tiers, créditos, planos, cobrança, limites comerciais
ou cálculo de custo não pertencem ao `aigen`. Quem chama o pacote pode usar
`total_tokens`, `input_tokens`, `output_tokens` e `reasoning_tokens` para fazer
qualquer cálculo externo.

## Instalação

SDKs de provider são extras opcionais. Instale só os que usar:

```bash
pip install "ai-generator[openai]"        # OpenAI, Groq, z.ai, Kimi, Alibaba, DeepSeek
pip install "ai-generator[gemini]"        # Google Gemini
pip install "ai-generator[claude]"        # Anthropic Claude
pip install "ai-generator[cerebras]"      # Cerebras
pip install "ai-generator[all]"           # tudo

# Desenvolvimento:
pip install -e ".[all]"
```

Providers HTTP puros funcionam só com o core (`httpx`, `requests`).

## Uso

Sempre passe `model='model:provider'`.

```python
import aigen

r = aigen.generate_text(
    'Resuma o texto X',
    model='gemini-2.5-flash:gemini',
)

print(r.content)
print(r.total_tokens)
```

Outras mídias usam o mesmo padrão:

```python
img = aigen.generate_image('um gato astronauta', model='gpt-image-2:openai')
video = aigen.generate_video('clipe contínuo de...', model='bytedance/seedance-1.5-pro:kie')
music = aigen.generate_music('lo-fi chill', model='music-2.6:minimax')
text = aigen.transcribe(audio_url, model='whisper-large-v3:groq')
audio = aigen.synthesize('Olá', model='elevenlabs/text-to-speech-turbo-2-5:kie')
```

Entry genérico:

```python
r = aigen.generate(prompt, mode='text', model='glm-5.2:zai')
r = aigen.generate(prompt, mode='video', model='bytedance/seedance-1.5-pro:kie')
r = aigen.generate(audio_url, mode='stt', model='whisper-large-v3:groq')
```

`mode`: `text` · `image` · `video` · `music` · `stt` · `tts`.

## Contrato

Sucesso retorna o dataclass do tipo. Falha levanta exception tipada.

| Mídia | Função | Retorno |
|-------|--------|---------|
| Texto | `generate_text` | `TextResponse` |
| Imagem | `generate_image` | `ProviderResponse` |
| Vídeo | `generate_video` | `VideoResponse` |
| Música | `generate_music` | `TTMResponse` |
| STT | `transcribe` | `STTResponse` |
| TTS | `synthesize` | `TTSResponse` |

Texto retorna `content`, `raw_content`, `input_tokens`, `output_tokens`,
`total_tokens`, `reasoning_tokens`, `response_time` e `model`. Outras mídias
seguem o mesmo padrão de resposta padronizada e metadados técnicos quando o
provider fornece.

## Erros

```text
ProviderError
├─ ProviderBlocked
└─ ProviderRetryable
   ├─ ProviderRateLimit
   └─ ProviderTimeout
```

Cada exception carrega `.provider`, `.model`, `.status_code`, `.response_time`
e `.raw_error`.

## Catálogo

O catálogo em `aigen/constants/{text,image,audio,video}.py` contém fatos técnicos:
providers suportados, variável de ambiente da API key, modelos conhecidos e
capabilities. Ele não contém preço, crédito, tier ou regra de cobrança.

Para registrar um modelo novo de um provider já suportado:

```python
import aigen

aigen.register_model('text', 'openai', 'gpt-5.4')
```

Providers novos exigem implementação de classe e registro no código do pacote.

## API keys

Cada provider lê a key de uma variável de ambiente (`api_key_env` no catálogo).
Defaults incluem `GOOGLE_API_KEY`, `OPENAI_API_KEY`, `CLAUDE_API_KEY`,
`GROQ_API_KEY`, `CEREBRAS_API_KEY`, `ZAI_API_KEY`, `MOONSHOT_AI_API_KEY`,
`DASHSCOPE_API_KEY`, `DEEPSEEK_API_KEY`, `MINIMAX_API_KEY` e `KIE_API_KEY`.

## Logs

O pacote usa `logging.getLogger(__name__)` e não configura handler. Para ver logs,
o app habilita logging no boot:

```python
import logging
logging.basicConfig(level=logging.INFO)
```

Stats de fim de chamada podem ser desligadas com `LOG_PROVIDER_STATS=0`.
