1use std::{
7 collections::{BTreeMap, BTreeSet, btree_map},
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::{
19 ArtifactModality, ByteCount, CapabilityIdentity, CapabilityLifecycleState, CapabilityName,
20 ContentPart, ExecutionCount, Extensions, Instruction, InstructionContent, InstructionIdentity,
21 Message, MessageId, ModelModalities, ModelModality, ModelRequirements, ModelRequirementsError,
22 ModelStructuredOutputLevel, ModelToolChoice, ModelToolChoices, ModelToolRequirements,
23 ModelTranscript, SchemaReference, TokenCount, ToolDescriptor,
24};
25
26const MEBIBYTE: u64 = 1024 * 1024;
27
28#[derive(
30 Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
31)]
32#[serde(rename_all = "snake_case")]
33pub enum ModelResponseMode {
34 Complete,
36 Streaming,
38}
39
40#[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
42#[serde(tag = "mode", rename_all = "snake_case", deny_unknown_fields)]
43pub enum ModelToolSelection {
44 None {},
46 Auto {},
48 Required {},
50 Specific {
52 name: CapabilityName,
54 },
55}
56
57impl ModelToolSelection {
58 #[must_use]
60 pub const fn none() -> Self {
61 Self::None {}
62 }
63
64 #[must_use]
66 pub const fn auto() -> Self {
67 Self::Auto {}
68 }
69
70 #[must_use]
72 pub const fn required() -> Self {
73 Self::Required {}
74 }
75
76 #[must_use]
78 pub const fn specific(name: CapabilityName) -> Self {
79 Self::Specific { name }
80 }
81
82 #[must_use]
84 pub const fn choice(&self) -> ModelToolChoice {
85 match self {
86 Self::None {} => ModelToolChoice::None,
87 Self::Auto {} => ModelToolChoice::Auto,
88 Self::Required {} => ModelToolChoice::Required,
89 Self::Specific { .. } => ModelToolChoice::Specific,
90 }
91 }
92
93 #[must_use]
95 pub const fn specific_name(&self) -> Option<&CapabilityName> {
96 match self {
97 Self::Specific { name } => Some(name),
98 Self::None {} | Self::Auto {} | Self::Required {} => None,
99 }
100 }
101}
102
103#[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
105#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
106pub enum ModelTextOutputFormat {
107 Text {},
109 Json {},
111 JsonSchema {
113 schema: SchemaReference,
115 },
116}
117
118impl ModelTextOutputFormat {
119 #[must_use]
121 pub const fn text() -> Self {
122 Self::Text {}
123 }
124
125 #[must_use]
127 pub const fn json() -> Self {
128 Self::Json {}
129 }
130
131 #[must_use]
133 pub const fn json_schema(schema: SchemaReference) -> Self {
134 Self::JsonSchema { schema }
135 }
136
137 #[must_use]
139 pub const fn required_level(&self) -> ModelStructuredOutputLevel {
140 match self {
141 Self::Text {} => ModelStructuredOutputLevel::Unsupported,
142 Self::Json {} => ModelStructuredOutputLevel::Json,
143 Self::JsonSchema { .. } => ModelStructuredOutputLevel::JsonSchema,
144 }
145 }
146
147 #[must_use]
149 pub const fn schema(&self) -> Option<&SchemaReference> {
150 match self {
151 Self::JsonSchema { schema } => Some(schema),
152 Self::Text {} | Self::Json {} => None,
153 }
154 }
155}
156
157#[allow(clippy::struct_field_names)]
164#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
165#[serde(deny_unknown_fields)]
166pub struct ModelRequestLimits {
167 max_input_tokens: TokenCount,
168 max_output_tokens: TokenCount,
169 max_content_bytes: ByteCount,
170}
171
172impl ModelRequestLimits {
173 pub const HARD_MAX_CONTENT_BYTES: ByteCount = ByteCount::new(64 * MEBIBYTE);
175
176 pub const fn new(
183 max_input_tokens: TokenCount,
184 max_output_tokens: TokenCount,
185 max_content_bytes: ByteCount,
186 ) -> Result<Self, ModelRequestLimitsError> {
187 if max_input_tokens.get() == 0 {
188 return Err(ModelRequestLimitsError::ZeroInputTokens);
189 }
190 if max_output_tokens.get() == 0 {
191 return Err(ModelRequestLimitsError::ZeroOutputTokens);
192 }
193 if max_content_bytes.get() == 0 {
194 return Err(ModelRequestLimitsError::ZeroContentBytes);
195 }
196 if max_content_bytes.get() > Self::HARD_MAX_CONTENT_BYTES.get() {
197 return Err(ModelRequestLimitsError::ContentBytesAboveHardMaximum {
198 maximum: Self::HARD_MAX_CONTENT_BYTES,
199 actual: max_content_bytes,
200 });
201 }
202 if max_input_tokens.checked_add(max_output_tokens).is_none() {
203 return Err(ModelRequestLimitsError::ContextTokensOverflow);
204 }
205 Ok(Self {
206 max_input_tokens,
207 max_output_tokens,
208 max_content_bytes,
209 })
210 }
211
212 #[must_use]
214 pub const fn max_input_tokens(&self) -> TokenCount {
215 self.max_input_tokens
216 }
217
218 #[must_use]
220 pub const fn max_output_tokens(&self) -> TokenCount {
221 self.max_output_tokens
222 }
223
224 #[must_use]
226 pub const fn max_content_bytes(&self) -> ByteCount {
227 self.max_content_bytes
228 }
229
230 #[must_use]
232 pub fn required_context_tokens(&self) -> TokenCount {
233 self.max_input_tokens
234 .checked_add(self.max_output_tokens)
235 .expect("validated model request token ceilings cannot overflow")
236 }
237}
238
239#[derive(Deserialize)]
240#[serde(deny_unknown_fields)]
241#[allow(clippy::struct_field_names)]
242struct ModelRequestLimitsWire {
243 max_input_tokens: TokenCount,
244 max_output_tokens: TokenCount,
245 max_content_bytes: ByteCount,
246}
247
248impl<'de> Deserialize<'de> for ModelRequestLimits {
249 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
250 where
251 D: Deserializer<'de>,
252 {
253 let wire = ModelRequestLimitsWire::deserialize(deserializer)?;
254 Self::new(
255 wire.max_input_tokens,
256 wire.max_output_tokens,
257 wire.max_content_bytes,
258 )
259 .map_err(de::Error::custom)
260 }
261}
262
263#[derive(Clone, Debug, Eq, Error, PartialEq)]
265#[non_exhaustive]
266pub enum ModelRequestLimitsError {
267 #[error("model request max input tokens must be greater than zero")]
269 ZeroInputTokens,
270 #[error("model request max output tokens must be greater than zero")]
272 ZeroOutputTokens,
273 #[error("model request max content bytes must be greater than zero")]
275 ZeroContentBytes,
276 #[error("model request content ceiling {actual} exceeds hard maximum {maximum}")]
278 ContentBytesAboveHardMaximum {
279 maximum: ByteCount,
281 actual: ByteCount,
283 },
284 #[error("model request input and output token ceilings overflow total context capacity")]
286 ContextTokensOverflow,
287}
288
289#[derive(Clone, Eq, PartialEq)]
290struct RequestInstructions {
291 values: Box<[Instruction]>,
292 content_bytes: ByteCount,
293}
294
295impl RequestInstructions {
296 const MAX_LEN: usize = 32;
297 const MAX_CONTENT_BYTES: ByteCount = ByteCount::new(8 * MEBIBYTE);
298
299 fn as_slice(&self) -> &[Instruction] {
300 &self.values
301 }
302
303 fn len(&self) -> usize {
304 self.values.len()
305 }
306
307 fn is_empty(&self) -> bool {
308 self.values.is_empty()
309 }
310}
311
312impl fmt::Debug for RequestInstructions {
313 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
314 formatter
315 .debug_struct("RequestInstructions")
316 .field("count", &self.len())
317 .field("content_bytes", &self.content_bytes)
318 .finish_non_exhaustive()
319 }
320}
321
322impl Serialize for RequestInstructions {
323 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
324 where
325 S: Serializer,
326 {
327 self.values.serialize(serializer)
328 }
329}
330
331impl<'de> Deserialize<'de> for RequestInstructions {
332 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
333 where
334 D: Deserializer<'de>,
335 {
336 deserializer.deserialize_seq(RequestInstructionsVisitor)
337 }
338}
339
340struct RequestInstructionsVisitor;
341
342impl<'de> de::Visitor<'de> for RequestInstructionsVisitor {
343 type Value = RequestInstructions;
344
345 fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
346 write!(
347 formatter,
348 "an array containing at most {} unique trusted instructions",
349 RequestInstructions::MAX_LEN
350 )
351 }
352
353 fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
354 where
355 A: SeqAccess<'de>,
356 {
357 let mut values = Vec::new();
358 let mut content_bytes = ByteCount::ZERO;
359 while let Some(value) = sequence.next_element::<Instruction>()? {
360 push_instruction(&mut values, &mut content_bytes, value).map_err(de::Error::custom)?;
361 }
362 Ok(RequestInstructions {
363 values: values.into_boxed_slice(),
364 content_bytes,
365 })
366 }
367}
368
369impl JsonSchema for RequestInstructions {
370 fn schema_name() -> std::borrow::Cow<'static, str> {
371 "ModelRequestInstructions".into()
372 }
373
374 fn schema_id() -> std::borrow::Cow<'static, str> {
375 concat!(module_path!(), "::RequestInstructions").into()
376 }
377
378 fn json_schema(generator: &mut SchemaGenerator) -> Schema {
379 json_schema!({
380 "type": "array",
381 "items": generator.subschema_for::<Instruction>(),
382 "maxItems": 32,
383 "uniqueItems": true,
384 "description": "Ordered application-controlled instructions; adapters preserve this precedence order. Runtime additionally rejects duplicate instruction identities and enforces an 8388608-byte resolved-content ceiling."
385 })
386 }
387}
388
389fn push_instruction(
390 values: &mut Vec<Instruction>,
391 content_bytes: &mut ByteCount,
392 value: Instruction,
393) -> Result<(), ModelRequestError> {
394 if values.len() == RequestInstructions::MAX_LEN {
395 return Err(ModelRequestError::TooManyInstructions {
396 max: RequestInstructions::MAX_LEN,
397 observed: RequestInstructions::MAX_LEN + 1,
398 });
399 }
400 if values
401 .iter()
402 .any(|existing| existing.identity() == value.identity())
403 {
404 return Err(ModelRequestError::DuplicateInstruction {
405 identity: value.identity().clone(),
406 });
407 }
408
409 let additional = match value.content() {
410 InstructionContent::Text(text) => ByteCount::new(text.text().len() as u64),
411 InstructionContent::Artifact(artifact) => {
412 let modality = artifact.representation().modality();
413 if modality != ArtifactModality::Text {
414 return Err(ModelRequestError::UnsupportedInstructionArtifact {
415 index: values.len(),
416 modality,
417 });
418 }
419 artifact.representation().byte_length()
420 }
421 };
422 *content_bytes = checked_content_add(
423 *content_bytes,
424 additional,
425 RequestInstructions::MAX_CONTENT_BYTES,
426 ModelContentCollection::Instructions,
427 )?;
428 values.push(value);
429 Ok(())
430}
431
432#[derive(Clone, Eq, PartialEq)]
433struct RequestMessages {
434 values: Box<[Message]>,
435 content_bytes: ByteCount,
436 modalities: ModelModalities,
437}
438
439impl RequestMessages {
440 const MAX_LEN: usize = 256;
441 const MAX_CONTENT_BYTES: ByteCount = ModelRequestLimits::HARD_MAX_CONTENT_BYTES;
442
443 fn as_slice(&self) -> &[Message] {
444 &self.values
445 }
446
447 fn len(&self) -> usize {
448 self.values.len()
449 }
450
451 fn is_empty(&self) -> bool {
452 self.values.is_empty()
453 }
454}
455
456impl fmt::Debug for RequestMessages {
457 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
458 formatter
459 .debug_struct("RequestMessages")
460 .field("count", &self.len())
461 .field("content_bytes", &self.content_bytes)
462 .field("modalities", &self.modalities)
463 .finish_non_exhaustive()
464 }
465}
466
467impl Serialize for RequestMessages {
468 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
469 where
470 S: Serializer,
471 {
472 self.values.serialize(serializer)
473 }
474}
475
476impl<'de> Deserialize<'de> for RequestMessages {
477 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
478 where
479 D: Deserializer<'de>,
480 {
481 deserializer.deserialize_seq(RequestMessagesVisitor)
482 }
483}
484
485struct RequestMessagesVisitor;
486
487impl<'de> de::Visitor<'de> for RequestMessagesVisitor {
488 type Value = RequestMessages;
489
490 fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
491 write!(
492 formatter,
493 "an array containing at most {} unique durable messages",
494 RequestMessages::MAX_LEN
495 )
496 }
497
498 fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
499 where
500 A: SeqAccess<'de>,
501 {
502 let mut values = Vec::new();
503 let mut content_bytes = ByteCount::ZERO;
504 let mut modalities = BTreeSet::new();
505 while let Some(value) = sequence.next_element::<Message>()? {
506 push_message(&mut values, &mut content_bytes, &mut modalities, value)
507 .map_err(de::Error::custom)?;
508 }
509 Ok(RequestMessages {
510 values: values.into_boxed_slice(),
511 content_bytes,
512 modalities: ModelModalities::try_new(modalities).map_err(de::Error::custom)?,
513 })
514 }
515}
516
517impl JsonSchema for RequestMessages {
518 fn schema_name() -> std::borrow::Cow<'static, str> {
519 "ModelRequestMessages".into()
520 }
521
522 fn schema_id() -> std::borrow::Cow<'static, str> {
523 concat!(module_path!(), "::RequestMessages").into()
524 }
525
526 fn json_schema(generator: &mut SchemaGenerator) -> Schema {
527 json_schema!({
528 "type": "array",
529 "items": generator.subschema_for::<Message>(),
530 "maxItems": 256,
531 "uniqueItems": true,
532 "description": "Ordered durable messages. Runtime additionally rejects duplicate message IDs, unsupported artifact modalities, and more than 67108864 resolved content bytes."
533 })
534 }
535}
536
537fn push_message(
538 values: &mut Vec<Message>,
539 content_bytes: &mut ByteCount,
540 modalities: &mut BTreeSet<ModelModality>,
541 value: Message,
542) -> Result<(), ModelRequestError> {
543 if values.len() == RequestMessages::MAX_LEN {
544 return Err(ModelRequestError::TooManyMessages {
545 max: RequestMessages::MAX_LEN,
546 observed: RequestMessages::MAX_LEN + 1,
547 });
548 }
549 if values
550 .iter()
551 .any(|existing| existing.message_id() == value.message_id())
552 {
553 return Err(ModelRequestError::DuplicateMessage {
554 message_id: value.message_id(),
555 });
556 }
557
558 for (part_index, part) in value.parts().iter().enumerate() {
559 let additional = match part {
560 ContentPart::Text(text) => {
561 modalities.insert(ModelModality::Text);
562 ByteCount::new(text.text().len() as u64)
563 }
564 ContentPart::Json(json) => {
565 modalities.insert(ModelModality::Text);
566 ByteCount::new(json.value().stats().compact_bytes() as u64)
567 }
568 ContentPart::Artifact(artifact) => {
569 let artifact_modality = artifact.representation().modality();
570 let model_modality = map_artifact_modality(artifact_modality).ok_or(
571 ModelRequestError::UnsupportedMessageArtifact {
572 message_index: values.len(),
573 part_index,
574 modality: artifact_modality,
575 },
576 )?;
577 modalities.insert(model_modality);
578 artifact.representation().byte_length()
579 }
580 };
581 *content_bytes = checked_content_add(
582 *content_bytes,
583 additional,
584 RequestMessages::MAX_CONTENT_BYTES,
585 ModelContentCollection::Messages,
586 )?;
587 }
588 values.push(value);
589 Ok(())
590}
591
592const fn map_artifact_modality(modality: ArtifactModality) -> Option<ModelModality> {
593 match modality {
594 ArtifactModality::Text => Some(ModelModality::Text),
595 ArtifactModality::Image => Some(ModelModality::Image),
596 ArtifactModality::Audio => Some(ModelModality::Audio),
597 ArtifactModality::Video => Some(ModelModality::Video),
598 ArtifactModality::Document => Some(ModelModality::Document),
599 ArtifactModality::StructuredData | ArtifactModality::Archive | ArtifactModality::Binary => {
600 None
601 }
602 }
603}
604
605#[derive(Clone, Eq, PartialEq)]
606struct RequestTools(BTreeMap<CapabilityName, ToolDescriptor>);
607
608impl RequestTools {
609 const MAX_LEN: usize = 128;
612
613 fn len(&self) -> usize {
614 self.0.len()
615 }
616
617 fn is_empty(&self) -> bool {
618 self.0.is_empty()
619 }
620
621 fn get(&self, name: &CapabilityName) -> Option<&ToolDescriptor> {
622 self.0.get(name)
623 }
624
625 fn iter(&self) -> btree_map::Values<'_, CapabilityName, ToolDescriptor> {
626 self.0.values()
627 }
628}
629
630impl fmt::Debug for RequestTools {
631 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
632 formatter
633 .debug_struct("RequestTools")
634 .field("count", &self.len())
635 .finish_non_exhaustive()
636 }
637}
638
639impl Serialize for RequestTools {
640 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
641 where
642 S: Serializer,
643 {
644 serializer.collect_seq(self.iter())
645 }
646}
647
648impl<'de> Deserialize<'de> for RequestTools {
649 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
650 where
651 D: Deserializer<'de>,
652 {
653 deserializer.deserialize_seq(RequestToolsVisitor)
654 }
655}
656
657struct RequestToolsVisitor;
658
659impl<'de> de::Visitor<'de> for RequestToolsVisitor {
660 type Value = RequestTools;
661
662 fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
663 write!(
664 formatter,
665 "an array containing at most {} active or deprecated tools with unique names",
666 RequestTools::MAX_LEN
667 )
668 }
669
670 fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
671 where
672 A: SeqAccess<'de>,
673 {
674 let mut values = BTreeMap::new();
675 while let Some(value) = sequence.next_element::<ToolDescriptor>()? {
676 insert_tool(&mut values, value).map_err(de::Error::custom)?;
677 }
678 Ok(RequestTools(values))
679 }
680}
681
682impl JsonSchema for RequestTools {
683 fn schema_name() -> std::borrow::Cow<'static, str> {
684 "ModelRequestTools".into()
685 }
686
687 fn schema_id() -> std::borrow::Cow<'static, str> {
688 concat!(module_path!(), "::RequestTools").into()
689 }
690
691 fn json_schema(generator: &mut SchemaGenerator) -> Schema {
692 json_schema!({
693 "type": "array",
694 "items": generator.subschema_for::<ToolDescriptor>(),
695 "maxItems": 128,
696 "uniqueItems": true,
697 "description": "Tools serialize in registry-local name order. Runtime rejects duplicate names across owners or versions and retired descriptors."
698 })
699 }
700}
701
702fn insert_tool(
703 values: &mut BTreeMap<CapabilityName, ToolDescriptor>,
704 value: ToolDescriptor,
705) -> Result<(), ModelRequestError> {
706 let name = value.metadata().identity().capability().name().clone();
707 if values.contains_key(&name) {
708 return Err(ModelRequestError::DuplicateToolName { name });
709 }
710 if values.len() == RequestTools::MAX_LEN {
711 return Err(ModelRequestError::TooManyTools {
712 max: RequestTools::MAX_LEN,
713 observed: RequestTools::MAX_LEN + 1,
714 });
715 }
716 if value.metadata().lifecycle().state() == CapabilityLifecycleState::Retired {
717 return Err(ModelRequestError::RetiredTool { name });
718 }
719 values.insert(name, value);
720 Ok(())
721}
722
723#[derive(Clone, Copy, Debug, Eq, PartialEq)]
724enum ModelContentCollection {
725 Instructions,
726 Messages,
727}
728
729fn checked_content_add(
730 current: ByteCount,
731 additional: ByteCount,
732 maximum: ByteCount,
733 collection: ModelContentCollection,
734) -> Result<ByteCount, ModelRequestError> {
735 let Some(actual) = current.checked_add(additional) else {
736 return Err(match collection {
737 ModelContentCollection::Instructions => {
738 ModelRequestError::InstructionContentBytesOverflow
739 }
740 ModelContentCollection::Messages => ModelRequestError::MessageContentBytesOverflow,
741 });
742 };
743 if actual > maximum {
744 return Err(match collection {
745 ModelContentCollection::Instructions => ModelRequestError::InstructionContentTooLarge {
746 maximum,
747 observed: actual,
748 },
749 ModelContentCollection::Messages => ModelRequestError::MessageContentTooLarge {
750 maximum,
751 observed: actual,
752 },
753 });
754 }
755 Ok(actual)
756}
757
758#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
771#[serde(deny_unknown_fields)]
772pub struct ModelRequest {
773 instructions: RequestInstructions,
774 messages: RequestMessages,
775 #[serde(default, skip_serializing_if = "ModelTranscript::is_empty")]
776 transcript: ModelTranscript,
777 tools: RequestTools,
778 tool_selection: ModelToolSelection,
779 max_tool_calls_per_response: ExecutionCount,
780 strict_tool_arguments: bool,
781 output_modalities: ModelModalities,
782 #[serde(skip_serializing_if = "Option::is_none")]
783 text_output_format: Option<ModelTextOutputFormat>,
784 response_mode: ModelResponseMode,
785 reasoning_summaries: bool,
786 limits: ModelRequestLimits,
787 extensions: Extensions,
788 requirements: ModelRequirements,
789}
790
791impl ModelRequest {
792 pub const MAX_TOOL_DEFINITIONS: ExecutionCount = ExecutionCount::new(128);
794
795 pub const MAX_TOOL_CALLS_PER_RESPONSE: ExecutionCount = ExecutionCount::new(1024);
797
798 #[must_use]
800 pub fn builder(limits: ModelRequestLimits) -> ModelRequestBuilder {
801 ModelRequestBuilder::new(limits)
802 }
803
804 #[allow(clippy::too_many_arguments)]
805 fn from_parts(
806 instructions: RequestInstructions,
807 messages: RequestMessages,
808 transcript: ModelTranscript,
809 tools: RequestTools,
810 tool_selection: ModelToolSelection,
811 max_tool_calls_per_response: ExecutionCount,
812 strict_tool_arguments: bool,
813 output_modalities: ModelModalities,
814 text_output_format: Option<ModelTextOutputFormat>,
815 response_mode: ModelResponseMode,
816 reasoning_summaries: bool,
817 limits: ModelRequestLimits,
818 extensions: Extensions,
819 wire_requirements: Option<&ModelRequirements>,
820 ) -> Result<Self, ModelRequestError> {
821 if instructions.is_empty() && messages.is_empty() && transcript.is_empty() {
822 return Err(ModelRequestError::EmptyInput);
823 }
824 if output_modalities.is_empty() {
825 return Err(ModelRequestError::EmptyOutputModalities);
826 }
827 let has_text_output = output_modalities.contains(ModelModality::Text);
828 match (has_text_output, text_output_format.is_some()) {
829 (true, false) => return Err(ModelRequestError::MissingTextOutputFormat),
830 (false, true) => return Err(ModelRequestError::UnexpectedTextOutputFormat),
831 _ => {}
832 }
833
834 validate_tool_controls(
835 &tools,
836 &tool_selection,
837 max_tool_calls_per_response,
838 strict_tool_arguments,
839 )?;
840 validate_transcript_tools(&transcript, &tools)?;
841
842 let content_bytes = instructions
843 .content_bytes
844 .checked_add(messages.content_bytes)
845 .and_then(|bytes| bytes.checked_add(transcript.payload_bytes()))
846 .ok_or(ModelRequestError::TranscriptContentBytesOverflow)?;
847 if content_bytes > limits.max_content_bytes() {
848 return Err(ModelRequestError::RequestContentTooLarge {
849 maximum: limits.max_content_bytes(),
850 observed: content_bytes,
851 });
852 }
853
854 let mut input_modalities = BTreeSet::new();
855 if !instructions.is_empty() {
856 input_modalities.insert(ModelModality::Text);
857 }
858 input_modalities.extend(messages.modalities.iter().copied());
859 if !transcript.is_empty() {
860 input_modalities.insert(ModelModality::Text);
861 }
862 let input_modalities = ModelModalities::try_new(input_modalities)
863 .expect("a BTreeSet of closed modalities is valid");
864
865 let tool_requirements = if tools.is_empty() {
866 ModelToolRequirements::none()
867 } else {
868 ModelToolRequirements::new(
869 ExecutionCount::new(tools.len() as u64),
870 max_tool_calls_per_response,
871 ModelToolChoices::try_new([tool_selection.choice()])
872 .expect("one closed tool choice is valid"),
873 strict_tool_arguments,
874 )
875 .map_err(ModelRequestError::InvalidToolRequirements)?
876 };
877 let structured_output = text_output_format
878 .as_ref()
879 .map_or(ModelStructuredOutputLevel::Unsupported, |format| {
880 format.required_level()
881 });
882 let requirements = ModelRequirements::new(
883 input_modalities,
884 output_modalities.clone(),
885 response_mode == ModelResponseMode::Streaming,
886 tool_requirements,
887 structured_output,
888 reasoning_summaries,
889 Some(limits.required_context_tokens()),
890 Some(limits.max_input_tokens()),
891 Some(limits.max_output_tokens()),
892 )
893 .map_err(ModelRequestError::InvalidRequirements)?;
894
895 if wire_requirements.is_some_and(|wire| wire != &requirements) {
896 return Err(ModelRequestError::RequirementsMismatch);
897 }
898
899 Ok(Self {
900 instructions,
901 messages,
902 transcript,
903 tools,
904 tool_selection,
905 max_tool_calls_per_response,
906 strict_tool_arguments,
907 output_modalities,
908 text_output_format,
909 response_mode,
910 reasoning_summaries,
911 limits,
912 extensions,
913 requirements,
914 })
915 }
916
917 #[must_use]
919 pub fn instructions(&self) -> &[Instruction] {
920 self.instructions.as_slice()
921 }
922
923 #[must_use]
925 pub fn messages(&self) -> &[Message] {
926 self.messages.as_slice()
927 }
928
929 #[must_use]
931 pub const fn transcript(&self) -> &ModelTranscript {
932 &self.transcript
933 }
934
935 pub fn tools(&self) -> impl ExactSizeIterator<Item = &ToolDescriptor> {
937 self.tools.iter()
938 }
939
940 #[must_use]
942 pub fn tool(&self, name: &CapabilityName) -> Option<&ToolDescriptor> {
943 self.tools.get(name)
944 }
945
946 #[must_use]
948 pub const fn tool_selection(&self) -> &ModelToolSelection {
949 &self.tool_selection
950 }
951
952 #[must_use]
954 pub const fn max_tool_calls_per_response(&self) -> ExecutionCount {
955 self.max_tool_calls_per_response
956 }
957
958 #[must_use]
960 pub const fn requires_strict_tool_arguments(&self) -> bool {
961 self.strict_tool_arguments
962 }
963
964 #[must_use]
966 pub const fn output_modalities(&self) -> &ModelModalities {
967 &self.output_modalities
968 }
969
970 #[must_use]
972 pub const fn text_output_format(&self) -> Option<&ModelTextOutputFormat> {
973 self.text_output_format.as_ref()
974 }
975
976 #[must_use]
978 pub const fn response_mode(&self) -> ModelResponseMode {
979 self.response_mode
980 }
981
982 #[must_use]
984 pub const fn requires_reasoning_summaries(&self) -> bool {
985 self.reasoning_summaries
986 }
987
988 #[must_use]
990 pub const fn limits(&self) -> &ModelRequestLimits {
991 &self.limits
992 }
993
994 #[must_use]
996 pub const fn extensions(&self) -> &Extensions {
997 &self.extensions
998 }
999
1000 #[must_use]
1002 pub const fn requirements(&self) -> &ModelRequirements {
1003 &self.requirements
1004 }
1005
1006 #[must_use]
1008 pub fn content_bytes(&self) -> ByteCount {
1009 self.instructions
1010 .content_bytes
1011 .checked_add(self.messages.content_bytes)
1012 .and_then(|bytes| bytes.checked_add(self.transcript.payload_bytes()))
1013 .expect("validated model request content bytes cannot overflow")
1014 }
1015}
1016
1017fn validate_tool_controls(
1018 tools: &RequestTools,
1019 selection: &ModelToolSelection,
1020 max_calls: ExecutionCount,
1021 strict_arguments: bool,
1022) -> Result<(), ModelRequestError> {
1023 if tools.is_empty() {
1024 if selection.choice() != ModelToolChoice::None {
1025 return Err(ModelRequestError::ToolSelectionWithoutTools {
1026 selection: selection.choice(),
1027 });
1028 }
1029 if max_calls.get() != 0 {
1030 return Err(ModelRequestError::ToolCallsWithoutTools { actual: max_calls });
1031 }
1032 if strict_arguments {
1033 return Err(ModelRequestError::StrictArgumentsWithoutTools);
1034 }
1035 return Ok(());
1036 }
1037
1038 if selection.choice() == ModelToolChoice::None {
1039 if max_calls != ExecutionCount::ZERO || strict_arguments {
1040 return Err(ModelRequestError::DisabledToolControls);
1041 }
1042 return Ok(());
1043 }
1044 if max_calls.get() == 0 {
1045 return Err(ModelRequestError::ZeroToolCalls);
1046 }
1047 if max_calls > ModelRequest::MAX_TOOL_CALLS_PER_RESPONSE {
1048 return Err(ModelRequestError::TooManyToolCalls {
1049 maximum: ModelRequest::MAX_TOOL_CALLS_PER_RESPONSE,
1050 actual: max_calls,
1051 });
1052 }
1053 if let Some(name) = selection.specific_name() {
1054 if tools.get(name).is_none() {
1055 return Err(ModelRequestError::SpecificToolNotFound { name: name.clone() });
1056 }
1057 }
1058 Ok(())
1059}
1060
1061fn validate_transcript_tools(
1062 transcript: &ModelTranscript,
1063 tools: &RequestTools,
1064) -> Result<(), ModelRequestError> {
1065 for (turn_index, turn) in transcript.iter().enumerate() {
1066 for (call_index, proposal) in turn.response().tool_calls().enumerate() {
1067 let Some(descriptor) = tools.get(proposal.tool().name()) else {
1068 return Err(ModelRequestError::TranscriptToolNotAvailable {
1069 turn_index,
1070 call_index,
1071 tool: Box::new(proposal.tool().clone()),
1072 });
1073 };
1074 let expected = descriptor.metadata().identity();
1075 if proposal.tool() != expected {
1076 return Err(ModelRequestError::TranscriptToolIdentityMismatch {
1077 turn_index,
1078 call_index,
1079 expected: Box::new(expected.clone()),
1080 actual: Box::new(proposal.tool().clone()),
1081 });
1082 }
1083 }
1084 }
1085 Ok(())
1086}
1087
1088impl fmt::Debug for ModelRequest {
1089 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1090 formatter
1091 .debug_struct("ModelRequest")
1092 .field("instructions", &self.instructions)
1093 .field("messages", &self.messages)
1094 .field("transcript", &self.transcript)
1095 .field("tools", &self.tools)
1096 .field("tool_selection", &self.tool_selection)
1097 .field(
1098 "max_tool_calls_per_response",
1099 &self.max_tool_calls_per_response,
1100 )
1101 .field("strict_tool_arguments", &self.strict_tool_arguments)
1102 .field("output_modalities", &self.output_modalities)
1103 .field("text_output_format", &self.text_output_format)
1104 .field("response_mode", &self.response_mode)
1105 .field("reasoning_summaries", &self.reasoning_summaries)
1106 .field("limits", &self.limits)
1107 .field("extensions", &self.extensions)
1108 .field("requirements", &self.requirements)
1109 .finish_non_exhaustive()
1110 }
1111}
1112
1113#[derive(Deserialize)]
1114#[serde(deny_unknown_fields)]
1115struct ModelRequestWire {
1116 instructions: RequestInstructions,
1117 messages: RequestMessages,
1118 #[serde(default)]
1119 transcript: ModelTranscript,
1120 tools: RequestTools,
1121 tool_selection: ModelToolSelection,
1122 max_tool_calls_per_response: ExecutionCount,
1123 strict_tool_arguments: bool,
1124 output_modalities: ModelModalities,
1125 #[serde(default)]
1126 text_output_format: Option<ModelTextOutputFormat>,
1127 response_mode: ModelResponseMode,
1128 reasoning_summaries: bool,
1129 limits: ModelRequestLimits,
1130 extensions: Extensions,
1131 requirements: ModelRequirements,
1132}
1133
1134impl<'de> Deserialize<'de> for ModelRequest {
1135 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1136 where
1137 D: Deserializer<'de>,
1138 {
1139 let wire = ModelRequestWire::deserialize(deserializer)?;
1140 Self::from_parts(
1141 wire.instructions,
1142 wire.messages,
1143 wire.transcript,
1144 wire.tools,
1145 wire.tool_selection,
1146 wire.max_tool_calls_per_response,
1147 wire.strict_tool_arguments,
1148 wire.output_modalities,
1149 wire.text_output_format,
1150 wire.response_mode,
1151 wire.reasoning_summaries,
1152 wire.limits,
1153 wire.extensions,
1154 Some(&wire.requirements),
1155 )
1156 .map_err(de::Error::custom)
1157 }
1158}
1159
1160pub struct ModelRequestBuilder {
1166 instructions: Vec<Instruction>,
1167 instruction_content_bytes: ByteCount,
1168 messages: Vec<Message>,
1169 message_content_bytes: ByteCount,
1170 message_modalities: BTreeSet<ModelModality>,
1171 transcript: ModelTranscript,
1172 tools: BTreeMap<CapabilityName, ToolDescriptor>,
1173 tool_selection: ModelToolSelection,
1174 max_tool_calls_per_response: ExecutionCount,
1175 strict_tool_arguments: bool,
1176 output_modalities: ModelModalities,
1177 text_output_format: Option<ModelTextOutputFormat>,
1178 response_mode: ModelResponseMode,
1179 reasoning_summaries: bool,
1180 limits: ModelRequestLimits,
1181 extensions: Extensions,
1182 error: Option<ModelRequestError>,
1183}
1184
1185impl ModelRequestBuilder {
1186 fn new(limits: ModelRequestLimits) -> Self {
1187 Self {
1188 instructions: Vec::new(),
1189 instruction_content_bytes: ByteCount::ZERO,
1190 messages: Vec::new(),
1191 message_content_bytes: ByteCount::ZERO,
1192 message_modalities: BTreeSet::new(),
1193 transcript: ModelTranscript::empty(),
1194 tools: BTreeMap::new(),
1195 tool_selection: ModelToolSelection::none(),
1196 max_tool_calls_per_response: ExecutionCount::ZERO,
1197 strict_tool_arguments: false,
1198 output_modalities: ModelModalities::try_new([ModelModality::Text])
1199 .expect("one closed modality is valid"),
1200 text_output_format: Some(ModelTextOutputFormat::text()),
1201 response_mode: ModelResponseMode::Complete,
1202 reasoning_summaries: false,
1203 limits,
1204 extensions: Extensions::default(),
1205 error: None,
1206 }
1207 }
1208
1209 #[must_use]
1211 pub fn instruction(mut self, instruction: Instruction) -> Self {
1212 if self.error.is_none() {
1213 if let Err(error) = push_instruction(
1214 &mut self.instructions,
1215 &mut self.instruction_content_bytes,
1216 instruction,
1217 ) {
1218 self.error = Some(error);
1219 }
1220 }
1221 self
1222 }
1223
1224 #[must_use]
1226 pub fn message(mut self, message: Message) -> Self {
1227 if self.error.is_none() {
1228 if let Err(error) = push_message(
1229 &mut self.messages,
1230 &mut self.message_content_bytes,
1231 &mut self.message_modalities,
1232 message,
1233 ) {
1234 self.error = Some(error);
1235 }
1236 }
1237 self
1238 }
1239
1240 #[must_use]
1242 pub fn transcript(mut self, transcript: ModelTranscript) -> Self {
1243 self.transcript = transcript;
1244 self
1245 }
1246
1247 #[must_use]
1249 pub fn tool(mut self, tool: ToolDescriptor) -> Self {
1250 if self.error.is_none() {
1251 if let Err(error) = insert_tool(&mut self.tools, tool) {
1252 self.error = Some(error);
1253 }
1254 }
1255 self
1256 }
1257
1258 #[must_use]
1260 pub fn tool_selection(mut self, selection: ModelToolSelection) -> Self {
1261 self.tool_selection = selection;
1262 self
1263 }
1264
1265 #[must_use]
1267 pub const fn max_tool_calls_per_response(mut self, maximum: ExecutionCount) -> Self {
1268 self.max_tool_calls_per_response = maximum;
1269 self
1270 }
1271
1272 #[must_use]
1274 pub const fn strict_tool_arguments(mut self, required: bool) -> Self {
1275 self.strict_tool_arguments = required;
1276 self
1277 }
1278
1279 #[must_use]
1281 pub fn output_modalities(mut self, modalities: ModelModalities) -> Self {
1282 self.output_modalities = modalities;
1283 self
1284 }
1285
1286 #[must_use]
1288 pub fn text_output_format(mut self, format: Option<ModelTextOutputFormat>) -> Self {
1289 self.text_output_format = format;
1290 self
1291 }
1292
1293 #[must_use]
1295 pub const fn response_mode(mut self, mode: ModelResponseMode) -> Self {
1296 self.response_mode = mode;
1297 self
1298 }
1299
1300 #[must_use]
1302 pub const fn reasoning_summaries(mut self, required: bool) -> Self {
1303 self.reasoning_summaries = required;
1304 self
1305 }
1306
1307 #[must_use]
1309 pub fn extensions(mut self, extensions: Extensions) -> Self {
1310 self.extensions = extensions;
1311 self
1312 }
1313
1314 pub fn build(self) -> Result<ModelRequest, ModelRequestError> {
1321 if let Some(error) = self.error {
1322 return Err(error);
1323 }
1324 ModelRequest::from_parts(
1325 RequestInstructions {
1326 values: self.instructions.into_boxed_slice(),
1327 content_bytes: self.instruction_content_bytes,
1328 },
1329 RequestMessages {
1330 values: self.messages.into_boxed_slice(),
1331 content_bytes: self.message_content_bytes,
1332 modalities: ModelModalities::try_new(self.message_modalities)
1333 .expect("a BTreeSet of closed modalities is valid"),
1334 },
1335 self.transcript,
1336 RequestTools(self.tools),
1337 self.tool_selection,
1338 self.max_tool_calls_per_response,
1339 self.strict_tool_arguments,
1340 self.output_modalities,
1341 self.text_output_format,
1342 self.response_mode,
1343 self.reasoning_summaries,
1344 self.limits,
1345 self.extensions,
1346 None,
1347 )
1348 }
1349}
1350
1351impl fmt::Debug for ModelRequestBuilder {
1352 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1353 formatter
1354 .debug_struct("ModelRequestBuilder")
1355 .field("instruction_count", &self.instructions.len())
1356 .field("instruction_content_bytes", &self.instruction_content_bytes)
1357 .field("message_count", &self.messages.len())
1358 .field("message_content_bytes", &self.message_content_bytes)
1359 .field("transcript", &self.transcript)
1360 .field("tool_count", &self.tools.len())
1361 .field("tool_selection", &self.tool_selection)
1362 .field(
1363 "max_tool_calls_per_response",
1364 &self.max_tool_calls_per_response,
1365 )
1366 .field("strict_tool_arguments", &self.strict_tool_arguments)
1367 .field("output_modalities", &self.output_modalities)
1368 .field("text_output_format", &self.text_output_format)
1369 .field("response_mode", &self.response_mode)
1370 .field("reasoning_summaries", &self.reasoning_summaries)
1371 .field("limits", &self.limits)
1372 .field("extensions", &self.extensions)
1373 .field("has_error", &self.error.is_some())
1374 .finish_non_exhaustive()
1375 }
1376}
1377
1378#[derive(Clone, Debug, Eq, Error, PartialEq)]
1380#[non_exhaustive]
1381pub enum ModelRequestError {
1382 #[error("model request requires at least one instruction, message, or transcript turn")]
1384 EmptyInput,
1385 #[error("model request contains at least {observed} instructions; maximum is {max}")]
1387 TooManyInstructions {
1388 max: usize,
1390 observed: usize,
1392 },
1393 #[error("model request repeats instruction identity {identity:?}")]
1395 DuplicateInstruction {
1396 identity: InstructionIdentity,
1398 },
1399 #[error("model request instruction {index} has unsupported artifact modality {modality:?}")]
1401 UnsupportedInstructionArtifact {
1402 index: usize,
1404 modality: ArtifactModality,
1406 },
1407 #[error("model request contains at least {observed} messages; maximum is {max}")]
1409 TooManyMessages {
1410 max: usize,
1412 observed: usize,
1414 },
1415 #[error("model request repeats message ID {message_id}")]
1417 DuplicateMessage {
1418 message_id: MessageId,
1420 },
1421 #[error(
1423 "model request message {message_index} part {part_index} has unsupported artifact modality {modality:?}"
1424 )]
1425 UnsupportedMessageArtifact {
1426 message_index: usize,
1428 part_index: usize,
1430 modality: ArtifactModality,
1432 },
1433 #[error("model request instruction content is {observed} bytes; maximum is {maximum}")]
1435 InstructionContentTooLarge {
1436 maximum: ByteCount,
1438 observed: ByteCount,
1440 },
1441 #[error("model request message content is {observed} bytes; maximum is {maximum}")]
1443 MessageContentTooLarge {
1444 maximum: ByteCount,
1446 observed: ByteCount,
1448 },
1449 #[error("model request instruction content-byte accounting overflowed")]
1451 InstructionContentBytesOverflow,
1452 #[error("model request message content-byte accounting overflowed")]
1454 MessageContentBytesOverflow,
1455 #[error("model request transcript content-byte accounting overflowed")]
1457 TranscriptContentBytesOverflow,
1458 #[error("model request content is {observed} bytes; configured maximum is {maximum}")]
1460 RequestContentTooLarge {
1461 maximum: ByteCount,
1463 observed: ByteCount,
1465 },
1466 #[error("model request contains at least {observed} tools; maximum is {max}")]
1468 TooManyTools {
1469 max: usize,
1471 observed: usize,
1473 },
1474 #[error("model request contains duplicate tool name {name}")]
1476 DuplicateToolName {
1477 name: CapabilityName,
1479 },
1480 #[error("model request cannot select retired tool {name}")]
1482 RetiredTool {
1483 name: CapabilityName,
1485 },
1486 #[error(
1488 "model transcript turn {turn_index} call {call_index} references unavailable tool {tool:?}"
1489 )]
1490 TranscriptToolNotAvailable {
1491 turn_index: usize,
1493 call_index: usize,
1495 tool: Box<CapabilityIdentity>,
1497 },
1498 #[error(
1500 "model transcript turn {turn_index} call {call_index} tool identity does not match the request snapshot"
1501 )]
1502 TranscriptToolIdentityMismatch {
1503 turn_index: usize,
1505 call_index: usize,
1507 expected: Box<CapabilityIdentity>,
1509 actual: Box<CapabilityIdentity>,
1511 },
1512 #[error("model request tool selection {selection:?} requires at least one tool")]
1514 ToolSelectionWithoutTools {
1515 selection: ModelToolChoice,
1517 },
1518 #[error("model request without tools cannot allow {actual} tool calls")]
1520 ToolCallsWithoutTools {
1521 actual: ExecutionCount,
1523 },
1524 #[error("model request without tools cannot require strict tool arguments")]
1526 StrictArgumentsWithoutTools,
1527 #[error("disabled tool selection requires zero calls and non-strict arguments")]
1529 DisabledToolControls,
1530 #[error("model request with tools requires a positive tool-call ceiling")]
1532 ZeroToolCalls,
1533 #[error("model request tool-call ceiling {actual} exceeds maximum {maximum}")]
1535 TooManyToolCalls {
1536 maximum: ExecutionCount,
1538 actual: ExecutionCount,
1540 },
1541 #[error("model request selected unavailable tool {name}")]
1543 SpecificToolNotFound {
1544 name: CapabilityName,
1546 },
1547 #[error("model request requires at least one output modality")]
1549 EmptyOutputModalities,
1550 #[error("model request with text output requires an explicit text output format")]
1552 MissingTextOutputFormat,
1553 #[error("model request without text output cannot declare a text output format")]
1555 UnexpectedTextOutputFormat,
1556 #[error("model request could not derive coherent tool requirements: {0}")]
1558 InvalidToolRequirements(crate::ModelToolRequirementsError),
1559 #[error("model request could not derive coherent requirements: {0}")]
1561 InvalidRequirements(ModelRequirementsError),
1562 #[error("model request serialized requirements do not match normalized request fields")]
1564 RequirementsMismatch,
1565}
1566
1567#[cfg(test)]
1568mod tests {
1569 use super::*;
1570 use crate::{ArtifactRef, MessageParts};
1571 use proptest::prelude::*;
1572 use serde_json::{Value, from_value, json, to_value};
1573
1574 fn fixture(path: &[&str], source: &str) -> Value {
1575 let mut value = serde_json::from_str::<Value>(source).unwrap();
1576 for segment in path {
1577 value = value[*segment].clone();
1578 }
1579 value
1580 }
1581
1582 fn instruction() -> Instruction {
1583 let values = fixture(
1584 &["instructions", "valid"],
1585 include_str!("../tests/fixtures/core-message-v1.json"),
1586 );
1587 from_value(values[0].clone()).unwrap()
1588 }
1589
1590 fn message() -> Message {
1591 let values = fixture(
1592 &["messages", "valid"],
1593 include_str!("../tests/fixtures/core-message-v1.json"),
1594 );
1595 from_value(values[0].clone()).unwrap()
1596 }
1597
1598 fn tool_value(name: &str) -> Value {
1599 let values = fixture(
1600 &["descriptors", "valid"],
1601 include_str!("../tests/fixtures/core-tool-v1.json"),
1602 );
1603 let mut value = values[0].clone();
1604 value["metadata"]["identity"]["capability"]["name"] = Value::from(name);
1605 value
1606 }
1607
1608 fn tool(name: &str) -> ToolDescriptor {
1609 from_value(tool_value(name)).unwrap()
1610 }
1611
1612 fn artifact(
1613 modality: ArtifactModality,
1614 byte_length: ByteCount,
1615 application_controlled: bool,
1616 ) -> ArtifactRef {
1617 let values = fixture(
1618 &["artifact_refs", "valid"],
1619 include_str!("../tests/fixtures/core-artifact-v1.json"),
1620 );
1621 let mut value = values[0].clone();
1622 value["representation"]["modality"] = to_value(modality).unwrap();
1623 value["representation"]["byte_length"] = Value::from(byte_length.get().to_string());
1624 if application_controlled {
1625 value["metadata"]["trust"] = Value::from("application_controlled");
1626 }
1627 from_value(value).unwrap()
1628 }
1629
1630 fn instruction_artifact(modality: ArtifactModality, byte_length: ByteCount) -> Instruction {
1631 let base = instruction();
1632 Instruction::new(
1633 base.identity().clone(),
1634 artifact(modality, byte_length, true).into(),
1635 base.provenance().clone(),
1636 )
1637 .unwrap()
1638 }
1639
1640 fn message_artifact(modality: ArtifactModality, byte_length: ByteCount) -> Message {
1641 let base = message();
1642 Message::new(
1643 base.message_id(),
1644 base.role(),
1645 MessageParts::try_new([ContentPart::from(artifact(modality, byte_length, false))])
1646 .unwrap(),
1647 base.provenance().clone(),
1648 )
1649 .unwrap()
1650 }
1651
1652 fn retired_tool(name: &str) -> ToolDescriptor {
1653 let mut value = tool_value(name);
1654 value["metadata"]["lifecycle"] = json!({
1655 "status": "retired",
1656 "retired_at": "2027-02-28T00:00:00.000001Z",
1657 "notice": "Retained only for durable history."
1658 });
1659 from_value(value).unwrap()
1660 }
1661
1662 fn limits() -> ModelRequestLimits {
1663 ModelRequestLimits::new(
1664 TokenCount::new(8_192),
1665 TokenCount::new(1_024),
1666 ByteCount::new(MEBIBYTE),
1667 )
1668 .unwrap()
1669 }
1670
1671 fn modalities(values: impl IntoIterator<Item = ModelModality>) -> ModelModalities {
1672 ModelModalities::try_new(values).unwrap()
1673 }
1674
1675 fn base_builder() -> ModelRequestBuilder {
1676 ModelRequest::builder(limits()).instruction(instruction())
1677 }
1678
1679 fn base_request() -> ModelRequest {
1680 base_builder().message(message()).build().unwrap()
1681 }
1682
1683 #[test]
1684 fn request_control_enums_have_closed_canonical_wire_forms() {
1685 assert_eq!(to_value(ModelResponseMode::Complete).unwrap(), "complete");
1686 assert_eq!(to_value(ModelResponseMode::Streaming).unwrap(), "streaming");
1687 assert!(from_value::<ModelResponseMode>(json!("incremental")).is_err());
1688
1689 assert_eq!(
1690 to_value(ModelToolSelection::none()).unwrap(),
1691 json!({"mode": "none"})
1692 );
1693 assert_eq!(
1694 to_value(ModelToolSelection::auto()).unwrap(),
1695 json!({"mode": "auto"})
1696 );
1697 assert_eq!(
1698 to_value(ModelToolSelection::required()).unwrap(),
1699 json!({"mode": "required"})
1700 );
1701 let name = CapabilityName::new("payments.capture").unwrap();
1702 let specific = ModelToolSelection::specific(name.clone());
1703 assert_eq!(specific.choice(), ModelToolChoice::Specific);
1704 assert_eq!(specific.specific_name(), Some(&name));
1705 assert_eq!(
1706 to_value(specific).unwrap(),
1707 json!({"mode": "specific", "name": "payments.capture"})
1708 );
1709 assert!(from_value::<ModelToolSelection>(json!({"mode": "none", "name": "x"})).is_err());
1710
1711 assert_eq!(
1712 to_value(ModelTextOutputFormat::text()).unwrap(),
1713 json!({"type": "text"})
1714 );
1715 assert_eq!(
1716 to_value(ModelTextOutputFormat::json()).unwrap(),
1717 json!({"type": "json"})
1718 );
1719 assert!(from_value::<ModelTextOutputFormat>(json!({"type": "xml"})).is_err());
1720 }
1721
1722 #[test]
1723 fn limits_are_positive_bounded_checked_and_closed() {
1724 assert_eq!(limits().required_context_tokens(), TokenCount::new(9_216));
1725 assert_eq!(
1726 ModelRequestLimits::new(TokenCount::ZERO, TokenCount::new(1), ByteCount::new(1)),
1727 Err(ModelRequestLimitsError::ZeroInputTokens)
1728 );
1729 assert_eq!(
1730 ModelRequestLimits::new(TokenCount::new(1), TokenCount::ZERO, ByteCount::new(1)),
1731 Err(ModelRequestLimitsError::ZeroOutputTokens)
1732 );
1733 assert_eq!(
1734 ModelRequestLimits::new(TokenCount::new(1), TokenCount::new(1), ByteCount::ZERO),
1735 Err(ModelRequestLimitsError::ZeroContentBytes)
1736 );
1737 assert_eq!(
1738 ModelRequestLimits::new(
1739 TokenCount::new(1),
1740 TokenCount::new(1),
1741 ByteCount::new(ModelRequestLimits::HARD_MAX_CONTENT_BYTES.get() + 1)
1742 ),
1743 Err(ModelRequestLimitsError::ContentBytesAboveHardMaximum {
1744 maximum: ModelRequestLimits::HARD_MAX_CONTENT_BYTES,
1745 actual: ByteCount::new(ModelRequestLimits::HARD_MAX_CONTENT_BYTES.get() + 1),
1746 })
1747 );
1748 assert_eq!(
1749 ModelRequestLimits::new(TokenCount::MAX, TokenCount::new(1), ByteCount::new(1)),
1750 Err(ModelRequestLimitsError::ContextTokensOverflow)
1751 );
1752
1753 let encoded = to_value(limits()).unwrap();
1754 assert_eq!(
1755 from_value::<ModelRequestLimits>(encoded.clone()).unwrap(),
1756 limits()
1757 );
1758 let mut unknown = encoded;
1759 unknown["unlimited"] = Value::Bool(true);
1760 assert!(from_value::<ModelRequestLimits>(unknown).is_err());
1761 }
1762
1763 #[test]
1764 fn default_request_derives_exact_requirements_and_redacts_payloads() {
1765 let request = base_request();
1766 assert_eq!(request.instructions(), &[instruction()]);
1767 assert_eq!(request.messages(), &[message()]);
1768 assert_eq!(request.tools().len(), 0);
1769 assert_eq!(request.tool_selection(), &ModelToolSelection::none());
1770 assert_eq!(request.max_tool_calls_per_response(), ExecutionCount::ZERO);
1771 assert!(!request.requires_strict_tool_arguments());
1772 assert_eq!(request.response_mode(), ModelResponseMode::Complete);
1773 assert_eq!(
1774 request.text_output_format(),
1775 Some(&ModelTextOutputFormat::text())
1776 );
1777
1778 let requirements = request.requirements();
1779 assert!(
1780 requirements
1781 .input_modalities()
1782 .contains(ModelModality::Text)
1783 );
1784 assert!(
1785 requirements
1786 .output_modalities()
1787 .contains(ModelModality::Text)
1788 );
1789 assert!(!requirements.requires_streaming());
1790 assert!(!requirements.tools().requires_tool_calling());
1791 assert_eq!(
1792 requirements.structured_output(),
1793 ModelStructuredOutputLevel::Unsupported
1794 );
1795 assert!(!requirements.requires_reasoning_summaries());
1796 assert_eq!(
1797 requirements.min_context_tokens(),
1798 Some(TokenCount::new(9_216))
1799 );
1800 assert_eq!(
1801 requirements.min_input_tokens(),
1802 Some(TokenCount::new(8_192))
1803 );
1804 assert_eq!(
1805 requirements.min_output_tokens(),
1806 Some(TokenCount::new(1_024))
1807 );
1808 assert!(request.content_bytes().get() > 0);
1809
1810 let encoded = to_value(&request).unwrap();
1811 assert_eq!(from_value::<ModelRequest>(encoded).unwrap(), request);
1812 let debug = format!("{request:?}");
1813 assert!(!debug.contains("Return a typed incident summary"));
1814 assert!(!debug.contains("Investigate incident 42"));
1815 }
1816
1817 #[test]
1818 fn tools_are_canonical_and_derive_exact_selection_requirements() {
1819 let selected = CapabilityName::new("alpha.lookup").unwrap();
1820 let request = base_builder()
1821 .tool(tool("zeta.lookup"))
1822 .tool(tool("alpha.lookup"))
1823 .tool_selection(ModelToolSelection::specific(selected.clone()))
1824 .max_tool_calls_per_response(ExecutionCount::new(4))
1825 .strict_tool_arguments(true)
1826 .build()
1827 .unwrap();
1828
1829 let names = request
1830 .tools()
1831 .map(|descriptor| {
1832 descriptor
1833 .metadata()
1834 .identity()
1835 .capability()
1836 .name()
1837 .as_str()
1838 })
1839 .collect::<Vec<_>>();
1840 assert_eq!(names, ["alpha.lookup", "zeta.lookup"]);
1841 assert!(request.tool(&selected).is_some());
1842 let requirements = request.requirements().tools();
1843 assert_eq!(requirements.min_definitions(), ExecutionCount::new(2));
1844 assert_eq!(
1845 requirements.min_calls_per_response(),
1846 ExecutionCount::new(4)
1847 );
1848 assert!(requirements.choices().contains(ModelToolChoice::Specific));
1849 assert!(requirements.requires_strict_arguments());
1850 }
1851
1852 #[test]
1853 fn disabled_tools_retain_definitions_and_require_explicit_provider_support() {
1854 let request = base_builder()
1855 .tool(tool("payments.capture"))
1856 .build()
1857 .unwrap();
1858 assert_eq!(request.tools().len(), 1);
1859 assert_eq!(request.max_tool_calls_per_response(), ExecutionCount::ZERO);
1860 assert!(
1861 request
1862 .requirements()
1863 .tools()
1864 .choices()
1865 .contains(ModelToolChoice::None)
1866 );
1867 assert_eq!(
1868 request.requirements().tools().min_definitions(),
1869 ExecutionCount::new(1)
1870 );
1871 assert_eq!(
1872 request.requirements().tools().min_calls_per_response(),
1873 ExecutionCount::ZERO
1874 );
1875 let wire = serde_json::to_value(&request).unwrap();
1876 assert_eq!(
1877 serde_json::from_value::<ModelRequest>(wire.clone()).unwrap(),
1878 request
1879 );
1880 let mut tampered = wire;
1881 tampered["max_tool_calls_per_response"] = serde_json::json!("1");
1882 assert!(serde_json::from_value::<ModelRequest>(tampered).is_err());
1883 assert_eq!(
1884 base_builder()
1885 .tool(tool("payments.capture"))
1886 .strict_tool_arguments(true)
1887 .build(),
1888 Err(ModelRequestError::DisabledToolControls)
1889 );
1890 }
1891
1892 #[test]
1893 fn tool_controls_and_registry_names_fail_closed() {
1894 assert_eq!(
1895 base_builder()
1896 .tool_selection(ModelToolSelection::auto())
1897 .build(),
1898 Err(ModelRequestError::ToolSelectionWithoutTools {
1899 selection: ModelToolChoice::Auto,
1900 })
1901 );
1902 assert_eq!(
1903 base_builder()
1904 .max_tool_calls_per_response(ExecutionCount::new(1))
1905 .build(),
1906 Err(ModelRequestError::ToolCallsWithoutTools {
1907 actual: ExecutionCount::new(1),
1908 })
1909 );
1910 assert_eq!(
1911 base_builder().strict_tool_arguments(true).build(),
1912 Err(ModelRequestError::StrictArgumentsWithoutTools)
1913 );
1914 assert_eq!(
1915 base_builder()
1916 .tool(tool("payments.capture"))
1917 .max_tool_calls_per_response(ExecutionCount::new(1))
1918 .build(),
1919 Err(ModelRequestError::DisabledToolControls)
1920 );
1921 assert_eq!(
1922 base_builder()
1923 .tool(tool("payments.capture"))
1924 .tool_selection(ModelToolSelection::auto())
1925 .build(),
1926 Err(ModelRequestError::ZeroToolCalls)
1927 );
1928 assert_eq!(
1929 base_builder()
1930 .tool(tool("payments.capture"))
1931 .tool_selection(ModelToolSelection::auto())
1932 .max_tool_calls_per_response(ExecutionCount::new(1_025))
1933 .build(),
1934 Err(ModelRequestError::TooManyToolCalls {
1935 maximum: ModelRequest::MAX_TOOL_CALLS_PER_RESPONSE,
1936 actual: ExecutionCount::new(1_025),
1937 })
1938 );
1939
1940 let missing = CapabilityName::new("missing.tool").unwrap();
1941 assert_eq!(
1942 base_builder()
1943 .tool(tool("payments.capture"))
1944 .tool_selection(ModelToolSelection::specific(missing.clone()))
1945 .max_tool_calls_per_response(ExecutionCount::new(1))
1946 .build(),
1947 Err(ModelRequestError::SpecificToolNotFound { name: missing })
1948 );
1949 assert_eq!(
1950 base_builder()
1951 .tool(tool("payments.capture"))
1952 .tool(tool("payments.capture"))
1953 .build(),
1954 Err(ModelRequestError::DuplicateToolName {
1955 name: CapabilityName::new("payments.capture").unwrap(),
1956 })
1957 );
1958 assert_eq!(
1959 base_builder().tool(retired_tool("retired.tool")).build(),
1960 Err(ModelRequestError::RetiredTool {
1961 name: CapabilityName::new("retired.tool").unwrap(),
1962 })
1963 );
1964 }
1965
1966 #[test]
1967 fn output_controls_derive_structured_streaming_and_reasoning_requirements() {
1968 let schema = tool("payments.capture").input_schema().clone();
1969 let request = base_builder()
1970 .text_output_format(Some(ModelTextOutputFormat::json_schema(schema.clone())))
1971 .response_mode(ModelResponseMode::Streaming)
1972 .reasoning_summaries(true)
1973 .build()
1974 .unwrap();
1975 assert_eq!(
1976 request
1977 .text_output_format()
1978 .and_then(ModelTextOutputFormat::schema),
1979 Some(&schema)
1980 );
1981 assert!(request.requirements().requires_streaming());
1982 assert!(request.requirements().requires_reasoning_summaries());
1983 assert_eq!(
1984 request.requirements().structured_output(),
1985 ModelStructuredOutputLevel::JsonSchema
1986 );
1987
1988 assert_eq!(
1989 base_builder()
1990 .output_modalities(ModelModalities::empty())
1991 .text_output_format(None)
1992 .build(),
1993 Err(ModelRequestError::EmptyOutputModalities)
1994 );
1995 assert_eq!(
1996 base_builder().text_output_format(None).build(),
1997 Err(ModelRequestError::MissingTextOutputFormat)
1998 );
1999 assert_eq!(
2000 base_builder()
2001 .output_modalities(modalities([ModelModality::Image]))
2002 .build(),
2003 Err(ModelRequestError::UnexpectedTextOutputFormat)
2004 );
2005
2006 let image = base_builder()
2007 .output_modalities(modalities([ModelModality::Image]))
2008 .text_output_format(None)
2009 .build()
2010 .unwrap();
2011 assert_eq!(image.text_output_format(), None);
2012 assert!(
2013 image
2014 .requirements()
2015 .output_modalities()
2016 .contains(ModelModality::Image)
2017 );
2018 }
2019
2020 #[test]
2021 fn duplicate_inputs_and_request_content_limits_are_enforced() {
2022 let duplicate_instruction = instruction();
2023 assert_eq!(
2024 ModelRequest::builder(limits())
2025 .instruction(duplicate_instruction.clone())
2026 .instruction(duplicate_instruction.clone())
2027 .build(),
2028 Err(ModelRequestError::DuplicateInstruction {
2029 identity: duplicate_instruction.identity().clone(),
2030 })
2031 );
2032
2033 let duplicate_message = message();
2034 assert_eq!(
2035 ModelRequest::builder(limits())
2036 .message(duplicate_message.clone())
2037 .message(duplicate_message.clone())
2038 .build(),
2039 Err(ModelRequestError::DuplicateMessage {
2040 message_id: duplicate_message.message_id(),
2041 })
2042 );
2043
2044 let tiny =
2045 ModelRequestLimits::new(TokenCount::new(1), TokenCount::new(1), ByteCount::new(1))
2046 .unwrap();
2047 assert!(matches!(
2048 ModelRequest::builder(tiny)
2049 .instruction(instruction())
2050 .build(),
2051 Err(ModelRequestError::RequestContentTooLarge { .. })
2052 ));
2053 assert_eq!(
2054 ModelRequest::builder(limits()).build(),
2055 Err(ModelRequestError::EmptyInput)
2056 );
2057 }
2058
2059 #[test]
2060 fn collection_count_ceilings_stop_at_the_first_excess_value() {
2061 let instruction_wire = to_value(instruction()).unwrap();
2062 let mut instruction_builder = ModelRequest::builder(limits());
2063 for index in 0..=RequestInstructions::MAX_LEN {
2064 let mut value = instruction_wire.clone();
2065 value["identity"]["name"] = Value::from(format!("policy.{index}"));
2066 instruction_builder = instruction_builder.instruction(from_value(value).unwrap());
2067 }
2068 assert_eq!(
2069 instruction_builder.build(),
2070 Err(ModelRequestError::TooManyInstructions {
2071 max: RequestInstructions::MAX_LEN,
2072 observed: RequestInstructions::MAX_LEN + 1,
2073 })
2074 );
2075
2076 let message_wire = to_value(message()).unwrap();
2077 let mut message_builder = ModelRequest::builder(limits());
2078 for index in 0..=RequestMessages::MAX_LEN {
2079 let mut value = message_wire.clone();
2080 value["message_id"] = Value::from(format!("01912345-6789-7abc-8def-{index:012x}"));
2081 message_builder = message_builder.message(from_value(value).unwrap());
2082 }
2083 assert_eq!(
2084 message_builder.build(),
2085 Err(ModelRequestError::TooManyMessages {
2086 max: RequestMessages::MAX_LEN,
2087 observed: RequestMessages::MAX_LEN + 1,
2088 })
2089 );
2090
2091 let tool_wire = to_value(tool("bounded.tool")).unwrap();
2092 let mut tool_builder = base_builder();
2093 for index in 0..=RequestTools::MAX_LEN {
2094 let mut value = tool_wire.clone();
2095 value["metadata"]["identity"]["capability"]["name"] =
2096 Value::from(format!("tool.{index}"));
2097 tool_builder = tool_builder.tool(from_value(value).unwrap());
2098 }
2099 assert_eq!(
2100 tool_builder.build(),
2101 Err(ModelRequestError::TooManyTools {
2102 max: RequestTools::MAX_LEN,
2103 observed: RequestTools::MAX_LEN + 1,
2104 })
2105 );
2106 }
2107
2108 #[test]
2109 fn artifact_modalities_and_resolved_byte_bounds_fail_closed() {
2110 for (artifact_modality, model_modality) in [
2111 (ArtifactModality::Text, ModelModality::Text),
2112 (ArtifactModality::Image, ModelModality::Image),
2113 (ArtifactModality::Audio, ModelModality::Audio),
2114 (ArtifactModality::Video, ModelModality::Video),
2115 (ArtifactModality::Document, ModelModality::Document),
2116 ] {
2117 let request = ModelRequest::builder(limits())
2118 .message(message_artifact(artifact_modality, ByteCount::new(12)))
2119 .build()
2120 .unwrap();
2121 assert!(
2122 request
2123 .requirements()
2124 .input_modalities()
2125 .contains(model_modality)
2126 );
2127 }
2128
2129 for modality in [
2130 ArtifactModality::StructuredData,
2131 ArtifactModality::Archive,
2132 ArtifactModality::Binary,
2133 ] {
2134 assert!(matches!(
2135 ModelRequest::builder(limits())
2136 .message(message_artifact(modality, ByteCount::new(12)))
2137 .build(),
2138 Err(ModelRequestError::UnsupportedMessageArtifact {
2139 message_index: 0,
2140 part_index: 0,
2141 modality: actual,
2142 }) if actual == modality
2143 ));
2144 }
2145
2146 assert_eq!(
2147 ModelRequest::builder(limits())
2148 .instruction(instruction_artifact(
2149 ArtifactModality::Image,
2150 ByteCount::new(12),
2151 ))
2152 .build(),
2153 Err(ModelRequestError::UnsupportedInstructionArtifact {
2154 index: 0,
2155 modality: ArtifactModality::Image,
2156 })
2157 );
2158 assert!(matches!(
2159 ModelRequest::builder(limits())
2160 .instruction(instruction_artifact(
2161 ArtifactModality::Text,
2162 ByteCount::new(RequestInstructions::MAX_CONTENT_BYTES.get() + 1),
2163 ))
2164 .build(),
2165 Err(ModelRequestError::InstructionContentTooLarge { .. })
2166 ));
2167 assert!(matches!(
2168 ModelRequest::builder(limits())
2169 .message(message_artifact(
2170 ArtifactModality::Document,
2171 ByteCount::new(RequestMessages::MAX_CONTENT_BYTES.get() + 1),
2172 ))
2173 .build(),
2174 Err(ModelRequestError::MessageContentTooLarge { .. })
2175 ));
2176 }
2177
2178 #[test]
2179 fn derived_wire_requirements_and_closed_fields_cannot_be_tampered() {
2180 let request = base_request();
2181 let mut tampered = to_value(&request).unwrap();
2182 tampered["requirements"]["streaming"] = Value::Bool(true);
2183 assert!(from_value::<ModelRequest>(tampered).is_err());
2184
2185 let mut unknown = to_value(&request).unwrap();
2186 unknown["store"] = Value::Bool(true);
2187 assert!(from_value::<ModelRequest>(unknown).is_err());
2188
2189 let encoded = serde_json::to_string(&request).unwrap();
2190 let duplicate = encoded.replacen(
2191 "\"response_mode\":\"complete\"",
2192 "\"response_mode\":\"complete\",\"response_mode\":\"streaming\"",
2193 1,
2194 );
2195 assert_ne!(duplicate, encoded);
2196 assert!(serde_json::from_str::<ModelRequest>(&duplicate).is_err());
2197 }
2198
2199 #[test]
2200 fn request_schemas_publish_closed_objects_and_resource_bounds() {
2201 for schema in [
2202 to_value(schemars::schema_for!(ModelRequestLimits)).unwrap(),
2203 to_value(schemars::schema_for!(ModelRequest)).unwrap(),
2204 ] {
2205 assert_eq!(schema["type"], "object");
2206 assert_eq!(schema["additionalProperties"], false);
2207 }
2208
2209 let request = to_value(schemars::schema_for!(ModelRequest)).unwrap();
2210 let definitions = request["$defs"].as_object().unwrap();
2211 assert_eq!(
2212 definitions["ModelRequestInstructions"]["maxItems"],
2213 RequestInstructions::MAX_LEN
2214 );
2215 assert_eq!(
2216 definitions["ModelRequestMessages"]["maxItems"],
2217 RequestMessages::MAX_LEN
2218 );
2219 assert_eq!(
2220 definitions["ModelRequestTools"]["maxItems"],
2221 RequestTools::MAX_LEN
2222 );
2223 }
2224
2225 proptest! {
2226 #[test]
2227 fn every_valid_request_limit_tuple_and_derived_request_round_trip(
2228 input in 1_u64..=1_000_000,
2229 output in 1_u64..=1_000_000,
2230 bytes in 1_u64..=ModelRequestLimits::HARD_MAX_CONTENT_BYTES.get(),
2231 ) {
2232 let limits = ModelRequestLimits::new(
2233 TokenCount::new(input),
2234 TokenCount::new(output),
2235 ByteCount::new(bytes),
2236 ).unwrap();
2237 let encoded = serde_json::to_vec(&limits).unwrap();
2238 prop_assert_eq!(
2239 serde_json::from_slice::<ModelRequestLimits>(&encoded).unwrap(),
2240 limits.clone()
2241 );
2242 prop_assert_eq!(limits.required_context_tokens(), TokenCount::new(input + output));
2243
2244 if bytes >= 31 {
2245 let request = ModelRequest::builder(limits).instruction(instruction()).build().unwrap();
2246 let encoded = serde_json::to_vec(&request).unwrap();
2247 prop_assert_eq!(serde_json::from_slice::<ModelRequest>(&encoded).unwrap(), request);
2248 }
2249 }
2250 }
2251}