Skip to main content

mutil_ai/
types.rs

1use std::fmt;
2
3use reqwest::header::HeaderMap;
4use serde::{Deserialize, Serialize};
5
6use crate::report::CompletionReport;
7
8/// The role used inside your application.
9///
10/// Provider APIs only understand a small set of roles. You may keep richer
11/// roles such as [`Role::Developer`] or [`Role::Custom`] in your agent history;
12/// the normalization layer decides how to downgrade them before sending.
13#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
14#[serde(rename_all = "snake_case")]
15pub enum Role {
16    /// System-level instructions.
17    System,
18    /// Developer-level instructions. Downgraded by providers that lack this
19    /// role (see [`crate::normalize`]).
20    Developer,
21    /// End-user input.
22    User,
23    /// Model output.
24    Assistant,
25    /// Tool output returned to the model.
26    Tool,
27    /// Application-defined role. Normalization decides how to downgrade it.
28    Custom(String),
29}
30
31/// A piece of a message.
32#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
33#[serde(tag = "type", rename_all = "snake_case")]
34pub enum Part {
35    /// Plain text content.
36    Text {
37        /// The text content.
38        text: String,
39        #[serde(default, skip_serializing_if = "Option::is_none")]
40        provider_state: Option<ProviderState>,
41    },
42    /// Model reasoning content.
43    Reasoning(Reasoning),
44    /// Image referenced by URL.
45    ImageUrl { image_url: ImageUrl },
46    /// Image passed inline as base64 data or a file reference.
47    Image { image: ImagePart },
48    /// A tool call requested by the model.
49    ToolCall(ToolCall),
50    /// A Responses native client-tool call with its original identity and input.
51    NativeToolCall(NativeToolCall),
52    /// A tool result sent back to the model.
53    ToolResult(ToolResult),
54    /// A provider-hosted tool item such as web-search output.
55    ProviderItem(ServerToolItem),
56}
57
58impl Part {
59    /// Creates a plain [`Part::Text`] part.
60    pub fn text(text: impl Into<String>) -> Self {
61        Self::Text {
62            text: text.into(),
63            provider_state: None,
64        }
65    }
66
67    /// Creates a [`Part::Text`] part carrying provider-specific replay state.
68    pub fn text_with_provider_state(
69        text: impl Into<String>,
70        format: ProviderStateFormat,
71        data: serde_json::Value,
72    ) -> Self {
73        Self::Text {
74            text: text.into(),
75            provider_state: Some(ProviderState::new(format, data)),
76        }
77    }
78
79    /// Creates a [`Part::Reasoning`] part.
80    pub fn reasoning(reasoning: Reasoning) -> Self {
81        Self::Reasoning(reasoning)
82    }
83
84    /// Creates a [`Part::ImageUrl`] part from a URL.
85    pub fn image_url(url: impl Into<String>) -> Self {
86        Self::ImageUrl {
87            image_url: ImageUrl {
88                url: url.into(),
89                detail: None,
90            },
91        }
92    }
93
94    /// Creates a [`Part::Image`] part from an inline image source.
95    pub fn image(image: ImagePart) -> Self {
96        Self::Image { image }
97    }
98}
99
100/// The main display category of a reasoning item.
101///
102/// Provider APIs disagree on names, but consumers usually only need to know
103/// whether they received a summary, readable reasoning text, encrypted state,
104/// or a safety-redacted block.
105#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
106#[serde(rename_all = "snake_case")]
107pub enum ReasoningKind {
108    /// A short summary of the reasoning, without full thought text.
109    Summary,
110    /// Readable reasoning text.
111    Text,
112    /// Encrypted reasoning kept for exact replay on the same provider.
113    Encrypted,
114    /// Reasoning redacted for safety; not displayable.
115    Redacted,
116}
117
118/// The wire format that owns an opaque provider state.
119#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
120#[serde(rename_all = "snake_case")]
121pub enum ProviderStateFormat {
122    /// OpenAI Chat Completions wire format.
123    OpenAiChat,
124    /// OpenAI Responses wire format.
125    OpenAiResponses,
126    /// Anthropic Messages wire format.
127    AnthropicMessages,
128    /// Gemini GenerateContent wire format.
129    GeminiGenerateContent,
130    /// A format not covered by the SDK.
131    Custom(String),
132}
133
134/// Opaque state needed to replay provider-specific content.
135///
136/// The `data` value must be passed back to the same provider unchanged. It can
137/// contain a signature, encrypted content, an item id, or other fields whose
138/// meaning is deliberately unknown to the SDK.
139#[derive(Clone, PartialEq, Serialize, Deserialize)]
140pub struct ProviderState {
141    /// The wire format this state belongs to.
142    pub format: ProviderStateFormat,
143    /// The opaque payload. Its meaning is deliberately unknown to the SDK.
144    pub data: serde_json::Value,
145}
146
147impl fmt::Debug for ProviderState {
148    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
149        let bytes = serde_json::to_vec(&self.data)
150            .map(|data| data.len())
151            .unwrap_or_default();
152        formatter
153            .debug_struct("ProviderState")
154            .field("format", &self.format)
155            .field("data_bytes", &bytes)
156            .finish_non_exhaustive()
157    }
158}
159
160impl ProviderState {
161    /// Creates provider state from a format and an opaque payload.
162    pub fn new(format: ProviderStateFormat, data: serde_json::Value) -> Self {
163        Self { format, data }
164    }
165}
166
167/// Provider-neutral reasoning content.
168///
169/// `summary` and `text` are display fields. `state` is for exact replay and is
170/// not user-visible content. Some providers return both a summary and readable
171/// reasoning text; in that case `kind` is [`ReasoningKind::Text`] and both
172/// fields are populated.
173#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
174pub struct Reasoning {
175    /// The display category of this reasoning item.
176    pub kind: ReasoningKind,
177    /// Short, user-visible summary of the reasoning.
178    pub summary: Option<String>,
179    /// Full readable reasoning text, when the provider returns it.
180    pub text: Option<String>,
181    /// Opaque state for exact replay on the originating provider.
182    pub state: Option<ProviderState>,
183}
184
185impl Reasoning {
186    /// Creates a [`ReasoningKind::Summary`] reasoning item.
187    pub fn summary(text: impl Into<String>) -> Self {
188        Self {
189            kind: ReasoningKind::Summary,
190            summary: Some(text.into()),
191            text: None,
192            state: None,
193        }
194    }
195
196    /// Creates a [`ReasoningKind::Text`] reasoning item.
197    pub fn text(text: impl Into<String>) -> Self {
198        Self {
199            kind: ReasoningKind::Text,
200            summary: None,
201            text: Some(text.into()),
202            state: None,
203        }
204    }
205
206    /// Creates a placeholder for encrypted reasoning with no display text.
207    pub fn encrypted() -> Self {
208        Self {
209            kind: ReasoningKind::Encrypted,
210            summary: None,
211            text: None,
212            state: None,
213        }
214    }
215
216    /// Creates a placeholder for safety-redacted reasoning.
217    pub fn redacted() -> Self {
218        Self {
219            kind: ReasoningKind::Redacted,
220            summary: None,
221            text: None,
222            state: None,
223        }
224    }
225
226    /// Attaches opaque provider state for exact replay.
227    pub fn with_state(mut self, format: ProviderStateFormat, data: serde_json::Value) -> Self {
228        self.state = Some(ProviderState::new(format, data));
229        self
230    }
231
232    /// Returns the best display text: full reasoning text if present,
233    /// otherwise the summary.
234    pub fn display_text(&self) -> Option<&str> {
235        self.text.as_deref().or(self.summary.as_deref())
236    }
237}
238
239/// Image input used by multimodal messages.
240#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
241pub struct ImageUrl {
242    /// The image URL.
243    pub url: String,
244    /// Optional processing-detail hint (OpenAI vision style).
245    pub detail: Option<ImageDetail>,
246}
247
248/// Processing-detail hint for image inputs.
249#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
250#[serde(rename_all = "snake_case")]
251pub enum ImageDetail {
252    /// Let the provider decide.
253    Auto,
254    /// Prefer cheap, low-resolution processing.
255    Low,
256    /// Prefer high-resolution processing.
257    High,
258}
259
260/// A provider-hosted tool declaration.
261#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
262#[serde(tag = "type", rename_all = "snake_case")]
263pub enum ServerTool {
264    /// Web search executed by the provider.
265    WebSearch,
266    /// Fetch and ground content from URLs supplied by the model.
267    UrlContext,
268    /// Search over a provider-hosted file store.
269    FileSearch,
270    /// A provider-specific hosted tool.
271    Custom {
272        /// Tool name understood by the provider.
273        name: String,
274        /// Provider-specific configuration for the tool.
275        config: serde_json::Value,
276    },
277}
278
279/// Generic state of a provider-hosted tool.
280#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
281#[serde(rename_all = "snake_case")]
282pub enum ServerToolState {
283    /// The tool is still running.
284    InProgress,
285    /// The tool finished successfully.
286    Completed,
287    /// The tool reported a failure.
288    Failed,
289    /// The provider did not report a state.
290    Unknown,
291}
292
293/// Opaque provider-hosted tool item returned by a provider.
294#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
295pub struct ServerToolItem {
296    /// Best-effort tool name, when the provider reports one.
297    pub tool: Option<String>,
298    /// Call id linking the item to a preceding tool call, when available.
299    pub call_id: Option<String>,
300    /// Best-effort execution state.
301    pub state: Option<ServerToolState>,
302    /// Provider-owned item. It must be replayed unchanged to the same provider.
303    pub provider_state: ProviderState,
304}
305
306impl ServerToolItem {
307    /// Creates an item wrapping opaque provider state.
308    pub fn new(provider_state: ProviderState) -> Self {
309        Self {
310            tool: None,
311            call_id: None,
312            state: None,
313            provider_state,
314        }
315    }
316}
317
318/// A provider-neutral image source.
319#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
320#[serde(tag = "type", rename_all = "snake_case")]
321pub enum ImageSource {
322    /// Image fetched by URL.
323    Url {
324        /// The image URL.
325        url: String,
326    },
327    /// Image embedded as base64 data.
328    Base64 {
329        /// MIME type such as `image/png`.
330        media_type: String,
331        /// Base64-encoded image bytes.
332        data: String,
333    },
334    /// Image referenced by a provider- or user-held file URI.
335    FileRef {
336        /// The file URI.
337        uri: String,
338        /// Optional MIME type.
339        #[serde(default, skip_serializing_if = "Option::is_none")]
340        media_type: Option<String>,
341    },
342}
343
344/// A multimodal image input.
345#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
346pub struct ImagePart {
347    /// Where the image bytes come from.
348    pub source: ImageSource,
349    /// Optional processing-detail hint.
350    #[serde(default, skip_serializing_if = "Option::is_none")]
351    pub detail: Option<ImageDetail>,
352}
353
354impl ImagePart {
355    /// Creates an image part referencing a URL.
356    pub fn url(url: impl Into<String>) -> Self {
357        Self {
358            source: ImageSource::Url { url: url.into() },
359            detail: None,
360        }
361    }
362
363    /// Creates an image part from base64 data.
364    pub fn base64(media_type: impl Into<String>, data: impl Into<String>) -> Self {
365        Self {
366            source: ImageSource::Base64 {
367                media_type: media_type.into(),
368                data: data.into(),
369            },
370            detail: None,
371        }
372    }
373
374    /// Creates an image part referencing a file URI.
375    pub fn file_ref(uri: impl Into<String>, media_type: Option<String>) -> Self {
376        Self {
377            source: ImageSource::FileRef {
378                uri: uri.into(),
379                media_type,
380            },
381            detail: None,
382        }
383    }
384
385    /// Sets the processing-detail hint.
386    pub fn detail(mut self, detail: ImageDetail) -> Self {
387        self.detail = Some(detail);
388        self
389    }
390}
391
392/// A tool call requested by the model.
393#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
394pub struct ToolCall {
395    /// Providers such as Gemini do not always return an id. The normalizer
396    /// fills a stable synthetic id when one is needed for pairing.
397    pub id: Option<String>,
398    /// The name of the tool to call.
399    pub name: String,
400    /// Tool arguments as a JSON object (usually parsed by the application).
401    pub arguments: serde_json::Value,
402    /// Provider-specific data attached to the tool-call block.
403    ///
404    /// Gemini currently uses this to carry `thoughtSignature`. Other adapters
405    /// ignore state that belongs to a different provider.
406    #[serde(default, skip_serializing_if = "Option::is_none")]
407    pub provider_state: Option<ProviderState>,
408}
409
410impl ToolCall {
411    /// Creates a tool call with no id and no provider state.
412    pub fn new(name: impl Into<String>, arguments: serde_json::Value) -> Self {
413        Self {
414            id: None,
415            name: name.into(),
416            arguments,
417            provider_state: None,
418        }
419    }
420
421    /// Sets the tool-call id.
422    pub fn with_id(mut self, id: impl Into<String>) -> Self {
423        self.id = Some(id.into());
424        self
425    }
426
427    /// Attaches provider-specific state such as a `thoughtSignature`.
428    pub fn with_provider_state(
429        mut self,
430        format: ProviderStateFormat,
431        data: serde_json::Value,
432    ) -> Self {
433        self.provider_state = Some(ProviderState::new(format, data));
434        self
435    }
436}
437
438/// A structured tool-result payload.
439#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
440#[serde(tag = "type", rename_all = "snake_case")]
441pub enum ToolResultPart {
442    /// Plain text output.
443    Text { text: String },
444    /// Structured JSON output.
445    Json { value: serde_json::Value },
446    /// Image output produced by the tool.
447    Image { image: ImagePart },
448}
449
450/// A tool result that will be sent back to the model.
451#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
452pub struct ToolResult {
453    /// Id of the originating tool call, when the provider issued one.
454    pub call_id: Option<String>,
455    /// Name of the tool that was executed.
456    pub name: String,
457    /// Plain-text fallback retained for simple tools and provider downgrade.
458    pub content: String,
459    /// Structured output parts; the richer representation of `content`.
460    #[serde(default, skip_serializing_if = "Vec::is_empty")]
461    pub parts: Vec<ToolResultPart>,
462    /// Whether the tool reported a failure.
463    pub is_error: bool,
464    /// Optional provider-style status label (e.g. `"completed"`).
465    #[serde(default, skip_serializing_if = "Option::is_none")]
466    pub status: Option<String>,
467    /// Optional provider-specific metadata attached to the result.
468    #[serde(default, skip_serializing_if = "Option::is_none")]
469    pub metadata: Option<serde_json::Value>,
470}
471
472impl ToolResult {
473    /// Creates a successful text result. A non-empty `content` is mirrored
474    /// into [`ToolResult::parts`] as a single [`ToolResultPart::Text`].
475    pub fn new(
476        call_id: Option<String>,
477        name: impl Into<String>,
478        content: impl Into<String>,
479    ) -> Self {
480        let content = content.into();
481        Self {
482            call_id,
483            name: name.into(),
484            parts: if content.is_empty() {
485                Vec::new()
486            } else {
487                vec![ToolResultPart::Text {
488                    text: content.clone(),
489                }]
490            },
491            content,
492            is_error: false,
493            status: None,
494            metadata: None,
495        }
496    }
497
498    /// Creates an error result with `is_error` set.
499    pub fn error(
500        call_id: Option<String>,
501        name: impl Into<String>,
502        content: impl Into<String>,
503    ) -> Self {
504        let mut result = Self::new(call_id, name, content);
505        result.is_error = true;
506        result
507    }
508
509    /// Creates a result from structured parts. `content` is derived from the
510    /// parts as a plain-text fallback.
511    pub fn from_parts(
512        call_id: Option<String>,
513        name: impl Into<String>,
514        parts: Vec<ToolResultPart>,
515    ) -> Self {
516        Self {
517            call_id,
518            name: name.into(),
519            content: tool_result_parts_text(&parts),
520            parts,
521            is_error: false,
522            status: None,
523            metadata: None,
524        }
525    }
526
527    /// Creates a result carrying a single JSON part.
528    pub fn json(
529        call_id: Option<String>,
530        name: impl Into<String>,
531        value: serde_json::Value,
532    ) -> Self {
533        Self::from_parts(call_id, name, vec![ToolResultPart::Json { value }])
534    }
535
536    /// Creates a result carrying a single image part.
537    pub fn image(call_id: Option<String>, name: impl Into<String>, image: ImagePart) -> Self {
538        Self::from_parts(call_id, name, vec![ToolResultPart::Image { image }])
539    }
540
541    /// Sets a provider-style status label.
542    pub fn status(mut self, status: impl Into<String>) -> Self {
543        self.status = Some(status.into());
544        self
545    }
546
547    /// Attaches provider-specific metadata.
548    pub fn metadata(mut self, metadata: serde_json::Value) -> Self {
549        self.metadata = Some(metadata);
550        self
551    }
552}
553
554fn tool_result_parts_text(parts: &[ToolResultPart]) -> String {
555    let mut output = String::new();
556    for part in parts {
557        if !output.is_empty() {
558            output.push('\n');
559        }
560        match part {
561            ToolResultPart::Text { text } => output.push_str(text),
562            ToolResultPart::Json { value } => {
563                output
564                    .push_str(&serde_json::to_string(value).unwrap_or_else(|_| "null".to_string()));
565            }
566            ToolResultPart::Image { image } => {
567                output.push_str(&format!("[image: {}]", image_source_label(&image.source)));
568            }
569        }
570    }
571    output
572}
573
574fn image_source_label(source: &ImageSource) -> String {
575    match source {
576        ImageSource::Url { url } => url.clone(),
577        ImageSource::Base64 { media_type, .. } => format!("base64:{media_type}"),
578        ImageSource::FileRef { uri, .. } => uri.clone(),
579    }
580}
581
582/// A message in the internal conversation model.
583#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
584pub struct Message {
585    /// Who produced this message.
586    pub role: Role,
587    /// The message content as an ordered list of parts.
588    pub parts: Vec<Part>,
589}
590
591impl Message {
592    /// Creates a message from a role and an ordered list of parts.
593    pub fn new(role: Role, parts: Vec<Part>) -> Self {
594        Self { role, parts }
595    }
596
597    /// Creates a single-text [`Role::System`] message.
598    pub fn system(text: impl Into<String>) -> Self {
599        Self::text(Role::System, text)
600    }
601
602    /// Creates a single-text [`Role::Developer`] message.
603    pub fn developer(text: impl Into<String>) -> Self {
604        Self::text(Role::Developer, text)
605    }
606
607    /// Creates a single-text [`Role::User`] message.
608    pub fn user(text: impl Into<String>) -> Self {
609        Self::text(Role::User, text)
610    }
611
612    /// Creates a single-text [`Role::Assistant`] message.
613    pub fn assistant(text: impl Into<String>) -> Self {
614        Self::text(Role::Assistant, text)
615    }
616
617    /// Creates a single-text [`Role::Custom`] message.
618    pub fn custom(role: impl Into<String>, text: impl Into<String>) -> Self {
619        Self::text(Role::Custom(role.into()), text)
620    }
621
622    /// Creates a message with a single text part of the given role.
623    pub fn text(role: Role, text: impl Into<String>) -> Self {
624        Self {
625            role,
626            parts: vec![Part::text(text)],
627        }
628    }
629
630    /// Creates an assistant message with optional text followed by tool-call
631    /// parts. Empty text is skipped.
632    pub fn assistant_with_tools(
633        text: impl Into<String>,
634        tool_calls: impl IntoIterator<Item = ToolCall>,
635    ) -> Self {
636        let text = text.into();
637        let mut parts = Vec::new();
638        if !text.is_empty() {
639            parts.push(Part::text(text));
640        }
641        parts.extend(tool_calls.into_iter().map(Part::ToolCall));
642        Self {
643            role: Role::Assistant,
644            parts,
645        }
646    }
647
648    /// Creates an assistant message holding a single reasoning part.
649    pub fn assistant_reasoning(reasoning: Reasoning) -> Self {
650        Self {
651            role: Role::Assistant,
652            parts: vec![Part::Reasoning(reasoning)],
653        }
654    }
655
656    /// Creates a [`Role::Tool`] message holding one tool result.
657    pub fn tool_result(result: ToolResult) -> Self {
658        Self {
659            role: Role::Tool,
660            parts: vec![Part::ToolResult(result)],
661        }
662    }
663
664    /// Creates a [`Role::Tool`] message holding multiple tool results.
665    pub fn tool_results(results: impl IntoIterator<Item = ToolResult>) -> Self {
666        Self {
667            role: Role::Tool,
668            parts: results.into_iter().map(Part::ToolResult).collect(),
669        }
670    }
671
672    /// Returns the text parts joined by newlines. Tool-result text content is
673    /// included; other part kinds are skipped.
674    pub fn text_content(&self) -> String {
675        let mut output = String::new();
676        for part in &self.parts {
677            match part {
678                Part::Text { text, .. } => {
679                    if !output.is_empty() {
680                        output.push('\n');
681                    }
682                    output.push_str(text);
683                }
684                Part::ToolResult(result) => {
685                    if !output.is_empty() {
686                        output.push('\n');
687                    }
688                    output.push_str(&result.content);
689                }
690                _ => {}
691            }
692        }
693        output
694    }
695
696    /// Iterates over the tool calls requested in this message.
697    pub fn tool_calls(&self) -> impl Iterator<Item = &ToolCall> {
698        self.parts.iter().filter_map(|part| match part {
699            Part::ToolCall(call) => Some(call),
700            _ => None,
701        })
702    }
703
704    /// Iterates over the tool results carried by this message.
705    /// Iterates over the tool results carried by this message.
706    pub fn tool_result_parts(&self) -> impl Iterator<Item = &ToolResult> {
707        self.parts.iter().filter_map(|part| match part {
708            Part::ToolResult(result) => Some(result),
709            _ => None,
710        })
711    }
712
713    /// Iterates over the reasoning parts of this message.
714    pub fn reasoning(&self) -> impl Iterator<Item = &Reasoning> {
715        self.parts.iter().filter_map(|part| match part {
716            Part::Reasoning(reasoning) => Some(reasoning),
717            _ => None,
718        })
719    }
720
721    /// Returns all reasoning display text joined by newlines.
722    pub fn reasoning_text(&self) -> String {
723        self.reasoning()
724            .filter_map(Reasoning::display_text)
725            .collect::<Vec<_>>()
726            .join("\n")
727    }
728}
729
730/// A provider-neutral tool definition.
731#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
732pub struct ToolSpec {
733    /// Function-style tool name the model may call.
734    pub name: String,
735    /// Human-readable description shown to the model.
736    pub description: String,
737    /// JSON Schema describing the tool's arguments.
738    pub parameters: serde_json::Value,
739    /// Opt in to provider-side structured-output schema enforcement. Responses
740    /// always sends this switch explicitly: omission can cause the endpoint to
741    /// make optional, non-nullable arguments required. This does not control the
742    /// application's argument validation. Schemas are never rewritten here.
743    #[serde(default)]
744    pub strict: bool,
745}
746
747impl ToolSpec {
748    /// Creates a tool definition.
749    pub fn new(
750        name: impl Into<String>,
751        description: impl Into<String>,
752        parameters: serde_json::Value,
753    ) -> Self {
754        Self {
755            name: name.into(),
756            description: description.into(),
757            parameters,
758            strict: false,
759        }
760    }
761
762    /// Use a provider-compatible strict schema supplied by the caller.
763    pub fn strict(mut self, strict: bool) -> Self {
764        self.strict = strict;
765        self
766    }
767}
768
769/// Input accepted by a client-executed custom tool.
770///
771/// Native declarations remain gated until call and replay support is complete.
772#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
773#[serde(tag = "type", rename_all = "snake_case")]
774pub enum CustomToolFormat {
775    /// Unconstrained raw text.
776    Text,
777    /// Raw text constrained by a provider-supported grammar.
778    Grammar {
779        /// Grammar syntax identifier, such as `lark`.
780        syntax: String,
781        /// Complete grammar definition supplied by the caller.
782        definition: String,
783    },
784}
785
786/// A client-executed tool within a declaration scope.
787///
788/// Unlike [`ServerTool`], custom tools are executed by the application. This
789/// Native declarations remain gated until streaming and replay are complete.
790#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
791#[serde(tag = "type", rename_all = "snake_case")]
792pub enum ScopedToolDeclaration {
793    /// A JSON-arguments function, including the legacy function definition.
794    Function { tool: ToolSpec },
795    /// A raw-text client tool.
796    Custom {
797        name: String,
798        description: String,
799        format: CustomToolFormat,
800    },
801}
802
803impl ScopedToolDeclaration {
804    /// Name exposed within the containing scope.
805    pub fn name(&self) -> &str {
806        match self {
807            Self::Function { tool } => &tool.name,
808            Self::Custom { name, .. } => name,
809        }
810    }
811}
812
813impl From<ToolSpec> for ScopedToolDeclaration {
814    fn from(tool: ToolSpec) -> Self {
815        Self::Function { tool }
816    }
817}
818
819/// A flat client tool or a single-level namespace of client tools.
820///
821/// Requests containing these declarations are currently rejected until native
822/// call decoding and result replay can be supported safely.
823#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
824#[serde(tag = "type", rename_all = "snake_case")]
825pub enum ToolDeclaration {
826    /// A tool in the top-level scope.
827    Tool { tool: ScopedToolDeclaration },
828    /// A named scope; nested namespaces cannot be represented.
829    Namespace {
830        name: String,
831        description: String,
832        tools: Vec<ScopedToolDeclaration>,
833    },
834}
835
836/// Reject duplicate names within each declaration scope, regardless of kind.
837///
838/// A namespace occupies a name in the top-level scope. Empty names are also
839/// rejected. Provider-specific naming and capability rules remain separate.
840pub fn validate_tool_declarations(declarations: &[ToolDeclaration]) -> crate::Result<()> {
841    fn insert<'a>(
842        names: &mut std::collections::HashSet<&'a str>,
843        name: &'a str,
844    ) -> crate::Result<()> {
845        if name.is_empty() || !names.insert(name) {
846            return Err(crate::Error::InvalidRequest(format!(
847                "tool_declaration_conflict: empty or duplicate name `{name}`"
848            )));
849        }
850        Ok(())
851    }
852
853    let mut top_level = std::collections::HashSet::new();
854    for declaration in declarations {
855        match declaration {
856            ToolDeclaration::Tool { tool } => insert(&mut top_level, tool.name())?,
857            ToolDeclaration::Namespace { name, tools, .. } => {
858                insert(&mut top_level, name)?;
859                let mut scoped = std::collections::HashSet::new();
860                for tool in tools {
861                    insert(&mut scoped, tool.name())?;
862                }
863            }
864        }
865    }
866    Ok(())
867}
868
869/// The original wire representation of a client-executed tool call.
870#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
871#[serde(rename_all = "snake_case")]
872pub enum NativeToolKind {
873    Function,
874    Custom,
875}
876
877/// Raw input, kept separate from application-specific canonical arguments.
878#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
879#[serde(tag = "type", content = "value", rename_all = "snake_case")]
880pub enum NativeToolPayload {
881    /// Unparsed JSON argument text as received on the wire.
882    JsonArguments(String),
883    /// Unmodified free-form input.
884    RawText(String),
885}
886
887/// Whether the protocol has reliably finished delivering a call.
888#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
889#[serde(rename_all = "snake_case")]
890pub enum NativeToolCompletion {
891    Receiving,
892    Completed,
893    Invalid,
894    Interrupted,
895}
896
897/// Original call identity and input, independent of a canonical tool call.
898///
899/// This is not yet integrated with message normalization or stream decoding;
900/// consumers must not treat the presence of this type as execution support.
901#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
902pub struct NativeToolCall {
903    pub kind: NativeToolKind,
904    pub namespace: Option<String>,
905    pub name: String,
906    /// The provider's real result-pairing identifier, never the item id.
907    pub call_id: String,
908    /// The output item's identifier, when supplied by the provider.
909    pub item_id: Option<String>,
910    pub payload: NativeToolPayload,
911    pub completion: NativeToolCompletion,
912    #[serde(default, skip_serializing_if = "Option::is_none")]
913    pub provider_state: Option<ProviderState>,
914}
915
916impl NativeToolCall {
917    /// Check identity and payload invariants before admitting a completed call.
918    pub fn validate_completed(&self) -> crate::Result<()> {
919        if self.completion != NativeToolCompletion::Completed {
920            return Err(crate::Error::InvalidRequest("tool_call_incomplete".into()));
921        }
922        if self.call_id.is_empty()
923            || self.name.is_empty()
924            || self.namespace.as_deref() == Some("")
925            || self.item_id.as_deref() == Some("")
926        {
927            return Err(crate::Error::InvalidRequest(
928                "tool_identity_conflict".into(),
929            ));
930        }
931        if !matches!(
932            (&self.kind, &self.payload),
933            (
934                NativeToolKind::Function,
935                NativeToolPayload::JsonArguments(_)
936            ) | (NativeToolKind::Custom, NativeToolPayload::RawText(_))
937        ) {
938            return Err(crate::Error::InvalidRequest("tool_payload_conflict".into()));
939        }
940        Ok(())
941    }
942}
943
944/// A provider-neutral reasoning-effort level.
945#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
946#[serde(rename_all = "snake_case")]
947pub enum ReasoningEffort {
948    /// Disable reasoning entirely where the provider supports it.
949    None,
950    /// The cheapest reasoning tier.
951    Minimal,
952    Low,
953    Medium,
954    High,
955    /// Extra-high reasoning (OpenAI `xhigh`).
956    #[serde(rename = "xhigh")]
957    XHigh,
958    /// The provider's maximum reasoning tier.
959    Max,
960    /// Above `max`: OpenAI 的 `ultra`(Codex 桌面端暴露的最高档,上游受门控)。
961    /// `snake_case` 直接给出 `"ultra"`,无需显式 rename。
962    Ultra,
963}
964
965/// How much reasoning detail the provider should expose.
966#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
967#[serde(rename_all = "snake_case")]
968pub enum ReasoningSummary {
969    /// Let the provider decide whether to include a summary.
970    Auto,
971    /// A short summary.
972    Concise,
973    /// A detailed summary.
974    Detailed,
975}
976
977/// High-level mode for providers that expose enable/disable controls.
978#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
979#[serde(rename_all = "snake_case")]
980pub enum ReasoningMode {
981    /// Always reason before answering.
982    Enabled,
983    /// Let the model decide when to reason.
984    Adaptive,
985    /// Do not reason.
986    Disabled,
987}
988
989/// Provider-neutral reasoning request configuration.
990///
991/// Adapters translate only the fields that their protocol supports. Fields
992/// that have no equivalent are ignored rather than guessed.
993#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
994pub struct ReasoningConfig {
995    /// Enable/disable mode for providers with a simple toggle.
996    pub mode: Option<ReasoningMode>,
997    /// Coarse effort level.
998    pub effort: Option<ReasoningEffort>,
999    /// Token budget for reasoning.
1000    pub budget_tokens: Option<u32>,
1001    /// How much reasoning summary to expose.
1002    pub summary: Option<ReasoningSummary>,
1003    /// Ask providers such as Gemini to include readable thought parts.
1004    pub include_text: Option<bool>,
1005    /// Ask OpenAI Responses to include encrypted reasoning for stateless replay.
1006    pub include_encrypted: Option<bool>,
1007}
1008
1009impl ReasoningConfig {
1010    /// Creates an empty configuration with all options unset.
1011    pub fn new() -> Self {
1012        Self::default()
1013    }
1014
1015    /// Sets the enable/disable mode.
1016    pub fn mode(mut self, mode: ReasoningMode) -> Self {
1017        self.mode = Some(mode);
1018        self
1019    }
1020
1021    /// Sets the effort level.
1022    pub fn effort(mut self, effort: ReasoningEffort) -> Self {
1023        self.effort = Some(effort);
1024        self
1025    }
1026
1027    /// Sets the reasoning token budget.
1028    pub fn budget_tokens(mut self, budget_tokens: u32) -> Self {
1029        self.budget_tokens = Some(budget_tokens);
1030        self
1031    }
1032
1033    /// Sets the reasoning summary verbosity.
1034    pub fn summary(mut self, summary: ReasoningSummary) -> Self {
1035        self.summary = Some(summary);
1036        self
1037    }
1038
1039    /// Requests readable thought parts (e.g. Gemini).
1040    pub fn include_text(mut self, include_text: bool) -> Self {
1041        self.include_text = Some(include_text);
1042        self
1043    }
1044
1045    /// Requests encrypted reasoning for stateless replay (e.g. OpenAI
1046    /// Responses).
1047    pub fn include_encrypted(mut self, include_encrypted: bool) -> Self {
1048        self.include_encrypted = Some(include_encrypted);
1049        self
1050    }
1051}
1052
1053/// Provider-neutral tool selection for one request.
1054#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1055#[serde(rename_all = "snake_case")]
1056pub enum ToolChoice {
1057    /// The model decides whether to call tools.
1058    Auto,
1059    /// The model must not call tools.
1060    None,
1061    /// The model must call at least one tool.
1062    Required,
1063    /// The model must call the named tool.
1064    Tool(String),
1065}
1066
1067/// Provider-neutral output format for one request.
1068#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1069#[serde(tag = "type", rename_all = "snake_case")]
1070pub enum ResponseFormat {
1071    /// Plain text output.
1072    Text,
1073    /// Output must be a valid JSON object.
1074    JsonObject,
1075    /// Output must conform to a JSON Schema.
1076    JsonSchema {
1077        /// Schema name used by providers that require one.
1078        name: String,
1079        /// The JSON Schema itself.
1080        schema: serde_json::Value,
1081        /// Whether the provider should strictly enforce the schema.
1082        strict: Option<bool>,
1083    },
1084}
1085
1086/// A request sent to a model adapter.
1087///
1088/// `extra_body` is an escape hatch for provider-specific wire fields. The SDK
1089/// merges it into the final JSON object but refuses to let it overwrite
1090/// canonical fields such as `model`, `messages`, `input`, or `stream`.
1091#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
1092pub struct ChatRequest {
1093    /// The conversation so far.
1094    pub messages: Vec<Message>,
1095    /// Client-side tools the model may call.
1096    pub tools: Vec<ToolSpec>,
1097    /// Native client declarations. Currently rejected by all wire adapters;
1098    /// this gate prevents exposing tools before call/result replay is complete.
1099    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1100    pub tool_declarations: Vec<ToolDeclaration>,
1101    /// Provider-hosted tools such as web search.
1102    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1103    pub server_tools: Vec<ServerTool>,
1104    /// How the model should choose among tools.
1105    pub tool_choice: Option<ToolChoice>,
1106    /// Requested output format.
1107    pub response_format: Option<ResponseFormat>,
1108    /// Sequences that stop generation.
1109    pub stop: Vec<String>,
1110    /// Sampling seed for reproducibility.
1111    pub seed: Option<u64>,
1112    /// Sampling temperature.
1113    pub temperature: Option<f32>,
1114    /// Upper bound on generated tokens.
1115    pub max_output_tokens: Option<u32>,
1116    /// Reasoning behavior, for providers that support it.
1117    pub reasoning: Option<ReasoningConfig>,
1118    /// Escape hatch for provider-specific wire fields. Reserved canonical
1119    /// fields cannot be overwritten.
1120    #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
1121    pub extra_body: serde_json::Map<String, serde_json::Value>,
1122}
1123
1124impl ChatRequest {
1125    /// Creates a request from the given messages; all other fields default.
1126    pub fn new(messages: impl IntoIterator<Item = Message>) -> Self {
1127        Self {
1128            messages: messages.into_iter().collect(),
1129            ..Self::default()
1130        }
1131    }
1132
1133    /// Creates a request with a single user text message.
1134    pub fn user(text: impl Into<String>) -> Self {
1135        Self::new([Message::user(text)])
1136    }
1137
1138    /// Appends a message.
1139    pub fn push(mut self, message: Message) -> Self {
1140        self.messages.push(message);
1141        self
1142    }
1143
1144    /// Replaces the client-side tool list.
1145    pub fn tools(mut self, tools: impl IntoIterator<Item = ToolSpec>) -> Self {
1146        self.tools = tools.into_iter().collect();
1147        self
1148    }
1149
1150    /// Replaces the native client declarations; the legacy function list is
1151    /// retained separately and participates in top-level conflict validation.
1152    pub fn tool_declarations(mut self, tools: impl IntoIterator<Item = ToolDeclaration>) -> Self {
1153        self.tool_declarations = tools.into_iter().collect();
1154        self
1155    }
1156
1157    /// Replaces the provider-hosted tool list.
1158    pub fn server_tools(mut self, tools: impl IntoIterator<Item = ServerTool>) -> Self {
1159        self.server_tools = tools.into_iter().collect();
1160        self
1161    }
1162
1163    /// Sets how the model should choose among tools.
1164    pub fn tool_choice(mut self, tool_choice: ToolChoice) -> Self {
1165        self.tool_choice = Some(tool_choice);
1166        self
1167    }
1168
1169    /// Sets the requested output format.
1170    pub fn response_format(mut self, response_format: ResponseFormat) -> Self {
1171        self.response_format = Some(response_format);
1172        self
1173    }
1174
1175    /// Replaces the stop sequences.
1176    pub fn stop<I, S>(mut self, stop: I) -> Self
1177    where
1178        I: IntoIterator<Item = S>,
1179        S: Into<String>,
1180    {
1181        self.stop = stop.into_iter().map(Into::into).collect();
1182        self
1183    }
1184
1185    /// Sets the sampling seed.
1186    pub fn seed(mut self, seed: u64) -> Self {
1187        self.seed = Some(seed);
1188        self
1189    }
1190
1191    /// Sets the sampling temperature.
1192    pub fn temperature(mut self, temperature: f32) -> Self {
1193        self.temperature = Some(temperature);
1194        self
1195    }
1196
1197    /// Sets the output token limit.
1198    pub fn max_output_tokens(mut self, max_output_tokens: u32) -> Self {
1199        self.max_output_tokens = Some(max_output_tokens);
1200        self
1201    }
1202
1203    /// Sets the reasoning configuration.
1204    pub fn reasoning(mut self, reasoning: ReasoningConfig) -> Self {
1205        self.reasoning = Some(reasoning);
1206        self
1207    }
1208
1209    /// Add one provider-specific request body field.
1210    ///
1211    /// Reserved canonical fields are rejected by the adapter at request time,
1212    /// not silently overwritten.
1213    pub fn extra_body(
1214        mut self,
1215        key: impl Into<String>,
1216        value: impl Into<serde_json::Value>,
1217    ) -> Self {
1218        self.extra_body.insert(key.into(), value.into());
1219        self
1220    }
1221}
1222
1223/// Token usage reported by a provider.
1224#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
1225pub struct Usage {
1226    /// Prompt tokens consumed.
1227    pub input_tokens: Option<u64>,
1228    /// Tokens generated.
1229    pub output_tokens: Option<u64>,
1230    /// Total tokens, when reported by the provider.
1231    pub total_tokens: Option<u64>,
1232    /// Tokens served from a prompt cache.
1233    pub cache_read_tokens: Option<u64>,
1234    /// Tokens written to a prompt cache.
1235    pub cache_write_tokens: Option<u64>,
1236    /// Tokens spent on reasoning.
1237    pub reasoning_tokens: Option<u64>,
1238    /// Provider-native usage object for fields not yet given a neutral name.
1239    pub raw: Option<serde_json::Value>,
1240}
1241
1242impl Usage {
1243    /// Remove provider-native data before exposing usage to audit sinks.
1244    pub(crate) fn without_raw(mut self) -> Self {
1245        self.raw = None;
1246        self
1247    }
1248}
1249
1250/// HTTP metadata associated with a model response.
1251#[derive(Debug, Clone, PartialEq)]
1252pub struct ResponseMetadata {
1253    /// HTTP status code of the response.
1254    pub status: u16,
1255    /// Request id taken from common provider headers, when present.
1256    pub request_id: Option<String>,
1257    /// All response headers.
1258    pub headers: HeaderMap,
1259}
1260
1261impl ResponseMetadata {
1262    /// Looks up a header by name. Header names are compared
1263    /// case-insensitively.
1264    pub fn header(&self, name: impl AsRef<str>) -> Option<&reqwest::header::HeaderValue> {
1265        reqwest::header::HeaderName::from_bytes(name.as_ref().as_bytes())
1266            .ok()
1267            .and_then(|name| self.headers.get(name))
1268    }
1269
1270    /// Returns the request id, when one was found.
1271    pub fn request_id(&self) -> Option<&str> {
1272        self.request_id.as_deref()
1273    }
1274
1275    /// Captures metadata from a completed response. The request id is taken
1276    /// from the first of `x-request-id`, `request-id`, `x-ms-request-id`, or
1277    /// `cf-ray` present in the headers.
1278    pub fn from_response(response: &reqwest::Response) -> Self {
1279        let request_id = ["x-request-id", "request-id", "x-ms-request-id", "cf-ray"]
1280            .into_iter()
1281            .find_map(|name| {
1282                response
1283                    .headers()
1284                    .get(name)
1285                    .and_then(|value| value.to_str().ok())
1286                    .map(str::to_string)
1287            });
1288
1289        Self {
1290            status: response.status().as_u16(),
1291            request_id,
1292            headers: response.headers().clone(),
1293        }
1294    }
1295}
1296
1297/// A normalized model response.
1298#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1299pub struct ChatResponse {
1300    /// The assistant message produced by the model.
1301    pub message: Message,
1302    /// Token usage, when reported by the provider.
1303    pub usage: Option<Usage>,
1304    /// Provider-native response or accumulated stream chunks.
1305    ///
1306    /// Shape is protocol-specific and can be large. Do not log it by default.
1307    pub raw: serde_json::Value,
1308    /// HTTP metadata, set by transports that keep it; not serialized.
1309    #[serde(skip)]
1310    pub metadata: Option<ResponseMetadata>,
1311    /// Transformations applied while preparing or decoding this response.
1312    #[serde(skip)]
1313    pub report: CompletionReport,
1314}
1315
1316impl ChatResponse {
1317    /// Creates a response with no usage, raw payload, metadata, or report.
1318    pub fn new(message: Message) -> Self {
1319        Self {
1320            message,
1321            usage: None,
1322            raw: serde_json::Value::Null,
1323            metadata: None,
1324            report: CompletionReport::default(),
1325        }
1326    }
1327
1328    /// Returns the text content of the response message.
1329    pub fn text(&self) -> String {
1330        self.message.text_content()
1331    }
1332
1333    /// Iterates over the tool calls requested in the response.
1334    pub fn tool_calls(&self) -> impl Iterator<Item = &ToolCall> {
1335        self.message.tool_calls()
1336    }
1337
1338    /// Iterates over the reasoning parts of the response.
1339    pub fn reasoning(&self) -> impl Iterator<Item = &Reasoning> {
1340        self.message.reasoning()
1341    }
1342
1343    /// Returns all reasoning display text joined by newlines.
1344    pub fn reasoning_text(&self) -> String {
1345        self.message.reasoning_text()
1346    }
1347}