Skip to main content

mojentic/llm/tools/
tool.rs

1use crate::error::Result;
2use async_trait::async_trait;
3use serde_json::Value;
4use std::collections::HashMap;
5use tokio_util::sync::CancellationToken;
6
7/// Descriptor for tool function parameters
8#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
9pub struct ToolDescriptor {
10    pub r#type: String,
11    pub function: FunctionDescriptor,
12}
13
14#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
15pub struct FunctionDescriptor {
16    pub name: String,
17    pub description: String,
18    pub parameters: Value,
19}
20
21/// Context passed to a tool runner (and, optionally, to the tools it runs)
22/// for a single batch.
23///
24/// Carries a [`CancellationToken`] so long-running async tools can opt in to
25/// cooperative cancellation. Tools that ignore the context continue to work
26/// unchanged.
27#[derive(Debug, Clone, Default)]
28pub struct ToolRunCtx {
29    /// Cancellation token signalled when the batch is aborted (e.g. by
30    /// barge-in or a manual `interrupt()`).
31    pub cancel: CancellationToken,
32    /// Optional correlation id propagated to per-tool tracing.
33    pub correlation_id: Option<String>,
34    /// Optional source identifier propagated to per-tool tracing.
35    pub source: Option<String>,
36}
37
38/// Trait for LLM tools.
39///
40/// **2.0 change:** `run` is now async and accepts an optional [`ToolRunCtx`].
41/// Existing tools that previously implemented sync `run(&self, args)` need to
42/// be ported to the new signature. The minimal migration is to wrap the body
43/// in `async {}` and add an unused `_ctx` parameter; see `book/src/migration.md`.
44#[async_trait]
45pub trait LlmTool: Send + Sync {
46    /// Execute the tool with given arguments.
47    async fn run(&self, args: &HashMap<String, Value>, ctx: &ToolRunCtx) -> Result<Value>;
48
49    /// Get tool descriptor for LLM
50    fn descriptor(&self) -> ToolDescriptor;
51
52    /// Check if this tool matches the given name
53    fn matches(&self, name: &str) -> bool {
54        self.descriptor().function.name == name
55    }
56
57    /// Clone the tool into a Box
58    ///
59    /// This method is required to support cloning trait objects.
60    /// Implementations should return `Box::new(self.clone())`.
61    fn clone_box(&self) -> Box<dyn LlmTool>;
62}
63
64#[cfg(test)]
65mod tests {
66    use super::*;
67    use serde_json::json;
68
69    #[test]
70    fn test_tool_descriptor_serialization() {
71        let descriptor = ToolDescriptor {
72            r#type: "function".to_string(),
73            function: FunctionDescriptor {
74                name: "test_tool".to_string(),
75                description: "A test tool".to_string(),
76                parameters: json!({
77                    "type": "object",
78                    "properties": {
79                        "arg1": {"type": "string"}
80                    }
81                }),
82            },
83        };
84
85        let json = serde_json::to_string(&descriptor).unwrap();
86        assert!(json.contains("test_tool"));
87        assert!(json.contains("A test tool"));
88        assert!(json.contains("function"));
89    }
90
91    #[test]
92    fn test_tool_descriptor_deserialization() {
93        let json = r#"{
94            "type": "function",
95            "function": {
96                "name": "calculator",
97                "description": "Perform calculations",
98                "parameters": {
99                    "type": "object",
100                    "properties": {
101                        "expression": {"type": "string"}
102                    }
103                }
104            }
105        }"#;
106
107        let descriptor: ToolDescriptor = serde_json::from_str(json).unwrap();
108        assert_eq!(descriptor.r#type, "function");
109        assert_eq!(descriptor.function.name, "calculator");
110        assert_eq!(descriptor.function.description, "Perform calculations");
111    }
112
113    #[test]
114    fn test_function_descriptor_clone() {
115        let desc1 = FunctionDescriptor {
116            name: "test".to_string(),
117            description: "desc".to_string(),
118            parameters: json!({"type": "object"}),
119        };
120
121        let desc2 = desc1.clone();
122        assert_eq!(desc1.name, desc2.name);
123        assert_eq!(desc1.description, desc2.description);
124    }
125
126    struct MockTool;
127
128    #[async_trait]
129    impl LlmTool for MockTool {
130        async fn run(&self, _args: &HashMap<String, Value>, _ctx: &ToolRunCtx) -> Result<Value> {
131            Ok(json!("result"))
132        }
133
134        fn descriptor(&self) -> ToolDescriptor {
135            ToolDescriptor {
136                r#type: "function".to_string(),
137                function: FunctionDescriptor {
138                    name: "mock_tool".to_string(),
139                    description: "A mock tool".to_string(),
140                    parameters: json!({}),
141                },
142            }
143        }
144
145        fn clone_box(&self) -> Box<dyn LlmTool> {
146            Box::new(MockTool)
147        }
148    }
149
150    #[test]
151    fn test_tool_matches() {
152        let tool = MockTool;
153        assert!(tool.matches("mock_tool"));
154        assert!(!tool.matches("other_tool"));
155    }
156
157    #[tokio::test]
158    async fn test_tool_run() {
159        let tool = MockTool;
160        let args = HashMap::new();
161        let ctx = ToolRunCtx::default();
162        let result = tool.run(&args, &ctx).await.unwrap();
163        assert_eq!(result, json!("result"));
164    }
165}