Providers e chaves de API

A jangada suporta vários providers, cada um isolado em um adapter que traduz os tipos normalizados (Message/Completion) para o SDK nativo.

Os três últimos são gateways de nuvem (AWS, Azure, Google Cloud): mesmos modelos, hospedados na sua conta da nuvem, com IAM/billing/residência de dados do provedor. Veja AWS Bedrock, Azure OpenAI e Vertex AI.

OpenRouter (gateway para centenas de modelos)

OpenRouter é um gateway compatível com o dialeto chat.completions da OpenAI — por isso reusa o mesmo SDK openai (extra jangada-ai[openai]), só apontando para outro base_url. Dá acesso a centenas de modelos de vários provedores com uma única chave. O modelo é qualificado por provedor (provedor/modelo):

LLM("openrouter", "openai/gpt-4o")                       # usa OPENROUTER_API_KEY
LLM("openrouter", "anthropic/claude-sonnet-4.6")
LLM("openrouter", "google/gemini-2.5-flash", api_key="sk-or-...")

Argumentos exclusivos do OpenRouter (ex.: models para roteamento com fallback) vão por extra=; cabeçalhos de ranking via default_headers=:

LLM(
    "openrouter", "openai/gpt-4o",
    default_headers={"HTTP-Referer": "https://meusite.com", "X-Title": "Meu App"},
    extra={"models": ["openai/gpt-4o", "anthropic/claude-sonnet-4.6"]},
)

Suporta texto, streaming, structured output (json_schema com fallback automático para JSON Object mode), vision, tools/function calling, transcrição de áudio (openai/whisper-*, openai/gpt-4o-transcribe) e embeddings (openai/text-embedding-3-*, google/gemini-embedding-001). O único recurso não suportado é MCP server-side (depende da Responses API, que o OpenRouter não expõe — levanta UnsupportedError).

DeepSeek (raciocínio + thinking mode)

DeepSeek também fala chat.completions num base_url próprio — mesma receita do OpenRouter, reusa o SDK openai:

LLM("deepseek", "deepseek-v4-flash")   # rápido/barato
LLM("deepseek", "deepseek-v4-pro")     # raciocínio (thinking mode)

O modo thinking é um campo fora do schema típado do SDK oficial da OpenAI — passe por extra= que o adapter empacota em extra_body sozinho:

LLM("deepseek", "deepseek-v4-pro", extra={
    "thinking": {"type": "enabled", "reasoning_effort": "high"},  # low/high/max
})

Suporta texto, streaming, vision (deepseek-v4-flash-vision-exp) e tools/function calling. Não suporta JSON Schema estrito (parse vai direto pro JSON Object mode), MCP server-side nem transcrição de áudio — os três levantam UnsupportedError. Veja DeepSeek para detalhes.

Resolução da chave

LLM("openai", "gpt-4o-mini", api_key="sk-...")   # explícito
LLM("openai", "gpt-4o-mini")                       # usa OPENAI_API_KEY ou .env

Precedência: api_key= explícito > variável de ambiente > arquivo .env. O .env é detectado de forma não-destrutiva na importação (desative com JANGADA_NO_DOTENV=1).

Como cada adapter trata structured output

• OpenAI: chat.completions.parse(response_format=Modelo) → .message.parsed
• Groq: response_format={"type":"json_schema",...} + model_validate_json
• Gemini: config.response_schema=Modelo → resp.parsed
• Anthropic: tool-forcing (tool_choice fixo) → valida tool_use.input
• OpenRouter: igual ao Groq (json_schema com fallback p/ JSON Object mode)
• DeepSeek: sem json_schema — vai direto pro JSON Object mode

Veja Structured output para o uso uniforme.

Adicionando um provider novo

Se ele falar o dialeto chat.completions da OpenAI, herde de _OpenAICompatible e ajuste sdk_module/sync_class/async_class. Caso contrário, implemente os 6 métodos do contrato Provider. Detalhes em Estendendo.