Skip to main content

rig_agent/test_utils/
tools.rs

1//! Tool helpers for deterministic tests.
2
3use std::sync::{Arc, Mutex};
4
5use serde::{Deserialize, Serialize};
6use serde_json::json;
7
8use rig_core::{
9    message::{ImageMediaType, ToolResultContent},
10    vector_store::{
11        VectorSearchIdResult, VectorSearchRequest, VectorSearchResult, VectorStoreError,
12        VectorStoreIndex, request::Filter,
13    },
14    wasm_compat::WasmCompatSend,
15};
16
17use crate::tool::{Tool, ToolContext, ToolErrorKind, ToolExecutionError, ToolOutput, ToolSet};
18
19/// Shared error type for mock tools.
20#[derive(Debug, thiserror::Error)]
21#[error("Mock tool error")]
22pub struct MockToolError;
23
24/// Arguments for arithmetic mock tools.
25#[derive(Deserialize)]
26pub struct MockOperationArgs {
27    x: i32,
28    y: i32,
29}
30
31/// A mock tool that adds `x` and `y`.
32#[derive(Deserialize, Serialize)]
33pub struct MockAddTool;
34
35impl Tool for MockAddTool {
36    const NAME: &'static str = "add";
37    type Error = MockToolError;
38    type Args = MockOperationArgs;
39    type Output = i32;
40
41    fn description(&self) -> String {
42        "Add x and y together".to_string()
43    }
44
45    fn parameters(&self) -> serde_json::Value {
46        json!({
47            "type": "object",
48            "properties": {
49                "x": {
50                    "type": "number",
51                    "description": "The first number to add"
52                },
53                "y": {
54                    "type": "number",
55                    "description": "The second number to add"
56                }
57            },
58            "required": ["x", "y"],
59        })
60    }
61
62    async fn call(
63        &self,
64        _context: &mut crate::tool::ToolContext,
65        args: Self::Args,
66    ) -> Result<Self::Output, Self::Error> {
67        Ok(args.x + args.y)
68    }
69}
70
71/// A caller-injected context value, like a session id or auth token carried in
72/// a [`ToolContext`](crate::tool::ToolContext).
73#[derive(Clone, serde::Serialize, serde::Deserialize)]
74pub struct SessionId(pub String);
75
76impl rig_core::tool::ContextValue for SessionId {
77    const KEY: &'static str = "test.session_id";
78}
79
80/// A mock tool that records whatever it observed in its per-call
81/// [`ToolContext`], so tests can assert the context reached tool execution.
82///
83/// The single `call` method records `session:<id>` (or `no-session`).
84#[derive(Clone, Default)]
85pub struct MockContextProbeTool {
86    /// One entry per call, in call order — lets tests assert across multiple
87    /// tool-call rounds, not just the most recent.
88    seen: Arc<Mutex<Vec<String>>>,
89}
90
91impl MockContextProbeTool {
92    /// What the tool observed on its most recent call, if it has been called.
93    pub fn observed(&self) -> Option<String> {
94        self.seen
95            .lock()
96            .unwrap_or_else(std::sync::PoisonError::into_inner)
97            .last()
98            .cloned()
99    }
100
101    /// Everything the tool observed, one entry per call in call order.
102    pub fn observations(&self) -> Vec<String> {
103        self.seen
104            .lock()
105            .unwrap_or_else(std::sync::PoisonError::into_inner)
106            .clone()
107    }
108}
109
110impl Tool for MockContextProbeTool {
111    const NAME: &'static str = "context_probe";
112    type Error = rig::tool::ToolExecutionError;
113    type Args = serde_json::Value;
114    type Output = String;
115
116    fn description(&self) -> String {
117        "Records the SessionId observed in its call context".to_string()
118    }
119
120    fn parameters(&self) -> serde_json::Value {
121        json!({"type": "object", "properties": {}})
122    }
123
124    async fn call(
125        &self,
126        context: &mut ToolContext,
127        _args: Self::Args,
128    ) -> Result<Self::Output, ToolExecutionError> {
129        let observed = match context.get::<SessionId>()? {
130            Some(session) => format!("session:{}", session.0),
131            None => "no-session".to_string(),
132        };
133        self.seen
134            .lock()
135            .unwrap_or_else(std::sync::PoisonError::into_inner)
136            .push(observed.clone());
137        Ok(observed)
138    }
139}
140
141/// A mock tool that subtracts `y` from `x`.
142#[derive(Deserialize, Serialize)]
143pub struct MockSubtractTool;
144
145impl Tool for MockSubtractTool {
146    const NAME: &'static str = "subtract";
147    type Error = MockToolError;
148    type Args = MockOperationArgs;
149    type Output = i32;
150
151    fn description(&self) -> String {
152        "Subtract y from x".to_string()
153    }
154
155    fn parameters(&self) -> serde_json::Value {
156        json!({
157            "type": "object",
158            "properties": {
159                "x": {
160                    "type": "number",
161                    "description": "The number to subtract from"
162                },
163                "y": {
164                    "type": "number",
165                    "description": "The number to subtract"
166                }
167            },
168            "required": ["x", "y"],
169        })
170    }
171
172    async fn call(
173        &self,
174        _context: &mut crate::tool::ToolContext,
175        args: Self::Args,
176    ) -> Result<Self::Output, Self::Error> {
177        Ok(args.x - args.y)
178    }
179}
180
181/// Create a [`ToolSet`] containing [`MockAddTool`] and [`MockSubtractTool`].
182pub fn mock_math_toolset() -> ToolSet {
183    let mut toolset = ToolSet::default();
184    toolset.add_tool(MockAddTool);
185    toolset.add_tool(MockSubtractTool);
186    toolset
187}
188
189/// A mock tool named `generate_test_image` that returns a 1x1 red PNG image payload.
190#[derive(Debug, Deserialize, Serialize)]
191pub struct MockImageGeneratorTool;
192
193impl Tool for MockImageGeneratorTool {
194    const NAME: &'static str = "generate_test_image";
195    type Error = MockToolError;
196    type Args = serde_json::Value;
197    type Output = ToolOutput;
198
199    fn description(&self) -> String {
200        "Generates a small test image (a 1x1 red pixel). Call this tool when asked to generate or show an image.".to_string()
201    }
202
203    fn parameters(&self) -> serde_json::Value {
204        json!({
205            "type": "object",
206            "properties": {},
207            "required": []
208        })
209    }
210
211    async fn call(
212        &self,
213        _context: &mut crate::tool::ToolContext,
214        _args: Self::Args,
215    ) -> Result<Self::Output, Self::Error> {
216        Ok(ToolOutput::one(ToolResultContent::image_base64(
217            "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==",
218            Some(ImageMediaType::PNG),
219            None,
220        )))
221    }
222}
223
224/// A mock tool that returns a JSON object.
225#[derive(Deserialize, Serialize)]
226pub struct MockObjectOutputTool;
227
228impl Tool for MockObjectOutputTool {
229    const NAME: &'static str = "object_output";
230    type Error = MockToolError;
231    type Args = serde_json::Value;
232    type Output = serde_json::Value;
233
234    fn description(&self) -> String {
235        "Returns an object".to_string()
236    }
237
238    fn parameters(&self) -> serde_json::Value {
239        json!({
240            "type": "object",
241            "properties": {}
242        })
243    }
244
245    async fn call(
246        &self,
247        _context: &mut crate::tool::ToolContext,
248        _args: Self::Args,
249    ) -> Result<Self::Output, Self::Error> {
250        Ok(json!({
251            "status": "ok",
252            "count": 42
253        }))
254    }
255}
256
257/// A mock tool named `example_tool` that returns `"Example answer"`.
258pub struct MockExampleTool;
259
260impl Tool for MockExampleTool {
261    const NAME: &'static str = "example_tool";
262    type Error = MockToolError;
263    type Args = ();
264    type Output = String;
265
266    fn description(&self) -> String {
267        "A tool that returns some example text.".to_string()
268    }
269
270    fn parameters(&self) -> serde_json::Value {
271        json!({
272            "type": "object",
273            "properties": {},
274            "required": []
275        })
276    }
277
278    async fn call(
279        &self,
280        _context: &mut crate::tool::ToolContext,
281        _input: Self::Args,
282    ) -> Result<Self::Output, Self::Error> {
283        Ok("Example answer".to_string())
284    }
285}
286
287/// A vector index that returns a predefined list of tool IDs from `top_n_ids`.
288pub struct MockToolIndex {
289    tool_ids: Vec<String>,
290}
291
292impl MockToolIndex {
293    /// Create a tool index that returns the given IDs in order.
294    pub fn new(tool_ids: impl IntoIterator<Item = impl Into<String>>) -> Self {
295        Self {
296            tool_ids: tool_ids.into_iter().map(Into::into).collect(),
297        }
298    }
299}
300
301impl VectorStoreIndex for MockToolIndex {
302    type Filter = Filter<serde_json::Value>;
303
304    async fn top_n<T: for<'a> Deserialize<'a> + WasmCompatSend>(
305        &self,
306        _req: VectorSearchRequest,
307    ) -> Result<Vec<VectorSearchResult<T>>, VectorStoreError> {
308        Ok(vec![])
309    }
310
311    async fn top_n_ids(
312        &self,
313        _req: VectorSearchRequest,
314    ) -> Result<Vec<VectorSearchIdResult>, VectorStoreError> {
315        Ok(self
316            .tool_ids
317            .iter()
318            .enumerate()
319            .map(|(i, id)| VectorSearchIdResult {
320                score: 1.0 - (i as f64 * 0.1),
321                id: id.clone(),
322            })
323            .collect())
324    }
325}
326
327/// Error type for [`MockFailingTool`], carrying a fixed message.
328#[derive(Debug, thiserror::Error)]
329#[error("mock tool call failed")]
330pub struct MockFailure;
331
332/// A tool that always fails with a configured [`ToolErrorKind`]. Used to exercise structured
333/// tool-failure surfacing (timeout, not-found, rate-limited, …) without a live
334/// provider. Registered under the name `flaky_tool`.
335#[derive(Clone)]
336pub struct MockFailingTool {
337    kind: ToolErrorKind,
338}
339
340impl MockFailingTool {
341    /// A tool that fails with the given classification every call.
342    pub fn new(kind: ToolErrorKind) -> Self {
343        Self { kind }
344    }
345}
346
347impl Tool for MockFailingTool {
348    const NAME: &'static str = "flaky_tool";
349    type Error = MockFailure;
350    type Args = serde_json::Value;
351    type Output = String;
352
353    fn description(&self) -> String {
354        "A tool that always fails".to_string()
355    }
356
357    fn parameters(&self) -> serde_json::Value {
358        json!({ "type": "object", "properties": {} })
359    }
360
361    async fn call(
362        &self,
363        _context: &mut ToolContext,
364        _args: Self::Args,
365    ) -> Result<Self::Output, Self::Error> {
366        Err(MockFailure)
367    }
368
369    fn map_error(&self, error: Self::Error) -> ToolExecutionError {
370        let error = ToolExecutionError::new(self.kind, error.to_string()).with_source(error);
371        match self.kind {
372            ToolErrorKind::NotFound => error.with_http_status(404),
373            ToolErrorKind::RateLimited => error.with_http_status(429),
374            _ => error,
375        }
376    }
377}
378
379/// A tool failure with separate operator and model-visible feedback.
380#[derive(Clone)]
381pub struct MockHandledFailureTool;
382
383impl Tool for MockHandledFailureTool {
384    const NAME: &'static str = "lookup";
385    type Error = MockToolError;
386    type Args = serde_json::Value;
387    type Output = String;
388
389    fn description(&self) -> String {
390        "Looks up a record".to_string()
391    }
392
393    fn parameters(&self) -> serde_json::Value {
394        json!({ "type": "object", "properties": {} })
395    }
396
397    async fn call(
398        &self,
399        _context: &mut ToolContext,
400        _args: Self::Args,
401    ) -> Result<Self::Output, Self::Error> {
402        Err(MockToolError)
403    }
404
405    fn map_error(&self, error: Self::Error) -> ToolExecutionError {
406        ToolExecutionError::not_found("record id 42 is missing")
407            .with_http_status(404)
408            .with_model_feedback("no record found for id 42; try a different id")
409            .with_source(error)
410    }
411}
412
413/// A tool that refuses execution, distinct from a framework policy skip.
414#[derive(Clone)]
415pub struct MockDeniedTool;
416
417impl Tool for MockDeniedTool {
418    const NAME: &'static str = "guarded";
419    type Error = MockToolError;
420    type Args = serde_json::Value;
421    type Output = String;
422
423    fn description(&self) -> String {
424        "A tool with an internal authorization check".to_string()
425    }
426
427    fn parameters(&self) -> serde_json::Value {
428        json!({ "type": "object", "properties": {} })
429    }
430
431    async fn call(
432        &self,
433        _context: &mut ToolContext,
434        _args: Self::Args,
435    ) -> Result<Self::Output, Self::Error> {
436        Err(MockToolError)
437    }
438
439    fn map_error(&self, error: Self::Error) -> ToolExecutionError {
440        ToolExecutionError::refused("operator authorization policy rejected the request")
441            .with_model_feedback("access to this resource is not permitted")
442            .with_source(error)
443    }
444}
445
446/// Cloneable metadata a [`MockMetadataTool`] attaches to its result, used to
447/// verify that result metadata reaches hooks without being sent to the model.
448#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
449pub struct MockRequestId(pub String);
450
451impl rig_core::tool::ContextValue for MockRequestId {
452    const KEY: &'static str = "test.mock_request_id";
453}
454
455/// A tool whose success carries a [`MockRequestId`] in its result metadata.
456/// Registered under the name `with_meta`.
457#[derive(Clone)]
458pub struct MockMetadataTool;
459
460impl Tool for MockMetadataTool {
461    const NAME: &'static str = "with_meta";
462    type Error = MockToolError;
463    type Args = serde_json::Value;
464    type Output = String;
465
466    fn description(&self) -> String {
467        "Succeeds and attaches request metadata".to_string()
468    }
469
470    fn parameters(&self) -> serde_json::Value {
471        json!({ "type": "object", "properties": {} })
472    }
473
474    async fn call(
475        &self,
476        context: &mut ToolContext,
477        _args: Self::Args,
478    ) -> Result<Self::Output, Self::Error> {
479        context
480            .insert_result(MockRequestId("req-7".to_string()))
481            .map_err(|_| MockToolError)?;
482        Ok("done".to_string())
483    }
484}