Metadata-Version: 2.4
Name: keel-llm-adapter-google
Version: 0.1.2
Summary: Reference keel-llm-protocol adapter for Google's native Gemini generateContent API.
Project-URL: Homepage, https://github.com/keelplatform/keel
Project-URL: Source, https://github.com/keelplatform/keel/tree/main/py/packages/llm-adapter-google
Project-URL: Changelog, https://github.com/keelplatform/keel/blob/main/py/packages/llm-adapter-google/CHANGELOG.md
Author: Raj Yakkali
License: MIT
Keywords: adapter,gemini,google,keel,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: keel-llm-protocol>=0.1.0
Description-Content-Type: text/markdown

# keel-llm-adapter-google

> A reference [`keel-llm-protocol`](https://pypi.org/project/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`](https://pypi.org/project/keel-llm-protocol/) / [`keel-llm-reliability`](https://pypi.org/project/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

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

## Use

```python
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 `Message`s |
| 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`](https://pypi.org/project/keel-llm-reliability/) · [`keel-llm-protocol`](https://pypi.org/project/keel-llm-protocol/) · [`keel-llm-adapter-openai`](https://pypi.org/project/keel-llm-adapter-openai/) · [`keel-llm-adapter-anthropic`](https://pypi.org/project/keel-llm-adapter-anthropic/) · [`keel-llm-adapter-google`](https://pypi.org/project/keel-llm-adapter-google/) · [`keel-circuit-breaker`](https://pypi.org/project/keel-circuit-breaker/)

MIT licensed.
