Skip to main content

mojentic/llm/
models.rs

1use serde::{Deserialize, Serialize};
2use std::collections::HashMap;
3
4/// Message role in LLM conversation
5#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
6#[serde(rename_all = "lowercase")]
7pub enum MessageRole {
8    System,
9    User,
10    Assistant,
11    Tool,
12}
13
14/// Tool call from LLM
15#[derive(Debug, Clone, Serialize, Deserialize)]
16pub struct LlmToolCall {
17    #[serde(skip_serializing_if = "Option::is_none")]
18    pub id: Option<String>,
19    pub name: String,
20    pub arguments: HashMap<String, serde_json::Value>,
21}
22
23/// Message in LLM conversation
24#[derive(Debug, Clone, Serialize, Deserialize)]
25pub struct LlmMessage {
26    #[serde(default = "default_role")]
27    pub role: MessageRole,
28    #[serde(skip_serializing_if = "Option::is_none")]
29    pub content: Option<String>,
30    #[serde(skip_serializing_if = "Option::is_none")]
31    pub tool_calls: Option<Vec<LlmToolCall>>,
32    #[serde(skip_serializing_if = "Option::is_none")]
33    pub image_paths: Option<Vec<String>>,
34    /// Native assistant reasoning, separate from visible content. Never inline as user text.
35    #[serde(default, alias = "thinking", skip_serializing_if = "Option::is_none")]
36    pub reasoning_content: Option<String>,
37}
38
39fn default_role() -> MessageRole {
40    MessageRole::User
41}
42
43/// Provider completion evidence and client stream timing for one response.
44///
45/// Every field is optional. A gateway fills what its provider reports and
46/// leaves the rest unknown: usage is never estimated from text length or a
47/// tokenizer, and `provider_model` is never copied from the configured model.
48#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
49#[serde(default)]
50pub struct ResponseEvidence {
51    /// Token usage in the provider's own shape, unchanged.
52    pub usage: Option<serde_json::Value>,
53    /// Model name the provider reported, which can differ from the requested model.
54    pub provider_model: Option<String>,
55    /// Provider finish reason (OpenAI `finish_reason`, Ollama `done_reason`).
56    pub finish_reason: Option<String>,
57    /// Other response facts: provider ids/durations and client stream timing fields.
58    pub metadata: HashMap<String, serde_json::Value>,
59}
60
61/// Response from LLM gateway
62#[derive(Debug, Clone, Default)]
63pub struct LlmGatewayResponse<T = ()> {
64    pub content: Option<String>,
65    pub object: Option<T>,
66    pub tool_calls: Vec<LlmToolCall>,
67    pub thinking: Option<String>,
68    /// What the provider reported about how this response finished.
69    pub evidence: ResponseEvidence,
70}
71
72impl LlmMessage {
73    /// Create a user message
74    pub fn user(content: impl Into<String>) -> Self {
75        Self {
76            role: MessageRole::User,
77            content: Some(content.into()),
78            tool_calls: None,
79            image_paths: None,
80            reasoning_content: None,
81        }
82    }
83
84    /// Create a system message
85    pub fn system(content: impl Into<String>) -> Self {
86        Self {
87            role: MessageRole::System,
88            content: Some(content.into()),
89            tool_calls: None,
90            image_paths: None,
91            reasoning_content: None,
92        }
93    }
94
95    /// Create an assistant message
96    pub fn assistant(content: impl Into<String>) -> Self {
97        Self {
98            role: MessageRole::Assistant,
99            content: Some(content.into()),
100            tool_calls: None,
101            image_paths: None,
102            reasoning_content: None,
103        }
104    }
105
106    /// Attach native reasoning to an assistant message for supported gateways.
107    pub fn with_reasoning(mut self, reasoning: impl Into<String>) -> Self {
108        self.reasoning_content = Some(reasoning.into());
109        self
110    }
111
112    /// Add image paths to this message
113    pub fn with_images(mut self, paths: Vec<String>) -> Self {
114        self.image_paths = Some(paths);
115        self
116    }
117}
118
119#[cfg(test)]
120mod tests {
121    use super::*;
122
123    #[test]
124    fn test_message_role_serialization() {
125        assert_eq!(serde_json::to_string(&MessageRole::System).unwrap(), "\"system\"");
126        assert_eq!(serde_json::to_string(&MessageRole::User).unwrap(), "\"user\"");
127        assert_eq!(serde_json::to_string(&MessageRole::Assistant).unwrap(), "\"assistant\"");
128        assert_eq!(serde_json::to_string(&MessageRole::Tool).unwrap(), "\"tool\"");
129    }
130
131    #[test]
132    fn test_message_role_deserialization() {
133        assert_eq!(serde_json::from_str::<MessageRole>("\"system\"").unwrap(), MessageRole::System);
134        assert_eq!(serde_json::from_str::<MessageRole>("\"user\"").unwrap(), MessageRole::User);
135        assert_eq!(
136            serde_json::from_str::<MessageRole>("\"assistant\"").unwrap(),
137            MessageRole::Assistant
138        );
139        assert_eq!(serde_json::from_str::<MessageRole>("\"tool\"").unwrap(), MessageRole::Tool);
140    }
141
142    #[test]
143    fn test_user_message() {
144        let msg = LlmMessage::user("Hello");
145        assert_eq!(msg.role, MessageRole::User);
146        assert_eq!(msg.content, Some("Hello".to_string()));
147        assert!(msg.tool_calls.is_none());
148        assert!(msg.image_paths.is_none());
149    }
150
151    #[test]
152    fn test_system_message() {
153        let msg = LlmMessage::system("You are a helpful assistant");
154        assert_eq!(msg.role, MessageRole::System);
155        assert_eq!(msg.content, Some("You are a helpful assistant".to_string()));
156        assert!(msg.tool_calls.is_none());
157        assert!(msg.image_paths.is_none());
158    }
159
160    #[test]
161    fn test_assistant_message() {
162        let msg = LlmMessage::assistant("I can help with that");
163        assert_eq!(msg.role, MessageRole::Assistant);
164        assert_eq!(msg.content, Some("I can help with that".to_string()));
165        assert!(msg.tool_calls.is_none());
166        assert!(msg.image_paths.is_none());
167    }
168
169    #[test]
170    fn test_message_with_images() {
171        let msg = LlmMessage::user("Describe this image")
172            .with_images(vec!["/path/to/image.jpg".to_string()]);
173        assert_eq!(msg.role, MessageRole::User);
174        assert_eq!(msg.content, Some("Describe this image".to_string()));
175        assert_eq!(msg.image_paths, Some(vec!["/path/to/image.jpg".to_string()]));
176    }
177
178    #[test]
179    fn test_llm_tool_call_serialization() {
180        let mut args = HashMap::new();
181        args.insert("key".to_string(), serde_json::json!("value"));
182
183        let tool_call = LlmToolCall {
184            id: Some("call_123".to_string()),
185            name: "test_tool".to_string(),
186            arguments: args,
187        };
188
189        let json = serde_json::to_string(&tool_call).unwrap();
190        assert!(json.contains("test_tool"));
191        assert!(json.contains("call_123"));
192    }
193
194    #[test]
195    fn test_llm_tool_call_without_id() {
196        let tool_call = LlmToolCall {
197            id: None,
198            name: "test_tool".to_string(),
199            arguments: HashMap::new(),
200        };
201
202        let json = serde_json::to_string(&tool_call).unwrap();
203        // id should be omitted when None
204        assert!(!json.contains("\"id\""));
205        assert!(json.contains("test_tool"));
206    }
207
208    #[test]
209    fn test_llm_message_serialization() {
210        let msg = LlmMessage::user("test content");
211        let json = serde_json::to_string(&msg).unwrap();
212
213        assert!(json.contains("\"role\":\"user\""));
214        assert!(json.contains("\"content\":\"test content\""));
215    }
216
217    #[test]
218    fn test_llm_message_deserialization() {
219        let json = r#"{"role":"assistant","content":"response"}"#;
220        let msg: LlmMessage = serde_json::from_str(json).unwrap();
221
222        assert_eq!(msg.role, MessageRole::Assistant);
223        assert_eq!(msg.content, Some("response".to_string()));
224    }
225
226    #[test]
227    fn test_llm_message_default_role() {
228        let json = r#"{"content":"test"}"#;
229        let msg: LlmMessage = serde_json::from_str(json).unwrap();
230
231        // Should default to User role
232        assert_eq!(msg.role, MessageRole::User);
233    }
234}