adk_gemini/generation/
model.rs

1use reqwest::Url;
2use serde::{Deserialize, Serialize, de};
3use time::OffsetDateTime;
4
5use crate::{
6    Content, Modality, Part,
7    safety::{SafetyRating, SafetySetting},
8};
9
10/// Reason why generation finished
11#[derive(Debug, Clone, Serialize, PartialEq)]
12#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
13pub enum FinishReason {
14    /// Default value. This value is unused.
15    FinishReasonUnspecified,
16    /// Natural stop point of the model or provided stop sequence.
17    Stop,
18    /// The maximum number of tokens as specified in the request was reached.
19    MaxTokens,
20    /// The response candidate content was flagged for safety reasons.
21    Safety,
22    /// The response candidate content was flagged for recitation reasons.
23    Recitation,
24    /// The response candidate content was flagged for using an unsupported language.
25    Language,
26    /// Unknown reason.
27    Other,
28    /// Token generation stopped because the content contains forbidden terms.
29    Blocklist,
30    /// Token generation stopped for potentially containing prohibited content.
31    ProhibitedContent,
32    /// Token generation stopped because the content potentially contains Sensitive Personally Identifiable Information (SPII).
33    Spii,
34    /// The function call generated by the model is invalid.
35    MalformedFunctionCall,
36    /// Token generation stopped because the response was blocked by Model Armor.
37    ModelArmor,
38    /// Token generation stopped because generated images contain safety violations.
39    ImageSafety,
40    /// Model generated a tool call but no tools were enabled in the request.
41    UnexpectedToolCall,
42    /// Model called too many tools consecutively, thus the system exited execution.
43    TooManyToolCalls,
44}
45
46impl FinishReason {
47    fn from_wire_str(value: &str) -> Self {
48        match value {
49            "FINISH_REASON_UNSPECIFIED" => Self::FinishReasonUnspecified,
50            "STOP" => Self::Stop,
51            "MAX_TOKENS" => Self::MaxTokens,
52            "SAFETY" => Self::Safety,
53            "RECITATION" => Self::Recitation,
54            "LANGUAGE" => Self::Language,
55            "OTHER" => Self::Other,
56            "BLOCKLIST" => Self::Blocklist,
57            "PROHIBITED_CONTENT" => Self::ProhibitedContent,
58            "SPII" => Self::Spii,
59            "MALFORMED_FUNCTION_CALL" => Self::MalformedFunctionCall,
60            "MODEL_ARMOR" => Self::ModelArmor,
61            "IMAGE_SAFETY" => Self::ImageSafety,
62            "UNEXPECTED_TOOL_CALL" => Self::UnexpectedToolCall,
63            "TOO_MANY_TOOL_CALLS" => Self::TooManyToolCalls,
64            _ => Self::Other,
65        }
66    }
67
68    fn from_wire_number(value: i64) -> Self {
69        match value {
70            0 => Self::FinishReasonUnspecified,
71            1 => Self::Stop,
72            2 => Self::MaxTokens,
73            3 => Self::Safety,
74            4 => Self::Recitation,
75            5 => Self::Other,
76            6 => Self::Blocklist,
77            7 => Self::ProhibitedContent,
78            8 => Self::Spii,
79            9 => Self::MalformedFunctionCall,
80            10 => Self::ModelArmor,
81            _ => Self::Other,
82        }
83    }
84}
85
86impl<'de> Deserialize<'de> for FinishReason {
87    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
88    where
89        D: serde::Deserializer<'de>,
90    {
91        let value = serde_json::Value::deserialize(deserializer)?;
92        match value {
93            serde_json::Value::String(s) => Ok(Self::from_wire_str(&s)),
94            serde_json::Value::Number(n) => {
95                n.as_i64().map(Self::from_wire_number).ok_or_else(|| {
96                    de::Error::custom("finishReason must be an integer-compatible number")
97                })
98            }
99            _ => Err(de::Error::custom("finishReason must be a string or integer")),
100        }
101    }
102}
103
104/// Citation metadata for content
105#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
106#[serde(rename_all = "camelCase")]
107pub struct CitationMetadata {
108    /// The citation sources
109    #[serde(default)]
110    pub citation_sources: Vec<CitationSource>,
111}
112
113/// Citation source
114#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
115#[serde(rename_all = "camelCase")]
116pub struct CitationSource {
117    /// The URI of the citation source
118    pub uri: Option<String>,
119    /// The title of the citation source
120    pub title: Option<String>,
121    /// The start index of the citation in the response
122    pub start_index: Option<i32>,
123    /// The end index of the citation in the response
124    pub end_index: Option<i32>,
125    /// The license of the citation source
126    pub license: Option<String>,
127    /// The publication date of the citation source
128    #[serde(default, with = "time::serde::rfc3339::option")]
129    pub publication_date: Option<OffsetDateTime>,
130}
131
132/// A candidate response
133#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
134#[serde(rename_all = "camelCase")]
135pub struct Candidate {
136    /// The content of the candidate
137    #[serde(default)]
138    pub content: Content,
139    /// The safety ratings for the candidate
140    #[serde(skip_serializing_if = "Option::is_none")]
141    pub safety_ratings: Option<Vec<SafetyRating>>,
142    /// The citation metadata for the candidate
143    #[serde(skip_serializing_if = "Option::is_none")]
144    pub citation_metadata: Option<CitationMetadata>,
145    /// The grounding metadata for the candidate
146    #[serde(skip_serializing_if = "Option::is_none")]
147    pub grounding_metadata: Option<GroundingMetadata>,
148    /// The finish reason for the candidate
149    #[serde(skip_serializing_if = "Option::is_none")]
150    pub finish_reason: Option<FinishReason>,
151    /// The index of the candidate
152    #[serde(skip_serializing_if = "Option::is_none")]
153    pub index: Option<i32>,
154}
155
156/// Metadata about token usage
157#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
158#[serde(rename_all = "camelCase")]
159pub struct UsageMetadata {
160    /// The number of prompt tokens (null if request processing failed)
161    #[serde(skip_serializing_if = "Option::is_none")]
162    pub prompt_token_count: Option<i32>,
163    /// The number of response tokens (null if generation failed)
164    #[serde(skip_serializing_if = "Option::is_none")]
165    pub candidates_token_count: Option<i32>,
166    /// The total number of tokens (null if individual counts unavailable)
167    #[serde(skip_serializing_if = "Option::is_none")]
168    pub total_token_count: Option<i32>,
169    /// The number of thinking tokens (Gemini 2.5 series only)
170    #[serde(skip_serializing_if = "Option::is_none")]
171    pub thoughts_token_count: Option<i32>,
172    /// Detailed prompt token information
173    #[serde(skip_serializing_if = "Option::is_none")]
174    pub prompt_tokens_details: Option<Vec<PromptTokenDetails>>,
175    /// The number of cached content tokens (batch API)
176    #[serde(skip_serializing_if = "Option::is_none")]
177    pub cached_content_token_count: Option<i32>,
178    /// Detailed cache token information (batch API)
179    #[serde(skip_serializing_if = "Option::is_none")]
180    pub cache_tokens_details: Option<Vec<PromptTokenDetails>>,
181}
182
183/// Details about prompt tokens by modality
184#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
185#[serde(rename_all = "camelCase")]
186pub struct PromptTokenDetails {
187    /// The modality (e.g., "TEXT")
188    pub modality: Modality,
189    /// Token count for this modality
190    pub token_count: i32,
191}
192
193/// Grounding metadata for responses that use grounding tools
194#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
195#[serde(rename_all = "camelCase")]
196pub struct GroundingMetadata {
197    /// Grounding chunks containing source information
198    #[serde(skip_serializing_if = "Option::is_none")]
199    pub grounding_chunks: Option<Vec<GroundingChunk>>,
200    /// Grounding supports connecting response text to sources
201    #[serde(skip_serializing_if = "Option::is_none")]
202    pub grounding_supports: Option<Vec<GroundingSupport>>,
203    /// Web search queries used for grounding
204    #[serde(skip_serializing_if = "Option::is_none")]
205    pub web_search_queries: Option<Vec<String>>,
206    /// Google Maps widget context token
207    #[serde(skip_serializing_if = "Option::is_none")]
208    pub google_maps_widget_context_token: Option<String>,
209}
210
211/// A chunk of grounding information from a source
212#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
213#[serde(rename_all = "camelCase")]
214pub struct GroundingChunk {
215    /// Maps-specific grounding information
216    #[serde(skip_serializing_if = "Option::is_none")]
217    pub maps: Option<MapsGroundingChunk>,
218    /// Web-specific grounding information
219    #[serde(skip_serializing_if = "Option::is_none")]
220    pub web: Option<WebGroundingChunk>,
221}
222
223/// Maps-specific grounding chunk information
224#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
225#[serde(rename_all = "camelCase")]
226pub struct MapsGroundingChunk {
227    /// The URI of the Maps source
228    #[serde(default)]
229    pub uri: Option<Url>,
230    /// The title of the Maps source
231    #[serde(default)]
232    pub title: Option<String>,
233    /// The place ID from Google Maps
234    #[serde(skip_serializing_if = "Option::is_none")]
235    pub place_id: Option<String>,
236}
237
238/// Web-specific grounding chunk information
239#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
240#[serde(rename_all = "camelCase")]
241pub struct WebGroundingChunk {
242    /// The URI of the web source
243    #[serde(default)]
244    pub uri: Option<Url>,
245    /// The title of the web source
246    #[serde(default)]
247    pub title: Option<String>,
248}
249
250/// Support information connecting response text to grounding sources
251#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
252#[serde(rename_all = "camelCase")]
253pub struct GroundingSupport {
254    /// Segment of the response text
255    pub segment: GroundingSegment,
256    /// Indices of grounding chunks that support this segment
257    pub grounding_chunk_indices: Vec<u32>,
258}
259
260/// A segment of response text
261#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
262#[serde(rename_all = "camelCase")]
263pub struct GroundingSegment {
264    /// Start index of the segment in the response text
265    #[serde(default)]
266    pub start_index: Option<u32>,
267    /// End index of the segment in the response text
268    #[serde(default)]
269    pub end_index: Option<u32>,
270    /// The text content of the segment
271    #[serde(default)]
272    pub text: Option<String>,
273}
274
275/// Response from the Gemini API for content generation
276#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
277#[serde(rename_all = "camelCase")]
278pub struct GenerationResponse {
279    /// The candidates generated
280    #[serde(default, skip_serializing_if = "Vec::is_empty")]
281    pub candidates: Vec<Candidate>,
282    /// The prompt feedback
283    #[serde(skip_serializing_if = "Option::is_none")]
284    pub prompt_feedback: Option<PromptFeedback>,
285    /// Usage metadata
286    #[serde(skip_serializing_if = "Option::is_none")]
287    pub usage_metadata: Option<UsageMetadata>,
288    /// Model version used
289    #[serde(skip_serializing_if = "Option::is_none")]
290    pub model_version: Option<String>,
291    /// Response ID
292    #[serde(skip_serializing_if = "Option::is_none")]
293    pub response_id: Option<String>,
294}
295
296/// Reason why content was blocked
297#[derive(Debug, Clone, Serialize, PartialEq)]
298#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
299pub enum BlockReason {
300    /// Default value. This value is unused.
301    BlockReasonUnspecified,
302    /// Prompt was blocked due to safety reasons. Inspect safetyRatings to understand which safety category blocked it.
303    Safety,
304    /// Prompt was blocked due to unknown reasons.
305    Other,
306    /// Prompt was blocked due to the terms which are included from the terminology blocklist.
307    Blocklist,
308    /// Prompt was blocked due to prohibited content.
309    ProhibitedContent,
310    /// Prompt was blocked by Model Armor.
311    ModelArmor,
312    /// Prompt was blocked due to jailbreak detection.
313    Jailbreak,
314    /// Candidates blocked due to unsafe image generation content.
315    ImageSafety,
316}
317
318impl BlockReason {
319    fn from_wire_str(value: &str) -> Self {
320        match value {
321            "BLOCK_REASON_UNSPECIFIED" | "BLOCKED_REASON_UNSPECIFIED" => {
322                Self::BlockReasonUnspecified
323            }
324            "SAFETY" => Self::Safety,
325            "OTHER" => Self::Other,
326            "BLOCKLIST" => Self::Blocklist,
327            "PROHIBITED_CONTENT" => Self::ProhibitedContent,
328            "MODEL_ARMOR" => Self::ModelArmor,
329            "JAILBREAK" => Self::Jailbreak,
330            "IMAGE_SAFETY" => Self::ImageSafety,
331            _ => Self::Other,
332        }
333    }
334
335    fn from_wire_number(value: i64) -> Self {
336        match value {
337            0 => Self::BlockReasonUnspecified,
338            1 => Self::Safety,
339            2 => Self::Other,
340            3 => Self::Blocklist,
341            4 => Self::ProhibitedContent,
342            5 => Self::ModelArmor,
343            6 => Self::Jailbreak,
344            7 => Self::ImageSafety,
345            _ => Self::Other,
346        }
347    }
348}
349
350impl<'de> Deserialize<'de> for BlockReason {
351    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
352    where
353        D: serde::Deserializer<'de>,
354    {
355        let value = serde_json::Value::deserialize(deserializer)?;
356        match value {
357            serde_json::Value::String(s) => Ok(Self::from_wire_str(&s)),
358            serde_json::Value::Number(n) => {
359                n.as_i64().map(Self::from_wire_number).ok_or_else(|| {
360                    de::Error::custom("blockReason must be an integer-compatible number")
361                })
362            }
363            _ => Err(de::Error::custom("blockReason must be a string or integer")),
364        }
365    }
366}
367
368/// Feedback about the prompt
369#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
370#[serde(rename_all = "camelCase")]
371pub struct PromptFeedback {
372    /// The safety ratings for the prompt
373    #[serde(default, skip_serializing_if = "Vec::is_empty")]
374    pub safety_ratings: Vec<SafetyRating>,
375    /// The block reason if the prompt was blocked
376    #[serde(skip_serializing_if = "Option::is_none")]
377    pub block_reason: Option<BlockReason>,
378}
379
380impl GenerationResponse {
381    /// Get the text of the first candidate
382    pub fn text(&self) -> String {
383        self.candidates
384            .first()
385            .and_then(|c| {
386                c.content.parts.as_ref().and_then(|parts| {
387                    parts.first().and_then(|p| match p {
388                        Part::Text { text, thought: _, thought_signature: _ } => Some(text.clone()),
389                        _ => None,
390                    })
391                })
392            })
393            .unwrap_or_default()
394    }
395
396    /// Get function calls from the response
397    pub fn function_calls(&self) -> Vec<&crate::tools::FunctionCall> {
398        self.candidates
399            .iter()
400            .flat_map(|c| {
401                c.content
402                    .parts
403                    .as_ref()
404                    .map(|parts| {
405                        parts
406                            .iter()
407                            .filter_map(|p| match p {
408                                Part::FunctionCall { function_call, thought_signature: _ } => {
409                                    Some(function_call)
410                                }
411                                _ => None,
412                            })
413                            .collect::<Vec<_>>()
414                    })
415                    .unwrap_or_default()
416            })
417            .collect()
418    }
419
420    /// Get function calls with their thought signatures from the response
421    pub fn function_calls_with_thoughts(
422        &self,
423    ) -> Vec<(&crate::tools::FunctionCall, Option<&String>)> {
424        self.candidates
425            .iter()
426            .flat_map(|c| {
427                c.content
428                    .parts
429                    .as_ref()
430                    .map(|parts| {
431                        parts
432                            .iter()
433                            .filter_map(|p| match p {
434                                Part::FunctionCall { function_call, thought_signature } => {
435                                    Some((function_call, thought_signature.as_ref()))
436                                }
437                                _ => None,
438                            })
439                            .collect::<Vec<_>>()
440                    })
441                    .unwrap_or_default()
442            })
443            .collect()
444    }
445
446    /// Get thought summaries from the response
447    pub fn thoughts(&self) -> Vec<String> {
448        self.candidates
449            .iter()
450            .flat_map(|c| {
451                c.content
452                    .parts
453                    .as_ref()
454                    .map(|parts| {
455                        parts
456                            .iter()
457                            .filter_map(|p| match p {
458                                Part::Text { text, thought: Some(true), thought_signature: _ } => {
459                                    Some(text.clone())
460                                }
461                                _ => None,
462                            })
463                            .collect::<Vec<_>>()
464                    })
465                    .unwrap_or_default()
466            })
467            .collect()
468    }
469
470    /// Get all text parts (both regular text and thoughts)
471    pub fn all_text(&self) -> Vec<(String, bool)> {
472        self.candidates
473            .iter()
474            .flat_map(|c| {
475                c.content
476                    .parts
477                    .as_ref()
478                    .map(|parts| {
479                        parts
480                            .iter()
481                            .filter_map(|p| match p {
482                                Part::Text { text, thought, thought_signature: _ } => {
483                                    Some((text.clone(), thought.unwrap_or(false)))
484                                }
485                                _ => None,
486                            })
487                            .collect::<Vec<_>>()
488                    })
489                    .unwrap_or_default()
490            })
491            .collect()
492    }
493
494    /// Get text parts with their thought signatures from the response
495    pub fn text_with_thoughts(&self) -> Vec<(String, bool, Option<&String>)> {
496        self.candidates
497            .iter()
498            .flat_map(|c| {
499                c.content
500                    .parts
501                    .as_ref()
502                    .map(|parts| {
503                        parts
504                            .iter()
505                            .filter_map(|p| match p {
506                                Part::Text { text, thought, thought_signature } => Some((
507                                    text.clone(),
508                                    thought.unwrap_or(false),
509                                    thought_signature.as_ref(),
510                                )),
511                                _ => None,
512                            })
513                            .collect::<Vec<_>>()
514                    })
515                    .unwrap_or_default()
516            })
517            .collect()
518    }
519}
520
521/// Request to generate content
522#[derive(Debug, Clone, Serialize, Deserialize)]
523#[serde(rename_all = "camelCase")]
524pub struct GenerateContentRequest {
525    /// The contents to generate content from
526    pub contents: Vec<Content>,
527    /// The generation config
528    #[serde(skip_serializing_if = "Option::is_none")]
529    pub generation_config: Option<GenerationConfig>,
530    /// The safety settings
531    #[serde(skip_serializing_if = "Option::is_none")]
532    pub safety_settings: Option<Vec<SafetySetting>>,
533    /// The tools that the model can use
534    #[serde(skip_serializing_if = "Option::is_none")]
535    pub tools: Option<Vec<crate::tools::Tool>>,
536    /// The tool config
537    #[serde(skip_serializing_if = "Option::is_none")]
538    pub tool_config: Option<crate::tools::ToolConfig>,
539    /// The system instruction
540    #[serde(skip_serializing_if = "Option::is_none")]
541    pub system_instruction: Option<Content>,
542    /// The cached content to use
543    #[serde(skip_serializing_if = "Option::is_none")]
544    pub cached_content: Option<String>,
545}
546
547impl GenerateContentRequest {
548    /// Strips fields that Vertex AI does not support.
549    ///
550    /// The Vertex AI surface (`aiplatform.googleapis.com`) rejects
551    /// `includeServerSideToolInvocations` with a 400 error. Vertex AI handles
552    /// built-in tools (Google Search, URL Context, etc.) natively without
553    /// needing this flag. This method clears the flag so the request can be
554    /// sent to Vertex AI without modification.
555    ///
556    /// AI Studio (`generativelanguage.googleapis.com`) requires the flag for
557    /// Gemini 3 models to return `toolCall`/`toolResponse` parts instead of
558    /// silently truncating the response.
559    pub fn strip_vertex_unsupported_fields(&mut self) {
560        if let Some(tc) = &mut self.tool_config {
561            tc.include_server_side_tool_invocations = None;
562        }
563    }
564}
565
566/// Native thinking level for Gemini 3 models.
567///
568/// Controls the amount of reasoning effort the model applies. This is the
569/// Gemini 3 native thinking control — for Gemini 2.5 budget-based thinking,
570/// use [`ThinkingConfig::with_thinking_budget`] instead.
571///
572/// Serializes as lowercase per the Gemini API contract
573/// (e.g., `"low"`, `"high"`).
574///
575/// Available levels (model support and defaults vary by model):
576/// - `Minimal` — matches "no thinking" for most queries; model may still
577///   think minimally for complex coding tasks. Not supported on Gemini 3.1 Pro.
578/// - `Low` — minimizes latency and cost; improved for code and agentic tasks
579///   that require fewer steps.
580/// - `Medium` — balanced thinking for most tasks. Default for Gemini 3.5 Flash.
581/// - `High` — maximizes reasoning depth. Default for Gemini 3 Flash Preview and
582///   Gemini 3.1 Pro.
583///
584/// Note: `temperature`, `top_p`, and `top_k` are no longer recommended for
585/// Gemini 3.x models — their reasoning is tuned for the default sampling
586/// settings. Use `thinking_level` to control reasoning effort instead.
587#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
588#[serde(rename_all = "lowercase")]
589pub enum ThinkingLevel {
590    /// Minimal reasoning effort. Matches "no thinking" for most queries.
591    /// Not supported on Gemini 3.1 Pro.
592    Minimal,
593    /// Low reasoning effort. Best for simple instruction following and chat.
594    Low,
595    /// Medium reasoning effort. Balanced thinking for most tasks.
596    /// Default for Gemini 3.5 Flash.
597    Medium,
598    /// High reasoning effort — maximizes reasoning depth. Default for
599    /// Gemini 3 Flash Preview and Gemini 3.1 Pro.
600    High,
601}
602
603/// Configuration for thinking (Gemini 2.5 and 3 series)
604#[derive(Debug, Clone, Serialize, Deserialize)]
605#[serde(rename_all = "camelCase")]
606pub struct ThinkingConfig {
607    /// The thinking budget (number of thinking tokens)
608    ///
609    /// This is the Gemini 2.5 budget-based thinking control.
610    ///
611    /// - Set to 0 to disable thinking
612    /// - Set to -1 for dynamic thinking (model decides)
613    /// - Set to a positive number for a specific token budget
614    ///
615    /// Model-specific ranges:
616    /// - 2.5 Pro: 128 to 32768 (cannot disable thinking)
617    /// - 2.5 Flash: 0 to 24576
618    /// - 2.5 Flash Lite: 512 to 24576
619    #[serde(skip_serializing_if = "Option::is_none")]
620    pub thinking_budget: Option<i32>,
621
622    /// Whether to include thought summaries in the response
623    ///
624    /// When enabled, the response will include synthesized versions of the model's
625    /// raw thoughts, providing insights into the reasoning process.
626    #[serde(skip_serializing_if = "Option::is_none")]
627    pub include_thoughts: Option<bool>,
628
629    /// Native thinking level for Gemini 3 models.
630    ///
631    /// When set, the model uses level-based reasoning instead of a token budget.
632    /// Do not combine with `thinking_budget` — use one or the other.
633    #[serde(skip_serializing_if = "Option::is_none")]
634    pub thinking_level: Option<ThinkingLevel>,
635}
636
637impl ThinkingConfig {
638    /// Validate the thinking configuration.
639    ///
640    /// Returns an error if both `thinking_budget` and `thinking_level` are set,
641    /// since they are mutually exclusive controls (budget for Gemini 2.5, level for Gemini 3).
642    pub fn validate(&self) -> Result<(), String> {
643        if self.thinking_budget.is_some() && self.thinking_level.is_some() {
644            return Err(
645                "thinking_budget and thinking_level are mutually exclusive; use one or the other"
646                    .to_string(),
647            );
648        }
649        Ok(())
650    }
651
652    /// Create a new thinking config with default settings
653    pub fn new() -> Self {
654        Self { thinking_budget: None, include_thoughts: None, thinking_level: None }
655    }
656
657    /// Set the thinking budget (Gemini 2.5 budget-based control)
658    pub fn with_thinking_budget(mut self, budget: i32) -> Self {
659        self.thinking_budget = Some(budget);
660        self
661    }
662
663    /// Enable dynamic thinking (model decides the budget)
664    pub fn with_dynamic_thinking(mut self) -> Self {
665        self.thinking_budget = Some(-1);
666        self
667    }
668
669    /// Include thought summaries in the response
670    pub fn with_thoughts_included(mut self, include: bool) -> Self {
671        self.include_thoughts = Some(include);
672        self
673    }
674
675    /// Set the thinking level (Gemini 3 native level-based control).
676    ///
677    /// This is the preferred control for Gemini 3 models. Do not combine
678    /// with `with_thinking_budget` — use one or the other.
679    pub fn with_thinking_level(mut self, level: ThinkingLevel) -> Self {
680        self.thinking_level = Some(level);
681        self
682    }
683
684    /// Create a thinking config that enables dynamic thinking with thoughts included
685    pub fn dynamic_thinking() -> Self {
686        Self { thinking_budget: Some(-1), include_thoughts: Some(true), thinking_level: None }
687    }
688}
689
690impl Default for ThinkingConfig {
691    fn default() -> Self {
692        Self::new()
693    }
694}
695
696/// Configuration for generation
697#[derive(Debug, Default, Clone, Serialize, Deserialize)]
698#[serde(rename_all = "camelCase")]
699pub struct GenerationConfig {
700    /// The temperature for the model (0.0 to 1.0)
701    ///
702    /// Controls the randomness of the output. Higher values (e.g., 0.9) make output
703    /// more random, lower values (e.g., 0.1) make output more deterministic.
704    #[serde(skip_serializing_if = "Option::is_none")]
705    pub temperature: Option<f32>,
706
707    /// The top-p value for the model (0.0 to 1.0)
708    ///
709    /// For each token generation step, the model considers the top_p percentage of
710    /// probability mass for potential token choices. Lower values are more selective,
711    /// higher values allow more variety.
712    #[serde(skip_serializing_if = "Option::is_none")]
713    pub top_p: Option<f32>,
714
715    /// The top-k value for the model
716    ///
717    /// For each token generation step, the model considers the top_k most likely tokens.
718    /// Lower values are more selective, higher values allow more variety.
719    #[serde(skip_serializing_if = "Option::is_none")]
720    pub top_k: Option<i32>,
721
722    /// The maximum number of tokens to generate
723    ///
724    /// Limits the length of the generated content. One token is roughly 4 characters.
725    #[serde(skip_serializing_if = "Option::is_none")]
726    pub max_output_tokens: Option<i32>,
727
728    /// The candidate count
729    ///
730    /// Number of alternative responses to generate.
731    #[serde(skip_serializing_if = "Option::is_none")]
732    pub candidate_count: Option<i32>,
733
734    /// Whether to stop on specific sequences
735    ///
736    /// The model will stop generating content when it encounters any of these sequences.
737    #[serde(skip_serializing_if = "Option::is_none")]
738    pub stop_sequences: Option<Vec<String>>,
739
740    /// The response mime type
741    ///
742    /// Specifies the format of the model's response.
743    #[serde(skip_serializing_if = "Option::is_none")]
744    pub response_mime_type: Option<String>,
745    /// The response schema
746    ///
747    /// Specifies the JSON schema for structured responses.
748    #[serde(skip_serializing_if = "Option::is_none")]
749    pub response_schema: Option<serde_json::Value>,
750
751    /// Response modalities (for TTS and other multimodal outputs)
752    #[serde(skip_serializing_if = "Option::is_none")]
753    pub response_modalities: Option<Vec<String>>,
754
755    /// Speech configuration for text-to-speech generation
756    #[serde(skip_serializing_if = "Option::is_none")]
757    pub speech_config: Option<SpeechConfig>,
758
759    /// The thinking configuration
760    ///
761    /// Configuration for the model's thinking process (Gemini 2.5 series only).
762    #[serde(skip_serializing_if = "Option::is_none")]
763    pub thinking_config: Option<ThinkingConfig>,
764}
765
766impl GenerationConfig {
767    /// Validate the generation configuration.
768    ///
769    /// Returns an error if any parameter is outside its valid range:
770    /// - `temperature`: must be between 0.0 and 2.0
771    /// - `top_p`: must be between 0.0 and 1.0
772    /// - `top_k`: must be positive
773    /// - `max_output_tokens`: must be positive
774    ///
775    /// If `thinking_config` is present, delegates to [`ThinkingConfig::validate`] as well.
776    /// All `None` fields are accepted without error.
777    pub fn validate(&self) -> Result<(), String> {
778        if let Some(t) = self.temperature
779            && !(0.0..=2.0).contains(&t)
780        {
781            return Err("temperature must be between 0.0 and 2.0".to_string());
782        }
783        if let Some(p) = self.top_p
784            && !(0.0..=1.0).contains(&p)
785        {
786            return Err("top_p must be between 0.0 and 1.0".to_string());
787        }
788        if let Some(k) = self.top_k
789            && k <= 0
790        {
791            return Err("top_k must be positive".to_string());
792        }
793        if let Some(m) = self.max_output_tokens
794            && m <= 0
795        {
796            return Err("max_output_tokens must be positive".to_string());
797        }
798        if let Some(ref tc) = self.thinking_config {
799            tc.validate()?;
800        }
801        Ok(())
802    }
803}
804
805/// Configuration for speech generation (text-to-speech)
806#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
807#[serde(rename_all = "camelCase")]
808pub struct SpeechConfig {
809    /// Single voice configuration
810    #[serde(skip_serializing_if = "Option::is_none")]
811    pub voice_config: Option<VoiceConfig>,
812    /// Multi-speaker voice configuration
813    #[serde(skip_serializing_if = "Option::is_none")]
814    pub multi_speaker_voice_config: Option<MultiSpeakerVoiceConfig>,
815}
816
817/// Voice configuration for text-to-speech
818#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
819#[serde(rename_all = "camelCase")]
820pub struct VoiceConfig {
821    /// Prebuilt voice configuration
822    #[serde(skip_serializing_if = "Option::is_none")]
823    pub prebuilt_voice_config: Option<PrebuiltVoiceConfig>,
824}
825
826/// Prebuilt voice configuration
827#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
828#[serde(rename_all = "camelCase")]
829pub struct PrebuiltVoiceConfig {
830    /// The name of the voice to use
831    pub voice_name: String,
832}
833
834/// Multi-speaker voice configuration
835#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
836#[serde(rename_all = "camelCase")]
837pub struct MultiSpeakerVoiceConfig {
838    /// Configuration for each speaker
839    pub speaker_voice_configs: Vec<SpeakerVoiceConfig>,
840}
841
842/// Configuration for a specific speaker in multi-speaker TTS
843#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
844#[serde(rename_all = "camelCase")]
845pub struct SpeakerVoiceConfig {
846    /// The name of the speaker (must match the name used in the prompt)
847    pub speaker: String,
848    /// Voice configuration for this speaker
849    pub voice_config: VoiceConfig,
850}
851
852impl SpeechConfig {
853    /// Create a new speech config with a single voice
854    pub fn single_voice(voice_name: impl Into<String>) -> Self {
855        Self {
856            voice_config: Some(VoiceConfig {
857                prebuilt_voice_config: Some(PrebuiltVoiceConfig { voice_name: voice_name.into() }),
858            }),
859            multi_speaker_voice_config: None,
860        }
861    }
862
863    /// Create a new speech config with multiple speakers
864    pub fn multi_speaker(speakers: Vec<SpeakerVoiceConfig>) -> Self {
865        Self {
866            voice_config: None,
867            multi_speaker_voice_config: Some(MultiSpeakerVoiceConfig {
868                speaker_voice_configs: speakers,
869            }),
870        }
871    }
872}
873
874impl SpeakerVoiceConfig {
875    /// Create a new speaker voice configuration
876    pub fn new(speaker: impl Into<String>, voice_name: impl Into<String>) -> Self {
877        Self {
878            speaker: speaker.into(),
879            voice_config: VoiceConfig {
880                prebuilt_voice_config: Some(PrebuiltVoiceConfig { voice_name: voice_name.into() }),
881            },
882        }
883    }
884}
adk_gemini/generation/model.rs

adk_gemini/generation/
model.rs
