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

//! Pure invocation policy shared by deployments. No discovery or provider routing.
use crate::ModelConstraints;
use serde::{Deserialize, Serialize};

/// Confirmed model capabilities. Missing information never establishes support.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct ModelCapabilities {
    pub vision: bool,
    pub tool_calling: bool,
    pub structured_output: bool,
}

impl ModelConstraints {
    /// Checks declarations only, including requirements on requests with no images/tools.
    pub fn validate(&self, capabilities: &ModelCapabilities) -> Result<(), &'static str> {
        for (required, supported, name) in [
            (self.vision, capabilities.vision, "vision"),
            (self.tool_calling, capabilities.tool_calling, "tool_calling"),
            (
                self.structured_output,
                capabilities.structured_output,
                "structured_output",
            ),
        ] {
            if required && !supported {
                return Err(name);
            }
        }
        Ok(())
    }
}

/// Deployment-owned generation settings, never supplied through Agent constraints.
/// None leaves the setting unspecified. These are desired preferences: adapters may omit
/// unsupported settings. Syntax validation does not establish model/provider support.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct GenerationParameters {
    pub reasoning_effort: Option<String>,
    pub temperature: Option<f64>,
}

impl GenerationParameters {
    pub fn validate(&self) -> Result<(), &'static str> {
        if let Some(effort) = self.reasoning_effort.as_deref() {
            if !matches!(
                effort,
                "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra"
            ) {
                return Err("invalid reasoning_effort");
            }
        }
        if self
            .temperature
            .is_some_and(|value| !value.is_finite() || value < 0.0)
        {
            return Err("temperature must be finite and nonnegative");
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn declarations_are_requirements_not_prohibitions() {
        let supported = ModelCapabilities {
            vision: true,
            tool_calling: true,
            structured_output: true,
        };
        assert!(ModelConstraints::default().validate(&supported).is_ok());
        assert!(ModelConstraints::default()
            .validate(&ModelCapabilities::default())
            .is_ok());
        for constraints in [
            ModelConstraints {
                vision: true,
                ..Default::default()
            },
            ModelConstraints {
                tool_calling: true,
                ..Default::default()
            },
            ModelConstraints {
                structured_output: true,
                ..Default::default()
            },
        ] {
            assert!(constraints.validate(&supported).is_ok());
            assert!(constraints.validate(&ModelCapabilities::default()).is_err());
        }
    }
    #[test]
    fn retired_generation_control_is_not_silently_ignored() {
        assert!(serde_json::from_value::<ModelConstraints>(serde_json::json!({
            "vision": false, "tool_calling": false, "structured_output": false, "reasoning": "high"
        })).is_err());
    }
    #[test]
    fn validates_explicit_generation_settings() {
        for effort in ["none", "low", "high", "max", "ultra"] {
            assert!(GenerationParameters {
                reasoning_effort: Some(effort.into()),
                temperature: None
            }
            .validate()
            .is_ok());
        }
        assert!(GenerationParameters {
            reasoning_effort: Some("unknown".into()),
            temperature: None
        }
        .validate()
        .is_err());
        for temperature in [-1.0, f64::NAN, f64::INFINITY] {
            assert!(GenerationParameters {
                temperature: Some(temperature),
                ..Default::default()
            }
            .validate()
            .is_err());
        }
    }
}