mhome-llm-api 2.0.1

Canonical model messages, completions and continuation contracts
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

use serde::{Deserialize, Serialize};
use serde_json::Value;

pub const COMPLETE_TARGET: &str = "/llm/complete";

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "camelCase")]
pub struct Image {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub base64: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mime_type: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub created_at: Option<i64>,
}

impl Image {
    #[must_use]
    pub fn from_base64(base64: impl Into<String>, mime_type: impl Into<String>) -> Self {
        Self {
            base64: Some(base64.into()),
            mime_type: Some(mime_type.into()),
            ..Self::default()
        }
    }

    #[must_use]
    pub fn from_url(url: impl Into<String>) -> Self {
        Self {
            url: Some(url.into()),
            ..Self::default()
        }
    }

    #[must_use]
    pub fn resolved_mime_type(&self) -> Option<String> {
        let mime_type = self
            .mime_type
            .as_ref()
            .map(|value| value.trim())
            .filter(|value| !value.is_empty())?;
        let normalized = mime_type.to_ascii_lowercase();
        Some(match normalized.as_str() {
            "image/jpg" => "image/jpeg".to_string(),
            _ => normalized,
        })
    }

    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.url
            .as_ref()
            .is_none_or(|value| value.trim().is_empty())
            && self
                .base64
                .as_ref()
                .is_none_or(|value| value.trim().is_empty())
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct LlmGenerationOptions {
    #[serde(default)]
    pub temperature: Option<f32>,
    #[serde(default)]
    pub max_tokens: Option<u32>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct LlmCompleteRequest {
    #[serde(default)]
    pub constraints: crate::ModelConstraints,
    #[serde(default)]
    pub use_case: Option<String>,
    #[serde(default)]
    pub mode: Option<String>,
    pub messages: Vec<crate::Message>,
    #[serde(default)]
    pub tools: Option<Vec<crate::ToolDefinition>>,
    #[serde(default)]
    pub provider: Option<Value>,
    #[serde(default)]
    pub response_format: Option<Value>,
    #[serde(default)]
    pub options: LlmGenerationOptions,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase")]
pub struct LlmRouteInfo {
    pub provider: String,
    pub model: String,
    pub mode: String,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase")]
pub struct LlmCompleteResponse {
    pub message: crate::Message,
    pub finish_reason: crate::FinishReason,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub usage: Option<crate::TokenUsage>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub route: Option<LlmRouteInfo>,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn request_rejects_removed_top_level_generation_options() {
        assert!(
            serde_json::from_value::<LlmCompleteRequest>(serde_json::json!({
                "messages": [],
                "options": {},
                "temperature": 0.2
            }))
            .is_err()
        );
    }

    #[test]
    fn response_includes_normalized_usage() {
        let response = LlmCompleteResponse {
            usage: Some(crate::TokenUsage {
                input_tokens: 2,
                output_tokens: 3,
                ..crate::TokenUsage::default()
            }),
            ..LlmCompleteResponse::default()
        };
        assert_eq!(response.usage.unwrap().total_tokens(), 5);
    }
}