Gemini

Provider gemini. Adapter sobre o SDK google-genai. Tem um único Client; o async fica em client.aio.

pip install "jangada-ai[gemini]"

provider=: "gemini"
Variável de ambiente: GEMINI_API_KEY (ou GOOGLE_API_KEY)

from jangada_ai import LLM
llm = LLM("gemini", "gemini-2.5-flash")

O que faz

Texto e streaming (generate_content / generate_content_stream).
Structured output (parse): config.response_schema=Modelo + response_mime_type="application/json" → resp.parsed.
Vision (images=): imagens viram types.Part.from_bytes.
Documentos (files=): extração de texto local.
Detecção de objetos (detect_objects): o mais preciso — o formato de bounding box 0–1000 é nativo do treino do Gemini.
Transcrição de áudio (transcribe): multimodal — o áudio entra como Part.from_bytes junto de uma instrução; não é endpoint dedicado.

Estrutura e quirks

Mensagens: o papel system vira system_instruction no GenerateContentConfig (não é uma mensagem comum); assistant vira model.
Parâmetros canônicos → config: max_tokens→max_output_tokens, stop→stop_sequences; temperature/top_p/top_k/seed passam direto. É o único provider com top_k.
Perfil de modelo (profiles.py): gemini-3.x descarta sampling (temperature/top_p/top_k). Veja Parâmetros e perfis.
Function calling multi-turno no 3.x — thought signatures (resolvido pela lib): o Gemini 3.x anexa um thought_signature opaco a cada function call e o exige de volta, inalterado, ao reenviar o histórico. A jangada preserva isso automaticamente — o valor viaja no campo opaco metadata: dict de ToolCall/ToolCallPart e o adapter o reanexa ao remontar o histórico. Assim tools=, Agent e MCPClient funcionam em multi-turno sem você tocar em nada. gemini-2.5 não usa esse campo. (corrigido em 1.3.1)
Resposta (Completion): usage vem de usage_metadata (prompt_token_count/candidates_token_count).

Thinking (raciocínio) — você passa só `thinking_budget`

O Gemini tem duas convenções incompatíveis: o 2.5 só aceita thinking_budget (em tokens) e o 3.x só aceita thinking_level (LOW/HIGH) — misturar dá HTTP 400. A jangada resolve isso por você: passe thinking_budget (ou thinking_level) e a lib adapta ao modelo, empacotando no thinking_config nativo por baixo dos panos.

# Funciona igual nas duas versões — você não muda nada:
LLM("gemini", "gemini-2.5-flash").complete("...", params={"thinking_budget": 1024})
LLM("gemini", "gemini-3-pro").complete("...",  params={"thinking_budget": 1024})
# no 2.5 vira thinking_config(thinking_budget=1024);
# no 3.x o perfil converte para thinking_config(thinking_level="HIGH").

thinking_budget: 0 desliga (quando o modelo permite), -1 é automático.
No 3.x, o budget é aproximado para um nível válido (LOW se ≤0, senão HIGH). No 2.5, um thinking_level é convertido para budget. Você também pode passar um thinking_config pronto, que é respeitado como veio.
Níveis aceitos: thinking_level reconhece MINIMAL/LOW/MEDIUM/HIGH. Como entrada no 2.5 os quatro viram um thinking_budget (0/1024/8192/24576). Direto no 3.x, o Gemini só aceita LOW/HIGH universalmente (MINIMAL é só Flash/Lite, MEDIUM só no 3.0 Flash; usá-los como nível em outros 3.x dá HTTP 400) — por isso a conversão budget→level usa só LOW/HIGH.

Por que é o "canivete suíço" aqui

É o único que cobre vision, detecção e áudio sem endpoints separados — tudo via generateContent. Veja Matriz de capacidades.

O que mudou na 1.9.0

ToolCall.id é o id que a API devolve (ou "nome#i" quando não vem) — não mais o nome da função. Duas chamadas paralelas à mesma função não colidem. O nome real continua sendo usado no function_response, e históricos antigos (id igual ao nome) seguem funcionando.
Parâmetro de tool chamado title não some mais do schema (o limpador de schema removia a chave title também dentro de properties).
Prompt bloqueado por safety levanta BadRequestError com o motivo (prompt_feedback.block_reason), sem retry nem fallback.
Usage: output_tokens inclui os tokens de thinking (reasoning_tokens mostra quantos) e input_tokens inclui os tokens de resultado de tools nativas — ambos são cobrados; antes o custo saía subestimado.
Tools nativas: Google Search, URL context, code execution, file search, Google Maps e computer use (veja Tools nativas). Para a Interactions API e os agentes (Deep Research), veja Interactions.
transcribe honra language=; parse com resposta vazia levanta erro em vez de devolver parsed=None; system em lista de partes tem o texto extraído.