Skip to main content

rig_core/providers/gemini/
completion.rs

1//! The [Gemini GenerateContent API](https://ai.google.dev/api/generate-content)
2//! completion wire. Its request is built as REST JSON by [`request_body`],
3//! which the Vertex AI and gRPC wires transcode, and its replies are read by
4//! [`GenerateContentDecoder`](super::streaming::GenerateContentDecoder).
5//!
6//! ```no_run
7//! use rig_core::providers::gemini::{Gemini, completion::GEMINI_2_5_FLASH};
8//!
9//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
10//! let wire = Gemini::from_env()?.completion(GEMINI_2_5_FLASH);
11//! # Ok(())
12//! # }
13//! ```
14
15/// `gemini-3.8-flash` completion model
16pub const GEMINI_3_8_FLASH: &str = "gemini-3.8-flash";
17/// `gemini-3.1-flash-lite-preview` completion model
18pub const GEMINI_3_1_FLASH_LITE_PREVIEW: &str = "gemini-3.1-flash-lite-preview";
19/// `gemini-3-flash-preview` completion model
20pub const GEMINI_3_FLASH_PREVIEW: &str = "gemini-3-flash-preview";
21/// `gemini-2.5-pro-preview-06-05` completion model
22pub const GEMINI_2_5_PRO_PREVIEW_06_05: &str = "gemini-2.5-pro-preview-06-05";
23/// `gemini-2.5-pro-exp-03-25` experimental completion model
24pub const GEMINI_2_5_PRO_EXP_03_25: &str = "gemini-2.5-pro-exp-03-25";
25/// `gemini-2.5-flash` completion model
26pub const GEMINI_2_5_FLASH: &str = "gemini-2.5-flash";
27/// `gemini-2.0-flash` completion model
28pub const GEMINI_2_0_FLASH: &str = "gemini-2.0-flash";
29
30use base64::Engine;
31use base64::prelude::BASE64_STANDARD;
32use serde_json::{Map, Value, json};
33
34pub use super::cached_content::with_cached_content;
35#[doc(hidden)]
36pub use super::options::Route;
37use super::options::generate_content_options;
38use crate::completion::options::{BaseInput, FinalBody, RawAt, Rewrite, request_params};
39use crate::completion::{Accepts, CompletionRequest, Media, Place, Replay, ReplayTarget};
40use crate::error::{EncodeError, ProviderError};
41use crate::json_utils::Lenient;
42use crate::json_utils::remove_preserving_order;
43use crate::message::{
44    AssistantContent, DocumentData, DocumentMediaType, DocumentSourceKind as Source, Message,
45    MimeType, ToolChoice, ToolResultContent, UserContent,
46};
47use crate::operation::Completion;
48use crate::providers::internal::set_fields;
49use crate::providers::internal::wire_ids::WireIds;
50use crate::telemetry::GenAiOperation;
51use crate::wire::{Descriptor, Encoded, Framing, Mode, Wire};
52
53/// Provider name used in normalized responses, streams, and telemetry.
54pub const PROVIDER_NAME: &str = "gcp.gemini";
55
56/// Completion wire for unary `generateContent` and SSE `streamGenerateContent`.
57/// Both modes use [`GenerateContentDecoder`](super::streaming::GenerateContentDecoder).
58#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
59pub struct GenerateContent {
60    /// The key and the API root.
61    pub provider: super::GeminiConfig,
62    /// The model to address, e.g. [`GEMINI_2_5_FLASH`].
63    pub model: String,
64    /// Handle of a `cachedContents` resource every request reads its prefix
65    /// from. See [`Self::with_cached_content`].
66    pub cached_content: Option<String>,
67    /// Which thought signatures requests re-send. See [`ThoughtReplay`].
68    #[serde(default)]
69    pub thought_replay: ThoughtReplay,
70    /// The model facts the encoder reads and replies are priced by.
71    #[serde(skip)]
72    pub facts: crate::catalog::ModelFacts,
73}
74
75/// Which earlier thought signatures a request re-sends.
76///
77/// On Gemini 3, every thought signature a request carries is expanded back
78/// into the reasoning it came from, and that reasoning is billed again as
79/// input on every later call. No explicit cache holds it. Measured on
80/// gemini-3.8-flash: a history whose earlier turns carried their signatures
81/// cost 6,708 prompt tokens; the same history without them cost 2,681, and
82/// Gemini answered normally. Over a 30-turn chat, dropping them cut input by
83/// 42%, and by 83% together with automatic caching.
84///
85/// Google's thinking guide says to send thought signatures back exactly as
86/// received. [`ThoughtReplay::CurrentTurn`] departs from that for turns the
87/// model has finished; its effect on answer quality is unmeasured. Hence
88/// [`ThoughtReplay::All`] is the default.
89#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
90pub enum ThoughtReplay {
91    /// Re-send every signature, as Google's guidance asks.
92    #[default]
93    All,
94    /// Re-send only the signatures at or after the newest user message: the
95    /// current turn, whose function calls Gemini validates. Parts before it
96    /// go out without their signature. The history itself is unchanged.
97    CurrentTurn,
98}
99
100impl GenerateContent {
101    /// The wire for `model`.
102    pub fn new(provider: super::GeminiConfig, model: impl Into<String>) -> Self {
103        Self {
104            provider,
105            model: model.into(),
106            cached_content: None,
107            thought_replay: ThoughtReplay::All,
108            facts: crate::catalog::ModelFacts::default(),
109        }
110    }
111
112    /// The same wire, encoding with `facts` and pricing its replies by
113    /// them.
114    pub fn with_facts(mut self, facts: crate::catalog::ModelFacts) -> Self {
115        self.facts = facts;
116        self
117    }
118
119    /// Re-send thought signatures as `replay` says. See [`ThoughtReplay`].
120    pub fn thought_replay(mut self, replay: ThoughtReplay) -> Self {
121        self.thought_replay = replay;
122        self
123    }
124
125    /// Use an explicit `cachedContents/<id>` handle as every request's prefix.
126    /// Encoding rejects requests with their own system instruction, tools, or
127    /// tool choice. See [`crate::providers::gemini::cached_content`] for cache ownership.
128    pub fn with_cached_content(mut self, name: impl Into<String>) -> Self {
129        self.cached_content = Some(name.into());
130        self
131    }
132}
133
134impl<T> crate::driver::Model<GenerateContent, T> {
135    /// This model, re-sending thought signatures as `replay` says. See
136    /// [`ThoughtReplay`]. Call it before [`caching`](Self::caching), which
137    /// reads it.
138    pub fn thought_replay(mut self, replay: ThoughtReplay) -> Self {
139        self.wire.thought_replay = replay;
140        self
141    }
142}
143
144/// Remove thought signatures from every part before the newest user text
145/// content: the turns the model has finished. Only the signature keys go;
146/// every other field is unchanged.
147fn drop_finished_signatures(contents: &mut [Value]) {
148    let current = contents.iter().rposition(|content| {
149        let parts = content.arr("parts");
150        content.str("role") == Some("user")
151            && parts.iter().any(|part| part.get("text").is_some())
152            && !parts
153                .iter()
154                .any(|part| part.get("functionResponse").is_some())
155    });
156    for content in contents.iter_mut().take(current.unwrap_or(0)) {
157        let parts = content.get_mut("parts").and_then(Value::as_array_mut);
158        for part in parts.into_iter().flatten().filter_map(Value::as_object_mut) {
159            remove_preserving_order(part, "thoughtSignature");
160        }
161    }
162}
163
164impl Wire for GenerateContent {
165    type Op = Completion;
166    type Payload = Encoded;
167    type Frame = crate::wire::WireFrame;
168    type Event = super::streaming::GenerateContentChunk;
169    type Decoder<'id> = super::streaming::GenerateContentDecoder;
170    type Reassembler = super::streaming::document::GenerateContentResponse;
171
172    fn describe(&self) -> Descriptor<'_> {
173        Descriptor::new(PROVIDER_NAME)
174            .model(self.model.as_str())
175            .facts(&self.facts)
176            .telemetry(|_| GenAiOperation::GenerateContent)
177            .replay(self)
178    }
179
180    fn encode(&self, request: CompletionRequest, mode: Mode) -> Result<Encoded, EncodeError> {
181        // The request may name a model of its own; the wire's is the default.
182        let model = request.model.clone().unwrap_or_else(|| self.model.clone());
183        let replay = self.thought_replay;
184        let body = request_body(
185            &request,
186            self,
187            &model,
188            self.cached_content.as_deref(),
189            |body| {
190                if let (ThoughtReplay::CurrentTurn, Some(Value::Array(contents))) =
191                    (replay, body.get_mut("contents"))
192                {
193                    drop_finished_signatures(contents);
194                }
195            },
196        )?;
197        use crate::providers::internal::LogTarget;
198        // `alt=sse` is what makes the streamed reply an event stream rather
199        // than a JSON array of the same chunks.
200        let (verb, framing, target) = match mode {
201            Mode::Unary => ("generateContent", Framing::Whole, LogTarget::Completions),
202            Mode::Streaming => (
203                "streamGenerateContent?alt=sse",
204                Framing::Sse,
205                LogTarget::Streaming,
206            ),
207        };
208        crate::providers::internal::trace_json(target, "Gemini completion request", &body);
209        let request = self
210            .provider
211            .post_json(&format!("/v1beta/models/{model}:{verb}"), body.into_body())?;
212        // Gemini supplies no transport request-id response header.
213        Ok(Encoded::new(request, framing))
214    }
215
216    fn decoder<'id>(&self) -> Self::Decoder<'id> {
217        super::streaming::GenerateContentDecoder::default()
218    }
219}
220
221impl GenerateContentWire for GenerateContent {
222    const ROUTE: Route = Route::Rest;
223
224    fn provider_name(&self) -> &'static str {
225        PROVIDER_NAME
226    }
227
228    fn wire_model(&self) -> &str {
229        &self.model
230    }
231
232    fn wire_facts(&self) -> &crate::catalog::ModelFacts {
233        &self.facts
234    }
235
236    fn cache_handle(&self) -> Option<&str> {
237        self.cached_content.as_deref()
238    }
239}
240
241/// A wire that speaks GenerateContent: the REST wire here, and the Vertex AI
242/// and gRPC wires in their crates. Each is a [`ReplayTarget`] through it.
243///
244/// For rig's own crates; not covered by semver.
245#[doc(hidden)]
246pub trait GenerateContentWire: std::fmt::Debug + crate::wasm_compat::WasmCompatSync {
247    /// The route, which decides the API name, whether a function response
248    /// takes file URLs, and the service tiers.
249    const ROUTE: Route;
250
251    /// The descriptor name of the provider the wire speaks to.
252    fn provider_name(&self) -> &'static str;
253
254    /// The model the wire addresses.
255    fn wire_model(&self) -> &str;
256
257    /// The model facts the encoder reads and replies are priced by.
258    fn wire_facts(&self) -> &crate::catalog::ModelFacts;
259
260    /// The `cachedContents` handle every request reads its prefix from.
261    fn cache_handle(&self) -> Option<&str> {
262        None
263    }
264}
265
266impl<W: GenerateContentWire> ReplayTarget for W {
267    fn facts(&self) -> Option<&crate::catalog::ModelFacts> {
268        Some(self.wire_facts())
269    }
270
271    fn api(&self) -> crate::message::Api {
272        crate::message::Api::from_static(match W::ROUTE {
273            Route::Vertex => "vertexai.generate_content",
274            Route::Rest | Route::Grpc => "gemini.generate_content",
275        })
276    }
277
278    fn provider(&self) -> &str {
279        self.provider_name()
280    }
281
282    fn model(&self) -> &str {
283        self.wire_model()
284    }
285
286    fn accepts(&self, model: &str) -> Accepts {
287        accepts(model)
288    }
289
290    /// Vertex AI declares `fileData` in a function response; the Gemini API
291    /// does not.
292    fn encodes(&self, _model: &str, media: Media<'_>) -> bool {
293        encodes(media, W::ROUTE == Route::Vertex)
294    }
295
296    fn normalize_tool_call_id(
297        &self,
298        id: &str,
299        model: &str,
300        _source: Option<&crate::message::Origin>,
301    ) -> String {
302        normalize_tool_call_id(model, id)
303    }
304
305    /// Gemini takes system text only in `systemInstruction`: later system
306    /// messages fold into the leading one, as pi's `collapseSystemMessages`.
307    fn later_system(&self, _model: &str) -> crate::completion::LaterSystem {
308        crate::completion::LaterSystem::Leading
309    }
310
311    fn call_id_slot(&self) -> Option<&'static str> {
312        Some("/functionCall/id")
313    }
314
315    fn blob_slots(&self) -> &'static [&'static str] {
316        &["/thoughtSignature"]
317    }
318
319    /// Tools in `tools`, in the `tools` of `additional_params`, or through a
320    /// `cachedContent` handle, since a cache holds its function
321    /// declarations.
322    fn declares_tools(&self, request: &CompletionRequest) -> bool {
323        let param = |key: &str| crate::completion::options::param(self, request, key);
324        self.cache_handle().is_some()
325            || !request.tools.is_empty()
326            || param("tools").is_some_and(|tools| !tools.as_array().is_none_or(Vec::is_empty))
327            || CACHED_CONTENT
328                .iter()
329                .any(|spelling| param(spelling).is_some_and(|value| !value.is_null()))
330    }
331
332    /// Section 6.4 of the typed-options design, for the route's tiers.
333    fn map_options(
334        &self,
335        request: &CompletionRequest,
336        fields: crate::completion::options::OptionFields<'_>,
337    ) -> crate::completion::options::OptionMap {
338        let model = request.model.as_deref().unwrap_or(self.wire_model());
339        generate_content_options(self.wire_facts(), model, W::ROUTE, fields)
340    }
341}
342
343/// The major version of a Gemini model id, read past a `models/` prefix:
344/// `gemini-<major>…` or `gemini-live-<major>…`, or `None` for an id that is
345/// not Gemini's. A Gemini id that names no version, such as the alias
346/// `gemini-flash-latest`, is the current generation (`u32::MAX`), so every
347/// rule reads an alias as the newest model.
348pub(super) fn gemini_major(model: &str) -> Option<u32> {
349    let model = model.to_ascii_lowercase();
350    let model = model.strip_prefix("models/").unwrap_or(&model);
351    let rest = model.strip_prefix("gemini-")?;
352    let rest = rest.strip_prefix("live-").unwrap_or(rest);
353    let end = rest
354        .find(|c: char| !c.is_ascii_digit())
355        .unwrap_or(rest.len());
356    Some(
357        rest.get(..end)
358            .and_then(|major| major.parse().ok())
359            .unwrap_or(u32::MAX),
360    )
361}
362
363/// Whether `model` is Gemini 3 or later, which validates the thought
364/// signatures of function calls. A Gemini alias counts as current.
365pub(super) fn gemini_3_or_later(model: &str) -> bool {
366    gemini_major(model).is_some_and(|major| major >= 3)
367}
368
369/// Whether `model` takes function-call ids on its calls and their
370/// responses: Claude, gpt-oss, and Gemini 3 or later (pi's rule).
371pub fn requires_tool_call_id(model: &str) -> bool {
372    let model = model.to_ascii_lowercase();
373    model.starts_with("claude-") || model.starts_with("gpt-oss-") || gemini_3_or_later(&model)
374}
375
376/// What `model` reads on every Gemini wire (REST, Vertex AI, gRPC and
377/// Interactions): images in every role, and images inside function
378/// responses only from Gemini 3 on. A Gemini alias reads them as the
379/// current generation, and a model that is not Gemini (Claude behind
380/// Vertex AI) is assumed to read them, as pi assumes.
381pub(crate) fn accepts(model: &str) -> Accepts {
382    Accepts {
383        tool_result_images: gemini_major(model).is_none_or(|major| major >= 3),
384        ..Accepts::ALL
385    }
386}
387
388/// Whether a GenerateContent wire takes `media`: data or a URL of a media
389/// type Gemini reads, or a text document, which goes as text. A YouTube video
390/// needs no media type and a file id is never taken. A function response
391/// takes image data, and a URL only when `response_files`: Vertex AI declares
392/// `fileData` there and the Gemini API does not.
393fn encodes(media: Media<'_>, response_files: bool) -> bool {
394    match media {
395        Media::Image(image, place) => {
396            reads_image(image.media_type.as_ref(), place)
397                && match image.data {
398                    Source::Base64(_) => true,
399                    Source::Url(_) => place != Place::ToolResult || response_files,
400                    _ => false,
401                }
402        }
403        Media::Audio(audio) => {
404            audio.media_type.is_some() && matches!(audio.data, Source::Url(_) | Source::Base64(_))
405        }
406        Media::Video(video) => match &video.data {
407            Source::Url(url) if url.starts_with("https://www.youtube.com") => true,
408            data => {
409                video.media_type.is_some() && matches!(data, Source::Url(_) | Source::Base64(_))
410            }
411        },
412        Media::Document(document) => match (&document.media_type, &document.data) {
413            (_, DocumentData::Text(_)) => true,
414            (Some(_), DocumentData::File(Source::Url(_))) => true,
415            (Some(media_type), DocumentData::File(Source::Base64(_))) => {
416                *media_type == DocumentMediaType::PDF
417            }
418            _ => false,
419        },
420    }
421}
422
423/// Whether Gemini reads an image of `media_type` at `place`: JPEG, PNG,
424/// WEBP, HEIC or HEIF, and only the first three in a function response.
425pub(crate) fn reads_image(
426    media_type: Option<&crate::message::ImageMediaType>,
427    place: Place,
428) -> bool {
429    use crate::message::ImageMediaType::{HEIC, HEIF, JPEG, PNG, WEBP};
430    match place {
431        Place::ToolResult => matches!(media_type, Some(JPEG | PNG | WEBP)),
432        _ => matches!(media_type, Some(JPEG | PNG | WEBP | HEIC | HEIF)),
433    }
434}
435
436/// `id` as `model` takes another model's call id: when the model takes ids
437/// at all, characters outside `[a-zA-Z0-9_-]` become `_` and it keeps at
438/// most 64 of them.
439fn normalize_tool_call_id(model: &str, id: &str) -> String {
440    if !requires_tool_call_id(model) {
441        return id.to_owned();
442    }
443    crate::providers::internal::wire_ids::legal_call_id(id, 64)
444}
445
446/// The REST `GenerateContentRequest` body `request` sends to `model` on
447/// `target`, a GenerateContent wire. The REST wire sends it; the Vertex AI
448/// and gRPC wires read it into their SDK and protobuf requests.
449///
450/// System messages become the system instruction, and the rest the
451/// contents. `adjust` finishes the wire's own encoding (a transport's
452/// spellings of `contents`, a `model` key) before [`request_params`] merges
453/// the mapped options and then `additional_params` over it: its `tools`
454/// add to the request's, its `generationConfig` merges over the typed
455/// fields key by key, and a `cachedContent` handle, like `cached_content`,
456/// is checked as [`GenerateContent::with_cached_content`] checks one. The
457/// fields Gemini's request shape leaves unset are sent as `null`, as
458/// recorded requests spell them.
459///
460/// # Errors
461///
462/// When an option is refused, `additional_params` is malformed, a tool's
463/// parameters are no schema Gemini reads, or a field is set two ways.
464pub fn request_body(
465    request: &CompletionRequest,
466    target: &dyn ReplayTarget,
467    model: &str,
468    cached_content: Option<&str>,
469    adjust: impl FnOnce(&mut Map<String, Value>),
470) -> Result<FinalBody, EncodeError> {
471    request_params(
472        target,
473        request,
474        |input| {
475            let mut body = base(request, target, model, input)?;
476            adjust(&mut body);
477            Ok(body)
478        },
479        RawAt::Top,
480        &[Rewrite::GeminiCachedContent(
481            cached_content.map(str::to_owned),
482        )],
483    )
484}
485
486/// The wire's own encoding of `request`: contents, system instruction,
487/// tools, tool choice and the typed fields in `generationConfig`.
488fn base(
489    request: &CompletionRequest,
490    target: &dyn ReplayTarget,
491    model: &str,
492    input: &mut BaseInput<'_>,
493) -> Result<Map<String, Value>, EncodeError> {
494    let extra_tools = input.raw_tools()?;
495    let schema = request
496        .output_schema
497        .clone()
498        .map(|schema| schema.to_value());
499    let mime = schema.as_ref().map(|_| json!("application/json"));
500    let (temperature, max_tokens) = (
501        request.temperature.map(Value::from),
502        request.max_tokens.map(Value::from),
503    );
504    let config = set_fields([
505        ("responseMimeType", mime),
506        ("responseJsonSchema", schema),
507        ("temperature", temperature),
508        ("maxOutputTokens", max_tokens),
509    ]);
510    let (mut system, mut history) = (Vec::new(), Vec::new());
511    for message in &request.chat_history {
512        match &**message {
513            Message::System { content } if content.is_empty() => {}
514            Message::System { content } => system.push(text_part(content)),
515            message => history.push(message),
516        }
517    }
518    // Gemini rejects a field set twice, and merges a tool choice set twice,
519    // which unions the allowed functions.
520    let preamble = "system instruction twice: as a preamble or system message";
521    let choice = "tool choice twice: as `tool_choice`, which Gemini merges,";
522    let twice = [
523        (!system.is_empty(), &SYSTEM_INSTRUCTION, preamble),
524        (request.tool_choice.is_some(), &TOOL_CONFIG, choice),
525    ];
526    for (set, spellings, what) in twice {
527        let raw = spellings
528            .iter()
529            .find(|spelling| input.param(spelling).is_some_and(|value| !value.is_null()));
530        if let (true, Some(spelling)) = (set, raw) {
531            return Err(EncodeError::request(format!(
532                "a Gemini request set the {what} and as `additional_params.{spelling}`. Set it \
533                 one way or the other"
534            )));
535        }
536    }
537    let declared: Vec<Value> = request.tools.iter().map(|tool| declaration(tool)).collect();
538    let declared = (!declared.is_empty()).then(|| {
539        Value::Object(set_fields([
540            ("functionDeclarations", Some(Value::Array(declared))),
541            ("codeExecution", Some(Value::Null)),
542        ]))
543    });
544    let tools: Vec<Value> = declared.into_iter().chain(extra_tools).collect();
545    let contents = Value::Array(contents(&history, target, model)?);
546    let system = (!system.is_empty()).then(|| content(system, "model"));
547    let tool_config = request
548        .tool_choice
549        .clone()
550        .map_or(Value::Null, calling_config);
551    Ok(set_fields([
552        ("contents", Some(contents)),
553        (
554            "generationConfig",
555            Some(if config.is_empty() {
556                Value::Null
557            } else {
558                Value::Object(config)
559            }),
560        ),
561        ("safetySettings", Some(Value::Null)),
562        ("toolConfig", Some(tool_config)),
563        ("systemInstruction", Some(system.unwrap_or(Value::Null))),
564        ("tools", (!tools.is_empty()).then_some(Value::Array(tools))),
565    ]))
566}
567
568/// A tool as its function declaration: its JSON Schema goes as
569/// `parametersJsonSchema`, which reads full JSON Schema, as pi sends it. A
570/// tool with no schema declares none.
571fn declaration(tool: &crate::completion::ToolDefinition) -> Value {
572    let parameters = (!tool.parameters.is_null()).then(|| tool.parameters.clone());
573    Value::Object(set_fields([
574        ("name", Some(Value::from(tool.name.as_str()))),
575        ("description", Some(Value::from(tool.description.as_str()))),
576        ("parametersJsonSchema", parameters),
577    ]))
578}
579
580/// Proto3 JSON accepts both lowerCamelCase and original proto field names.
581pub(super) const SYSTEM_INSTRUCTION: [&str; 2] = ["systemInstruction", "system_instruction"];
582pub(super) const TOOL_CONFIG: [&str; 2] = ["toolConfig", "tool_config"];
583const CACHED_CONTENT: [&str; 2] = ["cachedContent", "cached_content"];
584
585/// The first of `spellings` set to a value other than `null` in `body`.
586pub(super) fn present<'a>(body: &Map<String, Value>, spellings: &[&'a str]) -> Option<&'a str> {
587    let set = |spelling: &&&str| body.get(**spelling).is_some_and(|value| !value.is_null());
588    spellings.iter().find(set).copied()
589}
590
591/// The `functionCallingConfig` of `choice`.
592fn calling_config(choice: ToolChoice) -> Value {
593    let (mode, names) = match choice {
594        ToolChoice::Auto => ("AUTO", None),
595        ToolChoice::None => ("NONE", None),
596        ToolChoice::Required => ("ANY", None),
597        ToolChoice::Specific { function_names } => ("ANY", Some(json!(function_names))),
598    };
599    let config = set_fields([
600        ("mode", Some(json!(mode))),
601        ("allowed_function_names", names),
602    ]);
603    json!({ "functionCallingConfig": config })
604}
605
606/// The Gemini contents for `history`, a history without system messages,
607/// sent to `model` on `target`. A user message's function responses and
608/// its other parts go in contents of their own, in order, as pi sends
609/// them: Gemini answers text that shares a content with function responses
610/// poorly. Calls and their responses carry the ids [`WireIds`] spells when
611/// `model` takes ids.
612fn contents(
613    history: &[&Message],
614    target: &dyn ReplayTarget,
615    model: &str,
616) -> Result<Vec<Value>, EncodeError> {
617    let ids = WireIds::for_target(history, target, model);
618    let (with_ids, gemini3) = (requires_tool_call_id(model), gemini_3_or_later(model));
619    let mut contents = Vec::with_capacity(history.len());
620    let mut push = |role: &str, parts: Vec<Value>| {
621        // Gemini rejects a content with no parts, as pi skips one.
622        if !parts.is_empty() {
623            contents.push(content(parts, role));
624        }
625    };
626    for message in history {
627        match message {
628            Message::System { content } => push("user", vec![text_part(content)]),
629            Message::User { content } => {
630                let mut run = Vec::new();
631                let mut responses = false;
632                for part in content {
633                    let id = match part {
634                        UserContent::ToolResult(result) => {
635                            Some(ids.of(&result.call).filter(|_| with_ids))
636                        }
637                        _ => None,
638                    };
639                    if id.is_some() != responses {
640                        push("user", std::mem::take(&mut run));
641                    }
642                    responses = id.is_some();
643                    run.push(user_part(part, id.flatten())?);
644                }
645                push("user", run);
646            }
647            Message::Assistant(turn) => {
648                let parts = turn
649                    .content
650                    .iter()
651                    .map(|block| assistant_part(block, target, &ids, with_ids, gemini3));
652                push(
653                    "model",
654                    parts
655                        .collect::<Result<Vec<_>, _>>()?
656                        .into_iter()
657                        .flatten()
658                        .collect(),
659                );
660            }
661        }
662    }
663    Ok(contents)
664}
665
666/// A content of `parts` in `role`.
667fn content(parts: Vec<Value>, role: &str) -> Value {
668    Value::Object(set_fields([
669        ("parts", Some(Value::Array(parts))),
670        ("role", Some(Value::from(role))),
671    ]))
672}
673
674fn text_part(text: &str) -> Value {
675    json!({ "text": text, "thought": false })
676}
677
678pub(super) fn mime<M: MimeType>(media_type: Option<M>) -> Option<String> {
679    media_type.map(|media_type| media_type.to_mime_type().to_owned())
680}
681
682/// Where `source` puts media on every Gemini wire, REST and Interactions
683/// alike: a URL by reference (`true`) and base64 data inline. Each wire's
684/// `encodes` refuses every other form, so the adapter passes none.
685pub(super) fn carried(source: &Source) -> Result<(bool, &str), EncodeError> {
686    match source {
687        Source::Url(uri) => Ok((true, uri)),
688        Source::Base64(data) => Ok((false, data)),
689        _ => Err(EncodeError::request(
690            "Gemini cannot receive this media in its form",
691        )),
692    }
693}
694
695/// `source` of `mime_type` as GenerateContent part data, file data by URI
696/// or inline data, which needs a media type; a whole `part` is marked as no
697/// thought.
698pub(super) fn media(
699    mime_type: Option<String>,
700    source: &Source,
701    part: bool,
702) -> Result<Value, EncodeError> {
703    let (uri, data) = carried(source)?;
704    let data = match (uri, mime_type) {
705        (true, mime) => ("fileData", json!({ "mimeType": mime, "fileUri": data })),
706        (false, Some(mime)) => ("inlineData", json!({ "mimeType": mime, "data": data })),
707        (false, None) => {
708            return Err(EncodeError::request(
709                "Gemini cannot receive media without its type",
710            ));
711        }
712    };
713    Ok(Value::Object(set_fields([
714        (data.0, Some(data.1)),
715        ("thought", part.then_some(Value::Bool(false))),
716    ])))
717}
718
719/// A user part as Gemini takes it. A function response carries `id`, its
720/// call's wire spelling, when the model takes ids, and the error key when
721/// the tool failed, as the Gemini SDKs spell a function's failure. Images
722/// the adapter leaves in a result (a model that reads them) go in its
723/// `parts`, in order.
724fn user_part(part: &UserContent, id: Option<&str>) -> Result<Value, EncodeError> {
725    Ok(match part {
726        UserContent::Text(text) => text_part(&text.text),
727        UserContent::ToolResult(result) => {
728            let (mut values, mut parts) = (Vec::new(), Vec::new());
729            for item in &result.content {
730                match item {
731                    ToolResultContent::Text(text) => values.push(Value::from(text.text.as_str())),
732                    ToolResultContent::Json { value } => values.push(value.clone()),
733                    ToolResultContent::Image(image) => {
734                        parts.push(media(mime(image.media_type.clone()), &image.data, false)?);
735                    }
736                }
737            }
738            let key = if result.is_error { "error" } else { "result" };
739            let value = match values.len() {
740                0 => None,
741                1 => values.pop(),
742                _ => Some(Value::Array(values)),
743            };
744            let response = set_fields([
745                ("name", Some(json!(result.name))),
746                ("id", id.map(Value::from)),
747                (
748                    "response",
749                    value.map(|value| Value::Object(Map::from_iter([(key.into(), value)]))),
750                ),
751                ("parts", (!parts.is_empty()).then_some(Value::Array(parts))),
752            ]);
753            Value::Object(set_fields([
754                ("functionResponse", Some(Value::Object(response))),
755                ("thought", Some(Value::Bool(false))),
756            ]))
757        }
758        UserContent::Image(image) => media(mime(image.media_type.clone()), &image.data, true)?,
759        // A text document goes as text, so that RAG context reads as prose.
760        UserContent::Document(document) => match &document.data {
761            DocumentData::Text(text) => text_part(text),
762            DocumentData::File(data) => media(mime(document.media_type.clone()), data, true)?,
763        },
764        UserContent::Audio(audio) => media(mime(audio.media_type.clone()), &audio.data, true)?,
765        UserContent::Video(video) => {
766            let mut part = media(mime(video.media_type.clone()), &video.data, true)?;
767            if let (Some(Value::Object(extra)), Some(part)) =
768                (&video.additional_params, part.as_object_mut())
769            {
770                part.extend(extra.clone());
771            }
772            part
773        }
774    })
775}
776
777/// One assistant block as a Gemini part: its provider item while that is
778/// current, else a part rebuilt from its canonical fields, or `None` when
779/// it has nothing to send. Calls carry ids only `with_ids`. A rebuilt call
780/// on Gemini 3 (`gemini3`) carries Google's placeholder signature, since
781/// Gemini 3 rejects a call it did not sign without one ("Function call is
782/// missing a thought_signature in functionCall parts").
783fn assistant_part(
784    block: &AssistantContent,
785    target: &dyn ReplayTarget,
786    ids: &WireIds,
787    with_ids: bool,
788    gemini3: bool,
789) -> Result<Option<Value>, EncodeError> {
790    if let Replay::Item(item) = block.replay(target, ids) {
791        let mut item = item.into_owned();
792        if let Some(part) = item.as_object_mut() {
793            if let (false, Some(Value::Object(call))) = (with_ids, part.get_mut("functionCall")) {
794                remove_preserving_order(call, "id");
795            }
796            // Gemini rejects the whole request over a signature that is
797            // not base64 ("Base64 decoding failed").
798            if part
799                .get("thoughtSignature")
800                .and_then(Value::as_str)
801                .is_some_and(|signature| {
802                    signature.is_empty() || BASE64_STANDARD.decode(signature).is_err()
803                })
804            {
805                remove_preserving_order(part, "thoughtSignature");
806            }
807        }
808        return Ok(Some(item));
809    }
810    Ok(Some(match block {
811        AssistantContent::Text(text) => json!({ "text": text.text }),
812        AssistantContent::Reasoning(reasoning)
813            if reasoning.redacted || reasoning.text.trim().is_empty() =>
814        {
815            return Ok(None);
816        }
817        AssistantContent::Reasoning(reasoning) => {
818            json!({ "thought": true, "text": reasoning.text })
819        }
820        AssistantContent::ToolCall(call) => {
821            let id = ids.of(&call.id).filter(|_| with_ids).map(Value::from);
822            let name = Some(json!(call.function.name));
823            let args = Some(json!(call.function.arguments));
824            let signature = gemini3.then(|| json!("skip_thought_signature_validator"));
825            let call = Value::Object(set_fields([("name", name), ("args", args), ("id", id)]));
826            Value::Object(set_fields([
827                ("functionCall", Some(call)),
828                ("thoughtSignature", signature),
829            ]))
830        }
831        AssistantContent::Image(image) => media(mime(image.media_type.clone()), &image.data, true)?,
832        AssistantContent::Opaque(opaque) => opaque.item.clone(),
833    }))
834}
835
836/// Convert a specified prompt block reason into a provider error with its
837/// safety ratings. `feedback` is the reply's `promptFeedback` JSON, read
838/// leniently. Content refusals are final; `OTHER` and unknown reasons are
839/// transient. The zero value names no block: Gemini spells it
840/// `BLOCK_REASON_`, Vertex AI `BLOCKED_REASON_`.
841pub(crate) fn blocked_prompt_error(feedback: &Value) -> Option<ProviderError> {
842    let reason = match feedback.get("blockReason")? {
843        Value::String(reason) => reason.clone(),
844        Value::Number(number) => format!("BLOCK_REASON_{number}"),
845        _ => return None,
846    };
847    if matches!(
848        reason.as_str(),
849        "BLOCK_REASON_UNSPECIFIED" | "BLOCKED_REASON_UNSPECIFIED"
850    ) {
851        return None;
852    }
853    let spelled = |value: Option<&Value>| match value {
854        Some(Value::String(name)) => name.clone(),
855        Some(other) => other.to_string(),
856        None => "<unset>".to_owned(),
857    };
858    let ratings = feedback.arr("safetyRatings").iter();
859    let ratings = ratings.map(|rating| {
860        format!(
861            "{}={}",
862            spelled(rating.get("category")),
863            spelled(rating.get("probability"))
864        )
865    });
866    let ratings: Vec<String> = ratings.collect();
867    let ratings = match ratings.is_empty() {
868        true => String::new(),
869        false => format!(", safety_ratings=[{}]", ratings.join(", ")),
870    };
871    let message = format!("Gemini blocked the prompt: block_reason={reason}{ratings}");
872    let error = crate::provider_response::ProviderResponseError::without_status(message)
873        .with_code(Some(reason.clone()));
874    Some(ProviderError::ProviderResponse(match reason.as_str() {
875        "SAFETY" | "BLOCKLIST" | "PROHIBITED_CONTENT" | "IMAGE_SAFETY" | "MODEL_ARMOR"
876        | "JAILBREAK" => error.with_refusal(true),
877        _ => error.with_transient(Some(true)),
878    }))
879}
880
881/// Map a Google `finishReason` in its SCREAMING_SNAKE_CASE wire spelling.
882/// `STOP` is a stop (a tool use when the turn holds calls) and `MAX_TOKENS`
883/// a length stop. Every other reason, documented or not, is a failure: the
884/// content filters as
885/// [`ContentFilter`](crate::completion::FinishReason::ContentFilter), the
886/// rest as [`Other`](crate::completion::FinishReason::Other) with the
887/// reason's name.
888pub fn map_google_finish_reason(wire_name: &str) -> crate::completion::FinishReason {
889    use crate::completion::FinishReason;
890    match wire_name {
891        "STOP" => FinishReason::Stop,
892        "MAX_TOKENS" => FinishReason::Length,
893        "SAFETY"
894        | "BLOCKLIST"
895        | "PROHIBITED_CONTENT"
896        | "SPII"
897        | "IMAGE_SAFETY"
898        | "IMAGE_PROHIBITED_CONTENT"
899        | "MODEL_ARMOR" => FinishReason::ContentFilter,
900        other => FinishReason::Other(other.to_owned()),
901    }
902}
903
904/// A whole `generateContent` reply, as the image and transcription wires
905/// read one.
906pub(crate) fn classify_reply(body: &str) -> crate::wire::WireEvent<Value> {
907    crate::providers::internal::wire::classify_marker_keyed_frame(
908        body,
909        &["candidates", "promptFeedback", "usageMetadata"],
910    )
911}
912
913/// Rig's usage for a `usageMetadata` document, read leniently: a count that
914/// is absent or not a non-negative integer is unreported, and no other field
915/// is read, so usage never fails a reply. Rig's input is the prompt plus the
916/// tool-use prompt, its output the candidates plus the thoughts, and its
917/// total their sum. A count Gemini leaves out is zero in those sums, as its
918/// JSON omits zeros. The REST, Vertex AI and gRPC wires all read usage here.
919pub fn usage_of(usage: &Value) -> crate::completion::Usage {
920    let count = |key: &str| usage.get(key).and_then(Value::as_u64);
921    let tool_use = count("toolUsePromptTokenCount");
922    let thoughts = count("thoughtsTokenCount");
923    let input = count("promptTokenCount")
924        .unwrap_or(0)
925        .saturating_add(tool_use.unwrap_or(0));
926    let output = count("candidatesTokenCount")
927        .unwrap_or(0)
928        .saturating_add(thoughts.unwrap_or(0));
929    crate::completion::Usage {
930        input_tokens: Some(input),
931        output_tokens: Some(output),
932        cached_input_tokens: count("cachedContentTokenCount"),
933        reasoning_tokens: thoughts,
934        tool_use_prompt_tokens: tool_use,
935        total_tokens: Some(input.saturating_add(output)),
936        cache_creation_input_tokens: None,
937        ..Default::default()
938    }
939}
940
941#[cfg(test)]
942mod tests;
943
944#[cfg(test)]
945mod cached_content_conflict_matrix;
946#[cfg(test)]
947mod cached_content_request_tests;