Skip to main content

mojentic/llm/tools/
tell_user_tool.rs

1use crate::error::Result;
2use crate::llm::tools::{FunctionDescriptor, LlmTool, ToolDescriptor};
3use async_trait::async_trait;
4use serde_json::{json, Value};
5use std::collections::HashMap;
6
7/// Tool for displaying messages to the user without expecting a response
8///
9/// This tool allows the LLM to send important intermediate information to the user
10/// as it works on completing their request. It's useful for providing status updates,
11/// progress information, or other important messages during long-running operations.
12///
13/// # Examples
14///
15/// ```
16/// use mojentic::llm::tools::tell_user_tool::TellUserTool;
17/// use mojentic::llm::tools::{LlmTool, ToolRunCtx};
18/// use std::collections::HashMap;
19/// use serde_json::json;
20///
21/// # tokio_test::block_on(async {
22/// let tool = TellUserTool;
23/// let mut args = HashMap::new();
24/// args.insert("message".to_string(), json!("Processing your request..."));
25///
26/// let result = tool.run(&args, &ToolRunCtx::default()).await.unwrap();
27/// # });
28/// // Prints to stdout:
29/// //
30/// //
31/// //
32/// // MESSAGE FROM ASSISTANT:
33/// // Processing your request...
34/// //
35/// // Returns: "Message delivered to user."
36/// ```
37#[derive(Clone)]
38pub struct TellUserTool;
39
40impl TellUserTool {
41    /// Creates a new TellUserTool instance
42    pub fn new() -> Self {
43        Self
44    }
45}
46
47impl Default for TellUserTool {
48    fn default() -> Self {
49        Self::new()
50    }
51}
52
53#[async_trait]
54impl LlmTool for TellUserTool {
55    async fn run(
56        &self,
57        args: &HashMap<String, Value>,
58        _ctx: &crate::llm::tools::ToolRunCtx,
59    ) -> Result<Value> {
60        let message = args.get("message").and_then(|v| v.as_str()).unwrap_or("");
61
62        println!("\n\n\nMESSAGE FROM ASSISTANT:\n{}", message);
63
64        Ok(json!("Message delivered to user."))
65    }
66
67    fn descriptor(&self) -> ToolDescriptor {
68        ToolDescriptor {
69            r#type: "function".to_string(),
70            function: FunctionDescriptor {
71                name: "tell_user".to_string(),
72                description: "Display a message to the user without expecting a response. Use this to send important intermediate information to the user as you work on completing their request.".to_string(),
73                parameters: json!({
74                    "type": "object",
75                    "properties": {
76                        "message": {
77                            "type": "string",
78                            "description": "The important message you want to display to the user."
79                        }
80                    },
81                    "required": ["message"]
82                }),
83            },
84        }
85    }
86    fn clone_box(&self) -> Box<dyn LlmTool> {
87        Box::new(self.clone())
88    }
89}
90
91#[cfg(test)]
92mod tests {
93    use super::*;
94
95    #[test]
96    fn test_descriptor() {
97        let tool = TellUserTool::new();
98        let descriptor = tool.descriptor();
99
100        assert_eq!(descriptor.r#type, "function");
101        assert_eq!(descriptor.function.name, "tell_user");
102        assert!(descriptor.function.description.contains("Display a message to the user"));
103
104        // Verify parameters structure
105        let params = &descriptor.function.parameters;
106        assert_eq!(params["type"], "object");
107        assert!(params["properties"]["message"].is_object());
108        assert_eq!(params["properties"]["message"]["type"], "string");
109        assert!(params["required"].as_array().unwrap().contains(&json!("message")));
110    }
111
112    #[tokio::test]
113    async fn test_run_with_message() {
114        let tool = TellUserTool::new();
115        let mut args = HashMap::new();
116        args.insert("message".to_string(), json!("This is an important update"));
117
118        let result = tool.run(&args, &crate::llm::tools::ToolRunCtx::default()).await.unwrap();
119
120        assert_eq!(result, json!("Message delivered to user."));
121    }
122
123    #[tokio::test]
124    async fn test_run_without_message() {
125        let tool = TellUserTool::new();
126        let args = HashMap::new();
127
128        let result = tool.run(&args, &crate::llm::tools::ToolRunCtx::default()).await.unwrap();
129
130        assert_eq!(result, json!("Message delivered to user."));
131    }
132
133    #[test]
134    fn test_tool_matches() {
135        let tool = TellUserTool::new();
136        assert!(tool.matches("tell_user"));
137        assert!(!tool.matches("other_tool"));
138    }
139
140    #[tokio::test]
141    async fn test_multiline_message() {
142        let tool = TellUserTool::new();
143        let mut args = HashMap::new();
144        args.insert("message".to_string(), json!("Line 1\nLine 2\nLine 3"));
145
146        let result = tool.run(&args, &crate::llm::tools::ToolRunCtx::default()).await.unwrap();
147
148        assert_eq!(result, json!("Message delivered to user."));
149    }
150
151    #[test]
152    fn test_default_implementation() {
153        let tool = TellUserTool;
154        let descriptor = tool.descriptor();
155
156        assert_eq!(descriptor.function.name, "tell_user");
157    }
158}