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-3.0:minimax')
text = aigen.transcribe(audio_url, model='whisper-large-v3:groq')
audio = aigen.synthesize('Olá', model='elevenlabs/text-to-speech-turbo-2-5:kie')
vecs = aigen.generate_embeddings(['texto a'], model='text-embedding-3-large:openai')
ranked = aigen.rerank('query', ['doc a', 'doc b'], model='cohere/rerank-4-pro:openrouter')

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 · embedding · rerank.

Contrato

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

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.

Áudio segue o modelo do VideoResult (url ou data, conforme o provider): TTS retorna audio: AudioResult (url/data/mime_type/duration) e TTM retorna tracks: list[TrackResult] (mais title, image_url e lyrics).

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,embedding,rerank}.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')

O catálogo runtime default pode remover modelos e voltar ao estado inicial:

aigen.unregister_model('text', 'openai', 'gpt-5.4')
aigen.reset_registry()

Para manter configurações isoladas, crie um registry próprio e passe-o às factories de provider:

registry = aigen.CatalogRegistry()
registry.register_model('text', 'openai', 'gpt-custom')
provider = aigen.get_text_provider(
    'gpt-custom:openai',
    catalog_registry=registry,
)

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.