keel-llm-adapter-google 0.1.2

Reference keel-llm-protocol adapter for Google's native Gemini generateContent API.

keel-llm-adapter-google

A reference keel-llm-protocol adapter for Google's native Gemini generateContent API.

The third and most divergent grounding for the protocol standard. Gemini's native wire format differs from both OpenAI and Anthropic — contents/parts, the "model" role, systemInstruction, generationConfig, functionCall parts, finishReason + promptFeedback.blockReason, and the Google error envelope. Every divergence is absorbed in the adapter; the protocol's types are unchanged.

Notably, Gemini supports native structured output, so this adapter's capabilities include json_object and json_schema — the contrast with keel-llm-adapter-anthropic (which declares neither) shows the capability-introspection design doing real work.

Is this for you?

Adopt when — you're consuming via keel-llm-protocol / keel-llm-reliability and want Gemini calls mapped to the typed taxonomy. Especially valuable for Gemini's free-tier ceiling (15 RPM) where RESOURCE_EXHAUSTED → RateLimitError is the high-leverage mapping. Skip when — you're calling Gemini directly in a simple app — the official google-generativeai SDK has a wider surface; this adapter covers chat / streaming / tools.

Install

pip install keel-llm-adapter-google     # pulls in keel-llm-protocol + httpx

Use

from keel_llm_adapter_google import GoogleAdapter
from keel_llm_protocol import user
from keel_llm_protocol.errors import RateLimitError

adapter = GoogleAdapter(model="gemini-2.0-flash", api_key="...", provider="google")

try:
    resp = await adapter.generate([user("Explain rate limiting briefly.")])
    print(resp.text, resp.usage.total_tokens, resp.finish_reason)
except RateLimitError as e:
    # Gemini free tier is 15 RPM — a 429 here means healthy-but-throttled.
    # The typed error lets a circuit breaker defer to a rate limiter instead of
    # tripping the model's circuit.
    await asyncio.sleep(e.retry_after or 5.0)

Same keel-llm-protocol types as every other adapter — code written against the protocol runs unchanged whether it's pointed at Gemini, an OpenAI-compatible endpoint, or Anthropic. Implements ModelAdapter, StreamingModelAdapter, ToolCallingModelAdapter.

How Gemini diverges — and where it's handled

Gemini divergence	Absorbed by
contents/parts request shape	adapter builds parts from Messages
Assistant role is "model"	adapter maps assistant → model
System prompt is systemInstruction	adapter lifts Message(role="system")
Params under generationConfig	adapter wraps temperature/maxOutputTokens/stopSequences
functionCall.args is a parsed dict	normalized to ToolCall.arguments (JSON string)
functionDeclarations + functionCallingConfig {AUTO|ANY|NONE}	mapped from ToolSpec / tool_choice
finishReason (STOP/MAX_TOKENS/SAFETY/…) + promptFeedback.blockReason	mapped to FinishReason; safety/blocks → content_filter; unmapped → unknown
Google error envelope; RESOURCE_EXHAUSTED/UNAVAILABLE/…	mapped to the standard error taxonomy
Native structured output (responseMimeType + responseSchema)	declared in capabilities; honored flag set

Status

0.1.2 — 0.x while the API stabilizes through year one (breaking changes possible at minor bumps, documented in the CHANGELOG; pin exact versions).

The Keel toolkit

Composable, vendor-neutral LLM reliability libraries on PyPI: keel-llm-reliability · keel-llm-protocol · keel-llm-adapter-openai · keel-llm-adapter-anthropic · keel-llm-adapter-google · keel-circuit-breaker

MIT licensed.