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 requires_tools = !request.tools.is_empty()
108            || matches!(
109                request.tool_choice,
110                ToolChoice::Required | ToolChoice::Named { .. }
111            );
112        let requires_structured_output = !matches!(request.output_format, OutputFormat::Text);
113        let has_capability_sensitive_content = request
114            .messages
115            .iter()
116            .flat_map(|message| &message.content)
117            .any(|part| {
118                matches!(
119                    part,
120                    ContentPart::Image { .. }
121                        | ContentPart::Audio { .. }
122                        | ContentPart::Document { .. }
123                        | ContentPart::Reasoning(_)
124                )
125            });
126        if !requires_tools && !requires_structured_output && !has_capability_sensitive_content {
127            let mut warnings = Vec::new();
128            if streaming {
129                assess_feature(
130                    "streaming",
131                    &self.streaming,
132                    request.feature_policy,
133                    &mut warnings,
134                )?;
135            }
136            return Ok(warnings);
137        }
138
139        let mut required = Vec::new();
140        if streaming {
141            required.push(("streaming", &self.streaming));
142        }
143        if requires_tools {
144            required.push(("tools", &self.tools));
145        }
146        if requires_structured_output {
147            required.push(("structured_output", &self.structured_output));
148        }
149        for message in &request.messages {
150            for part in &message.content {
151                match part {
152                    ContentPart::Image { .. } => required.push(("image_input", &self.image_input)),
153                    ContentPart::Audio { .. } => required.push(("audio_input", &self.audio_input)),
154                    ContentPart::Document { .. } => {
155                        required.push(("document_input", &self.document_input));
156                    }
157                    ContentPart::Reasoning(_) => required.push(("reasoning", &self.reasoning)),
158                    _ => {}
159                }
160            }
161        }
162
163        required.sort_by_key(|(name, _)| *name);
164        required.dedup_by_key(|(name, _)| *name);
165        let mut warnings = Vec::new();
166        for (name, support) in required {
167            assess_feature(name, support, request.feature_policy, &mut warnings)?;
168        }
169        Ok(warnings)
170    }
171}
172
173fn assess_feature(
174    name: &str,
175    support: &FeatureSupport,
176    policy: FeaturePolicy,
177    warnings: &mut Vec<ModelWarning>,
178) -> Result<(), ModelError> {
179    match (support.level, policy) {
180        (Native, _) => Ok(()),
181        (Emulated, FeaturePolicy::AllowEmulation | FeaturePolicy::BestEffort) => {
182            warnings.push(compatibility_warning(
183                "runifold.feature_emulated",
184                name,
185                support,
186            ));
187            Ok(())
188        }
189        (Unknown, FeaturePolicy::BestEffort) => {
190            warnings.push(compatibility_warning(
191                "runifold.feature_support_unknown",
192                name,
193                support,
194            ));
195            Ok(())
196        }
197        (Unsupported, _) => Err(unsupported_error(name, "unsupported", support)),
198        (Emulated, FeaturePolicy::Strict) => Err(unsupported_error(name, "emulated", support)),
199        (Unknown, FeaturePolicy::Strict | FeaturePolicy::AllowEmulation) => {
200            Err(unsupported_error(name, "unknown", support))
201        }
202    }
203}
204
205fn compatibility_warning(code: &str, name: &str, support: &FeatureSupport) -> ModelWarning {
206    let mut metadata = support.constraints.clone();
207    metadata.insert("feature".into(), Value::String(name.into()));
208    ModelWarning {
209        code: code.into(),
210        message: format!("feature `{name}` is not natively supported"),
211        metadata,
212    }
213}
214
215fn unsupported_error(name: &str, level: &str, support: &FeatureSupport) -> ModelError {
216    let mut error = ModelError::local(
217        ModelErrorKind::UnsupportedFeature,
218        format!("required feature `{name}` has support level `{level}`"),
219    );
220    error
221        .metadata
222        .insert("feature".into(), Value::String(name.into()));
223    error.metadata.insert(
224        "constraints".into(),
225        Value::Object(support.constraints.clone().into_iter().collect()),
226    );
227    error
228}
229
230#[cfg(test)]
231mod tests {
232    use crate::{
233        FeaturePolicy, FeatureSupport, Message, ModelCapabilities, ModelErrorKind, ModelRef,
234        ModelRequest, OutputFormat, SupportLevel,
235    };
236
237    #[test]
238    fn strict_policy_rejects_unknown_required_support() {
239        let request = ModelRequest::new(ModelRef::new("test", "model"), Message::user("hello"));
240
241        let error = ModelCapabilities::default()
242            .validate_request(&request, true)
243            .unwrap_err();
244
245        assert_eq!(error.kind, ModelErrorKind::UnsupportedFeature);
246    }
247
248    #[test]
249    fn best_effort_makes_unknown_support_visible() {
250        let request = ModelRequest::new(ModelRef::new("test", "model"), Message::user("hello"))
251            .feature_policy(FeaturePolicy::BestEffort);
252
253        let warnings = ModelCapabilities::default()
254            .validate_request(&request, true)
255            .unwrap();
256
257        assert_eq!(warnings.len(), 1);
258        assert_eq!(warnings[0].code, "runifold.feature_support_unknown");
259    }
260
261    #[test]
262    fn unsupported_features_fail_even_in_best_effort_mode() {
263        let capabilities = ModelCapabilities {
264            structured_output: FeatureSupport::new(SupportLevel::Unsupported),
265            streaming: FeatureSupport::new(SupportLevel::Native),
266            ..ModelCapabilities::default()
267        };
268        let request = ModelRequest::new(ModelRef::new("test", "model"), Message::user("hello"))
269            .output_format(OutputFormat::Json)
270            .feature_policy(FeaturePolicy::BestEffort);
271
272        let error = capabilities.validate_request(&request, true).unwrap_err();
273
274        assert_eq!(error.kind, ModelErrorKind::UnsupportedFeature);
275        assert_eq!(error.metadata["feature"], "structured_output");
276    }
277}
runifold_model/capability.rs

runifold_model/
capability.rs
