1use std::collections::BTreeMap;
11use std::fmt;
12
13use serde::{Deserialize, Serialize};
14use serde_json::{Map, Value};
15
16use crate::format::FormatId;
17
18pub const MAX_IR_TEMPERATURE: f64 = 2.0;
20
21#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize, strum_macros::Display)]
23#[serde(rename_all = "snake_case")]
24#[strum(serialize_all = "snake_case")]
25pub enum Role {
26 System,
28 Developer,
30 User,
32 Assistant,
34 Tool,
36}
37
38#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
40pub struct InstructionBlock {
41 pub role: Role,
43 pub content: Vec<ContentBlock>,
45}
46
47#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
49pub struct Message {
50 pub role: Role,
52 pub content: Vec<ContentBlock>,
54 #[serde(default, skip_serializing_if = "Option::is_none")]
56 pub phase: Option<String>,
57}
58
59impl Message {
60 pub fn new(role: Role, content: Vec<ContentBlock>) -> Self {
62 Self {
63 role,
64 content,
65 phase: None,
66 }
67 }
68
69 pub fn text(role: Role, text: impl Into<String>) -> Self {
71 Self::new(role, vec![ContentBlock::Text { text: text.into() }])
72 }
73
74 pub fn text_content(&self, separator: &str) -> Option<String> {
76 let parts = self
77 .content
78 .iter()
79 .filter_map(|block| match block {
80 ContentBlock::Text { text } => Some(text.as_str()),
81 ContentBlock::Refusal { text } => Some(text.as_str()),
82 _ => None,
83 })
84 .collect::<Vec<_>>();
85 if parts.is_empty() {
86 None
87 } else {
88 Some(parts.join(separator))
89 }
90 }
91}
92
93#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
95#[serde(tag = "type", rename_all = "snake_case")]
96pub enum ContentBlock {
97 Text {
99 text: String,
101 },
102 Reasoning {
104 text: String,
106 signature: Option<String>,
108 #[serde(default, skip_serializing_if = "Vec::is_empty")]
111 details: Vec<Value>,
112 },
113 Image {
115 source: ImageSource,
117 },
118 Audio {
120 source: MediaSource,
122 },
123 Video {
125 source: MediaSource,
127 },
128 File {
130 source: FileSource,
132 },
133 ToolCall(ToolCall),
135 ToolResult(ToolResult),
137 Mcp(McpContent),
139 Refusal {
141 text: String,
143 },
144 Unknown {
146 provider: FormatId,
148 raw: Value,
150 },
151}
152
153#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
155#[serde(tag = "type", content = "data", rename_all = "snake_case")]
156pub enum ImageSource {
157 Url {
159 url: String,
161 detail: Option<String>,
163 },
164 Base64 {
166 media_type: Option<String>,
168 data: String,
170 },
171 Raw(Value),
173}
174
175#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
177#[serde(tag = "type", content = "data", rename_all = "snake_case")]
178pub enum FileSource {
179 FileId(String),
181 FileData {
183 data: String,
185 filename: Option<String>,
187 },
188 Raw(Value),
190}
191
192#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
194#[serde(tag = "type", content = "data", rename_all = "snake_case")]
195pub enum MediaSource {
196 Url {
198 url: String,
200 media_type: Option<String>,
202 },
203 Base64 {
205 media_type: Option<String>,
207 data: String,
209 },
210 Raw(Value),
212}
213
214#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
216pub struct ToolCall {
217 pub id: String,
219 pub name: String,
221 pub arguments: Value,
223}
224
225#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
227pub struct ToolResult {
228 pub tool_call_id: String,
230 pub content: Vec<ContentBlock>,
232 pub is_error: Option<bool>,
234}
235
236#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
238pub struct ToolDefinition {
239 pub name: String,
241 pub description: Option<String>,
243 pub parameters: Value,
245 pub strict: Option<bool>,
247}
248
249#[derive(Clone, PartialEq, Serialize)]
251#[serde(tag = "type", rename_all = "snake_case")]
252pub enum Tool {
253 Mcp(McpToolset),
255 Provider {
257 provider: FormatId,
259 raw: Value,
261 },
262 #[serde(untagged)]
264 Function(ToolDefinition),
265}
266
267impl<'de> Deserialize<'de> for Tool {
268 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
269 where
270 D: serde::Deserializer<'de>,
271 {
272 #[derive(Deserialize)]
274 #[serde(tag = "type", rename_all = "snake_case")]
275 enum TaggedTool {
276 Mcp(McpToolset),
277 Provider { provider: FormatId, raw: Value },
278 Function(ToolDefinition),
279 }
280
281 let value = Value::deserialize(deserializer)?;
282 if value.get("type").is_none() {
285 return serde_json::from_value(value)
286 .map(Self::Function)
287 .map_err(serde::de::Error::custom);
288 }
289 let tool = serde_json::from_value(value).map_err(serde::de::Error::custom)?;
290 Ok(match tool {
291 TaggedTool::Mcp(mcp) => Self::Mcp(mcp),
292 TaggedTool::Provider { provider, raw } => Self::Provider { provider, raw },
293 TaggedTool::Function(function) => Self::Function(function),
294 })
295 }
296}
297
298impl fmt::Debug for Tool {
299 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
300 match self {
301 Self::Function(definition) => f.debug_tuple("Function").field(definition).finish(),
302 Self::Mcp(mcp) => f.debug_tuple("Mcp").field(mcp).finish(),
303 Self::Provider { provider, .. } => f
305 .debug_struct("Provider")
306 .field("provider", provider)
307 .finish_non_exhaustive(),
308 }
309 }
310}
311
312impl From<ToolDefinition> for Tool {
313 fn from(definition: ToolDefinition) -> Self {
314 Self::Function(definition)
315 }
316}
317
318impl Tool {
319 pub fn function(&self) -> Option<&ToolDefinition> {
321 match self {
322 Self::Function(definition) => Some(definition),
323 _ => None,
324 }
325 }
326}
327
328#[derive(Clone, PartialEq, Serialize, Deserialize)]
334pub struct McpToolset {
335 pub name: String,
337 pub url: String,
339 #[serde(default, skip_serializing_if = "Option::is_none")]
341 pub authorization_token: Option<String>,
342 #[serde(default, skip_serializing_if = "McpToolConfig::is_empty")]
344 pub default_config: McpToolConfig,
345 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
348 pub configs: BTreeMap<String, McpToolConfig>,
349 #[serde(default, skip_serializing_if = "Option::is_none")]
353 pub require_approval: Option<bool>,
354}
355
356impl fmt::Debug for McpToolset {
357 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
358 let Self {
359 name,
360 url: _,
361 authorization_token,
362 default_config,
363 configs,
364 require_approval,
365 } = self;
366 f.debug_struct("McpToolset")
367 .field("name", name)
368 .field("url", &"[REDACTED]")
370 .field(
371 "authorization_token",
372 &authorization_token.as_ref().map(|_| "[REDACTED]"),
373 )
374 .field("default_config", default_config)
375 .field("configs", configs)
376 .field("require_approval", require_approval)
377 .finish()
378 }
379}
380
381#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
383pub struct McpToolConfig {
384 #[serde(default, skip_serializing_if = "Option::is_none")]
386 pub enabled: Option<bool>,
387 #[serde(default, skip_serializing_if = "Option::is_none")]
389 pub defer_loading: Option<bool>,
390}
391
392impl McpToolConfig {
393 fn is_empty(&self) -> bool {
394 self.enabled.is_none() && self.defer_loading.is_none()
395 }
396}
397
398#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
400pub struct McpListedTool {
401 pub name: String,
403 #[serde(default, skip_serializing_if = "Option::is_none")]
405 pub description: Option<String>,
406 pub input_schema: Value,
408 #[serde(default, skip_serializing_if = "Option::is_none")]
410 pub annotations: Option<Value>,
411}
412
413#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
415#[serde(tag = "kind", rename_all = "snake_case")]
416pub enum McpContent {
417 Listing {
419 server_name: String,
421 #[serde(default, skip_serializing_if = "Option::is_none")]
423 id: Option<String>,
424 tools: Vec<McpListedTool>,
426 #[serde(default, skip_serializing_if = "Option::is_none")]
428 error: Option<String>,
429 },
430 Call {
432 server_name: String,
434 call: ToolCall,
436 },
437 Result(ToolResult),
439}
440
441#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
443#[serde(tag = "type", content = "data", rename_all = "snake_case")]
444pub enum ToolChoice {
445 Auto,
447 Required,
449 None,
451 Tool {
453 name: String,
455 },
456 Raw(Value),
458}
459
460#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
462pub struct SamplingParams {
463 pub temperature: Option<f64>,
467 pub top_p: Option<f64>,
469 pub top_k: Option<i64>,
471}
472
473#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
475pub struct OutputParams {
476 pub max_output_tokens: Option<u64>,
478 pub response_format: Option<Value>,
480 #[serde(default, skip_serializing_if = "Option::is_none")]
483 pub is_schema_enforced: Option<bool>,
484}
485
486#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
488pub struct ReasoningParams {
489 pub effort: Option<String>,
491 pub raw: Option<Value>,
493}
494
495#[derive(Clone, Default, PartialEq, Serialize, Deserialize)]
497#[serde(default)]
498pub struct ProviderExtensions {
499 pub fields: Map<String, Value>,
504}
505
506impl fmt::Debug for ProviderExtensions {
508 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
509 f.debug_struct("ProviderExtensions")
510 .field("field_count", &self.fields.len())
511 .finish_non_exhaustive()
512 }
513}
514
515#[derive(Clone, Default, PartialEq, Serialize, Deserialize)]
522#[serde(default)]
523pub struct PreservationMetadata {
524 pub requests: BTreeMap<FormatId, Value>,
526 pub responses: BTreeMap<FormatId, Value>,
528}
529
530impl fmt::Debug for PreservationMetadata {
532 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
533 f.debug_struct("PreservationMetadata")
534 .field("request_formats", &self.requests.keys())
535 .field("response_formats", &self.responses.keys())
536 .finish_non_exhaustive()
537 }
538}
539
540#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
542#[serde(default)]
543pub struct LlmRequest {
544 pub model: Option<String>,
549 pub instructions: Vec<InstructionBlock>,
551 pub messages: Vec<Message>,
553 #[serde(skip)]
560 pub temporary_note_count: usize,
561 #[serde(skip_serializing_if = "std::ops::Not::not")]
563 pub is_compaction: bool,
564 #[serde(skip_serializing_if = "std::ops::Not::not")]
566 pub has_compaction: bool,
567 pub tools: Vec<Tool>,
569 pub tool_choice: Option<ToolChoice>,
571 pub sampling: SamplingParams,
573 pub output: OutputParams,
575 pub reasoning: ReasoningParams,
577 pub stream: bool,
579 pub extensions: ProviderExtensions,
581 pub preservation: PreservationMetadata,
585}
586
587#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
589pub struct Usage {
590 #[serde(default, skip_serializing_if = "Option::is_none")]
592 pub provider_cost: Option<f64>,
593 pub input_tokens: Option<u64>,
596 #[serde(flatten)]
598 pub cache: Option<Box<InputCacheUsage>>,
599 pub output_tokens: Option<u64>,
601 pub total_tokens: Option<u64>,
606 pub reasoning_tokens: Option<u64>,
608}
609
610#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
612pub struct InputCacheUsage {
613 #[serde(default, skip_serializing_if = "Option::is_none")]
615 pub cache_creation_1h_input_tokens: Option<u64>,
616 pub cached_input_tokens: Option<u64>,
618 pub cache_creation_input_tokens: Option<u64>,
620}
621
622impl Usage {
623 pub fn cache_details(
625 cached_input_tokens: Option<u64>,
626 cache_creation_input_tokens: Option<u64>,
627 ) -> Option<Box<InputCacheUsage>> {
628 if cached_input_tokens.is_none() && cache_creation_input_tokens.is_none() {
629 return None;
630 }
631 Some(Box::new(InputCacheUsage {
632 cache_creation_1h_input_tokens: None,
633 cached_input_tokens,
634 cache_creation_input_tokens,
635 }))
636 }
637
638 pub fn cached_input_tokens(&self) -> Option<u64> {
640 self.cache
641 .as_ref()
642 .and_then(|cache| cache.cached_input_tokens)
643 }
644
645 pub fn cache_creation_input_tokens(&self) -> Option<u64> {
647 self.cache
648 .as_ref()
649 .and_then(|cache| cache.cache_creation_input_tokens)
650 }
651
652 pub fn set_cached_input_tokens(&mut self, value: u64) {
654 self.cache
655 .get_or_insert_with(|| Box::new(InputCacheUsage::default()))
656 .cached_input_tokens = Some(value);
657 }
658
659 pub fn set_cache_creation_input_tokens(&mut self, value: u64) {
661 self.cache
662 .get_or_insert_with(|| Box::new(InputCacheUsage::default()))
663 .cache_creation_input_tokens = Some(value);
664 }
665}
666
667#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
669#[serde(rename_all = "snake_case")]
670pub enum StopReason {
671 EndTurn,
673 MaxTokens,
675 ToolUse,
677 ContentFilter,
679 Error,
681 Unknown,
683}
684
685#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
687pub struct UrlCitation {
688 pub start_index: usize,
690 pub end_index: usize,
692 pub url: String,
694 pub title: String,
696}
697
698#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
700pub struct ResponseOutput {
701 pub role: Role,
703 pub content: Vec<ContentBlock>,
705 #[serde(default, skip_serializing_if = "Vec::is_empty")]
707 pub url_citations: Vec<UrlCitation>,
708 pub stop_reason: Option<StopReason>,
710}
711
712#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
715#[serde(default)]
716pub struct AggLlmResponse {
717 pub id: Option<String>,
719 pub model: Option<String>,
721 pub outputs: Vec<ResponseOutput>,
723 pub usage: Usage,
725 pub extensions: ProviderExtensions,
727 pub preservation: PreservationMetadata,
729}
730
731impl AggLlmResponse {
732 pub fn first_output(&self) -> Option<&ResponseOutput> {
734 self.outputs.first()
735 }
736}
737
738#[cfg(test)]
739mod tests {
740 use serde_json::json;
741
742 use super::*;
743
744 #[test]
745 fn serde_uses_python_friendly_dictionary_shapes() -> Result<(), serde_json::Error> {
746 let request: LlmRequest = serde_json::from_value(json!({
747 "model": "auto",
748 "messages": [{
749 "role": "user",
750 "content": [{"type": "text", "text": "hello"}]
751 }]
752 }))?;
753 assert_eq!(request.messages[0], Message::text(Role::User, "hello"));
754
755 let tool_call = ContentBlock::ToolCall(ToolCall {
756 id: "call-1".to_string(),
757 name: "lookup".to_string(),
758 arguments: json!({"query": "rust"}),
759 });
760 assert_eq!(
761 serde_json::to_value(tool_call)?,
762 json!({
763 "type": "tool_call",
764 "id": "call-1",
765 "name": "lookup",
766 "arguments": {"query": "rust"}
767 })
768 );
769 Ok(())
770 }
771
772 #[test]
773 fn tool_deserialization_rejects_invalid_tagged_definitions() {
774 for definition in [
775 json!({"type": "mcp", "name": "inv", "parameters": {}}),
776 json!({"type": "provider", "provider": "x", "name": "n", "parameters": {}}),
777 json!({"type": "unknown", "name": "n", "parameters": {}}),
778 json!({"type": null, "name": "n", "parameters": {}}),
779 ] {
780 assert!(serde_json::from_value::<Tool>(definition).is_err());
781 }
782 let error = serde_json::from_value::<Tool>(json!({
783 "type": "mcp", "name": "inv", "url": "https://example.invalid/mcp",
784 "authorization_token": 5, "parameters": {}
785 }))
786 .expect_err("an invalid credential must not become a function")
787 .to_string();
788 assert!(error.contains("string"), "field error was lost: {error}");
789 }
790
791 #[test]
792 fn tool_catalog_preserves_function_json_and_backend_history() -> Result<(), serde_json::Error> {
793 let function = json!({"name": "lookup", "description": null, "parameters": {"type": "object"}, "strict": null});
794 let definitions = json!([
795 function,
796 {"type": "mcp", "name": "inventory", "url": "https://example.invalid/mcp", "require_approval": false},
797 {"type": "provider", "provider": "openai_responses", "raw": {"type": "mcp", "connector_id": "connector_example", "server_label": "example"}},
798 {
799 "type": "mcp", "name": "configured", "url": "https://example.invalid/mcp",
800 "default_config": {"enabled": false, "defer_loading": true},
801 "configs": {"lookup": {"enabled": true}, "search": {"defer_loading": false}}
802 }
803 ]);
804 let tools: Vec<Tool> = serde_json::from_value(definitions.clone())?;
805 assert!(matches!(&tools[0], Tool::Function(_)));
806 assert!(matches!(&tools[1], Tool::Mcp(_)));
807 assert!(matches!(&tools[2], Tool::Provider { .. }));
808 assert_eq!(serde_json::to_value(&tools)?, definitions);
809 let explicit_function: Tool = serde_json::from_value(json!({
810 "type": "function", "name": "lookup", "parameters": {"type": "object"}
811 }))?;
812 assert_eq!(explicit_function, tools[0]);
813
814 let history = json!([
815 {
816 "type": "mcp", "kind": "listing", "server_name": "inventory",
817 "id": "listing_1",
818 "tools": [{
819 "name": "lookup", "description": "Look up stock",
820 "input_schema": {"type": "object"},
821 "annotations": {"readOnlyHint": true}
822 }]
823 },
824 {"type": "mcp", "kind": "listing", "server_name": "empty", "tools": []},
825 {
826 "type": "mcp", "kind": "listing", "server_name": "unavailable",
827 "tools": [], "error": "Server unavailable"
828 },
829 {
830 "type": "mcp", "kind": "call", "server_name": "inventory",
831 "call": {"id": "call_1", "name": "lookup", "arguments": {}}
832 },
833 {
834 "type": "mcp", "kind": "result", "tool_call_id": "call_1",
835 "content": [{"type": "text", "text": "in stock"}], "is_error": false
836 }
837 ]);
838 let content: Vec<ContentBlock> = serde_json::from_value(history.clone())?;
839 assert_eq!(serde_json::to_value(&content)?, history);
840 Ok(())
841 }
842
843 #[test]
844 fn mcp_credentials_are_omitted_from_debug() -> Result<(), serde_json::Error> {
845 let token = "synthetic-mcp-debug-secret";
846 let url_secret = "synthetic-mcp-url-secret";
847 let url = format!("https://example.invalid/mcp?api_key={url_secret}");
848 let mcp: McpToolset = serde_json::from_value(json!({
849 "name": "inventory", "url": url,
850 "authorization_token": token
851 }))?;
852 let raw = json!({"mcp_servers": [{"authorization_token": token}]});
853 let mut request = LlmRequest {
854 tools: vec![
855 Tool::Mcp(mcp.clone()),
856 Tool::Provider {
857 provider: "openai_responses".into(),
858 raw: json!({"type": "mcp", "authorization": token}),
859 },
860 ],
861 ..LlmRequest::default()
862 };
863 request
864 .preservation
865 .requests
866 .insert("anthropic_messages".into(), raw.clone());
867 request.extensions.fields.insert("metadata".into(), raw);
868 let serialized = serde_json::to_value(&request)?;
869 for debug in [
870 format!("{mcp:?}"),
871 format!("{mcp:#?}"),
872 format!("{:?}", request.tools),
873 format!("{:?}", request.extensions),
874 format!("{:?}", request.preservation),
875 format!("{request:?}"),
876 format!("{request:#?}"),
877 ] {
878 assert!(!debug.contains(token), "Debug exposed an MCP credential");
879 assert!(
880 !debug.contains(url_secret),
881 "Debug exposed an MCP URL secret"
882 );
883 }
884 assert_eq!(serde_json::to_value(&request)?, serialized);
885 assert_eq!(serialized["tools"][0]["url"], url);
886 assert_eq!(serialized["tools"][0]["authorization_token"], token);
887 assert_eq!(serialized["tools"][1]["raw"]["authorization"], token);
888 Ok(())
889 }
890}