Skip to main content

rig_core/completion/
message.rs

1use serde::{Deserialize, Serialize};
2use std::{convert::Infallible, str::FromStr};
3
4/// A provider-agnostic chat message.
5///
6/// Messages are role-tagged and may contain one or many content items, including
7/// text, images, audio, documents, tool calls, and tool results. Provider modules
8/// are responsible for translating these generic messages into provider-native
9/// request bodies. That conversion may be lossy when a provider does not support
10/// a particular content type.
11#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
12#[serde(tag = "role", rename_all = "lowercase")]
13pub enum Message {
14    /// System message containing instruction text.
15    System { content: String },
16
17    /// User message containing one or more content types defined by `UserContent`.
18    User { content: Vec<UserContent> },
19
20    /// An assistant turn: its blocks in the order the provider produced
21    /// them, and where they came from.
22    Assistant(AssistantMessage),
23}
24
25pub mod citation;
26mod identity;
27mod native;
28
29pub use citation::{Citation, DocumentRange, Source, SourceLocation, Span};
30
31pub use identity::{CallId, EmptyCallId, EmptyToolName, LocalCallId, ProviderCallId, ToolName};
32pub(crate) use native::Canonical;
33pub use native::{Api, Blob, Fingerprint, Native, Opaque, Origin, StopReason};
34
35/// One assistant turn.
36///
37/// `content` holds one block per provider output item, in the order the
38/// provider produced them. `origin` names the wire, provider and model that
39/// produced the turn; a hand-built turn has none and always replays from its
40/// canonical fields.
41#[non_exhaustive]
42#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq)]
43pub struct AssistantMessage {
44    /// The blocks, in provider order.
45    pub content: Vec<AssistantContent>,
46    /// Who produced the turn.
47    #[serde(default, skip_serializing_if = "Option::is_none")]
48    pub origin: Option<Origin>,
49    /// How the turn ended.
50    #[serde(default, skip_serializing_if = "Option::is_none")]
51    pub stop: Option<StopReason>,
52}
53
54impl AssistantMessage {
55    /// A hand-built turn of `content`: no origin or stop.
56    pub fn new(content: Vec<AssistantContent>) -> Self {
57        Self {
58            content,
59            ..Self::default()
60        }
61    }
62
63    /// The turn a runtime rolls back over: what arrived of a reply from
64    /// `origin`, stopped to call tools, since the runtime answers its calls.
65    /// `content` keeps only the provider items its fold kept.
66    pub fn rolled_back(origin: Option<Origin>, content: Vec<AssistantContent>) -> Self {
67        Self {
68            content,
69            origin,
70            stop: Some(StopReason::ToolUse),
71        }
72    }
73
74    /// The turn a run stopped before the reply ended: kept in history as no
75    /// answer, replayed as its text alone.
76    pub fn aborted(
77        origin: Option<Origin>,
78        content: Vec<AssistantContent>,
79        reason: impl Into<String>,
80    ) -> Self {
81        Self {
82            content,
83            origin,
84            stop: Some(StopReason::Aborted(reason.into())),
85        }
86    }
87
88    /// This turn holding `content` in place of its blocks.
89    pub fn with_content(mut self, content: Vec<AssistantContent>) -> Self {
90        self.content = content;
91        self
92    }
93
94    /// This turn with `origin` as who produced it.
95    pub fn with_origin(mut self, origin: impl Into<Option<Origin>>) -> Self {
96        self.origin = origin.into();
97        self
98    }
99
100    /// This turn with `stop` as how it ended.
101    pub fn with_stop(mut self, stop: impl Into<Option<StopReason>>) -> Self {
102        self.stop = stop.into();
103        self
104    }
105
106    /// The tool calls, in order.
107    pub fn tool_calls(&self) -> impl Iterator<Item = &ToolCall> {
108        self.content
109            .iter()
110            .filter_map(AssistantContent::as_tool_call)
111    }
112
113    /// The text parts, concatenated.
114    pub fn text(&self) -> String {
115        AssistantContent::concat_text(&self.content)
116    }
117
118    /// Whether this generated turn is empty: every part is blank
119    /// ([`AssistantContent::is_blank`], the rule replay drops parts by). An
120    /// empty turn must not enter history.
121    pub fn is_empty_turn(&self) -> bool {
122        self.content.iter().all(AssistantContent::is_blank)
123    }
124}
125
126/// Whether no block of the choice is an answer
127/// ([`AssistantContent::is_answer`]): reasoning, provider-only items and
128/// blank text are not, even when retained in history.
129pub fn turn_delivered_no_answer(choice: &[AssistantContent]) -> bool {
130    !choice.iter().any(AssistantContent::is_answer)
131}
132
133/// Why a run fails on a turn, or `None` when it goes on. A turn that failed
134/// or was stopped ([`StopReason::is_failure`]) runs none of its tool calls.
135/// A turn the provider failed ([`StopReason::Error`]) fails even when it
136/// holds an answer, so the caller
137/// never takes as a success a turn the next request leaves out. A turn that
138/// delivered no answer ([`turn_delivered_no_answer`]) also fails when the
139/// output budget or a filter cut it (`finish` is truncating). A turn that
140/// ended at the token limit with a call is finished, so its call runs.
141/// Every runtime reads this one rule.
142pub fn turn_failure(
143    choice: &[AssistantContent],
144    stop: Option<&StopReason>,
145    finish: Option<&crate::completion::FinishReason>,
146) -> Option<String> {
147    let failed = stop.filter(|stop| stop.is_failure());
148    let calls = choice
149        .iter()
150        .any(|block| matches!(block, AssistantContent::ToolCall(_)));
151    if let Some(StopReason::Error(reason) | StopReason::Aborted(reason)) = failed
152        && calls
153    {
154        return Some(format!(
155            "the turn failed, so none of its tool calls ran: {reason}"
156        ));
157    }
158    let answered = !turn_delivered_no_answer(choice);
159    if !answered && let Some(finish) = finish.filter(|finish| finish.truncated_output()) {
160        return Some(finish.no_answer_message());
161    }
162    match failed {
163        Some(StopReason::Error(reason)) if answered => {
164            Some(format!("the provider failed the turn: {reason}"))
165        }
166        Some(StopReason::Error(reason)) => Some(format!(
167            "the provider failed the turn without an answer: {reason}"
168        )),
169        _ => None,
170    }
171}
172
173/// User text, tool results, or media. Supported source kinds and media types
174/// depend on the target provider.
175#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
176#[serde(tag = "type", rename_all = "lowercase")]
177pub enum UserContent {
178    /// Plain text user content.
179    Text(Text),
180    /// Result of a tool call returned as user-visible context to the model.
181    ToolResult(ToolResult),
182    /// Image content.
183    Image(Image),
184    /// Audio content.
185    Audio(Audio),
186    /// Video content.
187    Video(Video),
188    /// Document content.
189    Document(DocumentContent),
190}
191
192/// One block of an assistant turn: one provider output item.
193/// Deserialization requires the lowercase `type` tag.
194#[non_exhaustive]
195#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
196#[serde(tag = "type", rename_all = "lowercase")]
197pub enum AssistantContent {
198    /// Answer text.
199    Text(Text),
200    /// A tool call requested by the assistant.
201    ToolCall(ToolCall),
202    /// Reasoning the model showed.
203    Reasoning(Reasoning),
204    /// An image the assistant produced.
205    Image(Image),
206    /// A provider item with no canonical meaning.
207    Opaque(Opaque),
208}
209
210impl AssistantContent {
211    /// Borrow the text of a text block.
212    pub fn as_text(&self) -> Option<&str> {
213        match self {
214            Self::Text(text) => Some(&text.text),
215            _ => None,
216        }
217    }
218
219    /// Borrow the call of a tool-call block.
220    pub fn as_tool_call(&self) -> Option<&ToolCall> {
221        match self {
222            Self::ToolCall(call) => Some(call),
223            _ => None,
224        }
225    }
226
227    /// The text blocks of `parts`, concatenated in order.
228    pub fn concat_text(parts: &[Self]) -> String {
229        parts.iter().filter_map(Self::as_text).collect()
230    }
231
232    /// This block without its provider item: what a different provider can
233    /// use, and what its fingerprint covers. The item is not copied.
234    pub fn canonical(&self) -> Self {
235        match self {
236            Self::Text(text) => Self::Text(Text {
237                text: text.text.clone(),
238                citations: text.citations.clone(),
239                native: None,
240            }),
241            Self::ToolCall(call) => {
242                Self::ToolCall(ToolCall::new(call.id.clone(), call.function.clone()))
243            }
244            Self::Reasoning(reasoning) => Self::Reasoning(Reasoning {
245                text: reasoning.text.clone(),
246                redacted: reasoning.redacted,
247                native: None,
248            }),
249            Self::Image(image) => Self::Image(Image {
250                data: image.data.clone(),
251                media_type: image.media_type.clone(),
252                detail: image.detail.clone(),
253                native: None,
254            }),
255            Self::Opaque(opaque) => Self::Opaque(opaque.clone()),
256        }
257    }
258
259    /// [`Self::canonical`], taking the block.
260    pub fn into_canonical(mut self) -> Self {
261        if let Some(native) = self.native_slot() {
262            *native = None;
263        }
264        self
265    }
266
267    /// Whether the block answers the user: text that is not blank, a call
268    /// or an image. Reasoning and provider-only items are not an answer.
269    pub fn is_answer(&self) -> bool {
270        match self {
271            Self::Text(text) => !text.text.trim().is_empty(),
272            Self::ToolCall(_) | Self::Image(_) => true,
273            Self::Reasoning(_) | Self::Opaque(_) => false,
274        }
275    }
276
277    /// Whether the block has nothing to send, so replay drops it: blank text
278    /// or reasoning, and redacted reasoning, without a provider item that is
279    /// still current (with one, its identity pairs it with what follows, so
280    /// it replays whatever its text), and an opaque item that does not
281    /// replay.
282    pub fn is_blank(&self) -> bool {
283        match self {
284            Self::Text(Text { text, .. }) => text.trim().is_empty() && self.native_item().is_none(),
285            Self::Reasoning(Reasoning { text, redacted, .. }) => {
286                (*redacted || text.trim().is_empty()) && self.native_item().is_none()
287            }
288            Self::Opaque(opaque) => !opaque.replay,
289            Self::ToolCall(_) | Self::Image(_) => false,
290        }
291    }
292
293    /// The fingerprint of the block's canonical fields, through a fixed,
294    /// versioned projection rather than the block's serde layout, so a field
295    /// added to a canonical type never stales stored items. A rig-issued
296    /// call id counts as one placeholder: rig issues a fresh id each time it
297    /// decodes a call the provider sent without one.
298    pub fn fingerprint(&self) -> Fingerprint {
299        // Projection v1 of the canonical fields, as a JSON array. An image's
300        // media type and detail serialize as strings and its data as
301        // `{"type", "value"}` (keys in order, no floats), so only call
302        // arguments need `Canonical`.
303        match self {
304            Self::Text(text) => Fingerprint::of_canonical(&("v1", "text", &text.text)),
305            Self::Reasoning(reasoning) => {
306                Fingerprint::of_canonical(&("v1", "reasoning", &reasoning.text, reasoning.redacted))
307            }
308            Self::ToolCall(call) => call.fingerprint(),
309            Self::Image(image) => Fingerprint::of_canonical(&(
310                "v1",
311                "image",
312                &image.media_type,
313                &image.detail,
314                &image.data,
315            )),
316            Self::Opaque(_) => Fingerprint::of_canonical(&("v1", "opaque")),
317        }
318    }
319
320    pub(crate) fn native_slot(&mut self) -> Option<&mut Option<Native>> {
321        match self {
322            Self::Text(text) => Some(&mut text.native),
323            Self::ToolCall(call) => Some(&mut call.native),
324            Self::Reasoning(reasoning) => Some(&mut reasoning.native),
325            Self::Image(image) => Some(&mut image.native),
326            Self::Opaque(_) => None,
327        }
328    }
329
330    /// The provider item this block was decoded from, held for its current
331    /// canonical form. An [`Opaque`] block has no separate item.
332    pub fn with_native(mut self, item: serde_json::Value) -> Self {
333        let fingerprint = self.fingerprint();
334        let baseline = match &self {
335            Self::ToolCall(call) => call.baseline(),
336            _ => None,
337        };
338        if let Some(native) = self.native_slot() {
339            *native = Some(Native {
340                item,
341                fingerprint,
342                baseline,
343                edited: false,
344                blob_slot: None,
345            });
346        }
347        self
348    }
349
350    /// The provider item the block holds, and whether it is still current
351    /// (the block is what it was decoded from).
352    pub(crate) fn native(&self) -> Option<(&serde_json::Value, bool)> {
353        let native = match self {
354            Self::Text(text) => text.native.as_ref(),
355            Self::ToolCall(call) => call.native.as_ref(),
356            Self::Reasoning(reasoning) => reasoning.native.as_ref(),
357            Self::Image(image) => image.native.as_ref(),
358            Self::Opaque(_) => None,
359        }?;
360        let current = match self {
361            Self::ToolCall(call) => call.native_is_current(native),
362            _ => !native.edited && native.fingerprint == self.fingerprint(),
363        };
364        Some((&native.item, current))
365    }
366
367    /// The provider item of an edited block: no longer current, but its
368    /// identity keys still name the item it was.
369    pub(crate) fn stale_item(&self) -> Option<&serde_json::Value> {
370        self.native()
371            .and_then(|(item, current)| (!current).then_some(item))
372    }
373
374    /// The provider item, while the block is still what it was decoded
375    /// from. An edited block has none: encoders rebuild it.
376    pub fn native_item(&self) -> Option<&serde_json::Value> {
377        self.native()
378            .and_then(|(item, current)| current.then_some(item))
379    }
380}
381
382/// Reasoning the model showed: its text, or a redacted block with none.
383/// Signatures, encrypted payloads and ids are provider data and live in
384/// `native`.
385#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq)]
386pub struct Reasoning {
387    /// The reasoning text, summaries included.
388    pub text: String,
389    /// Whether the provider withheld the text.
390    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
391    pub redacted: bool,
392    /// The provider item this block was decoded from.
393    #[serde(
394        default,
395        skip_serializing_if = "Option::is_none",
396        deserialize_with = "lenient"
397    )]
398    pub native: Option<Native>,
399}
400
401impl Reasoning {
402    /// Reasoning text with no provider item.
403    pub fn new(text: impl Into<String>) -> Self {
404        Self {
405            text: text.into(),
406            ..Self::default()
407        }
408    }
409}
410
411/// The result of a tool call, sent back to the model.
412///
413/// Build it from the call it answers with [`ToolCall::result`], so its id
414/// and name match the call.
415#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
416pub struct ToolResult {
417    /// The id of the answered call.
418    pub call: CallId,
419    /// Executed tool name, which may differ from the model-requested name after
420    /// hook repair. Required for provider replay independently of call identity.
421    pub name: ToolName,
422    /// One or more content items produced by the tool.
423    pub content: Vec<ToolResultContent>,
424    /// Whether the tool failed, was refused, or never ran: `content` then
425    /// says why.
426    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
427    pub is_error: bool,
428}
429
430/// Describes one typed item in a tool result.
431#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
432#[serde(tag = "type", rename_all = "lowercase")]
433pub enum ToolResultContent {
434    /// Literal text. Providers must not reinterpret it as structured JSON.
435    Text(Text),
436    /// An image supplied explicitly by the tool.
437    Image(Image),
438    /// Structured JSON supplied explicitly by the tool runtime.
439    Json {
440        /// The structured value.
441        value: serde_json::Value,
442    },
443}
444
445impl ToolResultContent {
446    /// Borrow literal text content.
447    pub fn as_text(&self) -> Option<&str> {
448        match self {
449            Self::Text(text) => Some(&text.text),
450            Self::Image(_) | Self::Json { .. } => None,
451        }
452    }
453
454    /// Borrow structured JSON content.
455    pub fn as_json(&self) -> Option<&serde_json::Value> {
456        match self {
457            Self::Json { value } => Some(value),
458            Self::Text(_) | Self::Image(_) => None,
459        }
460    }
461
462    /// The content as text: literal text, JSON as its compact text, and an
463    /// image as `image`.
464    pub fn to_text(&self, image: &str) -> String {
465        match self {
466            Self::Text(text) => text.text.clone(),
467            Self::Json { value } => value.to_string(),
468            Self::Image(_) => image.to_owned(),
469        }
470    }
471
472    /// Decodes the content as `T`: structured JSON directly, and text parsed
473    /// as JSON, since many tools return JSON as text. An image, or text that
474    /// is not `T`'s JSON, is an error. The content itself is unchanged.
475    ///
476    /// ```
477    /// use rig_core::message::ToolResultContent;
478    ///
479    /// let text = ToolResultContent::text(r#"{"count": 3}"#);
480    /// let json = ToolResultContent::Json { value: serde_json::json!({"count": 3}) };
481    /// for content in [text, json] {
482    ///     let value: serde_json::Value = content.deserialize_json()?;
483    ///     assert_eq!(value["count"], 3);
484    /// }
485    /// # Ok::<(), serde_json::Error>(())
486    /// ```
487    pub fn deserialize_json<T>(&self) -> Result<T, serde_json::Error>
488    where
489        T: serde::de::DeserializeOwned,
490    {
491        match self {
492            Self::Json { value } => crate::json_utils::from_value(value),
493            Self::Text(text) => serde_json::from_str(&text.text),
494            Self::Image(_) => Err(<serde_json::Error as serde::de::Error>::custom(
495                "an image tool result is not JSON",
496            )),
497        }
498    }
499}
500
501/// A tool call: its id, and the function and arguments requested.
502#[derive(Clone, Debug, Deserialize, PartialEq)]
503pub struct ToolCall {
504    /// The call's one identity: the provider's id, or one rig issued when
505    /// the provider sent none.
506    pub id: CallId,
507    /// Function name and JSON arguments requested by the model.
508    pub function: ToolFunction,
509    /// The provider item this call was decoded from.
510    #[serde(
511        default,
512        skip_serializing_if = "Option::is_none",
513        deserialize_with = "lenient"
514    )]
515    pub native: Option<Native>,
516}
517
518impl ToolCall {
519    /// The id the fingerprint and the projection see: every local id is one
520    /// placeholder.
521    fn fingerprint_id(&self) -> &str {
522        match &self.id {
523            CallId::Provider(id) => id.as_str(),
524            CallId::Local(_) => "~local",
525        }
526    }
527
528    fn fingerprint(&self) -> Fingerprint {
529        Fingerprint::of_canonical(&(
530            "v1",
531            "call",
532            self.fingerprint_id(),
533            self.function.name.as_str(),
534            native::Canonical(&self.function.arguments),
535            &self.function.invalid_arguments,
536        ))
537    }
538
539    fn native_is_current(&self, native: &Native) -> bool {
540        !native.edited
541            && match &native.baseline {
542                Some(baseline) => native::matches_baseline(baseline, &self.projection()),
543                None => native.fingerprint == self.fingerprint(),
544            }
545    }
546
547    fn baseline(&self) -> Option<serde_json::Value> {
548        fn has_float(value: &serde_json::Value) -> bool {
549            match value {
550                serde_json::Value::Number(number) => number.is_f64(),
551                serde_json::Value::Array(values) => values.iter().any(has_float),
552                serde_json::Value::Object(fields) => fields.values().any(has_float),
553                _ => false,
554            }
555        }
556        self.function
557            .arguments
558            .values()
559            .any(has_float)
560            .then(|| native::baseline(self.projection()))
561    }
562
563    fn projection(&self) -> serde_json::Value {
564        serde_json::json!([
565            "v1",
566            "call",
567            self.fingerprint_id(),
568            self.function.name.as_str(),
569            self.function.arguments,
570            self.function.invalid_arguments,
571        ])
572    }
573
574    /// A call with `id` and no provider item.
575    pub fn new(id: CallId, function: ToolFunction) -> Self {
576        Self {
577            id,
578            function,
579            native: None,
580        }
581    }
582
583    /// A call the provider identified by `wire_id`; rig issues an id when it
584    /// is empty.
585    pub fn from_wire(wire_id: impl Into<String>, function: ToolFunction) -> Self {
586        Self::new(CallId::from_wire(wire_id), function)
587    }
588
589    /// The result answering this call: its id and name, and `content`.
590    pub fn result(&self, content: Vec<ToolResultContent>) -> ToolResult {
591        ToolResult {
592            call: self.id.clone(),
593            name: self.function.name.clone(),
594            content,
595            is_error: false,
596        }
597    }
598
599    /// The result answering this call with what its tool did: the output
600    /// the model reads, an error result for anything but a success.
601    pub fn answer(&self, result: &crate::tool::ToolResult) -> ToolResult {
602        ToolResult {
603            is_error: !result.is_success(),
604            ..self.result(result.output().clone().into_content())
605        }
606    }
607}
608
609impl Serialize for ToolCall {
610    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
611        #[derive(Serialize)]
612        struct Stored<'a> {
613            id: &'a CallId,
614            function: &'a ToolFunction,
615            #[serde(skip_serializing_if = "Option::is_none")]
616            native: Option<std::borrow::Cow<'a, Native>>,
617        }
618
619        let native = self.native.as_ref().map(|native| {
620            // Record staleness before parsing can collapse adjacent floats.
621            // The attachment baseline itself is never regenerated on save.
622            if self.native_is_current(native) {
623                std::borrow::Cow::Borrowed(native)
624            } else {
625                let mut stale = native.clone();
626                stale.edited = true;
627                std::borrow::Cow::Owned(stale)
628            }
629        });
630        Stored {
631            id: &self.id,
632            function: &self.function,
633            native,
634        }
635        .serialize(serializer)
636    }
637}
638
639/// A tool function to call: its name and its arguments, always a JSON
640/// object.
641///
642/// Arguments the model sent that are not an object are kept as text in
643/// `invalid_arguments`, with `arguments` holding what could be read of them
644/// (`{}` when nothing could), so a malformed call never fails a reply and
645/// every wire receives an object.
646///
647/// ```
648/// use rig_core::message::{ToolFunction, ToolName};
649///
650/// let name = ToolName::new("search")?;
651/// let call = ToolFunction::parse(name.clone(), r#"{"q": "ab"#);
652/// assert_eq!(call.arguments["q"], "ab");
653/// assert_eq!(call.invalid_arguments.as_deref(), Some(r#"{"q": "ab"#));
654///
655/// let call = ToolFunction::new(name, serde_json::json!("{\"q\":1}"));
656/// assert_eq!(call.arguments["q"], 1);
657/// assert!(call.invalid_arguments.is_none());
658/// # Ok::<(), rig_core::message::EmptyToolName>(())
659/// ```
660#[derive(Clone, Debug, Serialize, PartialEq)]
661pub struct ToolFunction {
662    /// Tool/function name to invoke.
663    pub name: ToolName,
664    /// The arguments.
665    pub arguments: serde_json::Map<String, serde_json::Value>,
666    /// The arguments as the model sent them, when they were not a JSON
667    /// object.
668    #[serde(default, skip_serializing_if = "Option::is_none")]
669    pub invalid_arguments: Option<String>,
670}
671
672impl ToolFunction {
673    /// A call to `name` with `arguments`. An object is kept; a string
674    /// holding an object is unwrapped once; `null` is `{}`; anything else is
675    /// `{}` with its JSON text in `invalid_arguments`.
676    pub fn new(name: ToolName, arguments: serde_json::Value) -> Self {
677        use serde_json::Value;
678        let (arguments, invalid_arguments) = match arguments {
679            Value::Object(arguments) => (arguments, None),
680            Value::Null => (serde_json::Map::new(), None),
681            Value::String(text) => {
682                return Self::parse(name, &text);
683            }
684            other => (serde_json::Map::new(), Some(other.to_string())),
685        };
686        Self {
687            name,
688            arguments,
689            invalid_arguments,
690        }
691    }
692
693    /// A call to `name` with the argument JSON `text`. Blank text is `{}`.
694    /// Text that is not an object keeps what a cut-off object still states,
695    /// or `{}`, and is kept in `invalid_arguments`. A string holding an
696    /// object is unwrapped once.
697    pub fn parse(name: ToolName, text: &str) -> Self {
698        use serde_json::Value;
699        let parsed = crate::json_utils::parse_tool_arguments(text);
700        let (arguments, invalid) = match parsed {
701            Ok(Value::Object(arguments)) => (arguments, false),
702            Ok(Value::Null) => (serde_json::Map::new(), false),
703            Ok(Value::String(inner)) => match serde_json::from_str(&inner) {
704                Ok(Value::Object(arguments)) => (arguments, false),
705                _ => (serde_json::Map::new(), true),
706            },
707            Ok(_) => (serde_json::Map::new(), true),
708            Err(_) => (
709                crate::json_utils::parse_partial_object(text).unwrap_or_default(),
710                true,
711            ),
712        };
713        Self {
714            name,
715            arguments,
716            invalid_arguments: invalid.then(|| text.to_owned()),
717        }
718    }
719
720    /// The arguments as a JSON value.
721    pub fn arguments_value(&self) -> serde_json::Value {
722        serde_json::Value::Object(self.arguments.clone())
723    }
724
725    /// The arguments object as JSON text, as [`Self::arguments_value`]
726    /// prints, without copying it.
727    pub fn arguments_json(&self) -> String {
728        serde_json::to_string(&self.arguments).unwrap_or_default()
729    }
730
731    /// The arguments as JSON text: what the model sent when it was not an
732    /// object, else the object.
733    pub fn raw_arguments(&self) -> String {
734        self.invalid_arguments
735            .clone()
736            .unwrap_or_else(|| self.arguments_json())
737    }
738}
739
740impl<'de> Deserialize<'de> for ToolFunction {
741    /// Arguments stored in any JSON shape are read through
742    /// [`ToolFunction::new`], so a history saved before arguments were
743    /// always objects still loads.
744    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
745        #[derive(Deserialize)]
746        struct Repr {
747            name: ToolName,
748            #[serde(default)]
749            arguments: serde_json::Value,
750            #[serde(default)]
751            invalid_arguments: Option<String>,
752        }
753        let Repr {
754            name,
755            arguments,
756            invalid_arguments,
757        } = Repr::deserialize(deserializer)?;
758        let mut function = Self::new(name, arguments);
759        if invalid_arguments.is_some() {
760            function.invalid_arguments = invalid_arguments;
761        }
762        Ok(function)
763    }
764}
765
766/// Text. On an assistant turn, `native` holds the provider item the block
767/// was decoded from, and [`Text::citations`] what the provider says supports
768/// it; user and tool-result text leave both empty.
769#[non_exhaustive]
770#[derive(Default, Clone, Debug, Deserialize, Serialize, PartialEq)]
771#[serde(from = "TextRepr")]
772pub struct Text {
773    /// Text content.
774    pub text: String,
775    /// The citations and the fingerprint of the text they fit; read through
776    /// [`Text::citations`].
777    #[serde(default, skip_serializing_if = "Option::is_none")]
778    citations: Option<citation::Citations>,
779    /// The provider item this block was decoded from.
780    #[serde(
781        default,
782        skip_serializing_if = "Option::is_none",
783        deserialize_with = "lenient"
784    )]
785    pub native: Option<Native>,
786}
787
788/// A stored field, or `None` when it cannot be read, such as a `native`
789/// fingerprinted by an earlier projection: the item then loads with its
790/// canonical fields and replays from them.
791fn lenient<'de, D: serde::Deserializer<'de>, T: serde::de::DeserializeOwned>(
792    deserializer: D,
793) -> Result<Option<T>, D::Error> {
794    let value = Option::<serde_json::Value>::deserialize(deserializer)?;
795    Ok(value.and_then(|value| crate::json_utils::from_value(&value).ok()))
796}
797
798/// A stored [`Text`], read leniently: unreadable citations or native load
799/// as none.
800#[derive(Deserialize)]
801struct TextRepr {
802    text: String,
803    #[serde(default, deserialize_with = "lenient")]
804    citations: Option<citation::Citations>,
805    #[serde(default, deserialize_with = "lenient")]
806    native: Option<Native>,
807}
808
809impl From<TextRepr> for Text {
810    fn from(repr: TextRepr) -> Self {
811        let TextRepr {
812            text,
813            citations,
814            native,
815        } = repr;
816        Self {
817            text,
818            citations,
819            native,
820        }
821        .checked()
822    }
823}
824
825impl Text {
826    /// Text with no provider item and no citations.
827    pub fn new(text: impl Into<String>) -> Self {
828        Self {
829            text: text.into(),
830            citations: None,
831            native: None,
832        }
833    }
834
835    /// Returns the inner text string.
836    pub fn text(&self) -> &str {
837        &self.text
838    }
839}
840
841impl std::fmt::Display for Text {
842    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
843        let Self { text, .. } = self;
844        write!(f, "{text}")
845    }
846}
847
848/// Image content containing image data and metadata about it. On an
849/// assistant turn, `native` holds the provider item it was decoded from.
850#[derive(Default, Clone, Debug, Deserialize, Serialize, PartialEq)]
851pub struct Image {
852    /// Image source data.
853    pub data: DocumentSourceKind,
854    /// Image media type, if known.
855    #[serde(skip_serializing_if = "Option::is_none")]
856    pub media_type: Option<ImageMediaType>,
857    /// Provider-specific image detail preference.
858    #[serde(skip_serializing_if = "Option::is_none")]
859    pub detail: Option<ImageDetail>,
860    /// The provider item this image was decoded from.
861    #[serde(
862        default,
863        skip_serializing_if = "Option::is_none",
864        deserialize_with = "lenient"
865    )]
866    pub native: Option<Native>,
867}
868
869/// Where a file's bytes are; never the content as text.
870#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Default)]
871#[serde(tag = "type", content = "value", rename_all = "camelCase")]
872pub enum DocumentSourceKind {
873    /// A file URL/URI.
874    Url(String),
875    /// A base-64 encoded string.
876    #[serde(alias = "string")]
877    Base64(String),
878    /// A provider-side uploaded file identifier.
879    FileId(String),
880    /// Raw bytes
881    Raw(Vec<u8>),
882    #[default]
883    /// An unknown file source (there's nothing there).
884    Unknown,
885}
886
887impl DocumentSourceKind {
888    /// Create a URL-backed source.
889    pub fn url(url: impl Into<String>) -> Self {
890        Self::Url(url.into())
891    }
892
893    /// Create a base64-backed source.
894    pub fn base64(base64_string: impl Into<String>) -> Self {
895        Self::Base64(base64_string.into())
896    }
897
898    /// Create a provider file ID-backed source.
899    pub fn file_id(file_id: impl Into<String>) -> Self {
900        Self::FileId(file_id.into())
901    }
902}
903
904impl std::fmt::Display for DocumentSourceKind {
905    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
906        match self {
907            Self::Url(string) => write!(f, "{string}"),
908            Self::Base64(string) => write!(f, "{string}"),
909            Self::FileId(string) => write!(f, "{string}"),
910            Self::Raw(_) => write!(f, "<binary data>"),
911            Self::Unknown => write!(f, "<unknown>"),
912        }
913    }
914}
915
916/// Audio content containing audio data and metadata about it.
917#[derive(Default, Clone, Debug, Deserialize, Serialize, PartialEq)]
918pub struct Audio {
919    /// Audio source data.
920    pub data: DocumentSourceKind,
921    /// Audio media type, if known.
922    #[serde(skip_serializing_if = "Option::is_none")]
923    pub media_type: Option<AudioMediaType>,
924}
925
926/// Video content containing video data and metadata about it.
927#[derive(Default, Clone, Debug, Deserialize, Serialize, PartialEq)]
928pub struct Video {
929    /// Video source data.
930    pub data: DocumentSourceKind,
931    /// Video media type, if known.
932    #[serde(skip_serializing_if = "Option::is_none")]
933    pub media_type: Option<VideoMediaType>,
934    /// Provider-specific video fields, a JSON object (Gemini's
935    /// `video_metadata`).
936    #[serde(default, skip_serializing_if = "Option::is_none")]
937    pub additional_params: Option<serde_json::Value>,
938}
939
940/// A document's content: its own text, or where its file's bytes are.
941#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
942#[serde(tag = "type", content = "value", rename_all = "camelCase")]
943pub enum DocumentData {
944    /// The document's own UTF-8 text; every wire sends it as text.
945    #[serde(alias = "string")]
946    Text(String),
947    /// Where the document's bytes are.
948    #[serde(untagged)]
949    File(DocumentSourceKind),
950}
951
952impl Default for DocumentData {
953    fn default() -> Self {
954        Self::File(DocumentSourceKind::Unknown)
955    }
956}
957
958impl From<DocumentSourceKind> for DocumentData {
959    fn from(source: DocumentSourceKind) -> Self {
960        Self::File(source)
961    }
962}
963
964/// Document content containing document data and metadata about it.
965#[derive(Default, Clone, Debug, Deserialize, Serialize, PartialEq)]
966pub struct DocumentContent {
967    /// Document content.
968    pub data: DocumentData,
969    /// Document media type, if known.
970    #[serde(skip_serializing_if = "Option::is_none")]
971    pub media_type: Option<DocumentMediaType>,
972    /// Provider-specific document fields, a JSON object (Anthropic's
973    /// `title`, `context` and `citations`).
974    #[serde(default, skip_serializing_if = "Option::is_none")]
975    pub additional_params: Option<serde_json::Value>,
976}
977
978/// Describes the image media type of the content. Not every provider supports every media type.
979/// Convertible to and from MIME type strings.
980#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
981#[serde(rename_all = "lowercase")]
982pub enum ImageMediaType {
983    JPEG,
984    PNG,
985    GIF,
986    WEBP,
987    HEIC,
988    HEIF,
989    SVG,
990}
991
992/// Describes the document media type of the content. Not every provider supports every media type.
993/// Includes also programming languages as document types for providers who support code running.
994/// Convertible to and from MIME type strings.
995#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
996#[serde(rename_all = "lowercase")]
997pub enum DocumentMediaType {
998    PDF,
999    TXT,
1000    RTF,
1001    HTML,
1002    CSS,
1003    MARKDOWN,
1004    CSV,
1005    XML,
1006    Javascript,
1007    Python,
1008}
1009
1010impl ImageMediaType {
1011    /// The image type encoded `bytes` start with, by their magic bytes:
1012    /// PNG, JPEG, GIF or WebP, the formats every image-taking provider
1013    /// reads. `None` for anything else.
1014    ///
1015    /// ```
1016    /// use rig_core::message::ImageMediaType;
1017    ///
1018    /// assert_eq!(ImageMediaType::sniff(b"GIF89a..."), Some(ImageMediaType::GIF));
1019    /// assert_eq!(ImageMediaType::sniff(b"plain text"), None);
1020    /// ```
1021    pub fn sniff(bytes: &[u8]) -> Option<Self> {
1022        if bytes.starts_with(b"\x89PNG\r\n\x1a\n") {
1023            Some(Self::PNG)
1024        } else if bytes.starts_with(b"\xff\xd8\xff") {
1025            Some(Self::JPEG)
1026        } else if bytes.starts_with(b"GIF87a") || bytes.starts_with(b"GIF89a") {
1027            Some(Self::GIF)
1028        } else if bytes.starts_with(b"RIFF") && bytes.get(8..12) == Some(b"WEBP".as_slice()) {
1029            Some(Self::WEBP)
1030        } else {
1031            None
1032        }
1033    }
1034
1035    /// The usual file extension of the type, without the dot.
1036    pub fn extension(&self) -> &'static str {
1037        match self {
1038            Self::JPEG => "jpg",
1039            Self::PNG => "png",
1040            Self::GIF => "gif",
1041            Self::WEBP => "webp",
1042            Self::HEIC => "heic",
1043            Self::HEIF => "heif",
1044            Self::SVG => "svg",
1045        }
1046    }
1047}
1048
1049/// Describes the audio media type of the content. Not every provider supports every media type.
1050/// Convertible to and from MIME type strings.
1051#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
1052#[serde(rename_all = "lowercase")]
1053pub enum AudioMediaType {
1054    WAV,
1055    MP3,
1056    AIFF,
1057    AAC,
1058    OGG,
1059    FLAC,
1060    M4A,
1061    PCM16,
1062    PCM24,
1063}
1064
1065/// Describes the video media type of the content. Not every provider supports every media type.
1066/// Convertible to and from MIME type strings.
1067#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
1068#[serde(rename_all = "lowercase")]
1069pub enum VideoMediaType {
1070    AVI,
1071    MP4,
1072    MPEG,
1073    MOV,
1074    WEBM,
1075}
1076
1077/// The resolution a wire that takes one reads an image at. Wires without the
1078/// setting ignore it.
1079#[derive(Default, Clone, Debug, Deserialize, Serialize, PartialEq)]
1080#[serde(rename_all = "lowercase")]
1081pub enum ImageDetail {
1082    Low,
1083    High,
1084    #[default]
1085    Auto,
1086}
1087
1088impl Message {
1089    /// The text of a final answer: the text parts of the model's message,
1090    /// joined by blank lines and trimmed. `None` when this is not the
1091    /// model's message, still asks for tool calls, or has no text.
1092    ///
1093    /// ```
1094    /// use rig_core::message::Message;
1095    ///
1096    /// assert_eq!(Message::assistant(" Done. ").final_answer().as_deref(), Some("Done."));
1097    /// assert_eq!(Message::user("Done.").final_answer(), None);
1098    /// ```
1099    pub fn final_answer(&self) -> Option<String> {
1100        let Message::Assistant(reply) = self else {
1101            return None;
1102        };
1103        let mut parts = Vec::new();
1104        for item in reply.content.iter() {
1105            match item {
1106                AssistantContent::Text(text) => parts.push(text.text.as_str()),
1107                AssistantContent::ToolCall(_) => return None,
1108                _ => {}
1109            }
1110        }
1111        let text = parts.join("\n\n");
1112        let text = text.trim();
1113        (!text.is_empty()).then(|| text.to_owned())
1114    }
1115
1116    /// Clones the first text block of a user message, or returns `None`.
1117    pub fn rag_text(&self) -> Option<String> {
1118        match self {
1119            Message::User { content } => {
1120                for item in content.iter() {
1121                    if let UserContent::Text(Text { text, .. }) = item {
1122                        return Some(text.clone());
1123                    }
1124                }
1125                None
1126            }
1127            Message::System { .. } => None,
1128            _ => None,
1129        }
1130    }
1131
1132    /// Creates a system instruction message.
1133    pub fn system(text: impl Into<String>) -> Self {
1134        Message::System {
1135            content: text.into(),
1136        }
1137    }
1138
1139    /// Creates a user message containing one text block.
1140    pub fn user(text: impl Into<String>) -> Self {
1141        Message::User {
1142            content: vec![UserContent::text(text)],
1143        }
1144    }
1145
1146    /// Creates a hand-built assistant message containing one text block.
1147    pub fn assistant(text: impl Into<String>) -> Self {
1148        Message::Assistant(AssistantMessage::new(vec![AssistantContent::text(text)]))
1149    }
1150
1151    /// Creates a user message containing a text tool result answering the
1152    /// call `call` to the tool `name`. To answer a call you hold, prefer
1153    /// [`ToolCall::result`] with [`Self::tool_results`].
1154    pub fn tool_result(call: CallId, name: ToolName, content: impl Into<String>) -> Self {
1155        Message::User {
1156            content: vec![UserContent::tool_result(
1157                call,
1158                name,
1159                vec![ToolResultContent::text(content)],
1160            )],
1161        }
1162    }
1163
1164    /// Creates a user message carrying `results`, in order.
1165    pub fn tool_results(results: Vec<ToolResult>) -> Self {
1166        Message::User {
1167            content: results.into_iter().map(UserContent::ToolResult).collect(),
1168        }
1169    }
1170
1171    /// The tool results a user message carries, in order; none for other
1172    /// roles.
1173    pub fn results(&self) -> impl Iterator<Item = &ToolResult> {
1174        let content = match self {
1175            Message::User { content } => content.as_slice(),
1176            _ => &[],
1177        };
1178        content.iter().filter_map(UserContent::as_tool_result)
1179    }
1180
1181    /// The images of this message, in order: a user message's own and
1182    /// those of its tool results, or an assistant turn's.
1183    pub fn images(&self) -> impl Iterator<Item = &Image> {
1184        let (user, turn): (&[UserContent], &[AssistantContent]) = match self {
1185            Message::User { content } => (content, &[]),
1186            Message::Assistant(turn) => (&[], &turn.content),
1187            Message::System { .. } => (&[], &[]),
1188        };
1189        let user = user.iter().flat_map(|item| {
1190            let (image, results): (_, &[ToolResultContent]) = match item {
1191                UserContent::Image(image) => (Some(image), &[]),
1192                UserContent::ToolResult(result) => (None, &result.content),
1193                _ => (None, &[]),
1194            };
1195            let results = results.iter().filter_map(|part| match part {
1196                ToolResultContent::Image(image) => Some(image),
1197                _ => None,
1198            });
1199            image.into_iter().chain(results)
1200        });
1201        let turn = turn.iter().filter_map(|block| match block {
1202            AssistantContent::Image(image) => Some(image),
1203            _ => None,
1204        });
1205        user.chain(turn)
1206    }
1207
1208    /// The images of this message, as [`Self::images`], to change in place.
1209    pub fn images_mut(&mut self) -> impl Iterator<Item = &mut Image> {
1210        let (user, turn): (&mut [UserContent], &mut [AssistantContent]) = match self {
1211            Message::User { content } => (content, Default::default()),
1212            Message::Assistant(turn) => (Default::default(), &mut turn.content),
1213            Message::System { .. } => Default::default(),
1214        };
1215        let user = user.iter_mut().flat_map(|item| {
1216            let (image, results): (_, &mut [ToolResultContent]) = match item {
1217                UserContent::Image(image) => (Some(image), Default::default()),
1218                UserContent::ToolResult(result) => (None, &mut result.content),
1219                _ => Default::default(),
1220            };
1221            let results = results.iter_mut().filter_map(|part| match part {
1222                ToolResultContent::Image(image) => Some(image),
1223                _ => None,
1224            });
1225            image.into_iter().chain(results)
1226        });
1227        let turn = turn.iter_mut().filter_map(|block| match block {
1228            AssistantContent::Image(image) => Some(image),
1229            _ => None,
1230        });
1231        user.chain(turn)
1232    }
1233}
1234
1235/// Generates media constructors without fetching or decoding source data.
1236macro_rules! media_ctors {
1237    () => {};
1238    (
1239        $(#[$meta:meta])* $name:ident => Image($kind:ident: $data:ty);
1240        $($rest:tt)*
1241    ) => {
1242        $(#[$meta])*
1243        pub fn $name(
1244            data: impl Into<$data>,
1245            media_type: Option<ImageMediaType>,
1246            detail: Option<ImageDetail>,
1247        ) -> Self {
1248            Self::Image(Image {
1249                data: DocumentSourceKind::$kind(data.into()),
1250                media_type,
1251                detail,
1252                native: None,
1253            })
1254        }
1255        media_ctors! { $($rest)* }
1256    };
1257    (
1258        $(#[$meta:meta])* $name:ident => $variant:ident($content:ident, params $mt:ty, $kind:path: $data:ty);
1259        $($rest:tt)*
1260    ) => {
1261        $(#[$meta])*
1262        pub fn $name(data: impl Into<$data>, media_type: Option<$mt>) -> Self {
1263            Self::$variant($content {
1264                data: $kind(data.into()).into(),
1265                media_type,
1266                additional_params: None,
1267            })
1268        }
1269        media_ctors! { $($rest)* }
1270    };
1271    (
1272        $(#[$meta:meta])* $name:ident => $variant:ident($mt:ty, $kind:ident: $data:ty);
1273        $($rest:tt)*
1274    ) => {
1275        $(#[$meta])*
1276        pub fn $name(data: impl Into<$data>, media_type: Option<$mt>) -> Self {
1277            Self::$variant($variant {
1278                data: DocumentSourceKind::$kind(data.into()),
1279                media_type,
1280            })
1281        }
1282        media_ctors! { $($rest)* }
1283    };
1284}
1285
1286impl UserContent {
1287    /// Borrow the text of a text block.
1288    pub fn as_text(&self) -> Option<&str> {
1289        match self {
1290            Self::Text(text) => Some(&text.text),
1291            _ => None,
1292        }
1293    }
1294
1295    /// Borrow the result of a tool-result block.
1296    pub fn as_tool_result(&self) -> Option<&ToolResult> {
1297        match self {
1298            Self::ToolResult(result) => Some(result),
1299            _ => None,
1300        }
1301    }
1302
1303    /// Creates user text content.
1304    pub fn text(text: impl Into<String>) -> Self {
1305        UserContent::Text(text.into().into())
1306    }
1307
1308    media_ctors! {
1309        /// Creates user image content from base64-encoded data.
1310        image_base64 => Image(Base64: String);
1311        /// Creates user image content from unencoded bytes.
1312        image_raw => Image(Raw: Vec<u8>);
1313        /// Creates user image content referencing a URL.
1314        image_url => Image(Url: String);
1315        /// Creates user audio content from base64-encoded data.
1316        audio_base64 => Audio(AudioMediaType, Base64: String);
1317        /// Creates user audio content from unencoded bytes.
1318        audio_raw => Audio(AudioMediaType, Raw: Vec<u8>);
1319        /// Creates user audio content referencing a URL.
1320        audio_url => Audio(AudioMediaType, Url: String);
1321        /// Creates user video content from base64-encoded data.
1322        video_base64 => Video(Video, params VideoMediaType, DocumentSourceKind::Base64: String);
1323        /// Creates user video content from unencoded bytes.
1324        video_raw => Video(Video, params VideoMediaType, DocumentSourceKind::Raw: Vec<u8>);
1325        /// Creates user video content referencing a URL.
1326        video_url => Video(Video, params VideoMediaType, DocumentSourceKind::Url: String);
1327        /// Creates user document content from base64-encoded data.
1328        document_base64 => Document(DocumentContent, params DocumentMediaType, DocumentSourceKind::Base64: String);
1329        /// Creates user document content from unencoded bytes.
1330        document_raw => Document(DocumentContent, params DocumentMediaType, DocumentSourceKind::Raw: Vec<u8>);
1331        /// Creates user document content referencing a URL.
1332        document_url => Document(DocumentContent, params DocumentMediaType, DocumentSourceKind::Url: String);
1333        /// Creates user document content from literal text, such as a plain
1334        /// text or Markdown file. Binary formats belong in
1335        /// [`Self::document_base64`] or [`Self::document_raw`].
1336        document_text => Document(DocumentContent, params DocumentMediaType, DocumentData::Text: String);
1337    }
1338
1339    /// Creates a tool result answering the call `call` to the tool `name`.
1340    pub fn tool_result(call: CallId, name: ToolName, content: Vec<ToolResultContent>) -> Self {
1341        UserContent::ToolResult(ToolResult {
1342            call,
1343            name,
1344            content,
1345            is_error: false,
1346        })
1347    }
1348}
1349
1350impl AssistantContent {
1351    /// Creates assistant text content.
1352    pub fn text(text: impl Into<String>) -> Self {
1353        AssistantContent::Text(text.into().into())
1354    }
1355
1356    media_ctors! {
1357        /// Creates assistant image content from base64-encoded data.
1358        image_base64 => Image(Base64: String);
1359    }
1360
1361    /// Creates a tool call from a provider-issued ID, name, and arguments.
1362    /// Rig issues an id when `id` is empty.
1363    pub fn tool_call(id: impl Into<String>, name: ToolName, arguments: serde_json::Value) -> Self {
1364        AssistantContent::ToolCall(ToolCall::from_wire(id, ToolFunction::new(name, arguments)))
1365    }
1366
1367    /// Creates reasoning text with no provider item.
1368    pub fn reasoning(reasoning: impl Into<String>) -> Self {
1369        AssistantContent::Reasoning(Reasoning::new(reasoning))
1370    }
1371}
1372
1373impl ToolResultContent {
1374    /// Creates literal text tool-result content.
1375    pub fn text(text: impl Into<String>) -> Self {
1376        ToolResultContent::Text(text.into().into())
1377    }
1378
1379    /// Creates structured JSON tool-result content.
1380    pub fn json(value: serde_json::Value) -> Self {
1381        ToolResultContent::Json { value }
1382    }
1383
1384    media_ctors! {
1385        /// Creates tool-result image content from base64-encoded data.
1386        image_base64 => Image(Base64: String);
1387        /// Creates tool-result image content from raw, unencoded bytes.
1388        image_raw => Image(Raw: Vec<u8>);
1389        /// Creates tool-result image content referencing a URL.
1390        image_url => Image(Url: String);
1391    }
1392}
1393
1394/// Trait for converting between MIME types and media types.
1395pub trait MimeType {
1396    fn from_mime_type(mime_type: &str) -> Option<Self>
1397    where
1398        Self: Sized;
1399    fn to_mime_type(&self) -> &'static str;
1400}
1401
1402// Emits both directions of a [`MimeType`] impl from a single pair list, so a
1403// variant's parse and emit spellings cannot drift apart. Extra `| "alias"`
1404// spellings parse to the same variant; only the first (canonical) string is
1405// emitted by `to_mime_type`.
1406macro_rules! impl_mime_type {
1407    ($ty:ident { $($variant:ident => $canonical:literal $(| $alias:literal)*),+ $(,)? }) => {
1408        impl MimeType for $ty {
1409            fn from_mime_type(mime_type: &str) -> Option<Self> {
1410                match mime_type {
1411                    $($canonical $(| $alias)* => Some($ty::$variant),)+
1412                    _ => None,
1413                }
1414            }
1415
1416            fn to_mime_type(&self) -> &'static str {
1417                match self {
1418                    $($ty::$variant => $canonical,)+
1419                }
1420            }
1421        }
1422    };
1423}
1424
1425impl_mime_type!(ImageMediaType {
1426    JPEG => "image/jpeg",
1427    PNG => "image/png",
1428    GIF => "image/gif",
1429    WEBP => "image/webp",
1430    HEIC => "image/heic",
1431    HEIF => "image/heif",
1432    SVG => "image/svg+xml",
1433});
1434
1435impl_mime_type!(DocumentMediaType {
1436    PDF => "application/pdf",
1437    TXT => "text/plain",
1438    RTF => "text/rtf",
1439    HTML => "text/html",
1440    CSS => "text/css",
1441    MARKDOWN => "text/markdown" | "text/md",
1442    CSV => "text/csv",
1443    XML => "text/xml",
1444    Javascript => "application/x-javascript" | "text/x-javascript",
1445    Python => "application/x-python" | "text/x-python",
1446});
1447
1448impl_mime_type!(AudioMediaType {
1449    WAV => "audio/wav",
1450    MP3 => "audio/mp3",
1451    AIFF => "audio/aiff",
1452    AAC => "audio/aac",
1453    OGG => "audio/ogg",
1454    FLAC => "audio/flac",
1455    M4A => "audio/m4a",
1456    PCM16 => "audio/pcm16",
1457    PCM24 => "audio/pcm24",
1458});
1459
1460impl_mime_type!(VideoMediaType {
1461    AVI => "video/avi",
1462    MP4 => "video/mp4",
1463    MPEG => "video/mpeg",
1464    MOV => "video/mov",
1465    WEBM => "video/webm",
1466});
1467
1468/// `From` impls for [`Text`] from string-like types.
1469macro_rules! text_from {
1470    ($($src:ty),+ $(,)?) => {$(
1471        impl From<$src> for Text {
1472            fn from(text: $src) -> Self {
1473                Text::new(text)
1474            }
1475        }
1476    )+};
1477}
1478
1479text_from!(String, &String, &str);
1480
1481/// `From<String>` impls that forward into a content type's `text` constructor.
1482macro_rules! text_content_from_string {
1483    ($($ty:ident),+ $(,)?) => {$(
1484        impl From<String> for $ty {
1485            fn from(text: String) -> Self {
1486                $ty::text(text)
1487            }
1488        }
1489    )+};
1490}
1491
1492text_content_from_string!(ToolResultContent, AssistantContent, UserContent);
1493
1494/// One-line `From<T> for Message` forwards: convert the value, wrap it in the
1495/// named content variant, and build a single-content message.
1496macro_rules! single_content_message_from {
1497    (User { $($src:ty => $variant:ident),+ $(,)? }) => {$(
1498        impl From<$src> for Message {
1499            fn from(value: $src) -> Self {
1500                Message::User {
1501                    content: vec![UserContent::$variant(value.into())],
1502                }
1503            }
1504        }
1505    )+};
1506    (Assistant { $($src:ty => $variant:ident),+ $(,)? }) => {$(
1507        impl From<$src> for Message {
1508            fn from(value: $src) -> Self {
1509                Message::Assistant(AssistantMessage::new(vec![AssistantContent::$variant(
1510                    value.into(),
1511                )]))
1512            }
1513        }
1514    )+};
1515}
1516
1517single_content_message_from!(User {
1518    String => Text,
1519    &str => Text,
1520    &String => Text,
1521    Text => Text,
1522    Image => Image,
1523    Audio => Audio,
1524    DocumentContent => Document,
1525    ToolResult => ToolResult,
1526});
1527
1528single_content_message_from!(Assistant {
1529    ToolCall => ToolCall,
1530});
1531
1532impl FromStr for Text {
1533    type Err = Infallible;
1534
1535    fn from_str(s: &str) -> Result<Self, Self::Err> {
1536        Ok(s.into())
1537    }
1538}
1539
1540impl From<&Message> for Message {
1541    fn from(msg: &Message) -> Self {
1542        msg.clone()
1543    }
1544}
1545
1546/// A shared message, such as a conversation's, taken out of its `Arc`:
1547/// moved when nothing else holds it, else copied.
1548impl From<std::sync::Arc<Message>> for Message {
1549    fn from(msg: std::sync::Arc<Message>) -> Self {
1550        std::sync::Arc::unwrap_or_clone(msg)
1551    }
1552}
1553
1554impl From<AssistantContent> for Message {
1555    fn from(content: AssistantContent) -> Self {
1556        Message::Assistant(AssistantMessage::new(vec![content]))
1557    }
1558}
1559
1560impl From<AssistantMessage> for Message {
1561    fn from(message: AssistantMessage) -> Self {
1562        Message::Assistant(message)
1563    }
1564}
1565
1566impl From<UserContent> for Message {
1567    fn from(content: UserContent) -> Self {
1568        Message::User {
1569            content: vec![content],
1570        }
1571    }
1572}
1573
1574impl From<Vec<AssistantContent>> for Message {
1575    fn from(content: Vec<AssistantContent>) -> Self {
1576        Message::Assistant(AssistantMessage::new(content))
1577    }
1578}
1579
1580impl From<Vec<UserContent>> for Message {
1581    fn from(content: Vec<UserContent>) -> Self {
1582        Message::User { content }
1583    }
1584}
1585
1586/// Which tools a model may call: any (`Auto`), none, at least one, or only the named ones.
1587#[derive(Default, Clone, Debug, Deserialize, Serialize, PartialEq)]
1588#[serde(rename_all = "snake_case")]
1589pub enum ToolChoice {
1590    /// The model decides.
1591    #[default]
1592    Auto,
1593    /// No tool.
1594    None,
1595    /// At least one tool.
1596    Required,
1597    /// Only these tools.
1598    Specific {
1599        /// The tools' names.
1600        function_names: Vec<ToolName>,
1601    },
1602}
1603
1604#[cfg(test)]
1605mod tests;