1use std::{
7 collections::{BTreeSet, btree_set},
8 fmt,
9};
10
11use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
12use serde::{
13 Deserialize, Deserializer, Serialize, Serializer,
14 de::{self, SeqAccess},
15};
16use thiserror::Error;
17
18use crate::{CapabilityKind, CapabilityMetadata, ExecutionCount, SchemaReference, TokenCount};
19
20#[derive(
27 Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
28)]
29#[serde(rename_all = "snake_case")]
30pub enum ModelModality {
31 Text,
33 Image,
35 Audio,
37 Video,
39 Document,
41}
42
43#[derive(Clone, Debug, Default, Eq, PartialEq)]
48pub struct ModelModalities(BTreeSet<ModelModality>);
49
50impl ModelModalities {
51 pub const MAX_LEN: usize = 5;
53
54 #[must_use]
56 pub const fn empty() -> Self {
57 Self(BTreeSet::new())
58 }
59
60 pub fn try_new<I>(modalities: I) -> Result<Self, ModelModalitiesError>
67 where
68 I: IntoIterator<Item = ModelModality>,
69 {
70 let mut values = BTreeSet::new();
71 for modality in modalities {
72 if values.contains(&modality) {
73 return Err(ModelModalitiesError::Duplicate { modality });
74 }
75 if values.len() == Self::MAX_LEN {
76 return Err(ModelModalitiesError::TooMany {
77 max: Self::MAX_LEN,
78 observed: Self::MAX_LEN + 1,
79 });
80 }
81 values.insert(modality);
82 }
83 Ok(Self(values))
84 }
85
86 #[must_use]
88 pub fn len(&self) -> usize {
89 self.0.len()
90 }
91
92 #[must_use]
94 pub fn is_empty(&self) -> bool {
95 self.0.is_empty()
96 }
97
98 #[must_use]
100 pub fn contains(&self, modality: ModelModality) -> bool {
101 self.0.contains(&modality)
102 }
103
104 pub fn iter(&self) -> btree_set::Iter<'_, ModelModality> {
106 self.0.iter()
107 }
108
109 #[must_use]
111 pub fn is_subset(&self, other: &Self) -> bool {
112 self.0.is_subset(&other.0)
113 }
114}
115
116impl<'a> IntoIterator for &'a ModelModalities {
117 type Item = &'a ModelModality;
118 type IntoIter = btree_set::Iter<'a, ModelModality>;
119
120 fn into_iter(self) -> Self::IntoIter {
121 self.iter()
122 }
123}
124
125impl TryFrom<Vec<ModelModality>> for ModelModalities {
126 type Error = ModelModalitiesError;
127
128 fn try_from(modalities: Vec<ModelModality>) -> Result<Self, Self::Error> {
129 Self::try_new(modalities)
130 }
131}
132
133impl Serialize for ModelModalities {
134 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
135 where
136 S: Serializer,
137 {
138 serializer.collect_seq(self.iter())
139 }
140}
141
142impl<'de> Deserialize<'de> for ModelModalities {
143 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
144 where
145 D: Deserializer<'de>,
146 {
147 deserializer.deserialize_seq(ModelModalitiesVisitor)
148 }
149}
150
151struct ModelModalitiesVisitor;
152
153impl<'de> de::Visitor<'de> for ModelModalitiesVisitor {
154 type Value = ModelModalities;
155
156 fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
157 write!(
158 formatter,
159 "an array containing at most {} unique model modalities",
160 ModelModalities::MAX_LEN
161 )
162 }
163
164 fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
165 where
166 A: SeqAccess<'de>,
167 {
168 let mut values = BTreeSet::new();
169 while let Some(modality) = sequence.next_element::<ModelModality>()? {
170 if values.contains(&modality) {
171 return Err(de::Error::custom(ModelModalitiesError::Duplicate {
172 modality,
173 }));
174 }
175 if values.len() == ModelModalities::MAX_LEN {
176 return Err(de::Error::custom(ModelModalitiesError::TooMany {
177 max: ModelModalities::MAX_LEN,
178 observed: ModelModalities::MAX_LEN + 1,
179 }));
180 }
181 values.insert(modality);
182 }
183 Ok(ModelModalities(values))
184 }
185}
186
187impl JsonSchema for ModelModalities {
188 fn schema_name() -> std::borrow::Cow<'static, str> {
189 "ModelModalities".into()
190 }
191
192 fn schema_id() -> std::borrow::Cow<'static, str> {
193 concat!(module_path!(), "::ModelModalities").into()
194 }
195
196 fn json_schema(generator: &mut SchemaGenerator) -> Schema {
197 json_schema!({
198 "type": "array",
199 "items": generator.subschema_for::<ModelModality>(),
200 "maxItems": 5,
201 "uniqueItems": true
202 })
203 }
204}
205
206#[derive(Clone, Debug, Eq, Error, PartialEq)]
208#[non_exhaustive]
209pub enum ModelModalitiesError {
210 #[error("model modality set contains duplicate {modality:?}")]
212 Duplicate {
213 modality: ModelModality,
215 },
216
217 #[error("model modality set contains at least {observed} values; maximum is {max}")]
219 TooMany {
220 max: usize,
222 observed: usize,
224 },
225}
226
227#[derive(
229 Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
230)]
231#[serde(rename_all = "snake_case")]
232pub enum ModelToolChoice {
233 Auto,
235 None,
237 Required,
239 Specific,
241}
242
243#[derive(Clone, Debug, Default, Eq, PartialEq)]
245pub struct ModelToolChoices(BTreeSet<ModelToolChoice>);
246
247impl ModelToolChoices {
248 pub const MAX_LEN: usize = 4;
250
251 #[must_use]
253 pub const fn empty() -> Self {
254 Self(BTreeSet::new())
255 }
256
257 pub fn try_new<I>(choices: I) -> Result<Self, ModelToolChoicesError>
263 where
264 I: IntoIterator<Item = ModelToolChoice>,
265 {
266 let mut values = BTreeSet::new();
267 for choice in choices {
268 if values.contains(&choice) {
269 return Err(ModelToolChoicesError::Duplicate { choice });
270 }
271 if values.len() == Self::MAX_LEN {
272 return Err(ModelToolChoicesError::TooMany {
273 max: Self::MAX_LEN,
274 observed: Self::MAX_LEN + 1,
275 });
276 }
277 values.insert(choice);
278 }
279 Ok(Self(values))
280 }
281
282 #[must_use]
284 pub fn len(&self) -> usize {
285 self.0.len()
286 }
287
288 #[must_use]
290 pub fn is_empty(&self) -> bool {
291 self.0.is_empty()
292 }
293
294 #[must_use]
296 pub fn contains(&self, choice: ModelToolChoice) -> bool {
297 self.0.contains(&choice)
298 }
299
300 pub fn iter(&self) -> btree_set::Iter<'_, ModelToolChoice> {
302 self.0.iter()
303 }
304
305 #[must_use]
307 pub fn is_subset(&self, other: &Self) -> bool {
308 self.0.is_subset(&other.0)
309 }
310}
311
312impl<'a> IntoIterator for &'a ModelToolChoices {
313 type Item = &'a ModelToolChoice;
314 type IntoIter = btree_set::Iter<'a, ModelToolChoice>;
315
316 fn into_iter(self) -> Self::IntoIter {
317 self.iter()
318 }
319}
320
321impl TryFrom<Vec<ModelToolChoice>> for ModelToolChoices {
322 type Error = ModelToolChoicesError;
323
324 fn try_from(choices: Vec<ModelToolChoice>) -> Result<Self, Self::Error> {
325 Self::try_new(choices)
326 }
327}
328
329impl Serialize for ModelToolChoices {
330 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
331 where
332 S: Serializer,
333 {
334 serializer.collect_seq(self.iter())
335 }
336}
337
338impl<'de> Deserialize<'de> for ModelToolChoices {
339 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
340 where
341 D: Deserializer<'de>,
342 {
343 deserializer.deserialize_seq(ModelToolChoicesVisitor)
344 }
345}
346
347struct ModelToolChoicesVisitor;
348
349impl<'de> de::Visitor<'de> for ModelToolChoicesVisitor {
350 type Value = ModelToolChoices;
351
352 fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
353 write!(
354 formatter,
355 "an array containing at most {} unique model tool choices",
356 ModelToolChoices::MAX_LEN
357 )
358 }
359
360 fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
361 where
362 A: SeqAccess<'de>,
363 {
364 let mut values = BTreeSet::new();
365 while let Some(choice) = sequence.next_element::<ModelToolChoice>()? {
366 if values.contains(&choice) {
367 return Err(de::Error::custom(ModelToolChoicesError::Duplicate {
368 choice,
369 }));
370 }
371 if values.len() == ModelToolChoices::MAX_LEN {
372 return Err(de::Error::custom(ModelToolChoicesError::TooMany {
373 max: ModelToolChoices::MAX_LEN,
374 observed: ModelToolChoices::MAX_LEN + 1,
375 }));
376 }
377 values.insert(choice);
378 }
379 Ok(ModelToolChoices(values))
380 }
381}
382
383impl JsonSchema for ModelToolChoices {
384 fn schema_name() -> std::borrow::Cow<'static, str> {
385 "ModelToolChoices".into()
386 }
387
388 fn schema_id() -> std::borrow::Cow<'static, str> {
389 concat!(module_path!(), "::ModelToolChoices").into()
390 }
391
392 fn json_schema(generator: &mut SchemaGenerator) -> Schema {
393 json_schema!({
394 "type": "array",
395 "items": generator.subschema_for::<ModelToolChoice>(),
396 "maxItems": 4,
397 "uniqueItems": true
398 })
399 }
400}
401
402#[derive(Clone, Debug, Eq, Error, PartialEq)]
404#[non_exhaustive]
405pub enum ModelToolChoicesError {
406 #[error("model tool-choice set contains duplicate {choice:?}")]
408 Duplicate {
409 choice: ModelToolChoice,
411 },
412
413 #[error("model tool-choice set contains at least {observed} values; maximum is {max}")]
415 TooMany {
416 max: usize,
418 observed: usize,
420 },
421}
422
423#[allow(clippy::struct_field_names)]
431#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
432#[serde(deny_unknown_fields)]
433pub struct ModelTokenLimits {
434 #[serde(skip_serializing_if = "Option::is_none")]
435 max_context_tokens: Option<TokenCount>,
436 #[serde(skip_serializing_if = "Option::is_none")]
437 max_input_tokens: Option<TokenCount>,
438 #[serde(skip_serializing_if = "Option::is_none")]
439 max_output_tokens: Option<TokenCount>,
440}
441
442impl ModelTokenLimits {
443 pub const fn new(
450 max_context_tokens: Option<TokenCount>,
451 max_input_tokens: Option<TokenCount>,
452 max_output_tokens: Option<TokenCount>,
453 ) -> Result<Self, ModelTokenLimitsError> {
454 if matches!(max_context_tokens, Some(value) if value.get() == 0) {
455 return Err(ModelTokenLimitsError::ZeroContext);
456 }
457 if matches!(max_input_tokens, Some(value) if value.get() == 0) {
458 return Err(ModelTokenLimitsError::ZeroInput);
459 }
460 if matches!(max_output_tokens, Some(value) if value.get() == 0) {
461 return Err(ModelTokenLimitsError::ZeroOutput);
462 }
463 if let (Some(context), Some(input)) = (max_context_tokens, max_input_tokens) {
464 if input.get() > context.get() {
465 return Err(ModelTokenLimitsError::InputExceedsContext { input, context });
466 }
467 }
468 if let (Some(context), Some(output)) = (max_context_tokens, max_output_tokens) {
469 if output.get() > context.get() {
470 return Err(ModelTokenLimitsError::OutputExceedsContext { output, context });
471 }
472 }
473 Ok(Self {
474 max_context_tokens,
475 max_input_tokens,
476 max_output_tokens,
477 })
478 }
479
480 #[must_use]
482 pub const fn unknown() -> Self {
483 Self {
484 max_context_tokens: None,
485 max_input_tokens: None,
486 max_output_tokens: None,
487 }
488 }
489
490 #[must_use]
492 pub const fn max_context_tokens(&self) -> Option<TokenCount> {
493 self.max_context_tokens
494 }
495
496 #[must_use]
498 pub const fn max_input_tokens(&self) -> Option<TokenCount> {
499 self.max_input_tokens
500 }
501
502 #[must_use]
504 pub const fn max_output_tokens(&self) -> Option<TokenCount> {
505 self.max_output_tokens
506 }
507}
508
509#[allow(clippy::struct_field_names)]
510#[derive(Deserialize)]
511#[serde(deny_unknown_fields)]
512struct ModelTokenLimitsWire {
513 #[serde(default)]
514 max_context_tokens: Option<TokenCount>,
515 #[serde(default)]
516 max_input_tokens: Option<TokenCount>,
517 #[serde(default)]
518 max_output_tokens: Option<TokenCount>,
519}
520
521impl<'de> Deserialize<'de> for ModelTokenLimits {
522 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
523 where
524 D: Deserializer<'de>,
525 {
526 let wire = ModelTokenLimitsWire::deserialize(deserializer)?;
527 Self::new(
528 wire.max_context_tokens,
529 wire.max_input_tokens,
530 wire.max_output_tokens,
531 )
532 .map_err(de::Error::custom)
533 }
534}
535
536#[derive(Clone, Debug, Eq, Error, PartialEq)]
538#[non_exhaustive]
539pub enum ModelTokenLimitsError {
540 #[error("known model context token limit must be greater than zero")]
542 ZeroContext,
543 #[error("known model input token limit must be greater than zero")]
545 ZeroInput,
546 #[error("known model output token limit must be greater than zero")]
548 ZeroOutput,
549 #[error("model input token limit {input} exceeds context limit {context}")]
551 InputExceedsContext {
552 input: TokenCount,
554 context: TokenCount,
556 },
557 #[error("model output token limit {output} exceeds context limit {context}")]
559 OutputExceedsContext {
560 output: TokenCount,
562 context: TokenCount,
564 },
565}
566
567#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
575#[serde(deny_unknown_fields)]
576pub struct ModelToolCapabilities {
577 #[serde(skip_serializing_if = "Option::is_none")]
578 schema_profile: Option<SchemaReference>,
579 max_definitions: ExecutionCount,
580 max_calls_per_response: ExecutionCount,
581 choices: ModelToolChoices,
582 strict_arguments: bool,
583}
584
585impl ModelToolCapabilities {
586 pub fn new(
596 schema_profile: Option<SchemaReference>,
597 max_definitions: ExecutionCount,
598 max_calls_per_response: ExecutionCount,
599 choices: ModelToolChoices,
600 strict_arguments: bool,
601 ) -> Result<Self, ModelToolCapabilitiesError> {
602 if schema_profile.is_none() {
603 if max_definitions.get() != 0
604 || max_calls_per_response.get() != 0
605 || !choices.is_empty()
606 || strict_arguments
607 {
608 return Err(ModelToolCapabilitiesError::UnsupportedHasCapabilities);
609 }
610 } else {
611 if max_definitions.get() == 0 {
612 return Err(ModelToolCapabilitiesError::ZeroDefinitions);
613 }
614 if max_calls_per_response.get() == 0 {
615 return Err(ModelToolCapabilitiesError::ZeroCallsPerResponse);
616 }
617 if !choices.contains(ModelToolChoice::Auto) {
618 return Err(ModelToolCapabilitiesError::MissingAutoChoice);
619 }
620 }
621 Ok(Self {
622 schema_profile,
623 max_definitions,
624 max_calls_per_response,
625 choices,
626 strict_arguments,
627 })
628 }
629
630 #[must_use]
632 pub fn unsupported() -> Self {
633 Self {
634 schema_profile: None,
635 max_definitions: ExecutionCount::ZERO,
636 max_calls_per_response: ExecutionCount::ZERO,
637 choices: ModelToolChoices::empty(),
638 strict_arguments: false,
639 }
640 }
641
642 #[must_use]
644 pub const fn supports_tool_calling(&self) -> bool {
645 self.schema_profile.is_some()
646 }
647
648 #[must_use]
650 pub const fn schema_profile(&self) -> Option<&SchemaReference> {
651 self.schema_profile.as_ref()
652 }
653
654 #[must_use]
656 pub const fn max_definitions(&self) -> ExecutionCount {
657 self.max_definitions
658 }
659
660 #[must_use]
662 pub const fn max_calls_per_response(&self) -> ExecutionCount {
663 self.max_calls_per_response
664 }
665
666 #[must_use]
668 pub const fn supports_parallel_calls(&self) -> bool {
669 self.max_calls_per_response.get() > 1
670 }
671
672 #[must_use]
674 pub const fn choices(&self) -> &ModelToolChoices {
675 &self.choices
676 }
677
678 #[must_use]
680 pub const fn supports_strict_arguments(&self) -> bool {
681 self.strict_arguments
682 }
683}
684
685#[derive(Deserialize)]
686#[serde(deny_unknown_fields)]
687struct ModelToolCapabilitiesWire {
688 #[serde(default)]
689 schema_profile: Option<SchemaReference>,
690 max_definitions: ExecutionCount,
691 max_calls_per_response: ExecutionCount,
692 choices: ModelToolChoices,
693 strict_arguments: bool,
694}
695
696impl<'de> Deserialize<'de> for ModelToolCapabilities {
697 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
698 where
699 D: Deserializer<'de>,
700 {
701 let wire = ModelToolCapabilitiesWire::deserialize(deserializer)?;
702 Self::new(
703 wire.schema_profile,
704 wire.max_definitions,
705 wire.max_calls_per_response,
706 wire.choices,
707 wire.strict_arguments,
708 )
709 .map_err(de::Error::custom)
710 }
711}
712
713#[derive(Clone, Debug, Eq, Error, PartialEq)]
715#[non_exhaustive]
716pub enum ModelToolCapabilitiesError {
717 #[error("unsupported model tool calling cannot declare capacities, choices, or strict mode")]
719 UnsupportedHasCapabilities,
720 #[error("supported model tool calling requires a positive definition capacity")]
722 ZeroDefinitions,
723 #[error("supported model tool calling requires a positive call capacity")]
725 ZeroCallsPerResponse,
726 #[error("supported model tool calling must include the auto choice")]
728 MissingAutoChoice,
729}
730
731#[derive(
733 Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
734)]
735#[serde(rename_all = "snake_case")]
736pub enum ModelStructuredOutputLevel {
737 Unsupported,
739 Json,
741 JsonSchema,
743}
744
745#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
751#[serde(deny_unknown_fields)]
752pub struct ModelStructuredOutputCapabilities {
753 level: ModelStructuredOutputLevel,
754 #[serde(skip_serializing_if = "Option::is_none")]
755 schema_profile: Option<SchemaReference>,
756}
757
758impl ModelStructuredOutputCapabilities {
759 pub fn new(
766 level: ModelStructuredOutputLevel,
767 schema_profile: Option<SchemaReference>,
768 ) -> Result<Self, ModelStructuredOutputCapabilitiesError> {
769 match (level, schema_profile.is_some()) {
770 (ModelStructuredOutputLevel::JsonSchema, false) => {
771 return Err(ModelStructuredOutputCapabilitiesError::MissingSchemaProfile);
772 }
773 (ModelStructuredOutputLevel::Unsupported | ModelStructuredOutputLevel::Json, true) => {
774 return Err(ModelStructuredOutputCapabilitiesError::UnexpectedSchemaProfile);
775 }
776 _ => {}
777 }
778 Ok(Self {
779 level,
780 schema_profile,
781 })
782 }
783
784 #[must_use]
786 pub const fn unsupported() -> Self {
787 Self {
788 level: ModelStructuredOutputLevel::Unsupported,
789 schema_profile: None,
790 }
791 }
792
793 #[must_use]
795 pub const fn json() -> Self {
796 Self {
797 level: ModelStructuredOutputLevel::Json,
798 schema_profile: None,
799 }
800 }
801
802 #[must_use]
804 pub const fn json_schema(schema_profile: SchemaReference) -> Self {
805 Self {
806 level: ModelStructuredOutputLevel::JsonSchema,
807 schema_profile: Some(schema_profile),
808 }
809 }
810
811 #[must_use]
813 pub const fn level(&self) -> ModelStructuredOutputLevel {
814 self.level
815 }
816
817 #[must_use]
819 pub const fn schema_profile(&self) -> Option<&SchemaReference> {
820 self.schema_profile.as_ref()
821 }
822}
823
824#[derive(Deserialize)]
825#[serde(deny_unknown_fields)]
826struct ModelStructuredOutputCapabilitiesWire {
827 level: ModelStructuredOutputLevel,
828 #[serde(default)]
829 schema_profile: Option<SchemaReference>,
830}
831
832impl<'de> Deserialize<'de> for ModelStructuredOutputCapabilities {
833 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
834 where
835 D: Deserializer<'de>,
836 {
837 let wire = ModelStructuredOutputCapabilitiesWire::deserialize(deserializer)?;
838 Self::new(wire.level, wire.schema_profile).map_err(de::Error::custom)
839 }
840}
841
842#[derive(Clone, Debug, Eq, Error, PartialEq)]
844#[non_exhaustive]
845pub enum ModelStructuredOutputCapabilitiesError {
846 #[error("JSON Schema structured output requires a schema profile")]
848 MissingSchemaProfile,
849 #[error("only JSON Schema structured output may declare a schema profile")]
851 UnexpectedSchemaProfile,
852}
853
854#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
861#[serde(deny_unknown_fields)]
862pub struct ModelCapabilities {
863 input_modalities: ModelModalities,
864 output_modalities: ModelModalities,
865 streaming: bool,
866 tools: ModelToolCapabilities,
867 structured_output: ModelStructuredOutputCapabilities,
868 reasoning_summaries: bool,
869 token_limits: ModelTokenLimits,
870}
871
872impl ModelCapabilities {
873 pub fn new(
881 input_modalities: ModelModalities,
882 output_modalities: ModelModalities,
883 streaming: bool,
884 tools: ModelToolCapabilities,
885 structured_output: ModelStructuredOutputCapabilities,
886 reasoning_summaries: bool,
887 token_limits: ModelTokenLimits,
888 ) -> Result<Self, ModelCapabilitiesError> {
889 if input_modalities.is_empty() {
890 return Err(ModelCapabilitiesError::EmptyInputModalities);
891 }
892 if output_modalities.is_empty() {
893 return Err(ModelCapabilitiesError::EmptyOutputModalities);
894 }
895 if tools.supports_tool_calling() && !input_modalities.contains(ModelModality::Text) {
896 return Err(ModelCapabilitiesError::ToolCallingRequiresTextInput);
897 }
898 if tools.supports_tool_calling() && !output_modalities.contains(ModelModality::Text) {
899 return Err(ModelCapabilitiesError::ToolCallingRequiresTextOutput);
900 }
901 if structured_output.level() != ModelStructuredOutputLevel::Unsupported
902 && !output_modalities.contains(ModelModality::Text)
903 {
904 return Err(ModelCapabilitiesError::StructuredOutputRequiresTextOutput);
905 }
906 if reasoning_summaries && !output_modalities.contains(ModelModality::Text) {
907 return Err(ModelCapabilitiesError::ReasoningSummaryRequiresTextOutput);
908 }
909 Ok(Self {
910 input_modalities,
911 output_modalities,
912 streaming,
913 tools,
914 structured_output,
915 reasoning_summaries,
916 token_limits,
917 })
918 }
919
920 #[must_use]
922 pub const fn input_modalities(&self) -> &ModelModalities {
923 &self.input_modalities
924 }
925
926 #[must_use]
928 pub const fn output_modalities(&self) -> &ModelModalities {
929 &self.output_modalities
930 }
931
932 #[must_use]
934 pub const fn supports_streaming(&self) -> bool {
935 self.streaming
936 }
937
938 #[must_use]
940 pub const fn tools(&self) -> &ModelToolCapabilities {
941 &self.tools
942 }
943
944 #[must_use]
946 pub const fn structured_output(&self) -> &ModelStructuredOutputCapabilities {
947 &self.structured_output
948 }
949
950 #[must_use]
952 pub const fn supports_reasoning_summaries(&self) -> bool {
953 self.reasoning_summaries
954 }
955
956 #[must_use]
958 pub const fn token_limits(&self) -> &ModelTokenLimits {
959 &self.token_limits
960 }
961
962 pub fn satisfies(
972 &self,
973 requirements: &ModelRequirements,
974 ) -> Result<(), ModelCapabilityMismatch> {
975 let mut unmet = BTreeSet::new();
976
977 for modality in requirements.input_modalities() {
978 if !self.input_modalities.contains(*modality) {
979 unmet.insert(ModelCapabilityIssue::InputModality {
980 required: *modality,
981 });
982 }
983 }
984 for modality in requirements.output_modalities() {
985 if !self.output_modalities.contains(*modality) {
986 unmet.insert(ModelCapabilityIssue::OutputModality {
987 required: *modality,
988 });
989 }
990 }
991 if requirements.requires_streaming() && !self.streaming {
992 unmet.insert(ModelCapabilityIssue::Streaming {});
993 }
994
995 let required_tools = requirements.tools();
996 if required_tools.requires_tool_calling() {
997 if !self.tools.supports_tool_calling() {
998 unmet.insert(ModelCapabilityIssue::ToolCalling {});
999 }
1000 if self.tools.max_definitions() < required_tools.min_definitions() {
1001 unmet.insert(ModelCapabilityIssue::ToolDefinitions {
1002 required: required_tools.min_definitions(),
1003 available: self.tools.max_definitions(),
1004 });
1005 }
1006 if self.tools.max_calls_per_response() < required_tools.min_calls_per_response() {
1007 unmet.insert(ModelCapabilityIssue::ToolCallsPerResponse {
1008 required: required_tools.min_calls_per_response(),
1009 available: self.tools.max_calls_per_response(),
1010 });
1011 }
1012 for choice in required_tools.choices() {
1013 if !self.tools.choices().contains(*choice) {
1014 unmet.insert(ModelCapabilityIssue::ToolChoice { required: *choice });
1015 }
1016 }
1017 if required_tools.requires_strict_arguments() && !self.tools.supports_strict_arguments()
1018 {
1019 unmet.insert(ModelCapabilityIssue::StrictToolArguments {});
1020 }
1021 }
1022
1023 let required_structured = requirements.structured_output();
1024 if self.structured_output.level() < required_structured {
1025 unmet.insert(ModelCapabilityIssue::StructuredOutput {
1026 required: required_structured,
1027 available: self.structured_output.level(),
1028 });
1029 }
1030 if requirements.requires_reasoning_summaries() && !self.reasoning_summaries {
1031 unmet.insert(ModelCapabilityIssue::ReasoningSummary {});
1032 }
1033
1034 if let Some(required) = requirements.min_context_tokens() {
1035 if !known_capacity_satisfies(self.token_limits.max_context_tokens(), required) {
1036 unmet.insert(ModelCapabilityIssue::ContextTokens {
1037 required,
1038 available: self.token_limits.max_context_tokens(),
1039 });
1040 }
1041 }
1042 if let Some(required) = requirements.min_input_tokens() {
1043 if !known_capacity_satisfies(self.token_limits.max_input_tokens(), required) {
1044 unmet.insert(ModelCapabilityIssue::InputTokens {
1045 required,
1046 available: self.token_limits.max_input_tokens(),
1047 });
1048 }
1049 }
1050 if let Some(required) = requirements.min_output_tokens() {
1051 if !known_capacity_satisfies(self.token_limits.max_output_tokens(), required) {
1052 unmet.insert(ModelCapabilityIssue::OutputTokens {
1053 required,
1054 available: self.token_limits.max_output_tokens(),
1055 });
1056 }
1057 }
1058
1059 if unmet.is_empty() {
1060 Ok(())
1061 } else {
1062 Err(ModelCapabilityMismatch(unmet))
1063 }
1064 }
1065}
1066
1067fn known_capacity_satisfies(available: Option<TokenCount>, required: TokenCount) -> bool {
1068 available.is_some_and(|available| available >= required)
1069}
1070
1071#[derive(Deserialize)]
1072#[serde(deny_unknown_fields)]
1073struct ModelCapabilitiesWire {
1074 input_modalities: ModelModalities,
1075 output_modalities: ModelModalities,
1076 streaming: bool,
1077 tools: ModelToolCapabilities,
1078 structured_output: ModelStructuredOutputCapabilities,
1079 reasoning_summaries: bool,
1080 token_limits: ModelTokenLimits,
1081}
1082
1083impl<'de> Deserialize<'de> for ModelCapabilities {
1084 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1085 where
1086 D: Deserializer<'de>,
1087 {
1088 let wire = ModelCapabilitiesWire::deserialize(deserializer)?;
1089 Self::new(
1090 wire.input_modalities,
1091 wire.output_modalities,
1092 wire.streaming,
1093 wire.tools,
1094 wire.structured_output,
1095 wire.reasoning_summaries,
1096 wire.token_limits,
1097 )
1098 .map_err(de::Error::custom)
1099 }
1100}
1101
1102#[derive(Clone, Debug, Eq, Error, PartialEq)]
1104#[non_exhaustive]
1105pub enum ModelCapabilitiesError {
1106 #[error("model capabilities require at least one input modality")]
1108 EmptyInputModalities,
1109 #[error("model capabilities require at least one output modality")]
1111 EmptyOutputModalities,
1112 #[error("model tool calling requires the text input modality")]
1114 ToolCallingRequiresTextInput,
1115 #[error("model tool calling requires the text output modality")]
1117 ToolCallingRequiresTextOutput,
1118 #[error("model structured output requires the text output modality")]
1120 StructuredOutputRequiresTextOutput,
1121 #[error("model reasoning summaries require the text output modality")]
1123 ReasoningSummaryRequiresTextOutput,
1124}
1125
1126#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
1136#[serde(deny_unknown_fields)]
1137pub struct ModelDescriptor {
1138 metadata: CapabilityMetadata,
1139 capabilities: ModelCapabilities,
1140}
1141
1142impl ModelDescriptor {
1143 pub fn new(
1150 metadata: CapabilityMetadata,
1151 capabilities: ModelCapabilities,
1152 ) -> Result<Self, ModelDescriptorError> {
1153 if metadata.kind() != CapabilityKind::Model {
1154 return Err(ModelDescriptorError::WrongCapabilityKind {
1155 actual: metadata.kind(),
1156 });
1157 }
1158 Ok(Self {
1159 metadata,
1160 capabilities,
1161 })
1162 }
1163
1164 #[must_use]
1166 pub const fn metadata(&self) -> &CapabilityMetadata {
1167 &self.metadata
1168 }
1169
1170 #[must_use]
1172 pub const fn capabilities(&self) -> &ModelCapabilities {
1173 &self.capabilities
1174 }
1175}
1176
1177impl fmt::Debug for ModelDescriptor {
1178 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1179 formatter
1180 .debug_struct("ModelDescriptor")
1181 .field("metadata", &self.metadata)
1182 .field("capabilities", &self.capabilities)
1183 .finish_non_exhaustive()
1184 }
1185}
1186
1187#[derive(Deserialize)]
1188#[serde(deny_unknown_fields)]
1189struct ModelDescriptorWire {
1190 metadata: CapabilityMetadata,
1191 capabilities: ModelCapabilities,
1192}
1193
1194impl<'de> Deserialize<'de> for ModelDescriptor {
1195 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1196 where
1197 D: Deserializer<'de>,
1198 {
1199 let wire = ModelDescriptorWire::deserialize(deserializer)?;
1200 Self::new(wire.metadata, wire.capabilities).map_err(de::Error::custom)
1201 }
1202}
1203
1204#[derive(Clone, Debug, Eq, Error, PartialEq)]
1206#[non_exhaustive]
1207pub enum ModelDescriptorError {
1208 #[error("model descriptor requires kind=model, received {actual:?}")]
1210 WrongCapabilityKind {
1211 actual: CapabilityKind,
1213 },
1214}
1215
1216#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
1218#[serde(deny_unknown_fields)]
1219pub struct ModelToolRequirements {
1220 min_definitions: ExecutionCount,
1221 min_calls_per_response: ExecutionCount,
1222 choices: ModelToolChoices,
1223 strict_arguments: bool,
1224}
1225
1226impl ModelToolRequirements {
1227 pub fn new(
1238 min_definitions: ExecutionCount,
1239 min_calls_per_response: ExecutionCount,
1240 choices: ModelToolChoices,
1241 strict_arguments: bool,
1242 ) -> Result<Self, ModelToolRequirementsError> {
1243 let disabled_with_definitions = min_definitions.get() != 0
1244 && min_calls_per_response.get() == 0
1245 && choices.len() == 1
1246 && choices.contains(ModelToolChoice::None)
1247 && !strict_arguments;
1248 if (min_definitions.get() == 0) != (min_calls_per_response.get() == 0)
1249 && !disabled_with_definitions
1250 {
1251 return Err(ModelToolRequirementsError::CapacityMismatch);
1252 }
1253 if min_definitions.get() == 0 && (!choices.is_empty() || strict_arguments) {
1254 return Err(ModelToolRequirementsError::InactiveHasRequirements);
1255 }
1256 Ok(Self {
1257 min_definitions,
1258 min_calls_per_response,
1259 choices,
1260 strict_arguments,
1261 })
1262 }
1263
1264 #[must_use]
1266 pub fn none() -> Self {
1267 Self {
1268 min_definitions: ExecutionCount::ZERO,
1269 min_calls_per_response: ExecutionCount::ZERO,
1270 choices: ModelToolChoices::empty(),
1271 strict_arguments: false,
1272 }
1273 }
1274
1275 #[must_use]
1277 pub const fn requires_tool_calling(&self) -> bool {
1278 self.min_definitions.get() != 0
1279 }
1280
1281 #[must_use]
1283 pub const fn min_definitions(&self) -> ExecutionCount {
1284 self.min_definitions
1285 }
1286
1287 #[must_use]
1289 pub const fn min_calls_per_response(&self) -> ExecutionCount {
1290 self.min_calls_per_response
1291 }
1292
1293 #[must_use]
1295 pub const fn choices(&self) -> &ModelToolChoices {
1296 &self.choices
1297 }
1298
1299 #[must_use]
1301 pub const fn requires_strict_arguments(&self) -> bool {
1302 self.strict_arguments
1303 }
1304}
1305
1306impl Default for ModelToolRequirements {
1307 fn default() -> Self {
1308 Self::none()
1309 }
1310}
1311
1312#[derive(Deserialize)]
1313#[serde(deny_unknown_fields)]
1314struct ModelToolRequirementsWire {
1315 min_definitions: ExecutionCount,
1316 min_calls_per_response: ExecutionCount,
1317 choices: ModelToolChoices,
1318 strict_arguments: bool,
1319}
1320
1321impl<'de> Deserialize<'de> for ModelToolRequirements {
1322 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1323 where
1324 D: Deserializer<'de>,
1325 {
1326 let wire = ModelToolRequirementsWire::deserialize(deserializer)?;
1327 Self::new(
1328 wire.min_definitions,
1329 wire.min_calls_per_response,
1330 wire.choices,
1331 wire.strict_arguments,
1332 )
1333 .map_err(de::Error::custom)
1334 }
1335}
1336
1337#[derive(Clone, Debug, Eq, Error, PartialEq)]
1339#[non_exhaustive]
1340pub enum ModelToolRequirementsError {
1341 #[error("model tool requirements need paired capacities or explicitly disabled definitions")]
1343 CapacityMismatch,
1344 #[error("inactive model tool requirements cannot require choices or strict arguments")]
1346 InactiveHasRequirements,
1347}
1348
1349#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
1355#[serde(deny_unknown_fields)]
1356pub struct ModelRequirements {
1357 input_modalities: ModelModalities,
1358 output_modalities: ModelModalities,
1359 streaming: bool,
1360 tools: ModelToolRequirements,
1361 structured_output: ModelStructuredOutputLevel,
1362 reasoning_summaries: bool,
1363 #[serde(skip_serializing_if = "Option::is_none")]
1364 min_context_tokens: Option<TokenCount>,
1365 #[serde(skip_serializing_if = "Option::is_none")]
1366 min_input_tokens: Option<TokenCount>,
1367 #[serde(skip_serializing_if = "Option::is_none")]
1368 min_output_tokens: Option<TokenCount>,
1369}
1370
1371impl ModelRequirements {
1372 #[allow(clippy::too_many_arguments)]
1379 pub fn new(
1380 input_modalities: ModelModalities,
1381 output_modalities: ModelModalities,
1382 streaming: bool,
1383 tools: ModelToolRequirements,
1384 structured_output: ModelStructuredOutputLevel,
1385 reasoning_summaries: bool,
1386 min_context_tokens: Option<TokenCount>,
1387 min_input_tokens: Option<TokenCount>,
1388 min_output_tokens: Option<TokenCount>,
1389 ) -> Result<Self, ModelRequirementsError> {
1390 if matches!(min_context_tokens, Some(value) if value.get() == 0) {
1391 return Err(ModelRequirementsError::ZeroContextTokens);
1392 }
1393 if matches!(min_input_tokens, Some(value) if value.get() == 0) {
1394 return Err(ModelRequirementsError::ZeroInputTokens);
1395 }
1396 if matches!(min_output_tokens, Some(value) if value.get() == 0) {
1397 return Err(ModelRequirementsError::ZeroOutputTokens);
1398 }
1399 Ok(Self {
1400 input_modalities,
1401 output_modalities,
1402 streaming,
1403 tools,
1404 structured_output,
1405 reasoning_summaries,
1406 min_context_tokens,
1407 min_input_tokens,
1408 min_output_tokens,
1409 })
1410 }
1411
1412 #[must_use]
1414 pub const fn input_modalities(&self) -> &ModelModalities {
1415 &self.input_modalities
1416 }
1417
1418 #[must_use]
1420 pub const fn output_modalities(&self) -> &ModelModalities {
1421 &self.output_modalities
1422 }
1423
1424 #[must_use]
1426 pub const fn requires_streaming(&self) -> bool {
1427 self.streaming
1428 }
1429
1430 #[must_use]
1432 pub const fn tools(&self) -> &ModelToolRequirements {
1433 &self.tools
1434 }
1435
1436 #[must_use]
1438 pub const fn structured_output(&self) -> ModelStructuredOutputLevel {
1439 self.structured_output
1440 }
1441
1442 #[must_use]
1444 pub const fn requires_reasoning_summaries(&self) -> bool {
1445 self.reasoning_summaries
1446 }
1447
1448 #[must_use]
1450 pub const fn min_context_tokens(&self) -> Option<TokenCount> {
1451 self.min_context_tokens
1452 }
1453
1454 #[must_use]
1456 pub const fn min_input_tokens(&self) -> Option<TokenCount> {
1457 self.min_input_tokens
1458 }
1459
1460 #[must_use]
1462 pub const fn min_output_tokens(&self) -> Option<TokenCount> {
1463 self.min_output_tokens
1464 }
1465}
1466
1467impl Default for ModelRequirements {
1468 fn default() -> Self {
1469 Self {
1470 input_modalities: ModelModalities::empty(),
1471 output_modalities: ModelModalities::empty(),
1472 streaming: false,
1473 tools: ModelToolRequirements::none(),
1474 structured_output: ModelStructuredOutputLevel::Unsupported,
1475 reasoning_summaries: false,
1476 min_context_tokens: None,
1477 min_input_tokens: None,
1478 min_output_tokens: None,
1479 }
1480 }
1481}
1482
1483#[derive(Deserialize)]
1484#[serde(deny_unknown_fields)]
1485struct ModelRequirementsWire {
1486 input_modalities: ModelModalities,
1487 output_modalities: ModelModalities,
1488 streaming: bool,
1489 tools: ModelToolRequirements,
1490 structured_output: ModelStructuredOutputLevel,
1491 reasoning_summaries: bool,
1492 #[serde(default)]
1493 min_context_tokens: Option<TokenCount>,
1494 #[serde(default)]
1495 min_input_tokens: Option<TokenCount>,
1496 #[serde(default)]
1497 min_output_tokens: Option<TokenCount>,
1498}
1499
1500impl<'de> Deserialize<'de> for ModelRequirements {
1501 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1502 where
1503 D: Deserializer<'de>,
1504 {
1505 let wire = ModelRequirementsWire::deserialize(deserializer)?;
1506 Self::new(
1507 wire.input_modalities,
1508 wire.output_modalities,
1509 wire.streaming,
1510 wire.tools,
1511 wire.structured_output,
1512 wire.reasoning_summaries,
1513 wire.min_context_tokens,
1514 wire.min_input_tokens,
1515 wire.min_output_tokens,
1516 )
1517 .map_err(de::Error::custom)
1518 }
1519}
1520
1521#[derive(Clone, Debug, Eq, Error, PartialEq)]
1523#[non_exhaustive]
1524pub enum ModelRequirementsError {
1525 #[error("model context-token requirement must be positive or absent")]
1527 ZeroContextTokens,
1528 #[error("model input-token requirement must be positive or absent")]
1530 ZeroInputTokens,
1531 #[error("model output-token requirement must be positive or absent")]
1533 ZeroOutputTokens,
1534}
1535
1536#[derive(
1538 Clone, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
1539)]
1540#[serde(tag = "requirement", rename_all = "snake_case", deny_unknown_fields)]
1541pub enum ModelCapabilityIssue {
1542 InputModality {
1544 required: ModelModality,
1546 },
1547 OutputModality {
1549 required: ModelModality,
1551 },
1552 Streaming {},
1554 ToolCalling {},
1556 ToolDefinitions {
1558 required: ExecutionCount,
1560 available: ExecutionCount,
1562 },
1563 ToolCallsPerResponse {
1565 required: ExecutionCount,
1567 available: ExecutionCount,
1569 },
1570 ToolChoice {
1572 required: ModelToolChoice,
1574 },
1575 StrictToolArguments {},
1577 StructuredOutput {
1579 required: ModelStructuredOutputLevel,
1581 available: ModelStructuredOutputLevel,
1583 },
1584 ReasoningSummary {},
1586 ContextTokens {
1588 required: TokenCount,
1590 #[serde(default, skip_serializing_if = "Option::is_none")]
1592 available: Option<TokenCount>,
1593 },
1594 InputTokens {
1596 required: TokenCount,
1598 #[serde(default, skip_serializing_if = "Option::is_none")]
1600 available: Option<TokenCount>,
1601 },
1602 OutputTokens {
1604 required: TokenCount,
1606 #[serde(default, skip_serializing_if = "Option::is_none")]
1608 available: Option<TokenCount>,
1609 },
1610}
1611
1612impl ModelCapabilityIssue {
1613 fn is_coherent(&self) -> bool {
1614 match self {
1615 Self::ToolDefinitions {
1616 required,
1617 available,
1618 }
1619 | Self::ToolCallsPerResponse {
1620 required,
1621 available,
1622 } => required.get() != 0 && required > available,
1623 Self::StructuredOutput {
1624 required,
1625 available,
1626 } => required > available,
1627 Self::ContextTokens {
1628 required,
1629 available,
1630 }
1631 | Self::InputTokens {
1632 required,
1633 available,
1634 }
1635 | Self::OutputTokens {
1636 required,
1637 available,
1638 } => required.get() != 0 && available.is_none_or(|available| required > &available),
1639 Self::InputModality { .. }
1640 | Self::OutputModality { .. }
1641 | Self::Streaming {}
1642 | Self::ToolCalling {}
1643 | Self::ToolChoice { .. }
1644 | Self::StrictToolArguments {}
1645 | Self::ReasoningSummary {} => true,
1646 }
1647 }
1648
1649 fn has_same_dimension(&self, other: &Self) -> bool {
1650 match (self, other) {
1651 (Self::InputModality { required: left }, Self::InputModality { required: right })
1652 | (Self::OutputModality { required: left }, Self::OutputModality { required: right }) => {
1653 left == right
1654 }
1655 (Self::ToolChoice { required: left }, Self::ToolChoice { required: right }) => {
1656 left == right
1657 }
1658 (Self::Streaming {}, Self::Streaming {})
1659 | (Self::ToolCalling {}, Self::ToolCalling {})
1660 | (Self::ToolDefinitions { .. }, Self::ToolDefinitions { .. })
1661 | (Self::ToolCallsPerResponse { .. }, Self::ToolCallsPerResponse { .. })
1662 | (Self::StrictToolArguments {}, Self::StrictToolArguments {})
1663 | (Self::StructuredOutput { .. }, Self::StructuredOutput { .. })
1664 | (Self::ReasoningSummary {}, Self::ReasoningSummary {})
1665 | (Self::ContextTokens { .. }, Self::ContextTokens { .. })
1666 | (Self::InputTokens { .. }, Self::InputTokens { .. })
1667 | (Self::OutputTokens { .. }, Self::OutputTokens { .. }) => true,
1668 _ => false,
1669 }
1670 }
1671}
1672
1673#[derive(Clone, Debug, Eq, PartialEq)]
1675pub struct ModelCapabilityMismatch(BTreeSet<ModelCapabilityIssue>);
1676
1677impl ModelCapabilityMismatch {
1678 pub const MAX_ISSUES: usize = 32;
1680
1681 pub fn try_new<I>(issues: I) -> Result<Self, ModelCapabilityMismatchError>
1688 where
1689 I: IntoIterator<Item = ModelCapabilityIssue>,
1690 {
1691 let mut values: BTreeSet<ModelCapabilityIssue> = BTreeSet::new();
1692 for issue in issues {
1693 if !issue.is_coherent() {
1694 return Err(ModelCapabilityMismatchError::IncoherentIssue { issue });
1695 }
1696 if values.contains(&issue) {
1697 return Err(ModelCapabilityMismatchError::Duplicate { issue });
1698 }
1699 if values
1700 .iter()
1701 .any(|existing| existing.has_same_dimension(&issue))
1702 {
1703 return Err(ModelCapabilityMismatchError::DuplicateDimension { issue });
1704 }
1705 if values.len() == Self::MAX_ISSUES {
1706 return Err(ModelCapabilityMismatchError::TooMany {
1707 max: Self::MAX_ISSUES,
1708 observed: Self::MAX_ISSUES + 1,
1709 });
1710 }
1711 values.insert(issue);
1712 }
1713 if values.is_empty() {
1714 return Err(ModelCapabilityMismatchError::Empty);
1715 }
1716 Ok(Self(values))
1717 }
1718
1719 #[must_use]
1721 pub fn len(&self) -> usize {
1722 self.0.len()
1723 }
1724
1725 #[must_use]
1727 pub fn is_empty(&self) -> bool {
1728 self.0.is_empty()
1729 }
1730
1731 pub fn iter(&self) -> btree_set::Iter<'_, ModelCapabilityIssue> {
1733 self.0.iter()
1734 }
1735
1736 #[must_use]
1738 pub fn contains(&self, issue: &ModelCapabilityIssue) -> bool {
1739 self.0.contains(issue)
1740 }
1741}
1742
1743impl<'a> IntoIterator for &'a ModelCapabilityMismatch {
1744 type Item = &'a ModelCapabilityIssue;
1745 type IntoIter = btree_set::Iter<'a, ModelCapabilityIssue>;
1746
1747 fn into_iter(self) -> Self::IntoIter {
1748 self.iter()
1749 }
1750}
1751
1752impl fmt::Display for ModelCapabilityMismatch {
1753 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1754 write!(
1755 formatter,
1756 "model binding does not satisfy {} requirement(s)",
1757 self.len()
1758 )
1759 }
1760}
1761
1762impl std::error::Error for ModelCapabilityMismatch {}
1763
1764impl Serialize for ModelCapabilityMismatch {
1765 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
1766 where
1767 S: Serializer,
1768 {
1769 serializer.collect_seq(self.iter())
1770 }
1771}
1772
1773impl<'de> Deserialize<'de> for ModelCapabilityMismatch {
1774 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1775 where
1776 D: Deserializer<'de>,
1777 {
1778 deserializer.deserialize_seq(ModelCapabilityMismatchVisitor)
1779 }
1780}
1781
1782struct ModelCapabilityMismatchVisitor;
1783
1784impl<'de> de::Visitor<'de> for ModelCapabilityMismatchVisitor {
1785 type Value = ModelCapabilityMismatch;
1786
1787 fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1788 write!(
1789 formatter,
1790 "a non-empty array containing at most {} unique model capability issues",
1791 ModelCapabilityMismatch::MAX_ISSUES
1792 )
1793 }
1794
1795 fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
1796 where
1797 A: SeqAccess<'de>,
1798 {
1799 let mut issues = Vec::new();
1800 while let Some(issue) = sequence.next_element::<ModelCapabilityIssue>()? {
1801 if issues.len() == ModelCapabilityMismatch::MAX_ISSUES {
1802 return Err(de::Error::custom(ModelCapabilityMismatchError::TooMany {
1803 max: ModelCapabilityMismatch::MAX_ISSUES,
1804 observed: ModelCapabilityMismatch::MAX_ISSUES + 1,
1805 }));
1806 }
1807 issues.push(issue);
1808 }
1809 ModelCapabilityMismatch::try_new(issues).map_err(de::Error::custom)
1810 }
1811}
1812
1813impl JsonSchema for ModelCapabilityMismatch {
1814 fn schema_name() -> std::borrow::Cow<'static, str> {
1815 "ModelCapabilityMismatch".into()
1816 }
1817
1818 fn schema_id() -> std::borrow::Cow<'static, str> {
1819 concat!(module_path!(), "::ModelCapabilityMismatch").into()
1820 }
1821
1822 fn json_schema(generator: &mut SchemaGenerator) -> Schema {
1823 json_schema!({
1824 "type": "array",
1825 "items": generator.subschema_for::<ModelCapabilityIssue>(),
1826 "minItems": 1,
1827 "maxItems": 32,
1828 "uniqueItems": true
1829 })
1830 }
1831}
1832
1833#[derive(Clone, Debug, Eq, Error, PartialEq)]
1835#[non_exhaustive]
1836pub enum ModelCapabilityMismatchError {
1837 #[error("model capability mismatch must contain at least one issue")]
1839 Empty,
1840 #[error("model capability mismatch contains duplicate issue {issue:?}")]
1842 Duplicate {
1843 issue: ModelCapabilityIssue,
1845 },
1846 #[error("model capability mismatch repeats requirement dimension in {issue:?}")]
1848 DuplicateDimension {
1849 issue: ModelCapabilityIssue,
1851 },
1852 #[error("model capability mismatch contains incoherent issue {issue:?}")]
1854 IncoherentIssue {
1855 issue: ModelCapabilityIssue,
1857 },
1858 #[error("model capability mismatch contains at least {observed} issues; maximum is {max}")]
1860 TooMany {
1861 max: usize,
1863 observed: usize,
1865 },
1866}
1867
1868#[cfg(test)]
1869mod tests {
1870 use super::*;
1871 use proptest::prelude::*;
1872 use serde_json::{Value, from_value, json, to_value};
1873
1874 use crate::{
1875 CapabilityDescription, CapabilityIdentity, CapabilityLifecycle, CapabilityName,
1876 CapabilityReference, Digest, Extensions, IssuerId, PrincipalIdentity, SchemaId, ScopeSet,
1877 SubjectId, Version,
1878 };
1879
1880 fn schema(name: &str) -> SchemaReference {
1881 SchemaReference::new(
1882 format!("https://schemas.example.com/model-profiles/{name}/1.0.0")
1883 .parse::<SchemaId>()
1884 .unwrap(),
1885 Version::new(1, 0, 0),
1886 Digest::sha256(name),
1887 )
1888 }
1889
1890 fn modalities(values: impl IntoIterator<Item = ModelModality>) -> ModelModalities {
1891 ModelModalities::try_new(values).unwrap()
1892 }
1893
1894 fn choices(values: impl IntoIterator<Item = ModelToolChoice>) -> ModelToolChoices {
1895 ModelToolChoices::try_new(values).unwrap()
1896 }
1897
1898 fn tool_capabilities() -> ModelToolCapabilities {
1899 ModelToolCapabilities::new(
1900 Some(schema("tool-input")),
1901 ExecutionCount::new(64),
1902 ExecutionCount::new(8),
1903 choices([
1904 ModelToolChoice::Specific,
1905 ModelToolChoice::Auto,
1906 ModelToolChoice::Required,
1907 ModelToolChoice::None,
1908 ]),
1909 true,
1910 )
1911 .unwrap()
1912 }
1913
1914 fn capabilities() -> ModelCapabilities {
1915 ModelCapabilities::new(
1916 modalities([
1917 ModelModality::Document,
1918 ModelModality::Text,
1919 ModelModality::Image,
1920 ]),
1921 modalities([ModelModality::Text]),
1922 true,
1923 tool_capabilities(),
1924 ModelStructuredOutputCapabilities::json_schema(schema("structured-output")),
1925 true,
1926 ModelTokenLimits::new(
1927 Some(TokenCount::new(128_000)),
1928 Some(TokenCount::new(120_000)),
1929 Some(TokenCount::new(16_384)),
1930 )
1931 .unwrap(),
1932 )
1933 .unwrap()
1934 }
1935
1936 fn metadata(kind: CapabilityKind, description: &str) -> CapabilityMetadata {
1937 CapabilityMetadata::new(
1938 CapabilityIdentity::new(
1939 PrincipalIdentity::new(
1940 "https://issuer.example.com/tenant"
1941 .parse::<IssuerId>()
1942 .unwrap(),
1943 "model-registry".parse::<SubjectId>().unwrap(),
1944 ),
1945 CapabilityReference::new(
1946 "models.primary".parse::<CapabilityName>().unwrap(),
1947 Version::new(1, 0, 0),
1948 ),
1949 ),
1950 kind,
1951 None,
1952 CapabilityDescription::new(description).unwrap(),
1953 CapabilityLifecycle::active(),
1954 ScopeSet::empty(),
1955 Extensions::default(),
1956 )
1957 .unwrap()
1958 }
1959
1960 fn descriptor(description: &str) -> ModelDescriptor {
1961 ModelDescriptor::new(metadata(CapabilityKind::Model, description), capabilities()).unwrap()
1962 }
1963
1964 #[test]
1965 fn model_enums_and_sets_have_closed_deterministic_wire_forms() {
1966 for (value, expected) in [
1967 (ModelModality::Text, "text"),
1968 (ModelModality::Image, "image"),
1969 (ModelModality::Audio, "audio"),
1970 (ModelModality::Video, "video"),
1971 (ModelModality::Document, "document"),
1972 ] {
1973 assert_eq!(to_value(value).unwrap(), Value::from(expected));
1974 assert_eq!(from_value::<ModelModality>(json!(expected)).unwrap(), value);
1975 }
1976 for (value, expected) in [
1977 (ModelToolChoice::Auto, "auto"),
1978 (ModelToolChoice::None, "none"),
1979 (ModelToolChoice::Required, "required"),
1980 (ModelToolChoice::Specific, "specific"),
1981 ] {
1982 assert_eq!(to_value(value).unwrap(), Value::from(expected));
1983 assert_eq!(
1984 from_value::<ModelToolChoice>(json!(expected)).unwrap(),
1985 value
1986 );
1987 }
1988 for (value, expected) in [
1989 (ModelStructuredOutputLevel::Unsupported, "unsupported"),
1990 (ModelStructuredOutputLevel::Json, "json"),
1991 (ModelStructuredOutputLevel::JsonSchema, "json_schema"),
1992 ] {
1993 assert_eq!(to_value(value).unwrap(), Value::from(expected));
1994 assert_eq!(
1995 from_value::<ModelStructuredOutputLevel>(json!(expected)).unwrap(),
1996 value
1997 );
1998 }
1999
2000 let modality_set = modalities([
2001 ModelModality::Document,
2002 ModelModality::Text,
2003 ModelModality::Audio,
2004 ]);
2005 assert_eq!(
2006 to_value(&modality_set).unwrap(),
2007 json!(["text", "audio", "document"])
2008 );
2009 assert!(modality_set.contains(ModelModality::Audio));
2010 assert_eq!(modality_set.len(), 3);
2011 assert!(ModelModalities::try_new([ModelModality::Text, ModelModality::Text]).is_err());
2012 assert!(from_value::<ModelModalities>(json!(["text", "text"])).is_err());
2013
2014 let choice_set = choices([
2015 ModelToolChoice::Specific,
2016 ModelToolChoice::Auto,
2017 ModelToolChoice::Required,
2018 ]);
2019 assert_eq!(
2020 to_value(&choice_set).unwrap(),
2021 json!(["auto", "required", "specific"])
2022 );
2023 assert!(choice_set.contains(ModelToolChoice::Specific));
2024 assert!(ModelToolChoices::try_new([ModelToolChoice::Auto, ModelToolChoice::Auto]).is_err());
2025 assert!(from_value::<ModelToolChoices>(json!(["auto", "auto"])).is_err());
2026
2027 assert!(from_value::<ModelModality>(json!("archive")).is_err());
2028 assert!(from_value::<ModelToolChoice>(json!("forced")).is_err());
2029 assert!(from_value::<ModelStructuredOutputLevel>(Value::Null).is_err());
2030 }
2031
2032 #[test]
2033 fn token_limits_preserve_unknown_and_reject_false_capacity() {
2034 let limits = ModelTokenLimits::new(
2035 Some(TokenCount::new(128_000)),
2036 Some(TokenCount::new(120_000)),
2037 Some(TokenCount::new(16_384)),
2038 )
2039 .unwrap();
2040 assert_eq!(limits.max_context_tokens(), Some(TokenCount::new(128_000)));
2041 assert_eq!(limits.max_input_tokens(), Some(TokenCount::new(120_000)));
2042 assert_eq!(limits.max_output_tokens(), Some(TokenCount::new(16_384)));
2043 assert_eq!(
2044 to_value(&limits).unwrap(),
2045 json!({
2046 "max_context_tokens": "128000",
2047 "max_input_tokens": "120000",
2048 "max_output_tokens": "16384"
2049 })
2050 );
2051 assert_eq!(
2052 from_value::<ModelTokenLimits>(to_value(&limits).unwrap()).unwrap(),
2053 limits
2054 );
2055
2056 let unknown = ModelTokenLimits::unknown();
2057 assert_eq!(to_value(&unknown).unwrap(), json!({}));
2058 assert_eq!(from_value::<ModelTokenLimits>(json!({})).unwrap(), unknown);
2059
2060 assert_eq!(
2061 ModelTokenLimits::new(Some(TokenCount::ZERO), None, None),
2062 Err(ModelTokenLimitsError::ZeroContext)
2063 );
2064 assert_eq!(
2065 ModelTokenLimits::new(None, Some(TokenCount::ZERO), None),
2066 Err(ModelTokenLimitsError::ZeroInput)
2067 );
2068 assert_eq!(
2069 ModelTokenLimits::new(None, None, Some(TokenCount::ZERO)),
2070 Err(ModelTokenLimitsError::ZeroOutput)
2071 );
2072 assert_eq!(
2073 ModelTokenLimits::new(Some(TokenCount::new(10)), Some(TokenCount::new(11)), None,),
2074 Err(ModelTokenLimitsError::InputExceedsContext {
2075 input: TokenCount::new(11),
2076 context: TokenCount::new(10),
2077 })
2078 );
2079 assert_eq!(
2080 ModelTokenLimits::new(Some(TokenCount::new(10)), None, Some(TokenCount::new(11)),),
2081 Err(ModelTokenLimitsError::OutputExceedsContext {
2082 output: TokenCount::new(11),
2083 context: TokenCount::new(10),
2084 })
2085 );
2086 for invalid in [
2087 json!({"max_context_tokens": "0"}),
2088 json!({"max_input_tokens": "0"}),
2089 json!({"max_output_tokens": "0"}),
2090 json!({"max_context_tokens": "10", "max_input_tokens": "11"}),
2091 json!({"unlimited": true}),
2092 Value::Null,
2093 ] {
2094 assert!(
2095 from_value::<ModelTokenLimits>(invalid.clone()).is_err(),
2096 "accepted token limits {invalid}"
2097 );
2098 }
2099 }
2100
2101 #[test]
2102 fn tool_capabilities_bind_profile_capacity_choice_and_strictness() {
2103 let tools = tool_capabilities();
2104 assert!(tools.supports_tool_calling());
2105 assert!(tools.supports_parallel_calls());
2106 assert!(tools.supports_strict_arguments());
2107 assert_eq!(tools.max_definitions(), ExecutionCount::new(64));
2108 assert_eq!(tools.max_calls_per_response(), ExecutionCount::new(8));
2109 assert_eq!(
2110 tools.schema_profile().unwrap().id().as_str(),
2111 "https://schemas.example.com/model-profiles/tool-input/1.0.0"
2112 );
2113 assert!(tools.choices().contains(ModelToolChoice::Auto));
2114 assert_eq!(
2115 from_value::<ModelToolCapabilities>(to_value(&tools).unwrap()).unwrap(),
2116 tools
2117 );
2118
2119 let unsupported = ModelToolCapabilities::unsupported();
2120 assert!(!unsupported.supports_tool_calling());
2121 assert!(!unsupported.supports_parallel_calls());
2122 assert!(!unsupported.supports_strict_arguments());
2123 assert_eq!(
2124 to_value(&unsupported).unwrap(),
2125 json!({
2126 "max_definitions": "0",
2127 "max_calls_per_response": "0",
2128 "choices": [],
2129 "strict_arguments": false
2130 })
2131 );
2132
2133 assert_eq!(
2134 ModelToolCapabilities::new(
2135 None,
2136 ExecutionCount::new(1),
2137 ExecutionCount::new(1),
2138 choices([ModelToolChoice::Auto]),
2139 false,
2140 ),
2141 Err(ModelToolCapabilitiesError::UnsupportedHasCapabilities)
2142 );
2143 assert_eq!(
2144 ModelToolCapabilities::new(
2145 Some(schema("tool")),
2146 ExecutionCount::ZERO,
2147 ExecutionCount::new(1),
2148 choices([ModelToolChoice::Auto]),
2149 false,
2150 ),
2151 Err(ModelToolCapabilitiesError::ZeroDefinitions)
2152 );
2153 assert_eq!(
2154 ModelToolCapabilities::new(
2155 Some(schema("tool")),
2156 ExecutionCount::new(1),
2157 ExecutionCount::ZERO,
2158 choices([ModelToolChoice::Auto]),
2159 false,
2160 ),
2161 Err(ModelToolCapabilitiesError::ZeroCallsPerResponse)
2162 );
2163 assert_eq!(
2164 ModelToolCapabilities::new(
2165 Some(schema("tool")),
2166 ExecutionCount::new(1),
2167 ExecutionCount::new(1),
2168 choices([ModelToolChoice::Required]),
2169 false,
2170 ),
2171 Err(ModelToolCapabilitiesError::MissingAutoChoice)
2172 );
2173
2174 let mut unknown = to_value(&tools).unwrap();
2175 unknown["provider_parallel"] = json!(true);
2176 assert!(from_value::<ModelToolCapabilities>(unknown).is_err());
2177 }
2178
2179 #[test]
2180 fn structured_output_profile_exists_exactly_for_schema_support() {
2181 let unsupported = ModelStructuredOutputCapabilities::unsupported();
2182 let json_only = ModelStructuredOutputCapabilities::json();
2183 let schema_bound =
2184 ModelStructuredOutputCapabilities::json_schema(schema("structured-output"));
2185
2186 assert_eq!(
2187 to_value(&unsupported).unwrap(),
2188 json!({"level": "unsupported"})
2189 );
2190 assert_eq!(to_value(&json_only).unwrap(), json!({"level": "json"}));
2191 assert_eq!(schema_bound.level(), ModelStructuredOutputLevel::JsonSchema);
2192 assert!(schema_bound.schema_profile().is_some());
2193 assert_eq!(
2194 from_value::<ModelStructuredOutputCapabilities>(to_value(&schema_bound).unwrap())
2195 .unwrap(),
2196 schema_bound
2197 );
2198
2199 assert_eq!(
2200 ModelStructuredOutputCapabilities::new(ModelStructuredOutputLevel::JsonSchema, None,),
2201 Err(ModelStructuredOutputCapabilitiesError::MissingSchemaProfile)
2202 );
2203 assert_eq!(
2204 ModelStructuredOutputCapabilities::new(
2205 ModelStructuredOutputLevel::Json,
2206 Some(schema("unexpected")),
2207 ),
2208 Err(ModelStructuredOutputCapabilitiesError::UnexpectedSchemaProfile)
2209 );
2210 assert!(
2211 from_value::<ModelStructuredOutputCapabilities>(json!({
2212 "level": "unsupported",
2213 "schema_profile": to_value(schema("unexpected")).unwrap()
2214 }))
2215 .is_err()
2216 );
2217 }
2218
2219 #[test]
2220 fn model_capabilities_revalidate_text_feature_invariants() {
2221 let capabilities = capabilities();
2222 assert_eq!(
2223 capabilities.input_modalities(),
2224 &modalities([
2225 ModelModality::Text,
2226 ModelModality::Image,
2227 ModelModality::Document,
2228 ])
2229 );
2230 assert_eq!(
2231 capabilities.output_modalities(),
2232 &modalities([ModelModality::Text])
2233 );
2234 assert!(capabilities.supports_streaming());
2235 assert!(capabilities.tools().supports_tool_calling());
2236 assert!(capabilities.supports_reasoning_summaries());
2237 assert_eq!(
2238 from_value::<ModelCapabilities>(to_value(&capabilities).unwrap()).unwrap(),
2239 capabilities
2240 );
2241
2242 assert_eq!(
2243 ModelCapabilities::new(
2244 ModelModalities::empty(),
2245 modalities([ModelModality::Text]),
2246 false,
2247 ModelToolCapabilities::unsupported(),
2248 ModelStructuredOutputCapabilities::unsupported(),
2249 false,
2250 ModelTokenLimits::unknown(),
2251 ),
2252 Err(ModelCapabilitiesError::EmptyInputModalities)
2253 );
2254 assert_eq!(
2255 ModelCapabilities::new(
2256 modalities([ModelModality::Text]),
2257 ModelModalities::empty(),
2258 false,
2259 ModelToolCapabilities::unsupported(),
2260 ModelStructuredOutputCapabilities::unsupported(),
2261 false,
2262 ModelTokenLimits::unknown(),
2263 ),
2264 Err(ModelCapabilitiesError::EmptyOutputModalities)
2265 );
2266 assert_eq!(
2267 ModelCapabilities::new(
2268 modalities([ModelModality::Image]),
2269 modalities([ModelModality::Text]),
2270 false,
2271 tool_capabilities(),
2272 ModelStructuredOutputCapabilities::unsupported(),
2273 false,
2274 ModelTokenLimits::unknown(),
2275 ),
2276 Err(ModelCapabilitiesError::ToolCallingRequiresTextInput)
2277 );
2278 assert_eq!(
2279 ModelCapabilities::new(
2280 modalities([ModelModality::Text]),
2281 modalities([ModelModality::Image]),
2282 false,
2283 tool_capabilities(),
2284 ModelStructuredOutputCapabilities::unsupported(),
2285 false,
2286 ModelTokenLimits::unknown(),
2287 ),
2288 Err(ModelCapabilitiesError::ToolCallingRequiresTextOutput)
2289 );
2290 assert_eq!(
2291 ModelCapabilities::new(
2292 modalities([ModelModality::Image]),
2293 modalities([ModelModality::Image]),
2294 false,
2295 ModelToolCapabilities::unsupported(),
2296 ModelStructuredOutputCapabilities::json(),
2297 false,
2298 ModelTokenLimits::unknown(),
2299 ),
2300 Err(ModelCapabilitiesError::StructuredOutputRequiresTextOutput)
2301 );
2302 assert_eq!(
2303 ModelCapabilities::new(
2304 modalities([ModelModality::Audio]),
2305 modalities([ModelModality::Audio]),
2306 true,
2307 ModelToolCapabilities::unsupported(),
2308 ModelStructuredOutputCapabilities::unsupported(),
2309 true,
2310 ModelTokenLimits::unknown(),
2311 ),
2312 Err(ModelCapabilitiesError::ReasoningSummaryRequiresTextOutput)
2313 );
2314
2315 let mut invalid = to_value(&capabilities).unwrap();
2316 invalid["output_modalities"] = json!(["image"]);
2317 assert!(from_value::<ModelCapabilities>(invalid).is_err());
2318 }
2319
2320 #[test]
2321 fn descriptors_bind_model_metadata_to_one_capability_snapshot() {
2322 let descriptor = descriptor("Private model registry description.");
2323 assert_eq!(descriptor.metadata().kind(), CapabilityKind::Model);
2324 assert_eq!(
2325 descriptor
2326 .metadata()
2327 .identity()
2328 .capability()
2329 .name()
2330 .as_str(),
2331 "models.primary"
2332 );
2333 assert!(descriptor.capabilities().supports_streaming());
2334
2335 let encoded = to_value(&descriptor).unwrap();
2336 assert_eq!(
2337 from_value::<ModelDescriptor>(encoded.clone()).unwrap(),
2338 descriptor
2339 );
2340 assert!(!format!("{descriptor:?}").contains("Private model registry description."));
2341
2342 assert_eq!(
2343 ModelDescriptor::new(
2344 metadata(CapabilityKind::Tool, "Wrong kind."),
2345 capabilities(),
2346 ),
2347 Err(ModelDescriptorError::WrongCapabilityKind {
2348 actual: CapabilityKind::Tool,
2349 })
2350 );
2351
2352 let mut wrong_kind = encoded.clone();
2353 wrong_kind["metadata"]["kind"] = json!("tool");
2354 assert!(from_value::<ModelDescriptor>(wrong_kind).is_err());
2355
2356 let mut unknown = encoded;
2357 unknown["provider_model"] = json!("mutable-alias");
2358 assert!(from_value::<ModelDescriptor>(unknown).is_err());
2359 }
2360
2361 #[test]
2362 fn requirements_reject_implicit_or_incoherent_demands() {
2363 let required_tools = ModelToolRequirements::new(
2364 ExecutionCount::new(12),
2365 ExecutionCount::new(4),
2366 choices([ModelToolChoice::Auto, ModelToolChoice::Specific]),
2367 true,
2368 )
2369 .unwrap();
2370 assert!(required_tools.requires_tool_calling());
2371 assert_eq!(required_tools.min_definitions(), ExecutionCount::new(12));
2372 assert_eq!(
2373 required_tools.min_calls_per_response(),
2374 ExecutionCount::new(4)
2375 );
2376 assert!(required_tools.requires_strict_arguments());
2377 assert_eq!(
2378 from_value::<ModelToolRequirements>(to_value(&required_tools).unwrap()).unwrap(),
2379 required_tools
2380 );
2381 assert!(!ModelToolRequirements::none().requires_tool_calling());
2382
2383 assert_eq!(
2384 ModelToolRequirements::new(
2385 ExecutionCount::new(1),
2386 ExecutionCount::ZERO,
2387 ModelToolChoices::empty(),
2388 false,
2389 ),
2390 Err(ModelToolRequirementsError::CapacityMismatch)
2391 );
2392 assert_eq!(
2393 ModelToolRequirements::new(
2394 ExecutionCount::ZERO,
2395 ExecutionCount::ZERO,
2396 choices([ModelToolChoice::Auto]),
2397 false,
2398 ),
2399 Err(ModelToolRequirementsError::InactiveHasRequirements)
2400 );
2401
2402 let requirements = ModelRequirements::new(
2403 modalities([ModelModality::Text, ModelModality::Image]),
2404 modalities([ModelModality::Text]),
2405 true,
2406 required_tools,
2407 ModelStructuredOutputLevel::JsonSchema,
2408 true,
2409 Some(TokenCount::new(64_000)),
2410 Some(TokenCount::new(48_000)),
2411 Some(TokenCount::new(8_192)),
2412 )
2413 .unwrap();
2414 assert_eq!(
2415 from_value::<ModelRequirements>(to_value(&requirements).unwrap()).unwrap(),
2416 requirements
2417 );
2418 assert_eq!(
2419 ModelRequirements::default().structured_output(),
2420 ModelStructuredOutputLevel::Unsupported
2421 );
2422
2423 for (context, input, output, expected) in [
2424 (
2425 Some(TokenCount::ZERO),
2426 None,
2427 None,
2428 ModelRequirementsError::ZeroContextTokens,
2429 ),
2430 (
2431 None,
2432 Some(TokenCount::ZERO),
2433 None,
2434 ModelRequirementsError::ZeroInputTokens,
2435 ),
2436 (
2437 None,
2438 None,
2439 Some(TokenCount::ZERO),
2440 ModelRequirementsError::ZeroOutputTokens,
2441 ),
2442 ] {
2443 assert_eq!(
2444 ModelRequirements::new(
2445 ModelModalities::empty(),
2446 ModelModalities::empty(),
2447 false,
2448 ModelToolRequirements::none(),
2449 ModelStructuredOutputLevel::Unsupported,
2450 false,
2451 context,
2452 input,
2453 output,
2454 ),
2455 Err(expected)
2456 );
2457 }
2458
2459 let mut unknown = to_value(&requirements).unwrap();
2460 unknown["fallback"] = json!(true);
2461 assert!(from_value::<ModelRequirements>(unknown).is_err());
2462 }
2463
2464 #[test]
2465 fn negotiation_reports_every_unmet_dimension_and_unknown_limit() {
2466 let weak = ModelCapabilities::new(
2467 modalities([ModelModality::Text]),
2468 modalities([ModelModality::Text]),
2469 false,
2470 ModelToolCapabilities::unsupported(),
2471 ModelStructuredOutputCapabilities::unsupported(),
2472 false,
2473 ModelTokenLimits::unknown(),
2474 )
2475 .unwrap();
2476 let requirements = ModelRequirements::new(
2477 modalities([ModelModality::Text, ModelModality::Image]),
2478 modalities([ModelModality::Text, ModelModality::Audio]),
2479 true,
2480 ModelToolRequirements::new(
2481 ExecutionCount::new(5),
2482 ExecutionCount::new(3),
2483 choices([ModelToolChoice::Required, ModelToolChoice::Specific]),
2484 true,
2485 )
2486 .unwrap(),
2487 ModelStructuredOutputLevel::JsonSchema,
2488 true,
2489 Some(TokenCount::new(100)),
2490 Some(TokenCount::new(50)),
2491 Some(TokenCount::new(20)),
2492 )
2493 .unwrap();
2494
2495 let mismatch = weak.satisfies(&requirements).unwrap_err();
2496 assert_eq!(mismatch.len(), 14);
2497 assert!(!mismatch.is_empty());
2498 for issue in [
2499 ModelCapabilityIssue::InputModality {
2500 required: ModelModality::Image,
2501 },
2502 ModelCapabilityIssue::OutputModality {
2503 required: ModelModality::Audio,
2504 },
2505 ModelCapabilityIssue::Streaming {},
2506 ModelCapabilityIssue::ToolCalling {},
2507 ModelCapabilityIssue::ToolDefinitions {
2508 required: ExecutionCount::new(5),
2509 available: ExecutionCount::ZERO,
2510 },
2511 ModelCapabilityIssue::ToolCallsPerResponse {
2512 required: ExecutionCount::new(3),
2513 available: ExecutionCount::ZERO,
2514 },
2515 ModelCapabilityIssue::ToolChoice {
2516 required: ModelToolChoice::Required,
2517 },
2518 ModelCapabilityIssue::ToolChoice {
2519 required: ModelToolChoice::Specific,
2520 },
2521 ModelCapabilityIssue::StrictToolArguments {},
2522 ModelCapabilityIssue::StructuredOutput {
2523 required: ModelStructuredOutputLevel::JsonSchema,
2524 available: ModelStructuredOutputLevel::Unsupported,
2525 },
2526 ModelCapabilityIssue::ReasoningSummary {},
2527 ModelCapabilityIssue::ContextTokens {
2528 required: TokenCount::new(100),
2529 available: None,
2530 },
2531 ModelCapabilityIssue::InputTokens {
2532 required: TokenCount::new(50),
2533 available: None,
2534 },
2535 ModelCapabilityIssue::OutputTokens {
2536 required: TokenCount::new(20),
2537 available: None,
2538 },
2539 ] {
2540 assert!(mismatch.contains(&issue), "missing issue {issue:?}");
2541 }
2542 assert_eq!(
2543 from_value::<ModelCapabilityMismatch>(to_value(&mismatch).unwrap()).unwrap(),
2544 mismatch
2545 );
2546 }
2547
2548 #[test]
2549 fn mismatch_wire_rejects_empty_duplicate_and_incoherent_diagnostics() {
2550 assert_eq!(
2551 ModelCapabilityMismatch::try_new([]),
2552 Err(ModelCapabilityMismatchError::Empty)
2553 );
2554 let issue = ModelCapabilityIssue::Streaming {};
2555 assert_eq!(
2556 ModelCapabilityMismatch::try_new([issue.clone(), issue.clone()]),
2557 Err(ModelCapabilityMismatchError::Duplicate { issue })
2558 );
2559 let first_capacity = ModelCapabilityIssue::ToolDefinitions {
2560 required: ExecutionCount::new(5),
2561 available: ExecutionCount::new(2),
2562 };
2563 let second_capacity = ModelCapabilityIssue::ToolDefinitions {
2564 required: ExecutionCount::new(6),
2565 available: ExecutionCount::new(2),
2566 };
2567 assert_eq!(
2568 ModelCapabilityMismatch::try_new([first_capacity, second_capacity.clone(),]),
2569 Err(ModelCapabilityMismatchError::DuplicateDimension {
2570 issue: second_capacity,
2571 })
2572 );
2573 let incoherent = ModelCapabilityIssue::OutputTokens {
2574 required: TokenCount::new(10),
2575 available: Some(TokenCount::new(10)),
2576 };
2577 assert_eq!(
2578 ModelCapabilityMismatch::try_new([incoherent.clone()]),
2579 Err(ModelCapabilityMismatchError::IncoherentIssue { issue: incoherent })
2580 );
2581 assert!(from_value::<ModelCapabilityMismatch>(json!([])).is_err());
2582 }
2583
2584 #[test]
2585 fn exact_or_weaker_requirements_pass_without_silent_downgrade() {
2586 let requirements = ModelRequirements::new(
2587 modalities([ModelModality::Text, ModelModality::Image]),
2588 modalities([ModelModality::Text]),
2589 true,
2590 ModelToolRequirements::new(
2591 ExecutionCount::new(32),
2592 ExecutionCount::new(4),
2593 choices([ModelToolChoice::Auto, ModelToolChoice::Specific]),
2594 true,
2595 )
2596 .unwrap(),
2597 ModelStructuredOutputLevel::JsonSchema,
2598 true,
2599 Some(TokenCount::new(128_000)),
2600 Some(TokenCount::new(100_000)),
2601 Some(TokenCount::new(16_384)),
2602 )
2603 .unwrap();
2604 assert!(capabilities().satisfies(&requirements).is_ok());
2605
2606 let excessive_output = ModelRequirements::new(
2607 ModelModalities::empty(),
2608 ModelModalities::empty(),
2609 false,
2610 ModelToolRequirements::none(),
2611 ModelStructuredOutputLevel::Unsupported,
2612 false,
2613 None,
2614 None,
2615 Some(TokenCount::new(16_385)),
2616 )
2617 .unwrap();
2618 let mismatch = capabilities().satisfies(&excessive_output).unwrap_err();
2619 assert_eq!(mismatch.len(), 1);
2620 assert!(mismatch.contains(&ModelCapabilityIssue::OutputTokens {
2621 required: TokenCount::new(16_385),
2622 available: Some(TokenCount::new(16_384)),
2623 }));
2624 }
2625
2626 #[test]
2627 fn model_contract_schemas_publish_closed_objects_and_set_bounds() {
2628 for schema in [
2629 to_value(schemars::schema_for!(ModelTokenLimits)).unwrap(),
2630 to_value(schemars::schema_for!(ModelToolCapabilities)).unwrap(),
2631 to_value(schemars::schema_for!(ModelStructuredOutputCapabilities)).unwrap(),
2632 to_value(schemars::schema_for!(ModelCapabilities)).unwrap(),
2633 to_value(schemars::schema_for!(ModelDescriptor)).unwrap(),
2634 to_value(schemars::schema_for!(ModelToolRequirements)).unwrap(),
2635 to_value(schemars::schema_for!(ModelRequirements)).unwrap(),
2636 ] {
2637 assert_eq!(schema["type"], "object");
2638 assert_eq!(schema["additionalProperties"], false);
2639 }
2640
2641 let modalities = to_value(schemars::schema_for!(ModelModalities)).unwrap();
2642 assert_eq!(modalities["maxItems"], ModelModalities::MAX_LEN);
2643 assert_eq!(modalities["uniqueItems"], true);
2644 let choices = to_value(schemars::schema_for!(ModelToolChoices)).unwrap();
2645 assert_eq!(choices["maxItems"], ModelToolChoices::MAX_LEN);
2646 assert_eq!(choices["uniqueItems"], true);
2647 let mismatch = to_value(schemars::schema_for!(ModelCapabilityMismatch)).unwrap();
2648 assert_eq!(mismatch["minItems"], 1);
2649 assert_eq!(mismatch["maxItems"], ModelCapabilityMismatch::MAX_ISSUES);
2650 assert_eq!(mismatch["uniqueItems"], true);
2651 }
2652
2653 proptest! {
2654 #[test]
2655 fn every_valid_token_limit_tuple_round_trips(
2656 context in 1_u64..=1_000_000_u64,
2657 input_seed in any::<u64>(),
2658 output_seed in any::<u64>(),
2659 ) {
2660 let input = 1 + input_seed % context;
2661 let output = 1 + output_seed % context;
2662 let limits = ModelTokenLimits::new(
2663 Some(TokenCount::new(context)),
2664 Some(TokenCount::new(input)),
2665 Some(TokenCount::new(output)),
2666 ).unwrap();
2667 let encoded = serde_json::to_vec(&limits).unwrap();
2668 let decoded = serde_json::from_slice::<ModelTokenLimits>(&encoded).unwrap();
2669 prop_assert_eq!(decoded, limits);
2670 }
2671
2672 #[test]
2673 fn every_requirement_within_known_token_capacity_is_satisfied(
2674 context in 1_u64..=1_000_000_u64,
2675 input_seed in any::<u64>(),
2676 output_seed in any::<u64>(),
2677 required_context_seed in any::<u64>(),
2678 required_input_seed in any::<u64>(),
2679 required_output_seed in any::<u64>(),
2680 ) {
2681 let input = 1 + input_seed % context;
2682 let output = 1 + output_seed % context;
2683 let capabilities = ModelCapabilities::new(
2684 modalities([ModelModality::Text]),
2685 modalities([ModelModality::Text]),
2686 false,
2687 ModelToolCapabilities::unsupported(),
2688 ModelStructuredOutputCapabilities::unsupported(),
2689 false,
2690 ModelTokenLimits::new(
2691 Some(TokenCount::new(context)),
2692 Some(TokenCount::new(input)),
2693 Some(TokenCount::new(output)),
2694 ).unwrap(),
2695 ).unwrap();
2696 let requirements = ModelRequirements::new(
2697 ModelModalities::empty(),
2698 ModelModalities::empty(),
2699 false,
2700 ModelToolRequirements::none(),
2701 ModelStructuredOutputLevel::Unsupported,
2702 false,
2703 Some(TokenCount::new(1 + required_context_seed % context)),
2704 Some(TokenCount::new(1 + required_input_seed % input)),
2705 Some(TokenCount::new(1 + required_output_seed % output)),
2706 ).unwrap();
2707 prop_assert!(capabilities.satisfies(&requirements).is_ok());
2708 }
2709 }
2710}