ai-generator 0.2.0

Roteador de chamadas LLM por model:provider, multi-provider, com retorno consistente.

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:

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'.

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:

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:

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

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:

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:

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

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