Skip to main content

rig_core/providers/gemini/
extension.rs

1//! Typed request options and reply extras for the Gemini API, keyed by
2//! [`PROVIDER_NAME`](super::PROVIDER_NAME). One [`GeminiOptions`] serves both
3//! routes: its `"*"` section goes to GenerateContent and Interactions alike,
4//! and each route section only to its own route.
5//!
6//! [`GeminiExtras`] reads the reply document of either route. A field the
7//! route taken does not return reads `None`.
8//!
9//! ```
10//! use rig_core::completion::CompletionRequest;
11//! use rig_core::providers::gemini::extension::GeminiOptions;
12//!
13//! let options = GeminiOptions::new().top_k(40);
14//! let request = CompletionRequest::new("hi").provider_option(options);
15//! # let _ = request;
16//! ```
17
18use std::collections::BTreeMap;
19
20use serde::de::Error as _;
21use serde::{Deserialize, Serialize, Serializer};
22use serde_json::Value;
23
24use crate::completion::provider_options::{ExtensionOptions, ProviderExtension, ReplyExtras};
25use crate::message::Api;
26
27use super::ImageSize;
28use super::interactions_api::InteractionSpeechConfig;
29
30/// The API name of the GenerateContent route.
31const GENERATE_CONTENT: &str = "gemini.generate_content";
32
33/// The API name of the Interactions route.
34const INTERACTIONS: &str = "gemini.interactions";
35
36/// The Gemini API's extension: [`GeminiOptions`] and [`GeminiExtras`].
37#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
38pub struct GeminiExt;
39
40impl ProviderExtension for GeminiExt {
41    const PROVIDER: &'static str = super::PROVIDER_NAME;
42    type Options = GeminiOptions;
43    type Extras = GeminiExtras;
44}
45
46/// Whether `value` is its type's default, so a section or config that sets
47/// nothing writes no key.
48fn is_default<T: Default + PartialEq>(value: &T) -> bool {
49    *value == T::default()
50}
51
52/// The Gemini API's request options: a section both routes read, and one
53/// per route.
54///
55/// The `generationConfig` setters here (`top_k`, `include_thoughts`, ...)
56/// write the same entry as the nested [`GenerateContentOptions`] form, so
57/// only GenerateContent sends them. [`generate_content`](Self::generate_content)
58/// replaces the whole section, including entries set before it. Safety
59/// settings stay per section, because each route spells them differently.
60#[non_exhaustive]
61#[derive(Clone, Debug, Default, PartialEq, Serialize)]
62pub struct GeminiOptions {
63    /// Fields both routes spell the same.
64    #[serde(rename = "*")]
65    pub shared: GeminiShared,
66    /// Fields only GenerateContent reads.
67    #[serde(rename = "gemini.generate_content")]
68    pub generate_content: GenerateContentOptions,
69    /// Fields only Interactions reads.
70    #[serde(rename = "gemini.interactions")]
71    pub interactions: InteractionsOptions,
72}
73
74impl GeminiOptions {
75    /// No field set.
76    pub fn new() -> Self {
77        Self::default()
78    }
79
80    /// Whether the API stores the request and its reply (`store`).
81    pub fn store(mut self, store: bool) -> Self {
82        self.shared.store = Some(store);
83        self
84    }
85
86    /// Add the label `key` = `value` (`labels`), user metadata the API
87    /// reports billing by.
88    pub fn label(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
89        self.shared.labels.insert(key.into(), value.into());
90        self
91    }
92
93    /// The GenerateContent section.
94    pub fn generate_content(mut self, section: GenerateContentOptions) -> Self {
95        self.generate_content = section;
96        self
97    }
98
99    /// The Interactions section.
100    pub fn interactions(mut self, section: InteractionsOptions) -> Self {
101        self.interactions = section;
102        self
103    }
104
105    /// Apply `set` to the GenerateContent `generationConfig` entries.
106    fn generation_config_entry(
107        mut self,
108        set: impl FnOnce(GenerationConfig) -> GenerationConfig,
109    ) -> Self {
110        let common = std::mem::take(&mut self.generate_content.generation_config.common);
111        self.generate_content.generation_config.common = set(common);
112        self
113    }
114
115    /// GenerateContent `generationConfig.thinkingConfig.includeThoughts`,
116    /// as [`GenerationConfig::include_thoughts`] in the GenerateContent
117    /// section. Interactions reads its own `thinking_summaries` instead.
118    pub fn include_thoughts(self, include: bool) -> Self {
119        self.generation_config_entry(|config| config.include_thoughts(include))
120    }
121
122    /// GenerateContent `generationConfig.topK`, as
123    /// [`GenerationConfig::top_k`] in the GenerateContent section.
124    pub fn top_k(self, top_k: u32) -> Self {
125        self.generation_config_entry(|config| config.top_k(top_k))
126    }
127
128    /// GenerateContent `generationConfig.presencePenalty`, as
129    /// [`GenerationConfig::presence_penalty`] in the GenerateContent section.
130    pub fn presence_penalty(self, penalty: f64) -> Self {
131        self.generation_config_entry(|config| config.presence_penalty(penalty))
132    }
133
134    /// GenerateContent `generationConfig.frequencyPenalty`, as
135    /// [`GenerationConfig::frequency_penalty`] in the GenerateContent
136    /// section.
137    pub fn frequency_penalty(self, penalty: f64) -> Self {
138        self.generation_config_entry(|config| config.frequency_penalty(penalty))
139    }
140
141    /// GenerateContent `generationConfig.responseLogprobs`, as
142    /// [`GenerationConfig::response_logprobs`] in the GenerateContent
143    /// section.
144    pub fn response_logprobs(self, enable: bool) -> Self {
145        self.generation_config_entry(|config| config.response_logprobs(enable))
146    }
147
148    /// GenerateContent `generationConfig.logprobs`, as
149    /// [`GenerationConfig::logprobs`] in the GenerateContent section.
150    pub fn logprobs(self, top: u32) -> Self {
151        self.generation_config_entry(|config| config.logprobs(top))
152    }
153
154    /// GenerateContent `generationConfig.candidateCount`, as
155    /// [`GenerationConfig::candidate_count`] in the GenerateContent section.
156    pub fn candidate_count(self, count: CandidateCount) -> Self {
157        self.generation_config_entry(|config| config.candidate_count(count))
158    }
159
160    /// GenerateContent `generationConfig.responseModalities`, as
161    /// [`GenerationConfig::response_modalities`] in the GenerateContent
162    /// section.
163    pub fn response_modalities(
164        self,
165        modalities: impl IntoIterator<Item = ResponseModality>,
166    ) -> Self {
167        self.generation_config_entry(|config| config.response_modalities(modalities))
168    }
169
170    /// GenerateContent `generationConfig.mediaResolution`, as
171    /// [`GenerationConfig::media_resolution`] in the GenerateContent
172    /// section.
173    pub fn media_resolution(self, resolution: MediaResolution) -> Self {
174        self.generation_config_entry(|config| config.media_resolution(resolution))
175    }
176}
177
178impl ExtensionOptions for GeminiOptions {
179    type Ext = GeminiExt;
180}
181
182/// The fields both Gemini routes read, at the top level of the body.
183#[non_exhaustive]
184#[derive(Clone, Debug, Default, PartialEq, Serialize)]
185pub struct GeminiShared {
186    /// `store`: whether the API stores the request and its reply.
187    #[serde(skip_serializing_if = "Option::is_none")]
188    pub store: Option<bool>,
189    /// `labels`: user metadata, each key and value at most 63 lowercase
190    /// letters, digits, underscores and dashes.
191    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
192    pub labels: BTreeMap<String, String>,
193}
194
195/// The GenerateContent-only fields: `generationConfig` entries and
196/// `safetySettings`.
197#[non_exhaustive]
198#[derive(Clone, Debug, Default, PartialEq, Serialize)]
199pub struct GenerateContentOptions {
200    /// `generationConfig` entries, merged key by key with the ones the
201    /// request and its generation options write.
202    #[serde(rename = "generationConfig", skip_serializing_if = "is_default")]
203    pub generation_config: GeminiGenerationConfig,
204    /// `safetySettings`, which take the place of the `null` sent otherwise.
205    #[serde(rename = "safetySettings", skip_serializing_if = "Vec::is_empty")]
206    pub safety_settings: Vec<SafetySetting>,
207}
208
209impl GenerateContentOptions {
210    /// No field set.
211    pub fn new() -> Self {
212        Self::default()
213    }
214
215    /// The `generationConfig` entries every GenerateContent route takes.
216    pub fn generation_config(mut self, config: GenerationConfig) -> Self {
217        self.generation_config.common = config;
218        self
219    }
220
221    /// `generationConfig.enableEnhancedCivicAnswers`.
222    pub fn enable_enhanced_civic_answers(mut self, enable: bool) -> Self {
223        self.generation_config.enable_enhanced_civic_answers = Some(enable);
224        self
225    }
226
227    /// Add a safety setting: block `category` at `threshold`.
228    pub fn safety_setting(mut self, category: HarmCategory, threshold: HarmBlockThreshold) -> Self {
229        self.safety_settings
230            .push(SafetySetting::new(category, threshold));
231        self
232    }
233}
234
235/// The Gemini API's `generationConfig` entries: the ones every
236/// GenerateContent route takes and the API's own.
237#[non_exhaustive]
238#[derive(Clone, Debug, Default, PartialEq, Serialize)]
239pub struct GeminiGenerationConfig {
240    /// The entries every GenerateContent route takes.
241    #[serde(flatten)]
242    pub common: GenerationConfig,
243    /// `enableEnhancedCivicAnswers`.
244    #[serde(
245        rename = "enableEnhancedCivicAnswers",
246        skip_serializing_if = "Option::is_none"
247    )]
248    pub enable_enhanced_civic_answers: Option<bool>,
249}
250
251/// The `generationConfig` entries the Gemini API, Vertex AI and the gRPC
252/// API all take. None of them is one a request or its generation options
253/// write: `temperature`, `maxOutputTokens`, `topP`, `seed`, `stopSequences`
254/// and the thinking level or budget are set there.
255#[non_exhaustive]
256#[derive(Clone, Debug, Default, PartialEq, Serialize)]
257#[serde(rename_all = "camelCase")]
258pub struct GenerationConfig {
259    /// `thinkingConfig.includeThoughts`, next to the thinking level or
260    /// budget the request's reasoning sets.
261    #[serde(skip_serializing_if = "is_default")]
262    pub thinking_config: ThinkingConfig,
263    /// `topK`.
264    #[serde(skip_serializing_if = "Option::is_none")]
265    pub top_k: Option<u32>,
266    /// `presencePenalty`.
267    #[serde(skip_serializing_if = "Option::is_none")]
268    pub presence_penalty: Option<f64>,
269    /// `frequencyPenalty`.
270    #[serde(skip_serializing_if = "Option::is_none")]
271    pub frequency_penalty: Option<f64>,
272    /// `responseLogprobs`: return the chosen tokens' log probabilities.
273    #[serde(skip_serializing_if = "Option::is_none")]
274    pub response_logprobs: Option<bool>,
275    /// `logprobs`: how many top candidates to return per token.
276    #[serde(skip_serializing_if = "Option::is_none")]
277    pub logprobs: Option<u32>,
278    /// `candidateCount`.
279    #[serde(skip_serializing_if = "Option::is_none")]
280    pub candidate_count: Option<CandidateCount>,
281    /// `responseModalities`.
282    #[serde(skip_serializing_if = "Vec::is_empty")]
283    pub response_modalities: Vec<ResponseModality>,
284    /// `imageConfig`.
285    #[serde(skip_serializing_if = "Option::is_none")]
286    pub image_config: Option<ImageConfig>,
287    /// `speechConfig`.
288    #[serde(skip_serializing_if = "Option::is_none")]
289    pub speech_config: Option<SpeechConfig>,
290    /// `mediaResolution`.
291    #[serde(skip_serializing_if = "Option::is_none")]
292    pub media_resolution: Option<MediaResolution>,
293}
294
295impl GenerationConfig {
296    /// No entry set.
297    pub fn new() -> Self {
298        Self::default()
299    }
300
301    /// `thinkingConfig.includeThoughts`: return thought summaries.
302    pub fn include_thoughts(mut self, include: bool) -> Self {
303        self.thinking_config.include_thoughts = Some(include);
304        self
305    }
306
307    /// `topK`.
308    pub fn top_k(mut self, top_k: u32) -> Self {
309        self.top_k = Some(top_k);
310        self
311    }
312
313    /// `presencePenalty`.
314    pub fn presence_penalty(mut self, penalty: f64) -> Self {
315        self.presence_penalty = Some(penalty);
316        self
317    }
318
319    /// `frequencyPenalty`.
320    pub fn frequency_penalty(mut self, penalty: f64) -> Self {
321        self.frequency_penalty = Some(penalty);
322        self
323    }
324
325    /// `responseLogprobs`.
326    pub fn response_logprobs(mut self, enable: bool) -> Self {
327        self.response_logprobs = Some(enable);
328        self
329    }
330
331    /// `logprobs`.
332    pub fn logprobs(mut self, top: u32) -> Self {
333        self.logprobs = Some(top);
334        self
335    }
336
337    /// `candidateCount`.
338    pub fn candidate_count(mut self, count: CandidateCount) -> Self {
339        self.candidate_count = Some(count);
340        self
341    }
342
343    /// `responseModalities`.
344    pub fn response_modalities(
345        mut self,
346        modalities: impl IntoIterator<Item = ResponseModality>,
347    ) -> Self {
348        self.response_modalities = modalities.into_iter().collect();
349        self
350    }
351
352    /// `imageConfig`.
353    pub fn image_config(mut self, config: ImageConfig) -> Self {
354        self.image_config = Some(config);
355        self
356    }
357
358    /// `speechConfig`.
359    pub fn speech_config(mut self, config: SpeechConfig) -> Self {
360        self.speech_config = Some(config);
361        self
362    }
363
364    /// `mediaResolution`.
365    pub fn media_resolution(mut self, resolution: MediaResolution) -> Self {
366        self.media_resolution = Some(resolution);
367        self
368    }
369}
370
371/// The provider half of `thinkingConfig`.
372#[non_exhaustive]
373#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
374#[serde(rename_all = "camelCase")]
375pub struct ThinkingConfig {
376    /// `includeThoughts`.
377    #[serde(skip_serializing_if = "Option::is_none")]
378    pub include_thoughts: Option<bool>,
379}
380
381/// How many candidates to generate. Rig reads only the first candidate of
382/// a reply, so one is the only count it can ask for.
383#[non_exhaustive]
384#[derive(Clone, Copy, Debug, PartialEq, Eq)]
385pub enum CandidateCount {
386    /// One candidate, sent as `1`.
387    One,
388}
389
390impl Serialize for CandidateCount {
391    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
392        match self {
393            Self::One => serializer.serialize_u32(1),
394        }
395    }
396}
397
398/// A modality of the reply.
399#[non_exhaustive]
400#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
401#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
402pub enum ResponseModality {
403    /// Text.
404    Text,
405    /// Images.
406    Image,
407    /// Audio.
408    Audio,
409}
410
411/// The resolution media inputs are read at.
412#[non_exhaustive]
413#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
414pub enum MediaResolution {
415    /// `MEDIA_RESOLUTION_LOW`.
416    #[serde(rename = "MEDIA_RESOLUTION_LOW")]
417    Low,
418    /// `MEDIA_RESOLUTION_MEDIUM`.
419    #[serde(rename = "MEDIA_RESOLUTION_MEDIUM")]
420    Medium,
421    /// `MEDIA_RESOLUTION_HIGH`.
422    #[serde(rename = "MEDIA_RESOLUTION_HIGH")]
423    High,
424}
425
426/// How generated images are shaped.
427#[non_exhaustive]
428#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
429#[serde(rename_all = "camelCase")]
430pub struct ImageConfig {
431    /// `aspectRatio`, such as `"16:9"`.
432    #[serde(skip_serializing_if = "Option::is_none")]
433    pub aspect_ratio: Option<String>,
434    /// `imageSize`.
435    #[serde(skip_serializing_if = "Option::is_none")]
436    pub image_size: Option<ImageSize>,
437}
438
439impl ImageConfig {
440    /// No entry set.
441    pub fn new() -> Self {
442        Self::default()
443    }
444
445    /// `aspectRatio`.
446    pub fn aspect_ratio(mut self, ratio: impl Into<String>) -> Self {
447        self.aspect_ratio = Some(ratio.into());
448        self
449    }
450
451    /// `imageSize`.
452    pub fn image_size(mut self, size: ImageSize) -> Self {
453        self.image_size = Some(size);
454        self
455    }
456}
457
458/// How generated speech sounds: one voice, or one per speaker.
459#[non_exhaustive]
460#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
461#[serde(rename_all = "camelCase")]
462pub struct SpeechConfig {
463    /// `voiceConfig`: the one voice.
464    #[serde(skip_serializing_if = "Option::is_none")]
465    pub voice_config: Option<VoiceConfig>,
466    /// `multiSpeakerVoiceConfig`: a voice per speaker.
467    #[serde(skip_serializing_if = "Option::is_none")]
468    pub multi_speaker_voice_config: Option<MultiSpeakerVoiceConfig>,
469    /// `languageCode`, such as `"en-US"`.
470    #[serde(skip_serializing_if = "Option::is_none")]
471    pub language_code: Option<String>,
472}
473
474impl SpeechConfig {
475    /// Speak with the prebuilt voice `voice_name`.
476    pub fn voice(voice_name: impl Into<String>) -> Self {
477        Self {
478            voice_config: Some(VoiceConfig::prebuilt(voice_name)),
479            multi_speaker_voice_config: None,
480            language_code: None,
481        }
482    }
483
484    /// Speak each `(speaker, voice_name)` pair's lines with its prebuilt
485    /// voice.
486    pub fn speakers<S: Into<String>, V: Into<String>>(
487        speakers: impl IntoIterator<Item = (S, V)>,
488    ) -> Self {
489        let speaker_voice_configs = speakers
490            .into_iter()
491            .map(|(speaker, voice)| SpeakerVoiceConfig {
492                speaker: speaker.into(),
493                voice_config: VoiceConfig::prebuilt(voice),
494            })
495            .collect();
496        Self {
497            voice_config: None,
498            multi_speaker_voice_config: Some(MultiSpeakerVoiceConfig {
499                speaker_voice_configs,
500            }),
501            language_code: None,
502        }
503    }
504
505    /// `languageCode`.
506    pub fn language_code(mut self, code: impl Into<String>) -> Self {
507        self.language_code = Some(code.into());
508        self
509    }
510}
511
512/// A voice.
513#[non_exhaustive]
514#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
515#[serde(rename_all = "camelCase")]
516pub struct VoiceConfig {
517    /// `prebuiltVoiceConfig`.
518    pub prebuilt_voice_config: PrebuiltVoiceConfig,
519}
520
521impl VoiceConfig {
522    /// The prebuilt voice `voice_name`, such as `"Kore"`.
523    pub fn prebuilt(voice_name: impl Into<String>) -> Self {
524        Self {
525            prebuilt_voice_config: PrebuiltVoiceConfig {
526                voice_name: voice_name.into(),
527            },
528        }
529    }
530}
531
532/// A prebuilt voice, by name.
533#[non_exhaustive]
534#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
535#[serde(rename_all = "camelCase")]
536pub struct PrebuiltVoiceConfig {
537    /// `voiceName`.
538    pub voice_name: String,
539}
540
541/// A voice per speaker.
542#[non_exhaustive]
543#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
544#[serde(rename_all = "camelCase")]
545pub struct MultiSpeakerVoiceConfig {
546    /// `speakerVoiceConfigs`.
547    pub speaker_voice_configs: Vec<SpeakerVoiceConfig>,
548}
549
550/// One speaker's voice.
551#[non_exhaustive]
552#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
553#[serde(rename_all = "camelCase")]
554pub struct SpeakerVoiceConfig {
555    /// `speaker`: the name the prompt gives the speaker.
556    pub speaker: String,
557    /// `voiceConfig`.
558    pub voice_config: VoiceConfig,
559}
560
561/// A harm category a safety setting applies to, serialized in the
562/// GenerateContent spelling such as `HARM_CATEGORY_HATE_SPEECH`.
563#[non_exhaustive]
564#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
565pub enum HarmCategory {
566    /// Hate speech.
567    #[serde(rename = "HARM_CATEGORY_HATE_SPEECH")]
568    HateSpeech,
569    /// Dangerous content.
570    #[serde(rename = "HARM_CATEGORY_DANGEROUS_CONTENT")]
571    DangerousContent,
572    /// Harassment.
573    #[serde(rename = "HARM_CATEGORY_HARASSMENT")]
574    Harassment,
575    /// Sexually explicit content.
576    #[serde(rename = "HARM_CATEGORY_SEXUALLY_EXPLICIT")]
577    SexuallyExplicit,
578    /// Content that may be used to harm civic integrity.
579    #[serde(rename = "HARM_CATEGORY_CIVIC_INTEGRITY")]
580    CivicIntegrity,
581    /// Jailbreak attempts.
582    #[serde(rename = "HARM_CATEGORY_JAILBREAK")]
583    Jailbreak,
584}
585
586impl HarmCategory {
587    /// The Interactions spelling, such as `hate_speech`.
588    fn interactions(self) -> &'static str {
589        match self {
590            Self::HateSpeech => "hate_speech",
591            Self::DangerousContent => "dangerous_content",
592            Self::Harassment => "harassment",
593            Self::SexuallyExplicit => "sexually_explicit",
594            Self::CivicIntegrity => "civic_integrity",
595            Self::Jailbreak => "jailbreak",
596        }
597    }
598}
599
600/// The probability at and above which content is blocked, serialized in
601/// the GenerateContent spelling such as `BLOCK_ONLY_HIGH`.
602#[non_exhaustive]
603#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
604#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
605pub enum HarmBlockThreshold {
606    /// Block low probability and above.
607    BlockLowAndAbove,
608    /// Block medium probability and above.
609    BlockMediumAndAbove,
610    /// Block only high probability.
611    BlockOnlyHigh,
612    /// Block nothing.
613    BlockNone,
614    /// Turn the safety filter off.
615    Off,
616}
617
618impl HarmBlockThreshold {
619    /// The Interactions spelling, such as `block_only_high`.
620    fn interactions(self) -> &'static str {
621        match self {
622            Self::BlockLowAndAbove => "block_low_and_above",
623            Self::BlockMediumAndAbove => "block_medium_and_above",
624            Self::BlockOnlyHigh => "block_only_high",
625            Self::BlockNone => "block_none",
626            Self::Off => "off",
627        }
628    }
629}
630
631/// Block `category` at `threshold`. Sent as
632/// `{"category": "HARM_CATEGORY_…", "threshold": "BLOCK_…"}` on
633/// GenerateContent and `{"type": "…", "threshold": "block_…"}` on
634/// Interactions.
635#[non_exhaustive]
636#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
637pub struct SafetySetting {
638    /// The category.
639    pub category: HarmCategory,
640    /// The threshold.
641    pub threshold: HarmBlockThreshold,
642}
643
644impl SafetySetting {
645    /// Block `category` at `threshold`.
646    pub fn new(category: HarmCategory, threshold: HarmBlockThreshold) -> Self {
647        Self {
648            category,
649            threshold,
650        }
651    }
652}
653
654/// `settings` in the Interactions spelling.
655fn interactions_safety<S: Serializer>(
656    settings: &[SafetySetting],
657    serializer: S,
658) -> Result<S::Ok, S::Error> {
659    serializer.collect_seq(settings.iter().map(|setting| {
660        BTreeMap::from([
661            ("type", setting.category.interactions()),
662            ("threshold", setting.threshold.interactions()),
663        ])
664    }))
665}
666
667/// The Interactions-only fields, at the top level of the create body but
668/// for `generation_config`.
669#[non_exhaustive]
670#[derive(Clone, Debug, Default, PartialEq, Serialize)]
671pub struct InteractionsOptions {
672    /// `agent`: the agent to run in place of the model, which the body then
673    /// leaves out.
674    #[serde(skip_serializing_if = "Option::is_none")]
675    pub agent: Option<String>,
676    /// `agent_config`.
677    #[serde(skip_serializing_if = "Option::is_none")]
678    pub agent_config: Option<AgentConfig>,
679    /// `background`: run the interaction in the background.
680    #[serde(skip_serializing_if = "Option::is_none")]
681    pub background: Option<bool>,
682    /// `previous_interaction_id`: continue a stored interaction.
683    #[serde(skip_serializing_if = "Option::is_none")]
684    pub previous_interaction_id: Option<String>,
685    /// `safety_settings`.
686    #[serde(
687        skip_serializing_if = "Vec::is_empty",
688        serialize_with = "interactions_safety"
689    )]
690    pub safety_settings: Vec<SafetySetting>,
691    /// `generation_config` entries, merged key by key with the ones the
692    /// request and its generation options write.
693    #[serde(skip_serializing_if = "is_default")]
694    pub generation_config: InteractionsGenerationConfig,
695}
696
697impl InteractionsOptions {
698    /// No field set.
699    pub fn new() -> Self {
700        Self::default()
701    }
702
703    /// `agent`.
704    pub fn agent(mut self, agent: impl Into<String>) -> Self {
705        self.agent = Some(agent.into());
706        self
707    }
708
709    /// `agent_config`.
710    pub fn agent_config(mut self, config: AgentConfig) -> Self {
711        self.agent_config = Some(config);
712        self
713    }
714
715    /// `background`.
716    pub fn background(mut self, background: bool) -> Self {
717        self.background = Some(background);
718        self
719    }
720
721    /// `previous_interaction_id`.
722    pub fn previous_interaction_id(mut self, id: impl Into<String>) -> Self {
723        self.previous_interaction_id = Some(id.into());
724        self
725    }
726
727    /// Add a safety setting: block `category` at `threshold`.
728    pub fn safety_setting(mut self, category: HarmCategory, threshold: HarmBlockThreshold) -> Self {
729        self.safety_settings
730            .push(SafetySetting::new(category, threshold));
731        self
732    }
733
734    /// `generation_config.thinking_summaries`.
735    pub fn thinking_summaries(mut self, summaries: ThinkingSummaries) -> Self {
736        self.generation_config.thinking_summaries = Some(summaries);
737        self
738    }
739
740    /// `generation_config.speech_config`.
741    pub fn speech_config(mut self, config: InteractionSpeechConfig) -> Self {
742        self.generation_config.speech_config = Some(config);
743        self
744    }
745}
746
747/// The provider entries of the Interactions `generation_config`.
748#[non_exhaustive]
749#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
750pub struct InteractionsGenerationConfig {
751    /// `thinking_summaries`.
752    #[serde(skip_serializing_if = "Option::is_none")]
753    pub thinking_summaries: Option<ThinkingSummaries>,
754    /// `speech_config`.
755    #[serde(skip_serializing_if = "Option::is_none")]
756    pub speech_config: Option<InteractionSpeechConfig>,
757}
758
759/// Whether the reply carries summaries of the model's thoughts.
760#[non_exhaustive]
761#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
762#[serde(rename_all = "snake_case")]
763pub enum ThinkingSummaries {
764    /// `auto`.
765    Auto,
766    /// `none`.
767    None,
768}
769
770/// An agent's configuration, tagged by `type`.
771#[non_exhaustive]
772#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
773#[serde(tag = "type", rename_all = "kebab-case")]
774pub enum AgentConfig {
775    /// `dynamic`.
776    Dynamic,
777    /// `deep-research`.
778    DeepResearch(DeepResearchConfig),
779}
780
781/// The Deep Research agent's `agent_config` fields. A field left unset
782/// takes the API's default.
783#[non_exhaustive]
784#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
785pub struct DeepResearchConfig {
786    /// `thinking_summaries`: stream the agent's intermediate thoughts.
787    #[serde(skip_serializing_if = "Option::is_none")]
788    pub thinking_summaries: Option<ThinkingSummaries>,
789    /// `visualization`: whether the agent may draw charts and images.
790    #[serde(skip_serializing_if = "Option::is_none")]
791    pub visualization: Option<Visualization>,
792    /// `collaborative_planning`: answer with a research plan to review
793    /// instead of the report. Send `false` on a later turn to approve it.
794    #[serde(skip_serializing_if = "Option::is_none")]
795    pub collaborative_planning: Option<bool>,
796}
797
798impl DeepResearchConfig {
799    /// No field set.
800    pub fn new() -> Self {
801        Self::default()
802    }
803
804    /// `thinking_summaries`.
805    pub fn thinking_summaries(mut self, summaries: ThinkingSummaries) -> Self {
806        self.thinking_summaries = Some(summaries);
807        self
808    }
809
810    /// `visualization`.
811    pub fn visualization(mut self, visualization: Visualization) -> Self {
812        self.visualization = Some(visualization);
813        self
814    }
815
816    /// `collaborative_planning`.
817    pub fn collaborative_planning(mut self, plan: bool) -> Self {
818        self.collaborative_planning = Some(plan);
819        self
820    }
821}
822
823impl From<DeepResearchConfig> for AgentConfig {
824    fn from(config: DeepResearchConfig) -> Self {
825        Self::DeepResearch(config)
826    }
827}
828
829/// Whether an agent may generate charts and images.
830#[non_exhaustive]
831#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
832#[serde(rename_all = "snake_case")]
833pub enum Visualization {
834    /// `auto`: when the prompt asks for visuals.
835    Auto,
836    /// `off`.
837    Off,
838}
839
840/// The Gemini API's reply fields rig does not normalize, from the reply
841/// document of either route. Each field says which route returns it; on the
842/// other route it reads `None`, as does a field the reply left out. A
843/// candidate field is the first candidate's, the one rig reads.
844#[non_exhaustive]
845#[derive(Clone, Debug, Default, PartialEq)]
846pub struct GeminiExtras {
847    /// GenerateContent `modelVersion`.
848    pub model_version: Option<String>,
849    /// GenerateContent `responseId`.
850    pub response_id: Option<String>,
851    /// The tier that served the request: GenerateContent
852    /// `usageMetadata.serviceTier`, Interactions `service_tier`.
853    pub service_tier: Option<String>,
854    /// GenerateContent `usageMetadata.promptTokensDetails`.
855    pub prompt_tokens_details: Option<Vec<ModalityTokenCount>>,
856    /// GenerateContent `usageMetadata.cacheTokensDetails`.
857    pub cache_tokens_details: Option<Vec<ModalityTokenCount>>,
858    /// GenerateContent `usageMetadata.candidatesTokensDetails`.
859    pub candidates_tokens_details: Option<Vec<ModalityTokenCount>>,
860    /// GenerateContent `usageMetadata.toolUsePromptTokensDetails`.
861    pub tool_use_prompt_tokens_details: Option<Vec<ModalityTokenCount>>,
862    /// GenerateContent `promptFeedback`.
863    pub prompt_feedback: Option<PromptFeedback>,
864    /// GenerateContent `safetyRatings` of the candidate.
865    pub safety_ratings: Option<Vec<SafetyRating>>,
866    /// GenerateContent `finishMessage` of the candidate.
867    pub finish_message: Option<String>,
868    /// GenerateContent `citationMetadata` of the candidate.
869    pub citation_metadata: Option<CitationMetadata>,
870    /// GenerateContent `groundingMetadata` of the candidate.
871    pub grounding_metadata: Option<GroundingMetadata>,
872    /// GenerateContent `urlContextMetadata` of the candidate.
873    pub url_context_metadata: Option<UrlContextMetadata>,
874    /// GenerateContent `avgLogprobs` of the candidate.
875    pub avg_logprobs: Option<f64>,
876    /// GenerateContent `logprobsResult` of the candidate.
877    pub logprobs_result: Option<LogprobsResult>,
878    /// Interactions `id`.
879    pub id: Option<String>,
880    /// Interactions `status`.
881    pub status: Option<InteractionStatus>,
882    /// Interactions `created`, an RFC 3339 timestamp.
883    pub created: Option<String>,
884    /// Interactions `updated`, an RFC 3339 timestamp.
885    pub updated: Option<String>,
886    /// Interactions `usage.input_tokens_by_modality`.
887    pub input_tokens_by_modality: Option<Vec<ModalityTokens>>,
888    /// Interactions `usage.output_tokens_by_modality`.
889    pub output_tokens_by_modality: Option<Vec<ModalityTokens>>,
890    /// Interactions `usage.cached_tokens_by_modality`.
891    pub cached_tokens_by_modality: Option<Vec<ModalityTokens>>,
892    /// Interactions `usage.grounding_tool_count`.
893    pub grounding_tool_count: Option<Vec<GroundingToolCount>>,
894}
895
896impl ReplyExtras for GeminiExtras {
897    fn from_reply(api: &Api, raw: &Value) -> Result<Self, serde_json::Error> {
898        match api.as_str() {
899            GENERATE_CONTENT => {
900                Ok(crate::json_utils::from_value::<GenerateContentReply>(raw)?.into())
901            }
902            INTERACTIONS => Ok(crate::json_utils::from_value::<InteractionReply>(raw)?.into()),
903            other => Err(serde_json::Error::custom(format!(
904                "the Gemini API returns no `{other}` reply"
905            ))),
906        }
907    }
908}
909
910/// The parts of a `generateContent` reply [`GeminiExtras`] reads.
911#[derive(Deserialize)]
912#[serde(rename_all = "camelCase")]
913struct GenerateContentReply {
914    model_version: Option<String>,
915    response_id: Option<String>,
916    usage_metadata: Option<UsageDetails>,
917    prompt_feedback: Option<PromptFeedback>,
918    #[serde(default)]
919    candidates: Vec<CandidateDetails>,
920}
921
922#[derive(Deserialize)]
923#[serde(rename_all = "camelCase")]
924struct UsageDetails {
925    service_tier: Option<String>,
926    prompt_tokens_details: Option<Vec<ModalityTokenCount>>,
927    cache_tokens_details: Option<Vec<ModalityTokenCount>>,
928    candidates_tokens_details: Option<Vec<ModalityTokenCount>>,
929    tool_use_prompt_tokens_details: Option<Vec<ModalityTokenCount>>,
930}
931
932#[derive(Deserialize)]
933#[serde(rename_all = "camelCase")]
934struct CandidateDetails {
935    safety_ratings: Option<Vec<SafetyRating>>,
936    finish_message: Option<String>,
937    citation_metadata: Option<CitationMetadata>,
938    grounding_metadata: Option<GroundingMetadata>,
939    url_context_metadata: Option<UrlContextMetadata>,
940    avg_logprobs: Option<f64>,
941    logprobs_result: Option<LogprobsResult>,
942}
943
944impl From<GenerateContentReply> for GeminiExtras {
945    fn from(reply: GenerateContentReply) -> Self {
946        let mut extras = Self {
947            model_version: reply.model_version,
948            response_id: reply.response_id,
949            prompt_feedback: reply.prompt_feedback,
950            ..Self::default()
951        };
952        if let Some(usage) = reply.usage_metadata {
953            extras.service_tier = usage.service_tier;
954            extras.prompt_tokens_details = listed(usage.prompt_tokens_details);
955            extras.cache_tokens_details = listed(usage.cache_tokens_details);
956            extras.candidates_tokens_details = listed(usage.candidates_tokens_details);
957            extras.tool_use_prompt_tokens_details = listed(usage.tool_use_prompt_tokens_details);
958        }
959        if let Some(candidate) = reply.candidates.into_iter().next() {
960            extras.safety_ratings = listed(candidate.safety_ratings);
961            extras.finish_message = candidate.finish_message;
962            extras.citation_metadata = candidate.citation_metadata;
963            extras.grounding_metadata = candidate.grounding_metadata;
964            extras.url_context_metadata = candidate.url_context_metadata;
965            extras.avg_logprobs = candidate.avg_logprobs;
966            extras.logprobs_result = candidate.logprobs_result;
967        }
968        extras
969    }
970}
971
972/// `items`, or `None` when the list is empty, as `reply_field` reads a
973/// list for every other `Extras` type.
974fn listed<T>(items: Option<Vec<T>>) -> Option<Vec<T>> {
975    items.filter(|items| !items.is_empty())
976}
977
978/// The parts of an interaction resource [`GeminiExtras`] reads.
979#[derive(Deserialize)]
980struct InteractionReply {
981    id: Option<String>,
982    status: Option<InteractionStatus>,
983    service_tier: Option<String>,
984    created: Option<String>,
985    updated: Option<String>,
986    usage: Option<InteractionUsage>,
987}
988
989#[derive(Deserialize)]
990struct InteractionUsage {
991    input_tokens_by_modality: Option<Vec<ModalityTokens>>,
992    output_tokens_by_modality: Option<Vec<ModalityTokens>>,
993    cached_tokens_by_modality: Option<Vec<ModalityTokens>>,
994    grounding_tool_count: Option<Vec<GroundingToolCount>>,
995}
996
997impl From<InteractionReply> for GeminiExtras {
998    fn from(reply: InteractionReply) -> Self {
999        let mut extras = Self {
1000            id: reply.id,
1001            status: reply.status,
1002            service_tier: reply.service_tier,
1003            created: reply.created,
1004            updated: reply.updated,
1005            ..Self::default()
1006        };
1007        if let Some(usage) = reply.usage {
1008            extras.input_tokens_by_modality = listed(usage.input_tokens_by_modality);
1009            extras.output_tokens_by_modality = listed(usage.output_tokens_by_modality);
1010            extras.cached_tokens_by_modality = listed(usage.cached_tokens_by_modality);
1011            extras.grounding_tool_count = listed(usage.grounding_tool_count);
1012        }
1013        extras
1014    }
1015}
1016
1017/// A token count of one modality, as GenerateContent reports it.
1018#[non_exhaustive]
1019#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1020#[serde(rename_all = "camelCase")]
1021pub struct ModalityTokenCount {
1022    /// `modality`, such as `TEXT`.
1023    pub modality: Option<String>,
1024    /// `tokenCount`.
1025    pub token_count: Option<u64>,
1026}
1027
1028/// Why the prompt was blocked, and how it rated.
1029#[non_exhaustive]
1030#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1031#[serde(rename_all = "camelCase")]
1032pub struct PromptFeedback {
1033    /// `blockReason`, such as `SAFETY`, when the prompt was blocked.
1034    pub block_reason: Option<String>,
1035    /// `safetyRatings`.
1036    pub safety_ratings: Option<Vec<SafetyRating>>,
1037}
1038
1039/// How a prompt or candidate rated in one harm category.
1040#[non_exhaustive]
1041#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1042#[serde(rename_all = "camelCase")]
1043pub struct SafetyRating {
1044    /// `category`, such as `HARM_CATEGORY_HARASSMENT`.
1045    pub category: Option<String>,
1046    /// `probability`, such as `NEGLIGIBLE`.
1047    pub probability: Option<String>,
1048    /// `blocked`: whether this rating blocked the content.
1049    pub blocked: Option<bool>,
1050}
1051
1052/// The sources a candidate recites.
1053#[non_exhaustive]
1054#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1055#[serde(rename_all = "camelCase")]
1056pub struct CitationMetadata {
1057    /// `citationSources`.
1058    pub citation_sources: Option<Vec<CitationSource>>,
1059}
1060
1061/// One recited source.
1062#[non_exhaustive]
1063#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1064#[serde(rename_all = "camelCase")]
1065pub struct CitationSource {
1066    /// `startIndex` of the reciting text.
1067    pub start_index: Option<u64>,
1068    /// `endIndex` of the reciting text.
1069    pub end_index: Option<u64>,
1070    /// `uri` of the source.
1071    pub uri: Option<String>,
1072    /// `license` of the source.
1073    pub license: Option<String>,
1074}
1075
1076/// What grounded a candidate in search or retrieval.
1077#[non_exhaustive]
1078#[derive(Clone, Debug, Default, PartialEq, Deserialize)]
1079#[serde(rename_all = "camelCase")]
1080pub struct GroundingMetadata {
1081    /// `webSearchQueries`.
1082    pub web_search_queries: Option<Vec<String>>,
1083    /// `searchEntryPoint`.
1084    pub search_entry_point: Option<SearchEntryPoint>,
1085    /// `groundingChunks`.
1086    pub grounding_chunks: Option<Vec<GroundingChunk>>,
1087    /// `groundingSupports`.
1088    pub grounding_supports: Option<Vec<GroundingSupport>>,
1089}
1090
1091/// The search suggestion to show with a grounded answer.
1092#[non_exhaustive]
1093#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1094#[serde(rename_all = "camelCase")]
1095pub struct SearchEntryPoint {
1096    /// `renderedContent`: HTML and CSS to embed.
1097    pub rendered_content: Option<String>,
1098}
1099
1100/// One grounding source.
1101#[non_exhaustive]
1102#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1103#[serde(rename_all = "camelCase")]
1104pub struct GroundingChunk {
1105    /// `web`: a web page.
1106    pub web: Option<WebChunk>,
1107    /// `retrievedContext`: a retrieved document.
1108    pub retrieved_context: Option<RetrievedContext>,
1109}
1110
1111/// A web page a candidate is grounded in.
1112#[non_exhaustive]
1113#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1114pub struct WebChunk {
1115    /// `uri`.
1116    pub uri: Option<String>,
1117    /// `title`.
1118    pub title: Option<String>,
1119}
1120
1121/// A retrieved document a candidate is grounded in.
1122#[non_exhaustive]
1123#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1124pub struct RetrievedContext {
1125    /// `uri`.
1126    pub uri: Option<String>,
1127    /// `title`.
1128    pub title: Option<String>,
1129    /// `text`.
1130    pub text: Option<String>,
1131}
1132
1133/// A span of the candidate and the chunks that support it.
1134#[non_exhaustive]
1135#[derive(Clone, Debug, Default, PartialEq, Deserialize)]
1136#[serde(rename_all = "camelCase")]
1137pub struct GroundingSupport {
1138    /// `segment`.
1139    pub segment: Option<Segment>,
1140    /// `groundingChunkIndices`, into `groundingChunks`.
1141    pub grounding_chunk_indices: Option<Vec<u32>>,
1142    /// `confidenceScores`, one per index.
1143    pub confidence_scores: Option<Vec<f64>>,
1144}
1145
1146/// A span of a candidate's content.
1147#[non_exhaustive]
1148#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1149#[serde(rename_all = "camelCase")]
1150pub struct Segment {
1151    /// `partIndex`.
1152    pub part_index: Option<u32>,
1153    /// `startIndex`, in bytes.
1154    pub start_index: Option<u64>,
1155    /// `endIndex`, in bytes.
1156    pub end_index: Option<u64>,
1157    /// `text`.
1158    pub text: Option<String>,
1159}
1160
1161/// The URLs the URL context tool retrieved.
1162#[non_exhaustive]
1163#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1164#[serde(rename_all = "camelCase")]
1165pub struct UrlContextMetadata {
1166    /// `urlMetadata`.
1167    pub url_metadata: Option<Vec<UrlMetadata>>,
1168}
1169
1170/// One URL the URL context tool retrieved.
1171#[non_exhaustive]
1172#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1173#[serde(rename_all = "camelCase")]
1174pub struct UrlMetadata {
1175    /// `retrievedUrl`.
1176    pub retrieved_url: Option<String>,
1177    /// `urlRetrievalStatus`, such as `URL_RETRIEVAL_STATUS_SUCCESS`.
1178    pub url_retrieval_status: Option<String>,
1179}
1180
1181/// The log probabilities of a candidate's tokens.
1182#[non_exhaustive]
1183#[derive(Clone, Debug, Default, PartialEq, Deserialize)]
1184#[serde(rename_all = "camelCase")]
1185pub struct LogprobsResult {
1186    /// `topCandidates`, one entry per decoding step.
1187    pub top_candidates: Option<Vec<TopCandidates>>,
1188    /// `chosenCandidates`, one per decoding step.
1189    pub chosen_candidates: Option<Vec<LogprobsCandidate>>,
1190    /// `logProbabilitySum`.
1191    pub log_probability_sum: Option<f64>,
1192}
1193
1194/// The most likely tokens of one decoding step.
1195#[non_exhaustive]
1196#[derive(Clone, Debug, Default, PartialEq, Deserialize)]
1197pub struct TopCandidates {
1198    /// `candidates`, most likely first.
1199    pub candidates: Option<Vec<LogprobsCandidate>>,
1200}
1201
1202/// A token and its log probability.
1203#[non_exhaustive]
1204#[derive(Clone, Debug, Default, PartialEq, Deserialize)]
1205#[serde(rename_all = "camelCase")]
1206pub struct LogprobsCandidate {
1207    /// `token`.
1208    pub token: Option<String>,
1209    /// `tokenId`.
1210    pub token_id: Option<i64>,
1211    /// `logProbability`.
1212    pub log_probability: Option<f64>,
1213}
1214
1215/// Where an interaction stands.
1216#[non_exhaustive]
1217#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
1218#[serde(rename_all = "snake_case")]
1219pub enum InteractionStatus {
1220    /// `in_progress`.
1221    InProgress,
1222    /// `requires_action`.
1223    RequiresAction,
1224    /// `incomplete`.
1225    Incomplete,
1226    /// `budget_exceeded`.
1227    BudgetExceeded,
1228    /// `completed`.
1229    Completed,
1230    /// `failed`.
1231    Failed,
1232    /// `cancelled`.
1233    Cancelled,
1234    /// `queued`: waiting for capacity, such as the flex tier's.
1235    Queued,
1236    /// A status this crate does not know yet, as the API spelled it.
1237    #[serde(untagged)]
1238    Unknown(String),
1239}
1240
1241/// A token count of one modality, as Interactions reports it.
1242#[non_exhaustive]
1243#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1244pub struct ModalityTokens {
1245    /// `modality`, such as `text`.
1246    pub modality: Option<String>,
1247    /// `tokens`.
1248    pub tokens: Option<u64>,
1249}
1250
1251/// How often a grounding tool ran.
1252#[non_exhaustive]
1253#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
1254pub struct GroundingToolCount {
1255    /// `type`, such as `google_search`.
1256    #[serde(rename = "type")]
1257    pub kind: Option<String>,
1258    /// `count`.
1259    pub count: Option<u64>,
1260    /// `search_query_count`.
1261    pub search_query_count: Option<u64>,
1262}
1263
1264#[cfg(test)]
1265mod tests;