Gemini protocol adapter
The Gemini protocol adapter presents the generateContent and streamGenerateContent contracts while using the shared routing and provider system underneath. It keeps Gemini content, tool calls, reasoning state, token usage, errors, and stream completion meaningful when the selected provider speaks Chat, Messages, Responses, or native Gemini. See Protocol adapters, Conversation history replay and correction, and API gateway for the surrounding systems.
Request boundary
The request boundary accepts a Gemini-shaped body and keeps the model name in the URL as the route key. It validates the body before provider execution, then passes a native Gemini request to routing without changing caller-owned history.
Request shape
The Gemini request model accepts ordered contents, optional text-only systemInstruction, function declarations, tool choice, and generation controls. Each content part has one meaning: text, image data, function call, function result, or a replay signature. Strict fields and Gemini camel-case aliases prevent unsupported request data from reaching a provider. The route accepts generateContent for JSON and streamGenerateContent only with alt=sse.
References: src/…/routes.py• L66-126 src/…/models.py• L14-35 src/…/models.py• L37-99 src/…/models.py• L226-256
Routing boundary
The router resolves the URL model to a provider model and records the public model separately from the upstream model. The provider layer can send this request to native Gemini or translate other public request protocols into Gemini before opening the upstream stream. The executor estimates input tokens and opens the provider stream through the same fallback and recovery lifecycle used by the other public protocols.
This boundary means a Gemini client does not need to know which provider wire is active. A provider can receive Chat, native Messages, Responses, or native Gemini input while the client always receives Gemini candidates.
References: src/…/routing.py• L103-108 src/…/routing.py• L382-392 src/…/execution.py• L375-430 src/…/execution.py• L448-629 src/…/client.py• L141-286
History replay
History replay lets a later Gemini request continue a prior response without sending foreign provider state as if it were local state. Gemini carries adapter-issued replay data in thoughtSignature, while the source request remains unchanged.
History validation
History normalization checks function-call ownership and replay metadata before conversion. It assigns missing call IDs, matches function results to one pending call by ID or unique name, and rejects duplicate, orphaned, ambiguous, or unresolved calls. It also rejects caller-native signatures because the gateway can safely replay only its own bundle format.
References: src/…/history.py• L10-21 src/…/history.py• L22-65 src/…/history.py• L66-81
Replay projection
An adapter-issued signature contains a response identity, provider-owned reasoning records, tool-call metadata, and an optional digest for echoed visible thoughts. The request converter projects these records into the target wire as redacted thinking, encrypted Responses reasoning, or structured Chat reasoning. It restores Chat tool metadata only when provider, endpoint, connection, and model provenance is accepted.
The projection uses a fresh request copy. Same-connection native data can continue provider work; foreign data becomes safe context or stays out of the request. The native Gemini provider applies the same history checks before sending a request and can build a continuation request after a recoverable stream failure. This follows the wider history replay rule that native state must not cross an incompatible provider boundary.
References: src/…/replay.py• L22-51 src/…/replay.py• L54-97 src/…/replay.py• L100-152 src/…/request.py• L108-132 src/…/transport.py• L148-185 src/…/transport.py• L330-345
Web search replay
Completed Messages WebSearch turns can return in later requests while preserving the original Gemini tool-call order. The adapter checks that every visible search call has one matching result, then uses a signed Gemini replay record to restore the hidden function call and turn the saved result into a Gemini function response.
When no signed Gemini record exists, the adapter replaces search blocks with safe history text instead of sending them as executable tool state. When a signed record exists, it validates the hidden tool name, query, call count, and call order before restoring the turn. Ordinary client tool calls remain in place, so a turn can contain both client calls and automatic search calls.
The restored history yields the assistant turn and a following user turn for search results. The native converter then joins those results with other tool results in the original function-call order. Incomplete, duplicated, or mismatched search history becomes a Gemini conversion error rather than an invented tool result.
References: src/…/web_search_replay.py• L17-65 src/…/web_search_replay.py• L75-144 src/…/native_request.py• L331-340 src/…/native_request.py• L369-426
Content and tool conversion
The adapter converts one Gemini conversation into the request shape required by the selected provider protocol. It preserves order and links tool results to their calls instead of treating the request as a set of unrelated fields.
Content mapping
Text becomes user or assistant text in every destination. For native Gemini requests, supported cross-protocol image parts must be base64 data URLs and become inline image data; unsupported image detail and other image forms are rejected. Function results become functionResponse parts with text or structured output, and result images remain attached to the function result. System text is placed in the destination's system or instruction field.
The converter rejects content that has no faithful destination. Native Gemini conversion also rejects unsupported provider fields, non-text system content, and empty or unresolved tool history rather than dropping it. When Google AI Studio is the selected provider, the provider adapter turns Chat, Messages, and Responses requests into the native Gemini body before transport.
References: src/…/request.py• L42-59 src/…/request.py• L177-240 src/…/request.py• L250-258 src/…/native_request.py• L34-77 src/…/native_request.py• L169-178 src/…/native_request.py• L318-484 src/…/native_request.py• L487-632 src/…/client.py• L153-165 src/…/client.py• L208-212 src/…/client.py• L239-243
Tool mapping
Gemini function declarations become provider function tools with a portable name, description, and JSON schema. The adapter includes historical call names when it builds the request-wide name map, so a provider alias can be decoded back to the Gemini name. Tool choice maps AUTO, NONE, and ANY to the closest destination mode.
The native Gemini conversion path accepts function tools but cannot enforce strict schemas, provider-hosted tools, or disabled parallel calls. It keeps call IDs and names across function results, requires each result to match one earlier call, and rejects unsupported declaration fields. Function calls are emitted only from structured provider tool events. Their arguments must finish as finite JSON objects. An undeclared provider function, changed streamed arguments, or invalid argument shape becomes a conversion failure rather than a client-visible call that cannot be replayed.
Native Gemini output follows the same declaration check before it is projected to another client protocol.
References: src/…/request.py• L78-98 src/…/request.py• L259-290 src/…/native_request.py• L134-150 src/…/native_request.py• L243-315 src/…/native_request.py• L337-484 src/…/native_request.py• L527-632 src/…/response.py• L35-51 src/…/messages_stream.py• L76-99 src/…/responses_stream.py• L243-271 src/…/stream.py• L157-184
Generation controls
Sampling, output limits, stop sequences, and structured output are mapped only when the destination can represent them. Gemini schemas are normalized to JSON Schema while preserving constraints such as required fields, nullability, and nested properties. Unsupported controls produce an explicit conversion error instead of being dropped.
The native Gemini path maps common controls to generationConfig, including output limits, sampling values, stop sequences, and JSON or schema output formats. It rejects structured output formats that it cannot express and leaves provider-specific controls out of the request when the source protocol does not define a native equivalent.
References: src/…/request.py• L294-367 src/…/schema.py• L39-112 src/…/native_request.py• L153-166 src/…/native_request.py• L260-315 src/…/native_request.py• L429-484 src/…/native_request.py• L583-632 src/…/transport.py• L867-883 src/…/transport.py• L195-203
Reasoning and token handling
Gemini reasoning is an optional part of the candidate stream and a separate form of provider state for later turns. The adapter keeps visible thought text separate from opaque replay data, then maps provider usage into Gemini names.
Reasoning controls
thinkingBudget and thinkingLevel become the shared reasoning policy. A zero budget disables reasoning, a positive budget enables it with a limit, a negative budget enables it without a fixed limit, and a level becomes an effort preference. includeThoughts controls whether thought text is sent to the client; it does not discard the provider-owned replay record needed for history.
The route may apply a configured reasoning preference to a fallback candidate. The fallback request removes the client computation control before the new policy is applied, so one candidate does not inherit stale controls from another. Native Gemini requests keep an equivalent native policy when one is already present; cross-protocol requests set thought visibility from the shared policy. Native Gemini requests and requests translated for a native Gemini provider receive the same shared policy before transport.
References: src/…/models.py• L137-164 src/…/response.py• L54-117 src/…/native_request.py• L91-131 src/…/reasoning.py• L61-92 src/…/client.py• L153-176 src/…/client.py• L271-275
Token accounting
Input token handling is a bounded estimate used before provider execution. It counts text, function calls, function results, and tool declarations; it does not treat image bytes as ordinary text. Provider usage takes precedence at completion when it is valid.
Gemini usage names include promptTokenCount, candidatesTokenCount, totalTokenCount, cachedContentTokenCount, and thoughtsTokenCount. When a provider reports reasoning tokens with output tokens, the adapter subtracts reasoning from candidate output so the two fields do not count the same tokens twice.
References: src/…/tokens.py• L10-32 src/…/messages_stream.py• L100-145 src/…/responses_stream.py• L282-309 src/…/gemini_output.py• L107-132 src/…/stream.py• L273-309
Response delivery
The adapter uses one Gemini candidate format for both streamed and non-streamed calls. Provider-specific event streams are translated into data: JSON frames, while the non-streaming path consumes those same frames and folds them into one completed response.
Candidate frames
Each public frame carries the response ID, public model version, and candidate content when content is available. Text and thought deltas become Gemini parts. Completed function calls become functionCall parts. The final frame carries a Gemini finish reason and, when available, usage metadata and one opaque thoughtSignature for replay.
The provider stream presenters cover the upstream families:
- Chat output converts shared Chat deltas into Gemini parts.
- Messages output validates native block order and maps text, thinking, and tool blocks.
- Responses output joins text snapshots and deltas, completes reasoning items, and closes function calls.
- Native Gemini output validates one candidate and projects text, thoughts, and function calls to the requested client protocol. A native Gemini client can receive the upstream candidate shape directly.
References: src/…/gemini_output.py• L18-35 src/…/gemini_output.py• L67-105 src/…/messages_stream.py• L14-45 src/…/responses_stream.py• L14-58 src/…/stream.py• L64-227
Stream completion
The stream contract is a sequence of data: JSON frames with no provider event names. A successful stream ends with a candidate finish reason. The accumulator merges adjacent text or thought parts of the same kind and rejects data after completion or a stream that ends without a finish reason.
For a non-streaming request, the handler first creates the same managed stream and then aggregates it into one JSON response. This keeps streamed and non-streamed calls aligned for part order, tool validation, reasoning signatures, finish reasons, and usage. The native transport also requires an SSE content type and decodes the upstream events before the common stream rules apply.
References: src/…/response.py• L17-32 src/…/response.py• L152-207 src/…/gemini.py• L54-87 src/…/transport.py• L186-214 src/…/stream.py• L230-245
Delivery recovery
The shared delivery state records what Gemini content the client already received. If a provider fails after a safe text prefix, recovery can continue or hand off without repeating that prefix. It stops when the delivered state contains unsafe opaque data, released tool work, or too much retained replay evidence.
The native Gemini transport uses this state for early retry and continuation. It holds back output until recovery is safe, preserves only bounded native response data, and closes the upstream attempt before it starts a continuation.
References: src/…/stream_delivery.py• L13-80 src/…/response.py• L68-87 tests/…/test_gemini_delivery.py• L15-39 src/…/transport.py• L148-160 src/…/transport.py• L249-345
Error translation
The Gemini boundary turns validation, conversion, provider, and stream failures into Google-shaped error objects. The public error preserves an HTTP code and a Gemini status name without exposing provider-specific error internals.
Error envelopes
A request conversion error becomes HTTP 400 with INVALID_ARGUMENT. Application failures and execution failures use their mapped HTTP status and a Gemini status value such as UNAVAILABLE, RESOURCE_EXHAUSTED, or DEADLINE_EXCEEDED. Error text is passed through the shared safe-message boundary before it is returned.
The native Gemini stream maps an upstream error payload to a classified execution failure. Authentication, permission, rate-limit, request, and upstream failures keep their HTTP status and retry meaning until the public Gemini error boundary formats them.
References: src/…/errors.py• L6-27 src/…/gemini.py• L92-122 src/…/stream.py• L64-88
Stream failure boundary
The API reads the first stream frame before it commits to a streaming response. A failure before that frame becomes an HTTP JSON error. A failure after output starts becomes one final Gemini data frame with the error object, then the managed response closes and releases its request resources.
The native transport treats a malformed or non-SSE upstream response as a provider protocol failure. It can retry or continue only when the shared delivery state says that doing so will not duplicate visible output or released tool work.
References: src/…/response_streams.py• L191-219 src/…/response_streams.py• L398-430 src/…/response_streams.py• L56-131 src/…/transport.py• L205-214 src/…/transport.py• L315-363
Change checklist
When these files or sections are changed, remember to consider these:
- Keep Gemini field aliases, duplicate-key checks, URL model parsing, and
altrules aligned so invalid input fails before provider execution. - When a content part changes, update all three request destinations and all three provider stream presenters.
- When native request conversion changes, check image form, system content, tool-result order, source-protocol field limits, and output formatting together.
- When tool identity or schema rules change, update declarations, historical calls, forced choices, provider aliases, and returned function calls together.
- When replay data changes, keep
thoughtSignaturevalidation, provenance checks, thought echo suppression, and provider-specific replay projection aligned. - When WebSearch history changes, keep visible search IDs, hidden Gemini call names, signed native call order, saved result payloads, and ordinary client tool calls aligned.
- When reasoning controls change, check client policy, fallback policy, provider request fields, thought visibility, and usage subtraction together.
- When finish or usage fields change, check both stream frames and non-stream aggregation for translated and native Gemini output.
- When native Gemini transport changes, preserve SSE decoding, one-candidate handling, upstream error classification, attempt cleanup, and continuation rules.
- When failure handling changes, preserve the pre-start HTTP contract, post-start terminal frame, safe message rule, and response-resource cleanup.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A request uses an unsupported field, generation control, or content form | The provider request cannot preserve Gemini meaning | Strict request models and destination conversion raise an invalid-argument error before inference |
| A cross-protocol image is not a base64 data URL or uses unsupported detail | Native Gemini cannot build valid inline image data | Native conversion accepts only data URLs and auto or absent image detail |
| A function result cannot be matched to one earlier call | Tool history can attach output to the wrong call | History normalization requires a valid ID or one unique name match |
| A provider returns an undeclared function or non-object arguments | The client can receive a tool call that it cannot safely execute | Stream presenters decode request-scoped names and validate finite JSON objects |
| A native Gemini response contains multiple candidates, unsupported output parts, grounding, or citation data | The requested client protocol cannot represent the result safely | The native presenter accepts one candidate and rejects unsupported content or metadata |
| A replay signature is caller-native, malformed, conflicting, or from an unsafe source | Foreign provider state can fail upstream or leak into the wrong account | Only FCC-issued bundles are accepted and provenance is checked before metadata restore |
| WebSearch history has a missing, duplicate, or mismatched result | The next request can lose a search result or replay the wrong hidden call | The replay adapter requires one result per visible search and checks signed call names, queries, count, and order |
| A provider reports reasoning and output tokens in one total | Gemini candidate usage can double count reasoning | Final usage subtracts valid reasoning tokens from candidate output tokens |
| A provider stream ends without a finish reason or sends data after completion | Non-stream output can look successful or contain an invalid extra frame | The accumulator requires completion and rejects post-terminal data |
| A native upstream response is not an SSE stream or its event data is malformed | The adapter cannot safely apply the public stream contract | Transport checks the content type and the shared event reader validates stream data |
| A provider fails before the first public frame | The client receives a malformed or empty stream response | The API returns a normal Gemini HTTP error before stream commitment |
| A provider fails after public content or tool work is released | Retrying can duplicate visible output or tool work | Delivery evidence limits recovery to safe retained prefixes and stops unsafe cases |
Key files
| File | Why to read it |
|---|---|
| src/…/routes.py | Defines Gemini URL parsing, authentication, validation, and response lifetime ownership. |
| src/…/gemini.py | Connects routing, execution, streaming, aggregation, and Gemini error output. |
| src/…/models.py | Defines the supported Gemini request, content, tool, reasoning, and generation concepts. |
| src/…/history.py | Defines function-call matching and replay-bundle checks for Gemini history. |
| src/…/request.py | Shows how Gemini content, tools, schemas, controls, and replay become provider requests. |
| src/…/native_request.py | Shows how Chat, Messages, and Responses inputs become native Gemini contents, tools, generation settings, and replayable WebSearch history. |
| src/…/web_search_replay.py | Defines how completed Messages WebSearch turns become validated Gemini tool history. |
| src/…/replay.py | Defines the Gemini thought-signature bundle and safe Chat metadata restoration. |
| src/…/response.py | Defines Gemini frames, replay output, function-argument validation, and non-stream aggregation. |
| src/…/messages_stream.py | Maps native Messages stream blocks into Gemini candidate parts. |
| src/…/responses_stream.py | Maps Responses events, reasoning items, and function calls into Gemini output. |
| src/…/gemini_output.py | Shows the Chat stream presenter and final usage and finish mapping. |
| src/…/client.py | Connects public request protocols to native Gemini request bodies and shared reasoning policy. |
| src/…/stream.py | Projects native Gemini candidates into public output or returns the native candidate contract. |
| src/…/transport.py | Owns native Gemini HTTP streaming, history correction, retries, continuation, and cleanup. |
| src/…/execution.py | Shows Gemini token estimation, provider selection, fallback, and recovery entry points. |
| src/…/response_streams.py | Defines first-frame commitment, terminal Gemini error frames, and cleanup. |