1use std::fmt;
5use std::sync::Arc;
6
7use futures::future::BoxFuture;
8use serde::{Deserialize, Serialize};
9
10use crate::value::Value;
11
12#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
14pub struct ToolSpec {
15 pub name: String,
17 pub description: String,
18 pub parameters: serde_json::Value,
20}
21
22#[derive(Clone, Debug, Default, PartialEq)]
24pub struct ToolOutput {
25 pub text: String,
27 pub data: Value,
29 pub is_error: bool,
31 pub images: Vec<ToolImage>,
33}
34
35impl ToolOutput {
36 pub fn text(text: impl Into<String>) -> Self {
37 Self { text: text.into(), ..Self::default() }
38 }
39
40 pub fn error(text: impl Into<String>) -> Self {
41 Self { text: text.into(), is_error: true, ..Self::default() }
42 }
43
44 pub fn with_image(mut self, image: ToolImage) -> Self {
46 self.images.push(image);
47 self
48 }
49}
50
51pub const MAX_TOOL_IMAGES: usize = 4;
53pub const MAX_TOOL_IMAGE_BYTES: usize = 5 * 1024 * 1024;
55pub const TOOL_IMAGE_MEDIA_TYPES: &[&str] = &["image/png", "image/jpeg", "image/webp", "image/gif"];
57
58#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
63#[serde(untagged)]
64pub enum ToolImage {
65 Base64 { media_type: String, data_base64: String },
67 Url { url: String },
69}
70
71impl ToolImage {
72 pub fn png(data_base64: impl Into<String>) -> Self {
74 Self::Base64 { media_type: "image/png".into(), data_base64: data_base64.into() }
75 }
76
77 pub fn jpeg(data_base64: impl Into<String>) -> Self {
79 Self::Base64 { media_type: "image/jpeg".into(), data_base64: data_base64.into() }
80 }
81
82 pub fn to_url(&self) -> String {
84 match self {
85 ToolImage::Base64 { media_type, data_base64 } => format!("data:{media_type};base64,{data_base64}"),
86 ToolImage::Url { url } => url.clone(),
87 }
88 }
89
90 pub fn check(&self) -> Result<(), ToolImageError> {
92 match self {
93 ToolImage::Url { url } => {
94 if url.len() > 8 && url.get(..8).is_some_and(|scheme| scheme.eq_ignore_ascii_case("https://")) {
95 Ok(())
96 } else {
97 Err(ToolImageError::new("image URLs must start with https:// (send inline images as base64)"))
98 }
99 }
100 ToolImage::Base64 { media_type, data_base64 } => {
101 if !TOOL_IMAGE_MEDIA_TYPES.contains(&media_type.as_str()) {
102 return Err(ToolImageError::new(format!(
103 "image media type `{media_type}` is not supported (use {})",
104 TOOL_IMAGE_MEDIA_TYPES.join(", ")
105 )));
106 }
107 let decoded = base64_decoded_len(data_base64)
108 .ok_or_else(|| ToolImageError::new("image data is not valid base64"))?;
109 if decoded == 0 {
110 return Err(ToolImageError::new("image data is empty"));
111 }
112 if decoded > MAX_TOOL_IMAGE_BYTES {
113 return Err(ToolImageError::new(format!(
114 "image is {decoded} bytes, above the {MAX_TOOL_IMAGE_BYTES}-byte limit"
115 )));
116 }
117 Ok(())
118 }
119 }
120 }
121}
122
123#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
125#[error("{0}")]
126pub struct ToolImageError(pub String);
127
128impl ToolImageError {
129 fn new(message: impl Into<String>) -> Self {
130 Self(message.into())
131 }
132}
133
134pub fn check_images(images: &[ToolImage]) -> Result<(), ToolImageError> {
137 if images.len() > MAX_TOOL_IMAGES {
138 return Err(ToolImageError::new(format!(
139 "{} images in one tool result, above the limit of {MAX_TOOL_IMAGES}",
140 images.len()
141 )));
142 }
143 for (index, image) in images.iter().enumerate() {
144 image.check().map_err(|e| ToolImageError::new(format!("image #{index}: {e}")))?;
145 }
146 Ok(())
147}
148
149fn base64_decoded_len(text: &str) -> Option<usize> {
152 let bytes = text.as_bytes();
153 let body = bytes.strip_suffix(b"==").or_else(|| bytes.strip_suffix(b"=")).unwrap_or(bytes);
154 let alphabet = |b: &u8| b.is_ascii_alphanumeric() || *b == b'+' || *b == b'/';
155 if !body.iter().all(alphabet) {
156 return None;
157 }
158 let padded = body.len() != bytes.len();
159 if padded && bytes.len() % 4 != 0 {
160 return None;
161 }
162 match body.len() % 4 {
163 1 => None,
164 rest => Some(body.len() / 4 * 3 + rest.saturating_sub(1)),
165 }
166}
167
168#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
170#[error("tool `{tool}`: {message}")]
171pub struct ToolError {
172 pub tool: String,
173 pub message: String,
174}
175
176pub trait ToolRuntime: Send + Sync + fmt::Debug {
178 fn list(&self) -> BoxFuture<'_, Result<Vec<ToolSpec>, ToolError>>;
180 fn call<'a>(&'a self, name: &'a str, arguments: serde_json::Value) -> BoxFuture<'a, Result<ToolOutput, ToolError>>;
182}
183
184#[derive(Clone, Default)]
187pub struct ToolRegistry {
188 providers: indexmap::IndexMap<String, Arc<dyn ToolRuntime>>,
189}
190
191impl fmt::Debug for ToolRegistry {
192 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
193 f.debug_list().entries(self.providers.keys()).finish()
194 }
195}
196
197impl ToolRegistry {
198 pub fn new() -> Self {
199 Self::default()
200 }
201
202 pub fn add(&mut self, provider: impl Into<String>, runtime: Arc<dyn ToolRuntime>) -> &mut Self {
203 self.providers.insert(provider.into(), runtime);
204 self
205 }
206
207 pub fn get(&self, provider: &str) -> Option<&Arc<dyn ToolRuntime>> {
208 self.providers.get(provider)
209 }
210
211 pub fn providers(&self) -> impl Iterator<Item = (&str, &Arc<dyn ToolRuntime>)> {
212 self.providers.iter().map(|(k, v)| (k.as_str(), v))
213 }
214}
215
216#[cfg(test)]
217mod tests {
218 use super::*;
219
220 #[test]
221 fn constructors_have_no_images() {
222 assert!(ToolOutput::text("a").images.is_empty());
223 let err = ToolOutput::error("b");
224 assert!(err.is_error && err.images.is_empty());
225 let out = ToolOutput::text("shot").with_image(ToolImage::png("aGVsbG8="));
226 assert_eq!(out.images.len(), 1);
227 }
228
229 #[test]
230 fn image_urls() {
231 assert_eq!(ToolImage::png("AAAA").to_url(), "data:image/png;base64,AAAA");
232 assert_eq!(ToolImage::Url { url: "https://x/a.png".into() }.to_url(), "https://x/a.png");
233 }
234
235 #[test]
236 fn serde_shapes() {
237 let images: Vec<ToolImage> = serde_json::from_value(serde_json::json!([
238 {"media_type": "image/png", "data_base64": "AAAA"},
239 {"url": "https://x/a.png"}
240 ]))
241 .unwrap();
242 assert_eq!(images[0], ToolImage::png("AAAA"));
243 assert_eq!(images[1], ToolImage::Url { url: "https://x/a.png".into() });
244 assert!(serde_json::from_value::<ToolImage>(serde_json::json!({"data": "AAAA"})).is_err());
245 }
246
247 #[test]
248 fn base64_lengths() {
249 assert_eq!(base64_decoded_len("aGVsbG8="), Some(5));
250 assert_eq!(base64_decoded_len("aGVsbG8"), Some(5));
251 assert_eq!(base64_decoded_len("aGVsbA=="), Some(4));
252 assert_eq!(base64_decoded_len("aGVs"), Some(3));
253 assert_eq!(base64_decoded_len("aGVsb"), None);
254 assert_eq!(base64_decoded_len("aGV="), Some(2));
255 assert_eq!(base64_decoded_len("aG V"), None);
256 assert_eq!(base64_decoded_len("aGVsbG8=="), None);
257 assert_eq!(base64_decoded_len(""), Some(0));
258 }
259
260 #[test]
261 fn limits_are_enforced() {
262 assert!(check_images(&[ToolImage::png("aGVsbG8="), ToolImage::jpeg("aGVs")]).is_ok());
263 let too_many = vec![ToolImage::png("aGVs"); MAX_TOOL_IMAGES + 1];
264 assert!(check_images(&too_many).unwrap_err().to_string().contains("limit of 4"));
265 let bmp = ToolImage::Base64 { media_type: "image/bmp".into(), data_base64: "aGVs".into() };
266 assert!(check_images(&[bmp]).unwrap_err().to_string().contains("image/bmp"));
267 assert!(ToolImage::png("not base64!").check().is_err());
268 assert!(ToolImage::png("").check().is_err());
269 let big = "A".repeat((MAX_TOOL_IMAGE_BYTES / 3 + 1) * 4);
270 assert!(ToolImage::png(big).check().unwrap_err().to_string().contains("limit"));
271 let exact = "A".repeat(MAX_TOOL_IMAGE_BYTES / 3 * 4);
272 assert!(ToolImage::png(exact).check().is_ok());
273 assert!(ToolImage::Url { url: "http://x/a.png".into() }.check().is_err());
274 assert!(ToolImage::Url { url: "data:image/png;base64,AAAA".into() }.check().is_err());
275 assert!(ToolImage::Url { url: "HTTPS://x/a.png".into() }.check().is_ok());
276 }
277}