runifold_model/
capability.rs

1use std::collections::BTreeMap;
2
3use serde::{Deserialize, Serialize};
4use serde_json::Value;
5
6use crate::{
7    ContentPart, FeaturePolicy, ModelError, ModelErrorKind, ModelRequest, ModelWarning,
8    OutputFormat, SupportLevel::Emulated, SupportLevel::Native, SupportLevel::Unknown,
9    SupportLevel::Unsupported, ToolChoice,
10};
11
12/// How a model or adapter supports a feature.
13#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
14#[serde(rename_all = "snake_case")]
15#[non_exhaustive]
16pub enum SupportLevel {
17    /// The provider implements the feature directly.
18    Native,
19    /// The adapter can approximate the feature with visible degradation.
20    Emulated,
21    /// The feature is known to be unsupported.
22    Unsupported,
23    /// Support is not known reliably.
24    Unknown,
25}
26
27/// Support level plus machine-readable constraints.
28#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
29pub struct FeatureSupport {
30    /// Support level.
31    pub level: SupportLevel,
32    /// Provider- or model-specific constraints.
33    pub constraints: BTreeMap<String, Value>,
34}
35
36impl FeatureSupport {
37    /// Creates feature support without constraints.
38    pub fn new(level: SupportLevel) -> Self {
39        Self {
40            level,
41            constraints: BTreeMap::new(),
42        }
43    }
44}
45
46/// Capabilities of a specific model endpoint.
47#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
48pub struct ModelCapabilities {
49    /// Streaming output.
50    pub streaming: FeatureSupport,
51    /// Tool calling.
52    pub tools: FeatureSupport,
53    /// Parallel tool calls.
54    pub parallel_tools: FeatureSupport,
55    /// Native structured output.
56    pub structured_output: FeatureSupport,
57    /// Reasoning or thinking round trips.
58    pub reasoning: FeatureSupport,
59    /// Image input.
60    pub image_input: FeatureSupport,
61    /// Audio input.
62    pub audio_input: FeatureSupport,
63    /// Document input.
64    pub document_input: FeatureSupport,
65    /// Known context-window limit.
66    pub max_context_tokens: Option<u64>,
67    /// Namespaced additional capabilities.
68    pub extensions: BTreeMap<String, FeatureSupport>,
69}
70
71impl Default for ModelCapabilities {
72    fn default() -> Self {
73        let unknown = || FeatureSupport::new(SupportLevel::Unknown);
74        Self {
75            streaming: unknown(),
76            tools: unknown(),
77            parallel_tools: unknown(),
78            structured_output: unknown(),
79            reasoning: unknown(),
80            image_input: unknown(),
81            audio_input: unknown(),
82            document_input: unknown(),
83            max_context_tokens: None,
84            extensions: BTreeMap::new(),
85        }
86    }
87}
88
89impl ModelCapabilities {
90    /// Validates the features required by a request and returns visible
91    /// compatibility warnings.
92    ///
93    /// Unsupported features always fail because generic middleware cannot
94    /// invent a safe degradation. Unknown support is accepted only under
95    /// [`FeaturePolicy::BestEffort`]. Emulation is accepted by
96    /// [`FeaturePolicy::AllowEmulation`] and [`FeaturePolicy::BestEffort`].
97    ///
98    /// # Errors
99    ///
100    /// Returns [`ModelErrorKind::UnsupportedFeature`] when the request's
101    /// feature policy cannot accept a required capability.
102    pub fn validate_request(
103        &self,
104        request: &ModelRequest,
105        streaming: bool,
106    ) -> Result<Vec<ModelWarning>, ModelError> {
107        let mut required = Vec::new();
108        if streaming {
109            required.push(("streaming", &self.streaming));
110        }
111        let requires_tools = !request.tools.is_empty()
112            || matches!(
113                request.tool_choice,
114                ToolChoice::Required | ToolChoice::Named { .. }
115            );
116        if requires_tools {
117            required.push(("tools", &self.tools));
118        }
119        if !matches!(request.output_format, OutputFormat::Text) {
120            required.push(("structured_output", &self.structured_output));
121        }
122        for message in &request.messages {
123            for part in &message.content {
124                match part {
125                    ContentPart::Image { .. } => required.push(("image_input", &self.image_input)),
126                    ContentPart::Audio { .. } => required.push(("audio_input", &self.audio_input)),
127                    ContentPart::Document { .. } => {
128                        required.push(("document_input", &self.document_input));
129                    }
130                    ContentPart::Reasoning(_) => required.push(("reasoning", &self.reasoning)),
131                    _ => {}
132                }
133            }
134        }
135
136        required.sort_by_key(|(name, _)| *name);
137        required.dedup_by_key(|(name, _)| *name);
138        let mut warnings = Vec::new();
139        for (name, support) in required {
140            assess_feature(name, support, request.feature_policy, &mut warnings)?;
141        }
142        Ok(warnings)
143    }
144}
145
146fn assess_feature(
147    name: &str,
148    support: &FeatureSupport,
149    policy: FeaturePolicy,
150    warnings: &mut Vec<ModelWarning>,
151) -> Result<(), ModelError> {
152    match (support.level, policy) {
153        (Native, _) => Ok(()),
154        (Emulated, FeaturePolicy::AllowEmulation | FeaturePolicy::BestEffort) => {
155            warnings.push(compatibility_warning(
156                "runifold.feature_emulated",
157                name,
158                support,
159            ));
160            Ok(())
161        }
162        (Unknown, FeaturePolicy::BestEffort) => {
163            warnings.push(compatibility_warning(
164                "runifold.feature_support_unknown",
165                name,
166                support,
167            ));
168            Ok(())
169        }
170        (Unsupported, _) => Err(unsupported_error(name, "unsupported", support)),
171        (Emulated, FeaturePolicy::Strict) => Err(unsupported_error(name, "emulated", support)),
172        (Unknown, FeaturePolicy::Strict | FeaturePolicy::AllowEmulation) => {
173            Err(unsupported_error(name, "unknown", support))
174        }
175    }
176}
177
178fn compatibility_warning(code: &str, name: &str, support: &FeatureSupport) -> ModelWarning {
179    let mut metadata = support.constraints.clone();
180    metadata.insert("feature".into(), Value::String(name.into()));
181    ModelWarning {
182        code: code.into(),
183        message: format!("feature `{name}` is not natively supported"),
184        metadata,
185    }
186}
187
188fn unsupported_error(name: &str, level: &str, support: &FeatureSupport) -> ModelError {
189    let mut error = ModelError::local(
190        ModelErrorKind::UnsupportedFeature,
191        format!("required feature `{name}` has support level `{level}`"),
192    );
193    error
194        .metadata
195        .insert("feature".into(), Value::String(name.into()));
196    error.metadata.insert(
197        "constraints".into(),
198        Value::Object(support.constraints.clone().into_iter().collect()),
199    );
200    error
201}
202
203#[cfg(test)]
204mod tests {
205    use crate::{
206        FeaturePolicy, FeatureSupport, Message, ModelCapabilities, ModelErrorKind, ModelRef,
207        ModelRequest, OutputFormat, SupportLevel,
208    };
209
210    #[test]
211    fn strict_policy_rejects_unknown_required_support() {
212        let request = ModelRequest::new(ModelRef::new("test", "model"), Message::user("hello"));
213
214        let error = ModelCapabilities::default()
215            .validate_request(&request, true)
216            .unwrap_err();
217
218        assert_eq!(error.kind, ModelErrorKind::UnsupportedFeature);
219    }
220
221    #[test]
222    fn best_effort_makes_unknown_support_visible() {
223        let request = ModelRequest::new(ModelRef::new("test", "model"), Message::user("hello"))
224            .feature_policy(FeaturePolicy::BestEffort);
225
226        let warnings = ModelCapabilities::default()
227            .validate_request(&request, true)
228            .unwrap();
229
230        assert_eq!(warnings.len(), 1);
231        assert_eq!(warnings[0].code, "runifold.feature_support_unknown");
232    }
233
234    #[test]
235    fn unsupported_features_fail_even_in_best_effort_mode() {
236        let capabilities = ModelCapabilities {
237            structured_output: FeatureSupport::new(SupportLevel::Unsupported),
238            streaming: FeatureSupport::new(SupportLevel::Native),
239            ..ModelCapabilities::default()
240        };
241        let request = ModelRequest::new(ModelRef::new("test", "model"), Message::user("hello"))
242            .output_format(OutputFormat::Json)
243            .feature_policy(FeaturePolicy::BestEffort);
244
245        let error = capabilities.validate_request(&request, true).unwrap_err();
246
247        assert_eq!(error.kind, ModelErrorKind::UnsupportedFeature);
248        assert_eq!(error.metadata["feature"], "structured_output");
249    }
250}
runifold_model/capability.rs

runifold_model/
capability.rs
