1use std::{borrow::Borrow, collections::BTreeSet, fmt, str::FromStr};
7
8use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
9use serde::{
10 Deserialize, Deserializer, Serialize, Serializer,
11 de::{self, SeqAccess},
12};
13use thiserror::Error;
14
15use crate::{
16 ArtifactModality, AttemptId, BoundedJson, ByteCount, CapabilityIdentity, CapabilityName,
17 ContentPart, ContentSource, ContentTrust, ExecutionCount, Extensions, JsonContent,
18 ModelDescriptor, ModelModality, ModelProviderReplay, ModelRequest, ModelTextOutputFormat,
19 ModelToolSelection, SchemaReference, TextContent, TokenCount,
20};
21
22const MEBIBYTE: u64 = 1024 * 1024;
23const PROVIDER_IDENTIFIER_PATTERN: &str = "^[!-~]+$";
24
25#[derive(Clone, Debug, Eq, Error, PartialEq)]
27#[non_exhaustive]
28pub enum ModelProviderIdentifierError {
29 #[error("model provider identifier must not be empty")]
31 Empty,
32 #[error("model provider identifier is {actual} bytes; maximum is {max}")]
34 TooLong {
35 max: usize,
37 actual: usize,
39 },
40 #[error("model provider identifier contains an invalid byte at offset {index}")]
42 InvalidByte {
43 index: usize,
45 },
46}
47
48fn validate_provider_identifier(
49 value: &str,
50 maximum: usize,
51) -> Result<(), ModelProviderIdentifierError> {
52 if value.is_empty() {
53 return Err(ModelProviderIdentifierError::Empty);
54 }
55 if value.len() > maximum {
56 return Err(ModelProviderIdentifierError::TooLong {
57 max: maximum,
58 actual: value.len(),
59 });
60 }
61 if let Some((index, _)) = value
62 .bytes()
63 .enumerate()
64 .find(|(_, byte)| !(b'!'..=b'~').contains(byte))
65 {
66 return Err(ModelProviderIdentifierError::InvalidByte { index });
67 }
68 Ok(())
69}
70
71macro_rules! define_provider_identifier {
72 ($name:ident, $visitor:ident, $schema_name:literal, $documentation:literal) => {
73 #[doc = $documentation]
74 #[derive(Clone, Eq, Hash, Ord, PartialEq, PartialOrd)]
78 pub struct $name(Box<str>);
79
80 impl $name {
81 pub const MAX_BYTES: usize = 512;
83
84 pub fn new(value: impl Into<String>) -> Result<Self, ModelProviderIdentifierError> {
91 let value = value.into();
92 validate_provider_identifier(&value, Self::MAX_BYTES)?;
93 Ok(Self(value.into_boxed_str()))
94 }
95
96 #[must_use]
98 pub fn as_str(&self) -> &str {
99 &self.0
100 }
101
102 #[must_use]
104 pub fn len_bytes(&self) -> usize {
105 self.0.len()
106 }
107 }
108
109 impl AsRef<str> for $name {
110 fn as_ref(&self) -> &str {
111 self.as_str()
112 }
113 }
114
115 impl Borrow<str> for $name {
116 fn borrow(&self) -> &str {
117 self.as_str()
118 }
119 }
120
121 impl fmt::Debug for $name {
122 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
123 formatter
124 .debug_struct(stringify!($name))
125 .field("bytes", &self.len_bytes())
126 .finish_non_exhaustive()
127 }
128 }
129
130 impl FromStr for $name {
131 type Err = ModelProviderIdentifierError;
132
133 fn from_str(value: &str) -> Result<Self, Self::Err> {
134 Self::new(value)
135 }
136 }
137
138 impl TryFrom<String> for $name {
139 type Error = ModelProviderIdentifierError;
140
141 fn try_from(value: String) -> Result<Self, Self::Error> {
142 Self::new(value)
143 }
144 }
145
146 impl TryFrom<&str> for $name {
147 type Error = ModelProviderIdentifierError;
148
149 fn try_from(value: &str) -> Result<Self, Self::Error> {
150 Self::new(value)
151 }
152 }
153
154 impl Serialize for $name {
155 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
156 where
157 S: Serializer,
158 {
159 serializer.serialize_str(self.as_str())
160 }
161 }
162
163 impl<'de> Deserialize<'de> for $name {
164 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
165 where
166 D: Deserializer<'de>,
167 {
168 deserializer.deserialize_string($visitor)
169 }
170 }
171
172 struct $visitor;
173
174 impl de::Visitor<'_> for $visitor {
175 type Value = $name;
176
177 fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
178 formatter.write_str("an opaque visible-ASCII model provider identifier")
179 }
180
181 fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
182 where
183 E: de::Error,
184 {
185 $name::try_from(value).map_err(E::custom)
186 }
187
188 fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
189 where
190 E: de::Error,
191 {
192 $name::try_from(value).map_err(E::custom)
193 }
194 }
195
196 impl JsonSchema for $name {
197 fn schema_name() -> std::borrow::Cow<'static, str> {
198 $schema_name.into()
199 }
200
201 fn schema_id() -> std::borrow::Cow<'static, str> {
202 concat!(module_path!(), "::", $schema_name).into()
203 }
204
205 fn json_schema(_: &mut SchemaGenerator) -> Schema {
206 json_schema!({
207 "type": "string",
208 "minLength": 1,
209 "maxLength": 512,
210 "pattern": PROVIDER_IDENTIFIER_PATTERN
211 })
212 }
213
214 fn inline_schema() -> bool {
215 true
216 }
217 }
218 };
219}
220
221define_provider_identifier!(
222 ModelProviderModelId,
223 ModelProviderModelIdVisitor,
224 "ModelProviderModelId",
225 "An opaque model identifier reported by the selected provider binding."
226);
227define_provider_identifier!(
228 ModelProviderRequestId,
229 ModelProviderRequestIdVisitor,
230 "ModelProviderRequestId",
231 "An opaque request correlation identifier reported or recognized by a model provider."
232);
233define_provider_identifier!(
234 ModelProviderResponseId,
235 ModelProviderResponseIdVisitor,
236 "ModelProviderResponseId",
237 "An opaque response identifier reported by a model provider."
238);
239define_provider_identifier!(
240 ModelProviderToolCallId,
241 ModelProviderToolCallIdVisitor,
242 "ModelProviderToolCallId",
243 "An opaque provider correlation identifier for one proposed tool call."
244);
245
246#[derive(
251 Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
252)]
253#[non_exhaustive]
254#[serde(rename_all = "snake_case")]
255pub enum ModelFinishReason {
256 Completed,
258 ToolCalls,
260 OutputLimit,
262 ContextLimit,
264 Refused,
266 ContentFiltered,
268 Paused,
270}
271
272#[derive(Clone, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
277#[serde(deny_unknown_fields)]
278pub struct ModelResponseProvenance {
279 attempt_id: AttemptId,
280 model: CapabilityIdentity,
281 #[serde(skip_serializing_if = "Option::is_none")]
282 provider_model_id: Option<ModelProviderModelId>,
283 #[serde(skip_serializing_if = "Option::is_none")]
284 provider_request_id: Option<ModelProviderRequestId>,
285 #[serde(skip_serializing_if = "Option::is_none")]
286 provider_response_id: Option<ModelProviderResponseId>,
287}
288
289impl ModelResponseProvenance {
290 #[must_use]
292 pub fn new(
293 attempt_id: AttemptId,
294 model: CapabilityIdentity,
295 provider_model_id: Option<ModelProviderModelId>,
296 provider_response_id: Option<ModelProviderResponseId>,
297 ) -> Self {
298 Self {
299 attempt_id,
300 model,
301 provider_model_id,
302 provider_request_id: None,
303 provider_response_id,
304 }
305 }
306
307 #[must_use]
312 pub fn with_provider_request_id(mut self, provider_request_id: ModelProviderRequestId) -> Self {
313 self.provider_request_id = Some(provider_request_id);
314 self
315 }
316
317 #[must_use]
319 pub const fn attempt_id(&self) -> AttemptId {
320 self.attempt_id
321 }
322
323 #[must_use]
325 pub const fn model(&self) -> &CapabilityIdentity {
326 &self.model
327 }
328
329 #[must_use]
331 pub const fn provider_model_id(&self) -> Option<&ModelProviderModelId> {
332 self.provider_model_id.as_ref()
333 }
334
335 #[must_use]
337 pub const fn provider_request_id(&self) -> Option<&ModelProviderRequestId> {
338 self.provider_request_id.as_ref()
339 }
340
341 #[must_use]
343 pub const fn provider_response_id(&self) -> Option<&ModelProviderResponseId> {
344 self.provider_response_id.as_ref()
345 }
346}
347
348impl fmt::Debug for ModelResponseProvenance {
349 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
350 formatter
351 .debug_struct("ModelResponseProvenance")
352 .field("attempt_id", &self.attempt_id)
353 .field("model", &self.model)
354 .field("provider_model_id", &self.provider_model_id)
355 .field("provider_request_id", &self.provider_request_id)
356 .field("provider_response_id", &self.provider_response_id)
357 .finish_non_exhaustive()
358 }
359}
360
361#[allow(clippy::struct_field_names)]
369#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
370#[serde(deny_unknown_fields)]
371pub struct ModelUsage {
372 input_tokens: TokenCount,
373 #[serde(skip_serializing_if = "Option::is_none")]
374 cached_input_tokens: Option<TokenCount>,
375 output_tokens: TokenCount,
376 #[serde(skip_serializing_if = "Option::is_none")]
377 reasoning_tokens: Option<TokenCount>,
378}
379
380impl ModelUsage {
381 pub const fn new(
388 input_tokens: TokenCount,
389 cached_input_tokens: Option<TokenCount>,
390 output_tokens: TokenCount,
391 reasoning_tokens: Option<TokenCount>,
392 ) -> Result<Self, ModelUsageError> {
393 if let Some(cached) = cached_input_tokens {
394 if cached.get() > input_tokens.get() {
395 return Err(ModelUsageError::CachedInputExceedsInput {
396 input_tokens,
397 cached_input_tokens: cached,
398 });
399 }
400 }
401 if let Some(reasoning) = reasoning_tokens {
402 if reasoning.get() > output_tokens.get() {
403 return Err(ModelUsageError::ReasoningExceedsOutput {
404 output_tokens,
405 reasoning_tokens: reasoning,
406 });
407 }
408 }
409 if input_tokens.checked_add(output_tokens).is_none() {
410 return Err(ModelUsageError::TotalTokensOverflow);
411 }
412 Ok(Self {
413 input_tokens,
414 cached_input_tokens,
415 output_tokens,
416 reasoning_tokens,
417 })
418 }
419
420 #[must_use]
422 pub const fn input_tokens(&self) -> TokenCount {
423 self.input_tokens
424 }
425
426 #[must_use]
428 pub const fn cached_input_tokens(&self) -> Option<TokenCount> {
429 self.cached_input_tokens
430 }
431
432 #[must_use]
434 pub const fn output_tokens(&self) -> TokenCount {
435 self.output_tokens
436 }
437
438 #[must_use]
440 pub const fn reasoning_tokens(&self) -> Option<TokenCount> {
441 self.reasoning_tokens
442 }
443
444 #[must_use]
446 pub fn total_tokens(&self) -> TokenCount {
447 self.input_tokens
448 .checked_add(self.output_tokens)
449 .expect("validated model usage cannot overflow")
450 }
451}
452
453#[derive(Deserialize)]
454#[serde(deny_unknown_fields)]
455#[allow(clippy::struct_field_names)]
456struct ModelUsageWire {
457 input_tokens: TokenCount,
458 #[serde(default)]
459 cached_input_tokens: Option<TokenCount>,
460 output_tokens: TokenCount,
461 #[serde(default)]
462 reasoning_tokens: Option<TokenCount>,
463}
464
465impl<'de> Deserialize<'de> for ModelUsage {
466 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
467 where
468 D: Deserializer<'de>,
469 {
470 let wire = ModelUsageWire::deserialize(deserializer)?;
471 Self::new(
472 wire.input_tokens,
473 wire.cached_input_tokens,
474 wire.output_tokens,
475 wire.reasoning_tokens,
476 )
477 .map_err(de::Error::custom)
478 }
479}
480
481#[derive(Clone, Debug, Eq, Error, PartialEq)]
483#[non_exhaustive]
484pub enum ModelUsageError {
485 #[error(
487 "cached input tokens {cached_input_tokens} exceed inclusive input tokens {input_tokens}"
488 )]
489 CachedInputExceedsInput {
490 input_tokens: TokenCount,
492 cached_input_tokens: TokenCount,
494 },
495 #[error("reasoning tokens {reasoning_tokens} exceed inclusive output tokens {output_tokens}")]
497 ReasoningExceedsOutput {
498 output_tokens: TokenCount,
500 reasoning_tokens: TokenCount,
502 },
503 #[error("model usage input and output tokens overflow total tokens")]
505 TotalTokensOverflow,
506}
507
508#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
517#[serde(deny_unknown_fields)]
518pub struct ModelToolCallProposal {
519 tool: CapabilityIdentity,
520 #[serde(skip_serializing_if = "Option::is_none")]
521 provider_call_id: Option<ModelProviderToolCallId>,
522 arguments: BoundedJson,
523 extensions: Extensions,
524}
525
526impl ModelToolCallProposal {
527 pub fn new(
534 tool: CapabilityIdentity,
535 provider_call_id: Option<ModelProviderToolCallId>,
536 arguments: BoundedJson,
537 extensions: Extensions,
538 ) -> Result<Self, ModelToolCallProposalError> {
539 if !arguments.as_value().is_object() {
540 return Err(ModelToolCallProposalError::ArgumentsMustBeObject);
541 }
542 Ok(Self {
543 tool,
544 provider_call_id,
545 arguments,
546 extensions,
547 })
548 }
549
550 #[must_use]
552 pub const fn tool(&self) -> &CapabilityIdentity {
553 &self.tool
554 }
555
556 #[must_use]
558 pub const fn provider_call_id(&self) -> Option<&ModelProviderToolCallId> {
559 self.provider_call_id.as_ref()
560 }
561
562 #[must_use]
564 pub const fn arguments(&self) -> &BoundedJson {
565 &self.arguments
566 }
567
568 #[must_use]
570 pub const fn extensions(&self) -> &Extensions {
571 &self.extensions
572 }
573}
574
575impl fmt::Debug for ModelToolCallProposal {
576 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
577 formatter
578 .debug_struct("ModelToolCallProposal")
579 .field("tool", &self.tool)
580 .field("provider_call_id", &self.provider_call_id)
581 .field("arguments", &self.arguments)
582 .field("extensions", &self.extensions)
583 .finish_non_exhaustive()
584 }
585}
586
587#[derive(Deserialize)]
588#[serde(deny_unknown_fields)]
589struct ModelToolCallProposalWire {
590 tool: CapabilityIdentity,
591 #[serde(default)]
592 provider_call_id: Option<ModelProviderToolCallId>,
593 arguments: BoundedJson,
594 extensions: Extensions,
595}
596
597impl<'de> Deserialize<'de> for ModelToolCallProposal {
598 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
599 where
600 D: Deserializer<'de>,
601 {
602 let wire = ModelToolCallProposalWire::deserialize(deserializer)?;
603 Self::new(
604 wire.tool,
605 wire.provider_call_id,
606 wire.arguments,
607 wire.extensions,
608 )
609 .map_err(de::Error::custom)
610 }
611}
612
613#[derive(Clone, Debug, Eq, Error, PartialEq)]
615#[non_exhaustive]
616pub enum ModelToolCallProposalError {
617 #[error("model tool-call arguments must be a JSON object")]
619 ArgumentsMustBeObject,
620}
621
622#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
624#[non_exhaustive]
625pub enum ModelOutputItemKind {
626 Content,
628 ReasoningSummary,
630 ToolCall,
632}
633
634#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
641#[serde(
642 tag = "type",
643 content = "content",
644 rename_all = "snake_case",
645 deny_unknown_fields
646)]
647pub enum ModelOutputItem {
648 Content(ContentPart),
650 ReasoningSummary(TextContent),
652 ToolCall(Box<ModelToolCallProposal>),
654}
655
656impl ModelOutputItem {
657 pub fn content(content: ContentPart) -> Result<Self, ModelOutputItemError> {
663 let item = Self::Content(content);
664 item.validate_intrinsic()?;
665 Ok(item)
666 }
667
668 pub fn reasoning_summary(summary: TextContent) -> Result<Self, ModelOutputItemError> {
674 let item = Self::ReasoningSummary(summary);
675 item.validate_intrinsic()?;
676 Ok(item)
677 }
678
679 #[must_use]
681 pub fn tool_call(proposal: ModelToolCallProposal) -> Self {
682 Self::ToolCall(Box::new(proposal))
683 }
684
685 #[must_use]
687 pub const fn kind(&self) -> ModelOutputItemKind {
688 match self {
689 Self::Content(_) => ModelOutputItemKind::Content,
690 Self::ReasoningSummary(_) => ModelOutputItemKind::ReasoningSummary,
691 Self::ToolCall(_) => ModelOutputItemKind::ToolCall,
692 }
693 }
694
695 #[must_use]
697 pub const fn as_content(&self) -> Option<&ContentPart> {
698 match self {
699 Self::Content(content) => Some(content),
700 Self::ReasoningSummary(_) | Self::ToolCall(_) => None,
701 }
702 }
703
704 #[must_use]
706 pub const fn as_reasoning_summary(&self) -> Option<&TextContent> {
707 match self {
708 Self::ReasoningSummary(summary) => Some(summary),
709 Self::Content(_) | Self::ToolCall(_) => None,
710 }
711 }
712
713 #[must_use]
715 pub const fn as_tool_call(&self) -> Option<&ModelToolCallProposal> {
716 match self {
717 Self::ToolCall(proposal) => Some(proposal),
718 Self::Content(_) | Self::ReasoningSummary(_) => None,
719 }
720 }
721
722 pub(crate) fn validate_intrinsic(&self) -> Result<(), ModelOutputItemError> {
723 match self {
724 Self::Content(content) => {
725 let expected_source = match content {
726 ContentPart::Text(_) | ContentPart::Json(_) => ContentSource::Model,
727 ContentPart::Artifact(_) => ContentSource::Artifact,
728 };
729 validate_output_metadata(self.kind(), content.metadata(), expected_source)
730 }
731 Self::ReasoningSummary(summary) => {
732 validate_output_metadata(self.kind(), summary.metadata(), ContentSource::Model)
733 }
734 Self::ToolCall(_) => Ok(()),
735 }
736 }
737
738 pub(crate) fn inline_payload_bytes(&self) -> usize {
739 match self {
740 Self::Content(content) => content.inline_payload_bytes(),
741 Self::ReasoningSummary(summary) => summary.text().len(),
742 Self::ToolCall(proposal) => {
743 proposal.arguments().stats().compact_bytes() + proposal.extensions().compact_bytes()
744 }
745 }
746 }
747}
748
749pub(crate) fn validate_output_metadata(
750 kind: ModelOutputItemKind,
751 metadata: &crate::ContentMetadata,
752 expected_source: ContentSource,
753) -> Result<(), ModelOutputItemError> {
754 if metadata.source() != expected_source {
755 return Err(ModelOutputItemError::InvalidSource {
756 kind,
757 expected: expected_source,
758 actual: metadata.source(),
759 });
760 }
761 if metadata.trust() != ContentTrust::Untrusted {
762 return Err(ModelOutputItemError::InvalidTrust {
763 kind,
764 actual: metadata.trust(),
765 });
766 }
767 Ok(())
768}
769
770impl fmt::Debug for ModelOutputItem {
771 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
772 match self {
773 Self::Content(content) => formatter
774 .debug_tuple("ModelOutputItem::Content")
775 .field(content)
776 .finish(),
777 Self::ReasoningSummary(summary) => formatter
778 .debug_tuple("ModelOutputItem::ReasoningSummary")
779 .field(summary)
780 .finish(),
781 Self::ToolCall(proposal) => formatter
782 .debug_tuple("ModelOutputItem::ToolCall")
783 .field(proposal)
784 .finish(),
785 }
786 }
787}
788
789#[derive(Deserialize)]
790#[serde(
791 tag = "type",
792 content = "content",
793 rename_all = "snake_case",
794 deny_unknown_fields
795)]
796enum ModelOutputItemWire {
797 Content(ContentPart),
798 ReasoningSummary(TextContent),
799 ToolCall(Box<ModelToolCallProposal>),
800}
801
802impl<'de> Deserialize<'de> for ModelOutputItem {
803 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
804 where
805 D: Deserializer<'de>,
806 {
807 let item = match ModelOutputItemWire::deserialize(deserializer)? {
808 ModelOutputItemWire::Content(content) => Self::Content(content),
809 ModelOutputItemWire::ReasoningSummary(summary) => Self::ReasoningSummary(summary),
810 ModelOutputItemWire::ToolCall(proposal) => Self::ToolCall(proposal),
811 };
812 item.validate_intrinsic().map_err(de::Error::custom)?;
813 Ok(item)
814 }
815}
816
817#[derive(Clone, Debug, Eq, Error, PartialEq)]
819#[non_exhaustive]
820pub enum ModelOutputItemError {
821 #[error("model output {kind:?} source must be {expected:?}, got {actual:?}")]
823 InvalidSource {
824 kind: ModelOutputItemKind,
826 expected: ContentSource,
828 actual: ContentSource,
830 },
831 #[error("model output {kind:?} must be untrusted, got {actual:?}")]
833 InvalidTrust {
834 kind: ModelOutputItemKind,
836 actual: ContentTrust,
838 },
839}
840
841#[derive(Clone, Eq, PartialEq)]
842struct ModelOutputItems {
843 values: Box<[ModelOutputItem]>,
844 content_items: usize,
845 tool_calls: usize,
846 inline_payload_bytes: ByteCount,
847 modalities: crate::ModelModalities,
848}
849
850impl ModelOutputItems {
851 const MAX_CONTENT_ITEMS: usize = 256;
852 const MAX_TOOL_CALLS: usize = 1024;
853 const MAX_ITEMS: usize = Self::MAX_CONTENT_ITEMS + Self::MAX_TOOL_CALLS;
854 const MAX_INLINE_PAYLOAD_BYTES: ByteCount = ByteCount::new(64 * MEBIBYTE);
855
856 fn try_new<I>(values: I) -> Result<Self, ModelResponseError>
857 where
858 I: IntoIterator<Item = ModelOutputItem>,
859 {
860 let mut output = Vec::new();
861 let mut content_items = 0;
862 let mut tool_calls = 0;
863 let mut inline_payload_bytes = ByteCount::ZERO;
864 let mut modalities = BTreeSet::new();
865 let mut provider_call_ids = BTreeSet::new();
866 for value in values {
867 push_output_item(
868 &mut output,
869 &mut content_items,
870 &mut tool_calls,
871 &mut inline_payload_bytes,
872 &mut modalities,
873 &mut provider_call_ids,
874 value,
875 )?;
876 }
877 Ok(Self {
878 values: output.into_boxed_slice(),
879 content_items,
880 tool_calls,
881 inline_payload_bytes,
882 modalities: crate::ModelModalities::try_new(modalities)
883 .expect("closed output modality set is always valid"),
884 })
885 }
886
887 fn as_slice(&self) -> &[ModelOutputItem] {
888 &self.values
889 }
890}
891
892impl fmt::Debug for ModelOutputItems {
893 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
894 formatter
895 .debug_struct("ModelOutputItems")
896 .field("items", &self.values.len())
897 .field("content_items", &self.content_items)
898 .field("tool_calls", &self.tool_calls)
899 .field("inline_payload_bytes", &self.inline_payload_bytes)
900 .field("modalities", &self.modalities)
901 .finish_non_exhaustive()
902 }
903}
904
905impl Serialize for ModelOutputItems {
906 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
907 where
908 S: Serializer,
909 {
910 self.values.serialize(serializer)
911 }
912}
913
914impl<'de> Deserialize<'de> for ModelOutputItems {
915 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
916 where
917 D: Deserializer<'de>,
918 {
919 deserializer.deserialize_seq(ModelOutputItemsVisitor)
920 }
921}
922
923struct ModelOutputItemsVisitor;
924
925impl<'de> de::Visitor<'de> for ModelOutputItemsVisitor {
926 type Value = ModelOutputItems;
927
928 fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
929 write!(
930 formatter,
931 "an ordered array containing at most {} bounded model output items",
932 ModelOutputItems::MAX_ITEMS
933 )
934 }
935
936 fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
937 where
938 A: SeqAccess<'de>,
939 {
940 let mut values = Vec::with_capacity(
941 sequence
942 .size_hint()
943 .unwrap_or_default()
944 .min(ModelOutputItems::MAX_ITEMS),
945 );
946 let mut content_items = 0;
947 let mut tool_calls = 0;
948 let mut inline_payload_bytes = ByteCount::ZERO;
949 let mut modalities = BTreeSet::new();
950 let mut provider_call_ids = BTreeSet::new();
951 while let Some(value) = sequence.next_element::<ModelOutputItem>()? {
952 push_output_item(
953 &mut values,
954 &mut content_items,
955 &mut tool_calls,
956 &mut inline_payload_bytes,
957 &mut modalities,
958 &mut provider_call_ids,
959 value,
960 )
961 .map_err(de::Error::custom)?;
962 }
963 Ok(ModelOutputItems {
964 values: values.into_boxed_slice(),
965 content_items,
966 tool_calls,
967 inline_payload_bytes,
968 modalities: crate::ModelModalities::try_new(modalities).map_err(de::Error::custom)?,
969 })
970 }
971}
972
973impl JsonSchema for ModelOutputItems {
974 fn schema_name() -> std::borrow::Cow<'static, str> {
975 "ModelResponseOutput".into()
976 }
977
978 fn schema_id() -> std::borrow::Cow<'static, str> {
979 concat!(module_path!(), "::ModelOutputItems").into()
980 }
981
982 fn json_schema(generator: &mut SchemaGenerator) -> Schema {
983 json_schema!({
984 "type": "array",
985 "items": generator.subschema_for::<ModelOutputItem>(),
986 "maxItems": 1280,
987 "description": "Provider-ordered output. Runtime additionally permits at most 256 content/summary items, at most 1024 tool proposals, unique present provider call IDs, and at most 67108864 aggregate inline content, argument, and per-proposal extension bytes."
988 })
989 }
990}
991
992#[allow(clippy::too_many_arguments)]
993fn push_output_item(
994 values: &mut Vec<ModelOutputItem>,
995 content_items: &mut usize,
996 tool_calls: &mut usize,
997 inline_payload_bytes: &mut ByteCount,
998 modalities: &mut BTreeSet<ModelModality>,
999 provider_call_ids: &mut BTreeSet<ModelProviderToolCallId>,
1000 value: ModelOutputItem,
1001) -> Result<(), ModelResponseError> {
1002 if values.len() == ModelOutputItems::MAX_ITEMS {
1003 return Err(ModelResponseError::TooManyOutputItems {
1004 max: ModelOutputItems::MAX_ITEMS,
1005 observed: ModelOutputItems::MAX_ITEMS + 1,
1006 });
1007 }
1008 value
1009 .validate_intrinsic()
1010 .map_err(|error| ModelResponseError::InvalidOutputItem {
1011 index: values.len(),
1012 error,
1013 })?;
1014
1015 match &value {
1016 ModelOutputItem::Content(content) => {
1017 if *content_items == ModelOutputItems::MAX_CONTENT_ITEMS {
1018 return Err(ModelResponseError::TooManyContentItems {
1019 max: ModelOutputItems::MAX_CONTENT_ITEMS,
1020 observed: ModelOutputItems::MAX_CONTENT_ITEMS + 1,
1021 });
1022 }
1023 *content_items += 1;
1024 let modality = content_modality(content).ok_or_else(|| {
1025 ModelResponseError::UnsupportedArtifactModality {
1026 index: values.len(),
1027 modality: match content {
1028 ContentPart::Artifact(artifact) => artifact.representation().modality(),
1029 ContentPart::Text(_) | ContentPart::Json(_) => {
1030 unreachable!("inline content always has a portable modality")
1031 }
1032 },
1033 }
1034 })?;
1035 modalities.insert(modality);
1036 }
1037 ModelOutputItem::ReasoningSummary(_) => {
1038 if *content_items == ModelOutputItems::MAX_CONTENT_ITEMS {
1039 return Err(ModelResponseError::TooManyContentItems {
1040 max: ModelOutputItems::MAX_CONTENT_ITEMS,
1041 observed: ModelOutputItems::MAX_CONTENT_ITEMS + 1,
1042 });
1043 }
1044 *content_items += 1;
1045 }
1046 ModelOutputItem::ToolCall(proposal) => {
1047 if *tool_calls == ModelOutputItems::MAX_TOOL_CALLS {
1048 return Err(ModelResponseError::TooManyToolCalls {
1049 max: ModelOutputItems::MAX_TOOL_CALLS,
1050 observed: ModelOutputItems::MAX_TOOL_CALLS + 1,
1051 });
1052 }
1053 if let Some(provider_call_id) = proposal.provider_call_id() {
1054 if !provider_call_ids.insert(provider_call_id.clone()) {
1055 return Err(ModelResponseError::DuplicateProviderToolCallId);
1056 }
1057 }
1058 *tool_calls += 1;
1059 }
1060 }
1061
1062 let additional = ByteCount::new(value.inline_payload_bytes() as u64);
1063 let Some(observed) = inline_payload_bytes.checked_add(additional) else {
1064 return Err(ModelResponseError::InlinePayloadBytesOverflow);
1065 };
1066 if observed > ModelOutputItems::MAX_INLINE_PAYLOAD_BYTES {
1067 return Err(ModelResponseError::InlinePayloadTooLarge {
1068 maximum: ModelOutputItems::MAX_INLINE_PAYLOAD_BYTES,
1069 observed,
1070 });
1071 }
1072 *inline_payload_bytes = observed;
1073 values.push(value);
1074 Ok(())
1075}
1076
1077const fn content_modality(content: &ContentPart) -> Option<ModelModality> {
1078 match content {
1079 ContentPart::Text(_) | ContentPart::Json(_) => Some(ModelModality::Text),
1080 ContentPart::Artifact(artifact) => match artifact.representation().modality() {
1081 ArtifactModality::Text => Some(ModelModality::Text),
1082 ArtifactModality::Image => Some(ModelModality::Image),
1083 ArtifactModality::Audio => Some(ModelModality::Audio),
1084 ArtifactModality::Video => Some(ModelModality::Video),
1085 ArtifactModality::Document => Some(ModelModality::Document),
1086 ArtifactModality::StructuredData
1087 | ArtifactModality::Archive
1088 | ArtifactModality::Binary => None,
1089 },
1090 }
1091}
1092
1093#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
1101#[serde(deny_unknown_fields)]
1102pub struct ModelResponse {
1103 provenance: ModelResponseProvenance,
1104 output: ModelOutputItems,
1105 finish_reason: ModelFinishReason,
1106 usage: ModelUsage,
1107 extensions: Extensions,
1108 #[serde(skip_serializing_if = "Option::is_none")]
1109 provider_replay: Option<ModelProviderReplay>,
1110}
1111
1112impl ModelResponse {
1113 pub const MAX_CONTENT_ITEMS: usize = ModelOutputItems::MAX_CONTENT_ITEMS;
1115 pub const MAX_TOOL_CALLS: usize = ModelOutputItems::MAX_TOOL_CALLS;
1117 pub const MAX_OUTPUT_ITEMS: usize = ModelOutputItems::MAX_ITEMS;
1119 pub const MAX_INLINE_PAYLOAD_BYTES: ByteCount = ModelOutputItems::MAX_INLINE_PAYLOAD_BYTES;
1121
1122 pub fn new<I>(
1131 provenance: ModelResponseProvenance,
1132 descriptor: &ModelDescriptor,
1133 request: &ModelRequest,
1134 output: I,
1135 finish_reason: ModelFinishReason,
1136 usage: ModelUsage,
1137 extensions: Extensions,
1138 ) -> Result<Self, ModelResponseError>
1139 where
1140 I: IntoIterator<Item = ModelOutputItem>,
1141 {
1142 let response = Self::from_parts(
1143 provenance,
1144 ModelOutputItems::try_new(output)?,
1145 finish_reason,
1146 usage,
1147 extensions,
1148 )?;
1149 response.validate_for(descriptor, request)?;
1150 Ok(response)
1151 }
1152
1153 fn from_parts(
1154 provenance: ModelResponseProvenance,
1155 output: ModelOutputItems,
1156 finish_reason: ModelFinishReason,
1157 usage: ModelUsage,
1158 extensions: Extensions,
1159 ) -> Result<Self, ModelResponseError> {
1160 match (finish_reason, output.tool_calls) {
1161 (ModelFinishReason::ToolCalls, 0) => {
1162 return Err(ModelResponseError::ToolCallsFinishRequiresProposal);
1163 }
1164 (ModelFinishReason::ToolCalls, _) => {}
1165 (reason, calls) if calls > 0 => {
1166 return Err(ModelResponseError::FinishForbidsToolCalls {
1167 finish_reason: reason,
1168 tool_calls: ExecutionCount::new(calls as u64),
1169 });
1170 }
1171 _ => {}
1172 }
1173 Ok(Self {
1174 provenance,
1175 output,
1176 finish_reason,
1177 usage,
1178 extensions,
1179 provider_replay: None,
1180 })
1181 }
1182
1183 pub fn with_provider_replay(
1190 mut self,
1191 provider_replay: ModelProviderReplay,
1192 ) -> Result<Self, ModelResponseError> {
1193 if self.finish_reason != ModelFinishReason::ToolCalls {
1194 return Err(ModelResponseError::ProviderReplayWithoutToolCalls);
1195 }
1196 let observed = self
1197 .output
1198 .inline_payload_bytes
1199 .checked_add(provider_replay.payload_bytes())
1200 .ok_or(ModelResponseError::InlinePayloadBytesOverflow)?;
1201 if observed > Self::MAX_INLINE_PAYLOAD_BYTES {
1202 return Err(ModelResponseError::InlinePayloadTooLarge {
1203 maximum: Self::MAX_INLINE_PAYLOAD_BYTES,
1204 observed,
1205 });
1206 }
1207 self.provider_replay = Some(provider_replay);
1208 Ok(self)
1209 }
1210
1211 pub fn validate_for(
1219 &self,
1220 descriptor: &ModelDescriptor,
1221 request: &ModelRequest,
1222 ) -> Result<(), ModelResponseError> {
1223 let expected_model = descriptor.metadata().identity();
1224 if self.provenance.model() != expected_model {
1225 return Err(ModelResponseError::ModelIdentityMismatch {
1226 expected: Box::new(expected_model.clone()),
1227 actual: Box::new(self.provenance.model().clone()),
1228 });
1229 }
1230 if self.usage.input_tokens() > request.limits().max_input_tokens() {
1231 return Err(ModelResponseError::InputUsageExceedsRequest {
1232 maximum: request.limits().max_input_tokens(),
1233 actual: self.usage.input_tokens(),
1234 });
1235 }
1236 if self.usage.output_tokens() > request.limits().max_output_tokens() {
1237 return Err(ModelResponseError::OutputUsageExceedsRequest {
1238 maximum: request.limits().max_output_tokens(),
1239 actual: self.usage.output_tokens(),
1240 });
1241 }
1242
1243 for (index, item) in self.output.values.iter().enumerate() {
1244 match item {
1245 ModelOutputItem::Content(content) => {
1246 let modality = content_modality(content).ok_or_else(|| {
1247 ModelResponseError::UnsupportedArtifactModality {
1248 index,
1249 modality: match content {
1250 ContentPart::Artifact(artifact) => {
1251 artifact.representation().modality()
1252 }
1253 ContentPart::Text(_) | ContentPart::Json(_) => {
1254 unreachable!("inline content always has a portable modality")
1255 }
1256 },
1257 }
1258 })?;
1259 if !request.output_modalities().contains(modality) {
1260 return Err(ModelResponseError::OutputModalityNotRequested {
1261 index,
1262 modality,
1263 });
1264 }
1265 }
1266 ModelOutputItem::ReasoningSummary(_) => {
1267 if !request.requires_reasoning_summaries() {
1268 return Err(ModelResponseError::ReasoningSummaryNotRequested { index });
1269 }
1270 }
1271 ModelOutputItem::ToolCall(proposal) => {
1272 validate_tool_proposal(index, proposal, request)?;
1273 }
1274 }
1275 }
1276
1277 let actual_calls = ExecutionCount::new(self.output.tool_calls as u64);
1278 if actual_calls > request.max_tool_calls_per_response() {
1279 return Err(ModelResponseError::ToolCallsExceedRequest {
1280 maximum: request.max_tool_calls_per_response(),
1281 actual: actual_calls,
1282 });
1283 }
1284
1285 if self.finish_reason == ModelFinishReason::Completed
1286 && matches!(
1287 request.tool_selection(),
1288 ModelToolSelection::Required {} | ModelToolSelection::Specific { .. }
1289 )
1290 {
1291 return Err(ModelResponseError::RequiredToolCallMissing);
1292 }
1293
1294 if self.finish_reason == ModelFinishReason::Completed {
1295 validate_completed_text_format(&self.output, request.text_output_format())?;
1296 }
1297 Ok(())
1298 }
1299
1300 #[must_use]
1302 pub const fn provenance(&self) -> &ModelResponseProvenance {
1303 &self.provenance
1304 }
1305
1306 #[must_use]
1308 pub fn output(&self) -> &[ModelOutputItem] {
1309 self.output.as_slice()
1310 }
1311
1312 pub fn tool_calls(&self) -> impl Iterator<Item = &ModelToolCallProposal> {
1314 self.output
1315 .values
1316 .iter()
1317 .filter_map(ModelOutputItem::as_tool_call)
1318 }
1319
1320 #[must_use]
1322 pub const fn tool_call_count(&self) -> usize {
1323 self.output.tool_calls
1324 }
1325
1326 #[must_use]
1328 pub const fn finish_reason(&self) -> ModelFinishReason {
1329 self.finish_reason
1330 }
1331
1332 #[must_use]
1334 pub const fn usage(&self) -> &ModelUsage {
1335 &self.usage
1336 }
1337
1338 #[must_use]
1340 pub const fn extensions(&self) -> &Extensions {
1341 &self.extensions
1342 }
1343
1344 #[must_use]
1346 pub const fn provider_replay(&self) -> Option<&ModelProviderReplay> {
1347 self.provider_replay.as_ref()
1348 }
1349
1350 #[must_use]
1352 pub fn inline_payload_bytes(&self) -> ByteCount {
1353 self.provider_replay
1354 .as_ref()
1355 .map_or(self.output.inline_payload_bytes, |replay| {
1356 self.output
1357 .inline_payload_bytes
1358 .checked_add(replay.payload_bytes())
1359 .expect("provider replay attachment validated byte accounting")
1360 })
1361 }
1362}
1363
1364impl fmt::Debug for ModelResponse {
1365 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1366 formatter
1367 .debug_struct("ModelResponse")
1368 .field("provenance", &self.provenance)
1369 .field("output", &self.output)
1370 .field("finish_reason", &self.finish_reason)
1371 .field("usage", &self.usage)
1372 .field("extensions", &self.extensions)
1373 .field("provider_replay", &self.provider_replay)
1374 .finish_non_exhaustive()
1375 }
1376}
1377
1378#[derive(Deserialize)]
1379#[serde(deny_unknown_fields)]
1380struct ModelResponseWire {
1381 provenance: ModelResponseProvenance,
1382 output: ModelOutputItems,
1383 finish_reason: ModelFinishReason,
1384 usage: ModelUsage,
1385 extensions: Extensions,
1386 #[serde(default)]
1387 provider_replay: Option<ModelProviderReplay>,
1388}
1389
1390impl<'de> Deserialize<'de> for ModelResponse {
1391 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1392 where
1393 D: Deserializer<'de>,
1394 {
1395 let wire = ModelResponseWire::deserialize(deserializer)?;
1396 let mut response = Self::from_parts(
1397 wire.provenance,
1398 wire.output,
1399 wire.finish_reason,
1400 wire.usage,
1401 wire.extensions,
1402 )
1403 .map_err(de::Error::custom)?;
1404 if let Some(provider_replay) = wire.provider_replay {
1405 response = response
1406 .with_provider_replay(provider_replay)
1407 .map_err(de::Error::custom)?;
1408 }
1409 Ok(response)
1410 }
1411}
1412
1413fn validate_tool_proposal(
1414 index: usize,
1415 proposal: &ModelToolCallProposal,
1416 request: &ModelRequest,
1417) -> Result<(), ModelResponseError> {
1418 let Some(expected) = request.tool(proposal.tool().name()) else {
1419 return Err(ModelResponseError::ToolNotRequested {
1420 index,
1421 tool: Box::new(proposal.tool().clone()),
1422 });
1423 };
1424 let expected_identity = expected.metadata().identity();
1425 if proposal.tool() != expected_identity {
1426 return Err(ModelResponseError::ToolIdentityMismatch {
1427 index,
1428 expected: Box::new(expected_identity.clone()),
1429 actual: Box::new(proposal.tool().clone()),
1430 });
1431 }
1432 if let ModelToolSelection::Specific { name } = request.tool_selection() {
1433 if proposal.tool().name() != name {
1434 return Err(ModelResponseError::SpecificToolMismatch {
1435 index,
1436 expected: name.clone(),
1437 actual: proposal.tool().name().clone(),
1438 });
1439 }
1440 }
1441 Ok(())
1442}
1443
1444fn validate_completed_text_format(
1445 output: &ModelOutputItems,
1446 format: Option<&ModelTextOutputFormat>,
1447) -> Result<(), ModelResponseError> {
1448 let Some(format) = format else {
1449 return Ok(());
1450 };
1451
1452 let textual = output
1453 .values
1454 .iter()
1455 .enumerate()
1456 .filter_map(|(index, item)| match item {
1457 ModelOutputItem::Content(ContentPart::Text(_)) => {
1458 Some((index, CompletedTextItem::Text))
1459 }
1460 ModelOutputItem::Content(ContentPart::Json(content)) => {
1461 Some((index, CompletedTextItem::Json(content)))
1462 }
1463 ModelOutputItem::Content(ContentPart::Artifact(artifact))
1464 if artifact.representation().modality() == ArtifactModality::Text =>
1465 {
1466 Some((index, CompletedTextItem::Artifact))
1467 }
1468 ModelOutputItem::Content(ContentPart::Artifact(_))
1469 | ModelOutputItem::ReasoningSummary(_)
1470 | ModelOutputItem::ToolCall(_) => None,
1471 })
1472 .collect::<Vec<_>>();
1473
1474 match format {
1475 ModelTextOutputFormat::Text {} => {
1476 if let Some((index, _)) = textual
1477 .iter()
1478 .find(|(_, item)| matches!(item, CompletedTextItem::Json(_)))
1479 {
1480 return Err(ModelResponseError::PlainTextCompletionContainsJson { index: *index });
1481 }
1482 }
1483 ModelTextOutputFormat::Json {} | ModelTextOutputFormat::JsonSchema { .. } => {
1484 if let Some((index, _)) = textual
1485 .iter()
1486 .find(|(_, item)| !matches!(item, CompletedTextItem::Json(_)))
1487 {
1488 return Err(ModelResponseError::StructuredCompletionContainsText { index: *index });
1489 }
1490 let json = textual
1491 .iter()
1492 .filter_map(|(index, item)| match item {
1493 CompletedTextItem::Json(content) => Some((*index, *content)),
1494 CompletedTextItem::Text | CompletedTextItem::Artifact => None,
1495 })
1496 .collect::<Vec<_>>();
1497 if json.len() != 1 {
1498 return Err(ModelResponseError::StructuredCompletionJsonCount {
1499 actual: json.len(),
1500 });
1501 }
1502 let (index, content) = json[0];
1503 match format {
1504 ModelTextOutputFormat::Json {} if content.schema().is_some() => {
1505 return Err(ModelResponseError::UnexpectedOutputSchema { index });
1506 }
1507 ModelTextOutputFormat::JsonSchema { schema }
1508 if content.schema() != Some(schema) =>
1509 {
1510 return Err(ModelResponseError::OutputSchemaMismatch {
1511 index,
1512 expected: Box::new(schema.clone()),
1513 actual: content.schema().cloned().map(Box::new),
1514 });
1515 }
1516 ModelTextOutputFormat::Json {}
1517 | ModelTextOutputFormat::JsonSchema { .. }
1518 | ModelTextOutputFormat::Text {} => {}
1519 }
1520 }
1521 }
1522 Ok(())
1523}
1524
1525enum CompletedTextItem<'a> {
1526 Text,
1527 Json(&'a JsonContent),
1528 Artifact,
1529}
1530
1531#[derive(Clone, Debug, Eq, Error, PartialEq)]
1533#[non_exhaustive]
1534pub enum ModelResponseError {
1535 #[error("model response contains at least {observed} output items; maximum is {max}")]
1537 TooManyOutputItems {
1538 max: usize,
1540 observed: usize,
1542 },
1543 #[error("model response contains at least {observed} content items; maximum is {max}")]
1545 TooManyContentItems {
1546 max: usize,
1548 observed: usize,
1550 },
1551 #[error("model response contains at least {observed} tool calls; maximum is {max}")]
1553 TooManyToolCalls {
1554 max: usize,
1556 observed: usize,
1558 },
1559 #[error("model response output item {index} is invalid: {error}")]
1561 InvalidOutputItem {
1562 index: usize,
1564 error: ModelOutputItemError,
1566 },
1567 #[error("model response provider tool-call identifiers must be unique when present")]
1569 DuplicateProviderToolCallId,
1570 #[error("model response inline payload-byte accounting overflowed")]
1572 InlinePayloadBytesOverflow,
1573 #[error("model response inline payload is {observed} bytes; maximum is {maximum}")]
1575 InlinePayloadTooLarge {
1576 maximum: ByteCount,
1578 observed: ByteCount,
1580 },
1581 #[error("model response tool_calls finish requires at least one complete proposal")]
1583 ToolCallsFinishRequiresProposal,
1584 #[error("model provider replay is only valid on a tool-calling response")]
1586 ProviderReplayWithoutToolCalls,
1587 #[error("model response finish {finish_reason:?} forbids {tool_calls} tool calls")]
1589 FinishForbidsToolCalls {
1590 finish_reason: ModelFinishReason,
1592 tool_calls: ExecutionCount,
1594 },
1595 #[error("model response output item {index} has unsupported artifact modality {modality:?}")]
1597 UnsupportedArtifactModality {
1598 index: usize,
1600 modality: ArtifactModality,
1602 },
1603 #[error("model response identity {actual:?} does not match descriptor {expected:?}")]
1605 ModelIdentityMismatch {
1606 expected: Box<CapabilityIdentity>,
1608 actual: Box<CapabilityIdentity>,
1610 },
1611 #[error("model response input usage {actual} exceeds request maximum {maximum}")]
1613 InputUsageExceedsRequest {
1614 maximum: TokenCount,
1616 actual: TokenCount,
1618 },
1619 #[error("model response output usage {actual} exceeds request maximum {maximum}")]
1621 OutputUsageExceedsRequest {
1622 maximum: TokenCount,
1624 actual: TokenCount,
1626 },
1627 #[error("model response output item {index} uses unrequested modality {modality:?}")]
1629 OutputModalityNotRequested {
1630 index: usize,
1632 modality: ModelModality,
1634 },
1635 #[error("model response output item {index} is an unrequested reasoning summary")]
1637 ReasoningSummaryNotRequested {
1638 index: usize,
1640 },
1641 #[error("model response has {actual} tool calls; request maximum is {maximum}")]
1643 ToolCallsExceedRequest {
1644 maximum: ExecutionCount,
1646 actual: ExecutionCount,
1648 },
1649 #[error("model response output item {index} proposes unrequested tool {tool:?}")]
1651 ToolNotRequested {
1652 index: usize,
1654 tool: Box<CapabilityIdentity>,
1656 },
1657 #[error("model response output item {index} tool {actual:?} does not match {expected:?}")]
1659 ToolIdentityMismatch {
1660 index: usize,
1662 expected: Box<CapabilityIdentity>,
1664 actual: Box<CapabilityIdentity>,
1666 },
1667 #[error(
1669 "model response output item {index} proposes {actual}; expected specific tool {expected}"
1670 )]
1671 SpecificToolMismatch {
1672 index: usize,
1674 expected: CapabilityName,
1676 actual: CapabilityName,
1678 },
1679 #[error("model response completed without the required tool call")]
1681 RequiredToolCallMissing,
1682 #[error("model response plain-text completion contains JSON at output item {index}")]
1684 PlainTextCompletionContainsJson {
1685 index: usize,
1687 },
1688 #[error("model response structured completion contains text at output item {index}")]
1690 StructuredCompletionContainsText {
1691 index: usize,
1693 },
1694 #[error(
1696 "model response structured completion contains {actual} JSON values; expected exactly one"
1697 )]
1698 StructuredCompletionJsonCount {
1699 actual: usize,
1701 },
1702 #[error("model response JSON output item {index} has an unrequested schema")]
1704 UnexpectedOutputSchema {
1705 index: usize,
1707 },
1708 #[error("model response JSON output item {index} schema does not match the requested schema")]
1710 OutputSchemaMismatch {
1711 index: usize,
1713 expected: Box<SchemaReference>,
1715 actual: Option<Box<SchemaReference>>,
1717 },
1718}
1719
1720#[cfg(test)]
1721mod tests {
1722 use super::*;
1723 use crate::{
1724 ArtifactRef, ContentMetadata, Instruction, ModelRequestBuilder, ModelRequestLimits,
1725 RedactionState, SecurityLabel, ToolDescriptor,
1726 };
1727 use proptest::prelude::*;
1728 use serde_json::{Value, from_value, json, to_value};
1729
1730 fn fixture(path: &[&str], source: &str) -> Value {
1731 let mut value = serde_json::from_str::<Value>(source).unwrap();
1732 for segment in path {
1733 value = value[*segment].clone();
1734 }
1735 value
1736 }
1737
1738 fn descriptor(name: &str) -> ModelDescriptor {
1739 let values = fixture(
1740 &["descriptors", "valid"],
1741 include_str!("../tests/fixtures/core-model-descriptor-v1.json"),
1742 );
1743 let mut value = values[0].clone();
1744 value["metadata"]["identity"]["capability"]["name"] = Value::from(name);
1745 from_value(value).unwrap()
1746 }
1747
1748 fn instruction() -> Instruction {
1749 let values = fixture(
1750 &["instructions", "valid"],
1751 include_str!("../tests/fixtures/core-message-v1.json"),
1752 );
1753 from_value(values[0].clone()).unwrap()
1754 }
1755
1756 fn tool(name: &str) -> ToolDescriptor {
1757 let values = fixture(
1758 &["descriptors", "valid"],
1759 include_str!("../tests/fixtures/core-tool-v1.json"),
1760 );
1761 let mut value = values[0].clone();
1762 value["metadata"]["identity"]["capability"]["name"] = Value::from(name);
1763 from_value(value).unwrap()
1764 }
1765
1766 fn artifact(modality: ArtifactModality) -> ArtifactRef {
1767 let values = fixture(
1768 &["artifact_refs", "valid"],
1769 include_str!("../tests/fixtures/core-artifact-v1.json"),
1770 );
1771 let mut value = values[0].clone();
1772 value["representation"]["modality"] = to_value(modality).unwrap();
1773 from_value(value).unwrap()
1774 }
1775
1776 fn limits() -> ModelRequestLimits {
1777 ModelRequestLimits::new(
1778 TokenCount::new(8_192),
1779 TokenCount::new(1_024),
1780 ByteCount::new(MEBIBYTE),
1781 )
1782 .unwrap()
1783 }
1784
1785 fn base_builder() -> ModelRequestBuilder {
1786 ModelRequest::builder(limits()).instruction(instruction())
1787 }
1788
1789 fn base_request() -> ModelRequest {
1790 base_builder().build().unwrap()
1791 }
1792
1793 fn provenance(descriptor: &ModelDescriptor) -> ModelResponseProvenance {
1794 ModelResponseProvenance::new(
1795 "01912345-6789-7abc-8def-0123456789ab".parse().unwrap(),
1796 descriptor.metadata().identity().clone(),
1797 Some(ModelProviderModelId::new("provider/model-v1").unwrap()),
1798 Some(ModelProviderResponseId::new("response_opaque-42").unwrap()),
1799 )
1800 }
1801
1802 fn model_metadata() -> ContentMetadata {
1803 ContentMetadata::untrusted(
1804 ContentSource::Model,
1805 SecurityLabel::new("internal/model-output").unwrap(),
1806 )
1807 }
1808
1809 fn text_item(text: &str) -> ModelOutputItem {
1810 ModelOutputItem::content(
1811 TextContent::new(text, None, model_metadata())
1812 .unwrap()
1813 .into(),
1814 )
1815 .unwrap()
1816 }
1817
1818 fn json_item(value: Value, schema: Option<SchemaReference>) -> ModelOutputItem {
1819 ModelOutputItem::content(
1820 JsonContent::new(
1821 BoundedJson::try_from_value(value).unwrap(),
1822 schema,
1823 model_metadata(),
1824 )
1825 .into(),
1826 )
1827 .unwrap()
1828 }
1829
1830 fn usage() -> ModelUsage {
1831 ModelUsage::new(
1832 TokenCount::new(120),
1833 Some(TokenCount::new(20)),
1834 TokenCount::new(30),
1835 Some(TokenCount::new(5)),
1836 )
1837 .unwrap()
1838 }
1839
1840 fn proposal(
1841 descriptor: &ToolDescriptor,
1842 provider_call_id: Option<&str>,
1843 ) -> ModelToolCallProposal {
1844 ModelToolCallProposal::new(
1845 descriptor.metadata().identity().clone(),
1846 provider_call_id.map(|value| ModelProviderToolCallId::new(value).unwrap()),
1847 BoundedJson::try_from_value(json!({"incident_id": 42})).unwrap(),
1848 Extensions::default(),
1849 )
1850 .unwrap()
1851 }
1852
1853 #[test]
1854 fn provider_identifiers_are_exact_bounded_and_redacted() {
1855 let value = ModelProviderResponseId::new("resp/abc:def_42.v1").unwrap();
1856 assert_eq!(value.as_str(), "resp/abc:def_42.v1");
1857 assert_eq!(to_value(&value).unwrap(), "resp/abc:def_42.v1");
1858 assert_eq!(
1859 from_value::<ModelProviderResponseId>(json!(value.as_str())).unwrap(),
1860 value
1861 );
1862 assert!(!format!("{value:?}").contains("resp/abc"));
1863
1864 for invalid in ["", "has space", "line\nbreak", "响应"] {
1865 assert!(ModelProviderResponseId::new(invalid).is_err());
1866 }
1867 assert_eq!(
1868 ModelProviderResponseId::new("x".repeat(ModelProviderResponseId::MAX_BYTES + 1)),
1869 Err(ModelProviderIdentifierError::TooLong {
1870 max: ModelProviderResponseId::MAX_BYTES,
1871 actual: ModelProviderResponseId::MAX_BYTES + 1,
1872 })
1873 );
1874 assert!(from_value::<ModelProviderResponseId>(json!(42)).is_err());
1875 }
1876
1877 #[test]
1878 fn finish_reasons_have_closed_canonical_wire_forms() {
1879 for (reason, expected) in [
1880 (ModelFinishReason::Completed, "completed"),
1881 (ModelFinishReason::ToolCalls, "tool_calls"),
1882 (ModelFinishReason::OutputLimit, "output_limit"),
1883 (ModelFinishReason::ContextLimit, "context_limit"),
1884 (ModelFinishReason::Refused, "refused"),
1885 (ModelFinishReason::ContentFiltered, "content_filtered"),
1886 (ModelFinishReason::Paused, "paused"),
1887 ] {
1888 assert_eq!(to_value(reason).unwrap(), expected);
1889 assert_eq!(
1890 from_value::<ModelFinishReason>(json!(expected)).unwrap(),
1891 reason
1892 );
1893 }
1894 assert!(from_value::<ModelFinishReason>(json!("provider_other")).is_err());
1895 assert!(from_value::<ModelFinishReason>(Value::Null).is_err());
1896 }
1897
1898 #[test]
1899 fn usage_requires_inclusive_checked_accounting() {
1900 assert_eq!(usage().total_tokens(), TokenCount::new(150));
1901 assert_eq!(
1902 ModelUsage::new(
1903 TokenCount::new(2),
1904 Some(TokenCount::new(3)),
1905 TokenCount::ZERO,
1906 None,
1907 ),
1908 Err(ModelUsageError::CachedInputExceedsInput {
1909 input_tokens: TokenCount::new(2),
1910 cached_input_tokens: TokenCount::new(3),
1911 })
1912 );
1913 assert_eq!(
1914 ModelUsage::new(
1915 TokenCount::ZERO,
1916 None,
1917 TokenCount::new(2),
1918 Some(TokenCount::new(3)),
1919 ),
1920 Err(ModelUsageError::ReasoningExceedsOutput {
1921 output_tokens: TokenCount::new(2),
1922 reasoning_tokens: TokenCount::new(3),
1923 })
1924 );
1925 assert_eq!(
1926 ModelUsage::new(TokenCount::MAX, None, TokenCount::new(1), None),
1927 Err(ModelUsageError::TotalTokensOverflow)
1928 );
1929
1930 let known_zero = ModelUsage::new(
1931 TokenCount::ZERO,
1932 Some(TokenCount::ZERO),
1933 TokenCount::ZERO,
1934 Some(TokenCount::ZERO),
1935 )
1936 .unwrap();
1937 assert!(
1938 to_value(known_zero)
1939 .unwrap()
1940 .get("cached_input_tokens")
1941 .is_some()
1942 );
1943 let unknown = ModelUsage::new(TokenCount::ZERO, None, TokenCount::ZERO, None).unwrap();
1944 let encoded = to_value(unknown).unwrap();
1945 assert!(encoded.get("cached_input_tokens").is_none());
1946 assert!(encoded.get("reasoning_tokens").is_none());
1947 assert!(from_value::<ModelUsage>(json!({"input_tokens":"0"})).is_err());
1948 }
1949
1950 #[test]
1951 fn output_items_enforce_untrusted_source_metadata() {
1952 let controlled = ContentMetadata::new(
1953 ContentSource::Model,
1954 ContentTrust::ApplicationControlled,
1955 SecurityLabel::new("internal/model-output").unwrap(),
1956 RedactionState::NotApplied,
1957 );
1958 let invalid = TextContent::new("unsafe", None, controlled).unwrap();
1959 assert!(matches!(
1960 ModelOutputItem::content(invalid.into()),
1961 Err(ModelOutputItemError::InvalidTrust { .. })
1962 ));
1963
1964 let wrong_source = ContentMetadata::untrusted(
1965 ContentSource::User,
1966 SecurityLabel::new("internal/model-output").unwrap(),
1967 );
1968 let invalid = TextContent::new("unsafe", None, wrong_source).unwrap();
1969 assert!(matches!(
1970 ModelOutputItem::content(invalid.into()),
1971 Err(ModelOutputItemError::InvalidSource { .. })
1972 ));
1973
1974 let summary = TextContent::new("Reason summary", None, model_metadata()).unwrap();
1975 assert_eq!(
1976 ModelOutputItem::reasoning_summary(summary).unwrap().kind(),
1977 ModelOutputItemKind::ReasoningSummary
1978 );
1979 }
1980
1981 #[test]
1982 fn completed_text_response_round_trips_and_redacts_debug() {
1983 let descriptor = descriptor("models.primary");
1984 let request = base_request();
1985 let response = ModelResponse::new(
1986 provenance(&descriptor),
1987 &descriptor,
1988 &request,
1989 [text_item("confidential model result")],
1990 ModelFinishReason::Completed,
1991 usage(),
1992 Extensions::default(),
1993 )
1994 .unwrap();
1995
1996 assert_eq!(response.output().len(), 1);
1997 assert_eq!(response.tool_call_count(), 0);
1998 assert_eq!(response.inline_payload_bytes(), ByteCount::new(25));
1999 assert_eq!(response.finish_reason(), ModelFinishReason::Completed);
2000 let encoded = to_value(&response).unwrap();
2001 let decoded = from_value::<ModelResponse>(encoded.clone()).unwrap();
2002 assert_eq!(decoded, response);
2003 decoded.validate_for(&descriptor, &request).unwrap();
2004 let debug = format!("{response:?}");
2005 assert!(!debug.contains("confidential model result"));
2006 assert!(!debug.contains("provider/model-v1"));
2007 assert!(!debug.contains("response_opaque-42"));
2008
2009 let mut unknown = encoded;
2010 unknown["provider"] = Value::from("openai");
2011 assert!(from_value::<ModelResponse>(unknown).is_err());
2012 }
2013
2014 #[test]
2015 fn empty_plain_text_completion_is_valid_but_usage_stays_required() {
2016 let descriptor = descriptor("models.primary");
2017 let request = base_request();
2018 let response = ModelResponse::new(
2019 provenance(&descriptor),
2020 &descriptor,
2021 &request,
2022 [],
2023 ModelFinishReason::Completed,
2024 ModelUsage::new(TokenCount::new(4), None, TokenCount::new(1), None).unwrap(),
2025 Extensions::default(),
2026 )
2027 .unwrap();
2028 assert!(response.output().is_empty());
2029
2030 let mut encoded = to_value(response).unwrap();
2031 encoded.as_object_mut().unwrap().remove("usage");
2032 assert!(from_value::<ModelResponse>(encoded).is_err());
2033 }
2034
2035 #[test]
2036 fn provenance_and_usage_are_bound_to_the_attempt_snapshot() {
2037 let primary_descriptor = descriptor("models.primary");
2038 let other = descriptor("models.other");
2039 let request = base_request();
2040 let response = ModelResponse::new(
2041 provenance(&primary_descriptor),
2042 &primary_descriptor,
2043 &request,
2044 [text_item("ok")],
2045 ModelFinishReason::Completed,
2046 usage(),
2047 Extensions::default(),
2048 )
2049 .unwrap();
2050 assert!(matches!(
2051 response.validate_for(&other, &request),
2052 Err(ModelResponseError::ModelIdentityMismatch { .. })
2053 ));
2054
2055 let excessive =
2056 ModelUsage::new(TokenCount::new(8_193), None, TokenCount::new(1), None).unwrap();
2057 assert!(matches!(
2058 ModelResponse::new(
2059 provenance(&primary_descriptor),
2060 &primary_descriptor,
2061 &request,
2062 [text_item("ok")],
2063 ModelFinishReason::Completed,
2064 excessive,
2065 Extensions::default(),
2066 ),
2067 Err(ModelResponseError::InputUsageExceedsRequest { .. })
2068 ));
2069 }
2070
2071 #[test]
2072 fn structured_completions_are_typed_and_schema_bound() {
2073 let descriptor = descriptor("models.primary");
2074 let generic_request = base_builder()
2075 .text_output_format(Some(ModelTextOutputFormat::json()))
2076 .build()
2077 .unwrap();
2078 ModelResponse::new(
2079 provenance(&descriptor),
2080 &descriptor,
2081 &generic_request,
2082 [json_item(json!({"status": "ok"}), None)],
2083 ModelFinishReason::Completed,
2084 usage(),
2085 Extensions::default(),
2086 )
2087 .unwrap();
2088 assert!(matches!(
2089 ModelResponse::new(
2090 provenance(&descriptor),
2091 &descriptor,
2092 &generic_request,
2093 [text_item("{\"status\":\"ok\"}")],
2094 ModelFinishReason::Completed,
2095 usage(),
2096 Extensions::default(),
2097 ),
2098 Err(ModelResponseError::StructuredCompletionContainsText { .. })
2099 ));
2100 assert!(matches!(
2101 ModelResponse::new(
2102 provenance(&descriptor),
2103 &descriptor,
2104 &generic_request,
2105 [],
2106 ModelFinishReason::Completed,
2107 usage(),
2108 Extensions::default(),
2109 ),
2110 Err(ModelResponseError::StructuredCompletionJsonCount { actual: 0 })
2111 ));
2112
2113 let schema = tool("incidents.lookup").input_schema().clone();
2114 let schema_request = base_builder()
2115 .text_output_format(Some(ModelTextOutputFormat::json_schema(schema.clone())))
2116 .build()
2117 .unwrap();
2118 ModelResponse::new(
2119 provenance(&descriptor),
2120 &descriptor,
2121 &schema_request,
2122 [json_item(json!({"incident_id": 42}), Some(schema.clone()))],
2123 ModelFinishReason::Completed,
2124 usage(),
2125 Extensions::default(),
2126 )
2127 .unwrap();
2128 assert!(matches!(
2129 ModelResponse::new(
2130 provenance(&descriptor),
2131 &descriptor,
2132 &schema_request,
2133 [json_item(json!({"incident_id": 42}), None)],
2134 ModelFinishReason::Completed,
2135 usage(),
2136 Extensions::default(),
2137 ),
2138 Err(ModelResponseError::OutputSchemaMismatch { .. })
2139 ));
2140
2141 ModelResponse::new(
2142 provenance(&descriptor),
2143 &descriptor,
2144 &schema_request,
2145 [text_item("partial JSON")],
2146 ModelFinishReason::OutputLimit,
2147 usage(),
2148 Extensions::default(),
2149 )
2150 .unwrap();
2151 }
2152
2153 #[test]
2154 fn tool_calls_are_unapproved_ordered_and_request_bound() {
2155 let descriptor = descriptor("models.primary");
2156 let first = tool("incidents.lookup");
2157 let second = tool("incidents.update");
2158 let request = base_builder()
2159 .tool(first.clone())
2160 .tool(second.clone())
2161 .tool_selection(ModelToolSelection::specific(
2162 CapabilityName::new("incidents.lookup").unwrap(),
2163 ))
2164 .max_tool_calls_per_response(ExecutionCount::new(2))
2165 .build()
2166 .unwrap();
2167 let response = ModelResponse::new(
2168 provenance(&descriptor),
2169 &descriptor,
2170 &request,
2171 [
2172 text_item("I will inspect the incident."),
2173 ModelOutputItem::tool_call(proposal(&first, Some("call_1"))),
2174 ],
2175 ModelFinishReason::ToolCalls,
2176 usage(),
2177 Extensions::default(),
2178 )
2179 .unwrap();
2180 assert_eq!(response.tool_call_count(), 1);
2181 assert_eq!(response.tool_calls().count(), 1);
2182 assert_eq!(response.output()[0].kind(), ModelOutputItemKind::Content);
2183 assert_eq!(response.output()[1].kind(), ModelOutputItemKind::ToolCall);
2184
2185 assert!(matches!(
2186 ModelResponse::new(
2187 provenance(&descriptor),
2188 &descriptor,
2189 &request,
2190 [ModelOutputItem::tool_call(proposal(
2191 &second,
2192 Some("call_2")
2193 ))],
2194 ModelFinishReason::ToolCalls,
2195 usage(),
2196 Extensions::default(),
2197 ),
2198 Err(ModelResponseError::SpecificToolMismatch { .. })
2199 ));
2200 assert!(matches!(
2201 ModelResponse::new(
2202 provenance(&descriptor),
2203 &descriptor,
2204 &request,
2205 [ModelOutputItem::tool_call(proposal(&first, Some("call_3")))],
2206 ModelFinishReason::Completed,
2207 usage(),
2208 Extensions::default(),
2209 ),
2210 Err(ModelResponseError::FinishForbidsToolCalls { .. })
2211 ));
2212 assert!(matches!(
2213 ModelResponse::new(
2214 provenance(&descriptor),
2215 &descriptor,
2216 &request,
2217 [],
2218 ModelFinishReason::ToolCalls,
2219 usage(),
2220 Extensions::default(),
2221 ),
2222 Err(ModelResponseError::ToolCallsFinishRequiresProposal)
2223 ));
2224 }
2225
2226 #[test]
2227 fn disabled_tool_definitions_cannot_authorize_a_new_call() {
2228 let descriptor = descriptor("models.primary");
2229 let selected = tool("incidents.lookup");
2230 let request = base_builder().tool(selected.clone()).build().unwrap();
2231 assert!(matches!(
2232 ModelResponse::new(
2233 provenance(&descriptor),
2234 &descriptor,
2235 &request,
2236 [ModelOutputItem::tool_call(proposal(
2237 &selected,
2238 Some("forbidden")
2239 ))],
2240 ModelFinishReason::ToolCalls,
2241 usage(),
2242 Extensions::default(),
2243 ),
2244 Err(ModelResponseError::ToolCallsExceedRequest {
2245 maximum: ExecutionCount::ZERO,
2246 ..
2247 })
2248 ));
2249 }
2250
2251 #[test]
2252 fn tool_argument_and_correlation_invariants_fail_closed() {
2253 let descriptor = descriptor("models.primary");
2254 let selected = tool("incidents.lookup");
2255 assert_eq!(
2256 ModelToolCallProposal::new(
2257 selected.metadata().identity().clone(),
2258 None,
2259 BoundedJson::try_from_value(json!([1, 2])).unwrap(),
2260 Extensions::default(),
2261 ),
2262 Err(ModelToolCallProposalError::ArgumentsMustBeObject)
2263 );
2264
2265 let request = base_builder()
2266 .tool(selected.clone())
2267 .tool_selection(ModelToolSelection::auto())
2268 .max_tool_calls_per_response(ExecutionCount::new(2))
2269 .build()
2270 .unwrap();
2271 assert!(matches!(
2272 ModelResponse::new(
2273 provenance(&descriptor),
2274 &descriptor,
2275 &request,
2276 [
2277 ModelOutputItem::tool_call(proposal(&selected, Some("duplicate"))),
2278 ModelOutputItem::tool_call(proposal(&selected, Some("duplicate"))),
2279 ],
2280 ModelFinishReason::ToolCalls,
2281 usage(),
2282 Extensions::default(),
2283 ),
2284 Err(ModelResponseError::DuplicateProviderToolCallId)
2285 ));
2286
2287 let one_call_request = base_builder()
2288 .tool(selected.clone())
2289 .tool_selection(ModelToolSelection::auto())
2290 .max_tool_calls_per_response(ExecutionCount::new(1))
2291 .build()
2292 .unwrap();
2293 assert!(matches!(
2294 ModelResponse::new(
2295 provenance(&descriptor),
2296 &descriptor,
2297 &one_call_request,
2298 [
2299 ModelOutputItem::tool_call(proposal(&selected, Some("one"))),
2300 ModelOutputItem::tool_call(proposal(&selected, Some("two"))),
2301 ],
2302 ModelFinishReason::ToolCalls,
2303 usage(),
2304 Extensions::default(),
2305 ),
2306 Err(ModelResponseError::ToolCallsExceedRequest { .. })
2307 ));
2308 }
2309
2310 #[test]
2311 fn required_tools_and_reasoning_opt_in_are_enforced() {
2312 let descriptor = descriptor("models.primary");
2313 let selected = tool("incidents.lookup");
2314 let required = base_builder()
2315 .tool(selected)
2316 .tool_selection(ModelToolSelection::required())
2317 .max_tool_calls_per_response(ExecutionCount::new(1))
2318 .build()
2319 .unwrap();
2320 assert!(matches!(
2321 ModelResponse::new(
2322 provenance(&descriptor),
2323 &descriptor,
2324 &required,
2325 [text_item("done")],
2326 ModelFinishReason::Completed,
2327 usage(),
2328 Extensions::default(),
2329 ),
2330 Err(ModelResponseError::RequiredToolCallMissing)
2331 ));
2332
2333 let summary = ModelOutputItem::reasoning_summary(
2334 TextContent::new("Readable summary", None, model_metadata()).unwrap(),
2335 )
2336 .unwrap();
2337 assert!(matches!(
2338 ModelResponse::new(
2339 provenance(&descriptor),
2340 &descriptor,
2341 &base_request(),
2342 [summary.clone(), text_item("done")],
2343 ModelFinishReason::Completed,
2344 usage(),
2345 Extensions::default(),
2346 ),
2347 Err(ModelResponseError::ReasoningSummaryNotRequested { index: 0 })
2348 ));
2349 let requested = base_builder().reasoning_summaries(true).build().unwrap();
2350 ModelResponse::new(
2351 provenance(&descriptor),
2352 &descriptor,
2353 &requested,
2354 [summary, text_item("done")],
2355 ModelFinishReason::Completed,
2356 usage(),
2357 Extensions::default(),
2358 )
2359 .unwrap();
2360 }
2361
2362 #[test]
2363 fn artifact_modalities_are_portable_requested_and_externally_bounded() {
2364 let descriptor = descriptor("models.primary");
2365 let document =
2366 ModelOutputItem::content(artifact(ArtifactModality::Document).into()).unwrap();
2367 assert!(matches!(
2368 ModelResponse::new(
2369 provenance(&descriptor),
2370 &descriptor,
2371 &base_request(),
2372 [document.clone()],
2373 ModelFinishReason::Completed,
2374 usage(),
2375 Extensions::default(),
2376 ),
2377 Err(ModelResponseError::OutputModalityNotRequested {
2378 modality: ModelModality::Document,
2379 ..
2380 })
2381 ));
2382
2383 let document_request = base_builder()
2384 .output_modalities(crate::ModelModalities::try_new([ModelModality::Document]).unwrap())
2385 .text_output_format(None)
2386 .build()
2387 .unwrap();
2388 let response = ModelResponse::new(
2389 provenance(&descriptor),
2390 &descriptor,
2391 &document_request,
2392 [document],
2393 ModelFinishReason::Completed,
2394 usage(),
2395 Extensions::default(),
2396 )
2397 .unwrap();
2398 assert_eq!(response.inline_payload_bytes(), ByteCount::ZERO);
2399
2400 let unsupported =
2401 ModelOutputItem::Content(ContentPart::from(artifact(ArtifactModality::Archive)));
2402 assert!(matches!(
2403 ModelResponse::new(
2404 provenance(&descriptor),
2405 &descriptor,
2406 &document_request,
2407 [unsupported],
2408 ModelFinishReason::Completed,
2409 usage(),
2410 Extensions::default(),
2411 ),
2412 Err(ModelResponseError::UnsupportedArtifactModality {
2413 modality: ArtifactModality::Archive,
2414 ..
2415 })
2416 ));
2417 }
2418
2419 #[test]
2420 fn collection_and_inline_resource_ceilings_stop_at_first_excess() {
2421 let content = text_item("x");
2422 assert_eq!(
2423 ModelOutputItems::try_new(std::iter::repeat_n(
2424 content,
2425 ModelOutputItems::MAX_CONTENT_ITEMS + 1
2426 )),
2427 Err(ModelResponseError::TooManyContentItems {
2428 max: ModelOutputItems::MAX_CONTENT_ITEMS,
2429 observed: ModelOutputItems::MAX_CONTENT_ITEMS + 1,
2430 })
2431 );
2432
2433 let selected = tool("incidents.lookup");
2434 let proposal = ModelOutputItem::tool_call(proposal(&selected, None));
2435 assert_eq!(
2436 ModelOutputItems::try_new(std::iter::repeat_n(
2437 proposal,
2438 ModelOutputItems::MAX_TOOL_CALLS + 1
2439 )),
2440 Err(ModelResponseError::TooManyToolCalls {
2441 max: ModelOutputItems::MAX_TOOL_CALLS,
2442 observed: ModelOutputItems::MAX_TOOL_CALLS + 1,
2443 })
2444 );
2445
2446 let mut values = Vec::new();
2447 let mut content_items = 0;
2448 let mut tool_calls = 0;
2449 let mut bytes = ModelOutputItems::MAX_INLINE_PAYLOAD_BYTES;
2450 let mut modalities = BTreeSet::new();
2451 let mut provider_call_ids = BTreeSet::new();
2452 assert_eq!(
2453 push_output_item(
2454 &mut values,
2455 &mut content_items,
2456 &mut tool_calls,
2457 &mut bytes,
2458 &mut modalities,
2459 &mut provider_call_ids,
2460 text_item("x"),
2461 ),
2462 Err(ModelResponseError::InlinePayloadTooLarge {
2463 maximum: ModelOutputItems::MAX_INLINE_PAYLOAD_BYTES,
2464 observed: ByteCount::new(ModelOutputItems::MAX_INLINE_PAYLOAD_BYTES.get() + 1),
2465 })
2466 );
2467 }
2468
2469 #[test]
2470 fn response_schemas_publish_closed_objects_and_hard_bounds() {
2471 for schema in [
2472 to_value(schemars::schema_for!(ModelUsage)).unwrap(),
2473 to_value(schemars::schema_for!(ModelToolCallProposal)).unwrap(),
2474 to_value(schemars::schema_for!(ModelResponseProvenance)).unwrap(),
2475 to_value(schemars::schema_for!(ModelResponse)).unwrap(),
2476 ] {
2477 assert_eq!(schema["type"], "object");
2478 assert_eq!(schema["additionalProperties"], false);
2479 }
2480
2481 let response = to_value(schemars::schema_for!(ModelResponse)).unwrap();
2482 assert_eq!(
2483 response["$defs"]["ModelResponseOutput"]["maxItems"],
2484 ModelResponse::MAX_OUTPUT_ITEMS
2485 );
2486 let provider_id = to_value(schemars::schema_for!(ModelProviderResponseId)).unwrap();
2487 assert_eq!(provider_id["maxLength"], ModelProviderResponseId::MAX_BYTES);
2488 assert_eq!(provider_id["pattern"], PROVIDER_IDENTIFIER_PATTERN);
2489 }
2490
2491 proptest! {
2492 #[test]
2493 fn valid_usage_round_trips_without_losing_known_breakdowns(
2494 input in 0_u64..=1_000_000,
2495 output in 0_u64..=1_000_000,
2496 cached_fraction in 0_u64..=1_000_000,
2497 reasoning_fraction in 0_u64..=1_000_000,
2498 ) {
2499 let cached = TokenCount::new(cached_fraction.min(input));
2500 let reasoning = TokenCount::new(reasoning_fraction.min(output));
2501 let usage = ModelUsage::new(
2502 TokenCount::new(input),
2503 Some(cached),
2504 TokenCount::new(output),
2505 Some(reasoning),
2506 ).unwrap();
2507 let encoded = serde_json::to_vec(&usage).unwrap();
2508 prop_assert_eq!(serde_json::from_slice::<ModelUsage>(&encoded).unwrap(), usage);
2509 }
2510
2511 #[test]
2512 fn visible_ascii_provider_identifiers_round_trip(bytes in prop::collection::vec(33_u8..127, 1..100)) {
2513 let text = String::from_utf8(bytes).unwrap();
2514 let id = ModelProviderToolCallId::new(text.clone()).unwrap();
2515 let encoded = serde_json::to_vec(&id).unwrap();
2516 prop_assert_eq!(serde_json::from_slice::<ModelProviderToolCallId>(&encoded).unwrap(), id.clone());
2517 prop_assert_eq!(id.as_str(), text);
2518 }
2519 }
2520}