Skip to main content

rig_core/model/
listing.rs

1//! Provider model metadata and listing interfaces.
2//!
3//! ```
4//! use rig_core::model::{ModelInfo, ModelList};
5//!
6//! let models = ModelList::new(vec![ModelInfo::new("example", "Example model")]);
7//! assert_eq!(models.len(), 1);
8//! ```
9
10use crate::error::ProviderError;
11use serde::{Deserialize, Serialize};
12use std::fmt;
13
14/// Provider-advertised model identifier and optional metadata.
15#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
16pub struct ModelInfo {
17    /// The unique identifier for the model (required)
18    pub id: String,
19
20    /// A human-readable name for the model
21    #[serde(skip_serializing_if = "Option::is_none")]
22    pub name: Option<String>,
23
24    /// A detailed description of the model's capabilities
25    #[serde(skip_serializing_if = "Option::is_none")]
26    pub description: Option<String>,
27
28    /// The type of model (e.g., "chat", "completion", "embedding")
29    #[serde(skip_serializing_if = "Option::is_none")]
30    #[serde(rename = "type")]
31    pub r#type: Option<String>,
32
33    /// Timestamp when the model was created (Unix epoch)
34    #[serde(skip_serializing_if = "Option::is_none")]
35    pub created_at: Option<u64>,
36
37    /// The organization or entity that owns the model
38    #[serde(skip_serializing_if = "Option::is_none")]
39    pub owned_by: Option<String>,
40
41    /// The maximum context window size for the model
42    #[serde(skip_serializing_if = "Option::is_none")]
43    pub context_length: Option<u32>,
44
45    /// Provider-reported output-token ceiling, or `None` when unreported.
46    /// Distinct from context length and not automatically applied to requests.
47    #[serde(skip_serializing_if = "Option::is_none")]
48    pub max_output_tokens: Option<u32>,
49
50    /// Provider-reported tool-call support, or `None` when unreported.
51    #[serde(skip_serializing_if = "Option::is_none")]
52    pub supports_tool_calls: Option<bool>,
53}
54
55impl ModelInfo {
56    /// Creates a model with an ID and display name; other metadata is absent.
57    pub fn new(id: impl Into<String>, name: impl Into<String>) -> Self {
58        Self {
59            name: Some(name.into()),
60            ..Self::from_id(id)
61        }
62    }
63
64    /// Creates a model with an ID and no optional metadata.
65    pub fn from_id(id: impl Into<String>) -> Self {
66        Self {
67            id: id.into(),
68            name: None,
69            description: None,
70            r#type: None,
71            created_at: None,
72            owned_by: None,
73            context_length: None,
74            max_output_tokens: None,
75            supports_tool_calls: None,
76        }
77    }
78
79    /// Returns the name when present, otherwise the ID.
80    pub fn display_name(&self) -> &str {
81        self.name.as_ref().unwrap_or(&self.id)
82    }
83}
84
85impl fmt::Display for ModelInfo {
86    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
87        write!(f, "{}", self.display_name())
88    }
89}
90
91/// Ordered provider model entries. May represent one page or an aggregated listing.
92#[derive(Debug, Clone, Serialize, Deserialize)]
93pub struct ModelList {
94    /// Model entries in returned order.
95    pub data: Vec<ModelInfo>,
96}
97
98impl ModelList {
99    /// Wraps model entries without sorting or deduplicating them.
100    pub fn new(data: Vec<ModelInfo>) -> Self {
101        Self { data }
102    }
103
104    /// Returns whether the list has no entries.
105    pub fn is_empty(&self) -> bool {
106        self.data.is_empty()
107    }
108
109    /// Returns the number of entries.
110    pub fn len(&self) -> usize {
111        self.data.len()
112    }
113
114    /// Borrows entries in list order.
115    pub fn iter(&self) -> std::slice::Iter<'_, ModelInfo> {
116        self.data.iter()
117    }
118}
119
120impl IntoIterator for ModelList {
121    type Item = ModelInfo;
122    type IntoIter = std::vec::IntoIter<ModelInfo>;
123
124    fn into_iter(self) -> Self::IntoIter {
125        self.data.into_iter()
126    }
127}
128
129impl<'a> IntoIterator for &'a ModelList {
130    type Item = &'a ModelInfo;
131    type IntoIter = std::slice::Iter<'a, ModelInfo>;
132
133    fn into_iter(self) -> Self::IntoIter {
134        self.data.iter()
135    }
136}
137
138const RESPONSE_BODY_PREVIEW_LIMIT: usize = 2048;
139
140fn format_response_body_preview(body: &[u8]) -> String {
141    let preview_len = body.len().min(RESPONSE_BODY_PREVIEW_LIMIT);
142    let preview_bytes = body.get(..preview_len).unwrap_or(body);
143    let mut preview = String::from_utf8_lossy(preview_bytes).into_owned();
144
145    if body.len() > RESPONSE_BODY_PREVIEW_LIMIT {
146        preview.push_str(&format!(
147            "\n...<truncated {} bytes>",
148            body.len() - RESPONSE_BODY_PREVIEW_LIMIT
149        ));
150    }
151
152    preview
153}
154
155fn format_response_context(
156    provider: &str,
157    path: &str,
158    details: impl fmt::Display,
159    body: &[u8],
160) -> String {
161    format!(
162        "provider={provider}\npath={path}\n{details}\nbody_bytes={}\nresponse_body_preview:\n{}",
163        body.len(),
164        format_response_body_preview(body)
165    )
166}
167
168/// A listing page that did not parse, with the request context and a bounded
169/// preview of the body.
170pub(crate) fn parse_error(
171    provider: &str,
172    path: &str,
173    details: impl fmt::Display,
174    body: &[u8],
175) -> ProviderError {
176    ProviderError::Response(format_response_context(provider, path, details, body))
177}
178
179/// Adds the provider and request path to a failed listing: a preserved reply
180/// records them as its route, and a decode failure names them in its message.
181pub(crate) fn with_route(error: ProviderError, provider: &str, path: &str) -> ProviderError {
182    match error {
183        ProviderError::ProviderResponse(mut response) => {
184            response.route = Some(format!("provider={provider} path={path}"));
185            ProviderError::ProviderResponse(response)
186        }
187        ProviderError::Json(error) => parse_error(
188            provider,
189            path,
190            format_args!("parse_error"),
191            error.to_string().as_bytes(),
192        ),
193        ProviderError::Response(message) => parse_error(
194            provider,
195            path,
196            format_args!("parse_error"),
197            message.as_bytes(),
198        ),
199        other => other,
200    }
201}
202
203#[cfg(test)]
204mod tests;