Skip to main content

unllm_core/
model.rs

1use std::collections::{BTreeMap, BTreeSet};
2
3use bytes::Bytes;
4use schemars::JsonSchema;
5use serde::{Deserialize, Serialize};
6use serde_json::Value;
7
8/// Arbitrary JSON values keyed by provider namespace.
9pub type Extensions = BTreeMap<String, Value>;
10
11/// A protocol understood by unllm.
12#[derive(
13    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema,
14)]
15#[serde(rename_all = "snake_case")]
16pub enum Protocol {
17    /// OpenAI Chat Completions.
18    OpenAiChatCompletions,
19    /// OpenAI Responses.
20    OpenAiResponses,
21    /// Anthropic Messages.
22    AnthropicMessages,
23    /// Google Gemini Developer API.
24    Gemini,
25}
26
27impl Protocol {
28    /// Returns the stable provider namespace used by extensions.
29    #[must_use]
30    pub const fn namespace(self) -> &'static str {
31        match self {
32            Self::OpenAiChatCompletions | Self::OpenAiResponses => "openai",
33            Self::AnthropicMessages => "anthropic",
34            Self::Gemini => "gemini",
35        }
36    }
37}
38
39/// A top-level inference operation.
40#[derive(
41    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema,
42)]
43#[serde(rename_all = "snake_case")]
44pub enum Operation {
45    /// Conversational or multimodal generation.
46    Generate,
47    /// Embedding generation.
48    Embed,
49    /// Image generation, editing, or variation.
50    Image,
51}
52
53/// A capability that may be advertised by an adapter or route.
54#[derive(
55    Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema,
56)]
57#[serde(rename_all = "snake_case")]
58pub enum Capability {
59    /// Streaming generation.
60    Streaming,
61    /// Text input or output.
62    Text,
63    /// Image input or output.
64    Image,
65    /// Audio input or output.
66    Audio,
67    /// Video input or output.
68    Video,
69    /// File input.
70    File,
71    /// Function tool calling.
72    FunctionTools,
73    /// Structured JSON output.
74    StructuredOutput,
75    /// Reasoning controls or content.
76    Reasoning,
77    /// Multiple candidates.
78    MultipleCandidates,
79    /// Embeddings.
80    Embeddings,
81    /// Image editing.
82    ImageEdit,
83    /// Image variations.
84    ImageVariation,
85    /// Provider-managed file upload.
86    FileUpload,
87}
88
89/// Capabilities supported by an adapter or configured route.
90#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
91pub struct Capabilities {
92    /// Supported top-level operations.
93    pub operations: BTreeSet<Operation>,
94    /// Supported operation features.
95    pub features: BTreeSet<Capability>,
96}
97
98impl Capabilities {
99    /// Returns true when this set includes every requested capability.
100    #[must_use]
101    pub fn contains_all(&self, requested: &BTreeSet<Capability>) -> bool {
102        requested.is_subset(&self.features)
103    }
104
105    /// Intersects this capability set with a route-level restriction.
106    #[must_use]
107    pub fn restricted_to(&self, allowed: &Self) -> Self {
108        Self {
109            operations: self
110                .operations
111                .intersection(&allowed.operations)
112                .copied()
113                .collect(),
114            features: self
115                .features
116                .intersection(&allowed.features)
117                .cloned()
118                .collect(),
119        }
120    }
121}
122
123/// A media value used by multimodal inputs and outputs.
124#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
125pub struct MediaAsset {
126    /// The media payload or reference.
127    pub source: MediaSource,
128    /// Optional pixel width.
129    #[serde(skip_serializing_if = "Option::is_none")]
130    pub width: Option<u32>,
131    /// Optional pixel height.
132    #[serde(skip_serializing_if = "Option::is_none")]
133    pub height: Option<u32>,
134    /// Optional SHA-256 digest in lowercase hexadecimal form.
135    #[serde(skip_serializing_if = "Option::is_none")]
136    pub sha256: Option<String>,
137    /// Provider-specific media metadata.
138    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
139    pub extensions: Extensions,
140}
141
142impl MediaAsset {
143    /// Creates an inline media value.
144    #[must_use]
145    pub fn inline(mime_type: impl Into<String>, data: Bytes) -> Self {
146        Self {
147            source: MediaSource::Inline {
148                mime_type: mime_type.into(),
149                data,
150            },
151            width: None,
152            height: None,
153            sha256: None,
154            extensions: Extensions::new(),
155        }
156    }
157
158    /// Creates a remote media reference.
159    #[must_use]
160    pub fn url(url: impl Into<String>, mime_type: Option<String>) -> Self {
161        Self {
162            source: MediaSource::Url {
163                url: url.into(),
164                mime_type,
165            },
166            width: None,
167            height: None,
168            sha256: None,
169            extensions: Extensions::new(),
170        }
171    }
172}
173
174/// The backing source of a media asset.
175#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
176#[serde(tag = "kind", rename_all = "snake_case")]
177pub enum MediaSource {
178    /// Bytes held directly by the request or response.
179    Inline {
180        /// IANA media type.
181        mime_type: String,
182        /// Raw decoded bytes. Canonical JSON uses base64.
183        #[serde(with = "base64_bytes")]
184        #[schemars(with = "String")]
185        data: Bytes,
186    },
187    /// A remote URL.
188    Url {
189        /// Absolute media URL.
190        url: String,
191        /// Optional IANA media type.
192        #[serde(skip_serializing_if = "Option::is_none")]
193        mime_type: Option<String>,
194    },
195    /// A provider-managed file reference.
196    ProviderFile {
197        /// Provider namespace that owns the file.
198        provider: String,
199        /// Provider file identifier.
200        id: String,
201        /// Optional IANA media type.
202        #[serde(skip_serializing_if = "Option::is_none")]
203        mime_type: Option<String>,
204    },
205}
206
207/// A message author role.
208#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
209#[serde(rename_all = "snake_case")]
210pub enum Role {
211    /// End-user content.
212    User,
213    /// Model-generated content.
214    Assistant,
215    /// A tool result message.
216    Tool,
217}
218
219/// The kind of high-priority instruction.
220#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
221#[serde(rename_all = "snake_case")]
222pub enum InstructionKind {
223    /// A system-level instruction.
224    System,
225    /// A developer-level instruction.
226    Developer,
227}
228
229/// A high-priority instruction kept separate from conversation messages.
230#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
231pub struct Instruction {
232    /// Instruction class.
233    pub kind: InstructionKind,
234    /// Lower values indicate higher priority.
235    #[serde(default)]
236    pub priority: i32,
237    /// Ordered multimodal content.
238    pub content: Vec<ContentPart>,
239    /// Provider-specific instruction data.
240    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
241    pub extensions: Extensions,
242}
243
244impl Instruction {
245    /// Creates a system instruction from text.
246    #[must_use]
247    pub fn system(text: impl Into<String>) -> Self {
248        Self {
249            kind: InstructionKind::System,
250            priority: 0,
251            content: vec![ContentPart::text(text)],
252            extensions: Extensions::new(),
253        }
254    }
255}
256
257/// A conversation message.
258#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
259pub struct Message {
260    /// Message author.
261    pub role: Role,
262    /// Ordered message content.
263    pub content: Vec<ContentPart>,
264    /// Optional stable provider message identifier.
265    #[serde(skip_serializing_if = "Option::is_none")]
266    pub id: Option<String>,
267    /// Provider-specific message data.
268    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
269    pub extensions: Extensions,
270}
271
272impl Message {
273    /// Creates a user message from text.
274    #[must_use]
275    pub fn user(text: impl Into<String>) -> Self {
276        Self::text(Role::User, text)
277    }
278
279    /// Creates an assistant message from text.
280    #[must_use]
281    pub fn assistant(text: impl Into<String>) -> Self {
282        Self::text(Role::Assistant, text)
283    }
284
285    fn text(role: Role, text: impl Into<String>) -> Self {
286        Self {
287            role,
288            content: vec![ContentPart::text(text)],
289            id: None,
290            extensions: Extensions::new(),
291        }
292    }
293}
294
295/// A typed content item.
296#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
297#[serde(tag = "type", rename_all = "snake_case")]
298pub enum ContentPart {
299    /// Plain text.
300    Text {
301        /// Text content.
302        text: String,
303        /// Structured annotations associated with the text.
304        #[serde(default, skip_serializing_if = "Vec::is_empty")]
305        annotations: Vec<Annotation>,
306    },
307    /// An image.
308    Image { asset: MediaAsset },
309    /// Audio.
310    Audio { asset: MediaAsset },
311    /// Video.
312    Video { asset: MediaAsset },
313    /// A general file or document.
314    File {
315        asset: MediaAsset,
316        #[serde(skip_serializing_if = "Option::is_none")]
317        filename: Option<String>,
318    },
319    /// A model-requested function invocation.
320    ToolCall { call: ToolCall },
321    /// The result of a previous tool invocation.
322    ToolResult { result: ToolResult },
323    /// Model reasoning or thinking content.
324    Reasoning {
325        #[serde(skip_serializing_if = "Option::is_none")]
326        text: Option<String>,
327        #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
328        extensions: Extensions,
329    },
330    /// A structured refusal.
331    Refusal { reason: String },
332}
333
334impl ContentPart {
335    /// Creates a plain text content part.
336    #[must_use]
337    pub fn text(text: impl Into<String>) -> Self {
338        Self::Text {
339            text: text.into(),
340            annotations: Vec::new(),
341        }
342    }
343}
344
345/// A portable response annotation.
346#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
347#[serde(tag = "type", rename_all = "snake_case")]
348pub enum Annotation {
349    /// A citation into a source.
350    Citation {
351        source: String,
352        #[serde(skip_serializing_if = "Option::is_none")]
353        start: Option<u64>,
354        #[serde(skip_serializing_if = "Option::is_none")]
355        end: Option<u64>,
356        #[serde(skip_serializing_if = "Option::is_none")]
357        title: Option<String>,
358    },
359    /// A safety classification.
360    Safety {
361        category: String,
362        #[serde(skip_serializing_if = "Option::is_none")]
363        probability: Option<f32>,
364        blocked: bool,
365    },
366    /// A refusal marker.
367    Refusal { reason: String },
368}
369
370/// A portable function declaration.
371#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
372pub struct ToolDefinition {
373    /// Function name.
374    pub name: String,
375    /// Optional function description.
376    #[serde(skip_serializing_if = "Option::is_none")]
377    pub description: Option<String>,
378    /// JSON Schema accepted by the function.
379    pub input_schema: Value,
380    /// Provider-specific tool data.
381    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
382    pub extensions: Extensions,
383}
384
385/// Tool selection policy.
386#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
387#[serde(tag = "type", rename_all = "snake_case")]
388pub enum ToolChoice {
389    /// The provider chooses whether to call a tool.
390    Auto,
391    /// The model must not call a tool.
392    None,
393    /// The model must call at least one tool.
394    Required,
395    /// The model must call a named function.
396    Function { name: String },
397}
398
399/// A completed tool call.
400#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
401pub struct ToolCall {
402    /// Stable call identifier.
403    pub id: String,
404    /// Function name.
405    pub name: String,
406    /// Completed JSON arguments.
407    pub arguments: Value,
408    /// Provider-specific call data.
409    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
410    pub extensions: Extensions,
411}
412
413/// A completed tool result.
414#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
415pub struct ToolResult {
416    /// Identifier of the matching tool call.
417    pub call_id: String,
418    /// Ordered tool result content.
419    pub content: Vec<ContentPart>,
420    /// True when the tool invocation failed.
421    #[serde(default)]
422    pub is_error: bool,
423    /// Provider-specific result data.
424    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
425    pub extensions: Extensions,
426}
427
428/// Structured output preference.
429#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
430#[serde(tag = "type", rename_all = "snake_case")]
431pub enum ResponseFormat {
432    /// Unconstrained text.
433    Text,
434    /// Any JSON object.
435    JsonObject,
436    /// JSON constrained by a named JSON Schema.
437    JsonSchema {
438        name: String,
439        schema: Value,
440        #[serde(default)]
441        strict: bool,
442    },
443}
444
445/// Common reasoning controls.
446#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
447pub struct ReasoningConfig {
448    /// Provider-neutral effort label such as low, medium, or high.
449    #[serde(skip_serializing_if = "Option::is_none")]
450    pub effort: Option<String>,
451    /// Requested reasoning token budget.
452    #[serde(skip_serializing_if = "Option::is_none")]
453    pub budget_tokens: Option<u64>,
454    /// Whether a human-readable summary is requested.
455    #[serde(skip_serializing_if = "Option::is_none")]
456    pub include_summary: Option<bool>,
457}
458
459/// Common generation controls.
460#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
461pub struct GenerationParameters {
462    #[serde(skip_serializing_if = "Option::is_none")]
463    pub max_output_tokens: Option<u64>,
464    #[serde(skip_serializing_if = "Option::is_none")]
465    pub temperature: Option<f32>,
466    #[serde(skip_serializing_if = "Option::is_none")]
467    pub top_p: Option<f32>,
468    #[serde(skip_serializing_if = "Option::is_none")]
469    pub top_k: Option<u64>,
470    #[serde(skip_serializing_if = "Option::is_none")]
471    pub presence_penalty: Option<f32>,
472    #[serde(skip_serializing_if = "Option::is_none")]
473    pub frequency_penalty: Option<f32>,
474    #[serde(skip_serializing_if = "Option::is_none")]
475    pub seed: Option<i64>,
476    #[serde(skip_serializing_if = "Option::is_none")]
477    pub logprobs: Option<bool>,
478    #[serde(default, skip_serializing_if = "Vec::is_empty")]
479    pub stop_sequences: Vec<String>,
480    #[serde(skip_serializing_if = "Option::is_none")]
481    pub candidate_count: Option<u32>,
482}
483
484/// A normalized generation request.
485#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
486pub struct GenerateRequest {
487    /// Route-facing model name.
488    pub model: String,
489    /// High-priority instructions.
490    #[serde(default, skip_serializing_if = "Vec::is_empty")]
491    pub instructions: Vec<Instruction>,
492    /// Conversation history and current user input.
493    pub messages: Vec<Message>,
494    /// Available function tools.
495    #[serde(default, skip_serializing_if = "Vec::is_empty")]
496    pub tools: Vec<ToolDefinition>,
497    /// Tool selection policy.
498    #[serde(skip_serializing_if = "Option::is_none")]
499    pub tool_choice: Option<ToolChoice>,
500    /// Structured output preference.
501    #[serde(skip_serializing_if = "Option::is_none")]
502    pub response_format: Option<ResponseFormat>,
503    /// Reasoning controls.
504    #[serde(skip_serializing_if = "Option::is_none")]
505    pub reasoning: Option<ReasoningConfig>,
506    /// Sampling and output controls.
507    #[serde(default)]
508    pub parameters: GenerationParameters,
509    /// Whether the caller requested a stream.
510    #[serde(default)]
511    pub stream: bool,
512    /// Provider-specific request fields.
513    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
514    pub extensions: Extensions,
515}
516
517impl GenerateRequest {
518    /// Creates a generation request with default optional controls.
519    #[must_use]
520    pub fn new(model: impl Into<String>, messages: Vec<Message>) -> Self {
521        Self {
522            model: model.into(),
523            instructions: Vec::new(),
524            messages,
525            tools: Vec::new(),
526            tool_choice: None,
527            response_format: None,
528            reasoning: None,
529            parameters: GenerationParameters::default(),
530            stream: false,
531            extensions: Extensions::new(),
532        }
533    }
534}
535
536/// A model candidate.
537#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
538pub struct Candidate {
539    /// Stable candidate position.
540    pub index: u32,
541    /// Optional provider candidate identifier.
542    #[serde(skip_serializing_if = "Option::is_none")]
543    pub id: Option<String>,
544    /// Ordered output content.
545    pub content: Vec<ContentPart>,
546    /// Why generation ended.
547    #[serde(skip_serializing_if = "Option::is_none")]
548    pub finish_reason: Option<FinishReason>,
549    /// Provider-specific candidate data.
550    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
551    pub extensions: Extensions,
552}
553
554/// A normalized finish reason.
555#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
556#[serde(tag = "kind", content = "raw", rename_all = "snake_case")]
557pub enum FinishReason {
558    Stop,
559    Length,
560    ToolCall,
561    ContentFilter,
562    Error,
563    Other(String),
564}
565
566/// Token usage reported by an upstream provider.
567#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
568pub struct Usage {
569    #[serde(skip_serializing_if = "Option::is_none")]
570    pub input_tokens: Option<u64>,
571    #[serde(skip_serializing_if = "Option::is_none")]
572    pub output_tokens: Option<u64>,
573    #[serde(skip_serializing_if = "Option::is_none")]
574    pub total_tokens: Option<u64>,
575    #[serde(skip_serializing_if = "Option::is_none")]
576    pub cached_tokens: Option<u64>,
577    #[serde(skip_serializing_if = "Option::is_none")]
578    pub reasoning_tokens: Option<u64>,
579    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
580    pub details: BTreeMap<String, u64>,
581}
582
583/// A normalized generation response.
584#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
585pub struct GenerateResponse {
586    /// Optional provider response identifier.
587    #[serde(skip_serializing_if = "Option::is_none")]
588    pub id: Option<String>,
589    /// Model reported by the provider.
590    pub model: String,
591    /// Ordered response candidates.
592    pub candidates: Vec<Candidate>,
593    /// Provider-reported usage.
594    #[serde(skip_serializing_if = "Option::is_none")]
595    pub usage: Option<Usage>,
596    /// Provider-specific response fields.
597    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
598    pub extensions: Extensions,
599}
600
601/// Input accepted by the embedding operation.
602#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
603#[serde(tag = "type", rename_all = "snake_case")]
604pub enum EmbeddingInput {
605    /// Plain text.
606    Text { text: String },
607    /// Ordered multimodal content.
608    Content { content: Vec<ContentPart> },
609}
610
611/// A normalized embedding request.
612#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
613pub struct EmbedRequest {
614    pub model: String,
615    /// A non-empty ordered list of inputs.
616    pub inputs: Vec<EmbeddingInput>,
617    #[serde(skip_serializing_if = "Option::is_none")]
618    pub dimensions: Option<u32>,
619    #[serde(skip_serializing_if = "Option::is_none")]
620    pub task_type: Option<String>,
621    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
622    pub extensions: Extensions,
623}
624
625impl EmbedRequest {
626    /// Creates an embedding request.
627    #[must_use]
628    pub fn new(model: impl Into<String>, inputs: Vec<EmbeddingInput>) -> Self {
629        Self {
630            model: model.into(),
631            inputs,
632            dimensions: None,
633            task_type: None,
634            extensions: Extensions::new(),
635        }
636    }
637}
638
639/// A single embedding vector.
640#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
641pub struct Embedding {
642    pub index: u32,
643    pub values: Vec<f32>,
644    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
645    pub extensions: Extensions,
646}
647
648/// A normalized embedding response.
649#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
650pub struct EmbedResponse {
651    pub model: String,
652    pub embeddings: Vec<Embedding>,
653    #[serde(skip_serializing_if = "Option::is_none")]
654    pub usage: Option<Usage>,
655    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
656    pub extensions: Extensions,
657}
658
659/// Image operation details.
660#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
661#[serde(tag = "type", rename_all = "snake_case")]
662pub enum ImageTask {
663    /// Generate images from a prompt.
664    Generate,
665    /// Edit an input image, optionally under a mask.
666    Edit {
667        image: MediaAsset,
668        #[serde(skip_serializing_if = "Option::is_none")]
669        mask: Option<MediaAsset>,
670    },
671    /// Produce variations of an input image.
672    Variation { image: MediaAsset },
673}
674
675/// A normalized image request.
676#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
677pub struct ImageRequest {
678    pub model: String,
679    pub task: ImageTask,
680    pub prompt: String,
681    #[serde(skip_serializing_if = "Option::is_none")]
682    pub negative_prompt: Option<String>,
683    #[serde(skip_serializing_if = "Option::is_none")]
684    pub count: Option<u32>,
685    #[serde(skip_serializing_if = "Option::is_none")]
686    pub size: Option<String>,
687    #[serde(skip_serializing_if = "Option::is_none")]
688    pub quality: Option<String>,
689    #[serde(skip_serializing_if = "Option::is_none")]
690    pub style: Option<String>,
691    #[serde(skip_serializing_if = "Option::is_none")]
692    pub output_format: Option<String>,
693    #[serde(default)]
694    pub stream: bool,
695    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
696    pub extensions: Extensions,
697}
698
699impl ImageRequest {
700    /// Creates a text-to-image generation request.
701    #[must_use]
702    pub fn generate(model: impl Into<String>, prompt: impl Into<String>) -> Self {
703        Self {
704            model: model.into(),
705            task: ImageTask::Generate,
706            prompt: prompt.into(),
707            negative_prompt: None,
708            count: None,
709            size: None,
710            quality: None,
711            style: None,
712            output_format: None,
713            stream: false,
714            extensions: Extensions::new(),
715        }
716    }
717}
718
719/// A normalized image response.
720#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
721pub struct ImageResponse {
722    pub model: String,
723    pub images: Vec<MediaAsset>,
724    #[serde(skip_serializing_if = "Option::is_none")]
725    pub usage: Option<Usage>,
726    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
727    pub extensions: Extensions,
728}
729
730/// Any normalized request.
731#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
732#[serde(tag = "operation", content = "request", rename_all = "snake_case")]
733pub enum UnifiedRequest {
734    Generate(GenerateRequest),
735    Embed(EmbedRequest),
736    Image(ImageRequest),
737}
738
739impl UnifiedRequest {
740    /// Returns the operation represented by this request.
741    #[must_use]
742    pub const fn operation(&self) -> Operation {
743        match self {
744            Self::Generate(_) => Operation::Generate,
745            Self::Embed(_) => Operation::Embed,
746            Self::Image(_) => Operation::Image,
747        }
748    }
749
750    /// Returns the route-facing model name.
751    #[must_use]
752    pub fn model(&self) -> &str {
753        match self {
754            Self::Generate(request) => &request.model,
755            Self::Embed(request) => &request.model,
756            Self::Image(request) => &request.model,
757        }
758    }
759
760    /// Replaces the model name after route resolution.
761    pub fn set_model(&mut self, model: impl Into<String>) {
762        let model = model.into();
763        match self {
764            Self::Generate(request) => request.model = model,
765            Self::Embed(request) => request.model = model,
766            Self::Image(request) => request.model = model,
767        }
768    }
769
770    /// Returns whether this request asks for a streaming response.
771    #[must_use]
772    pub const fn is_streaming(&self) -> bool {
773        match self {
774            Self::Generate(request) => request.stream,
775            Self::Image(request) => request.stream,
776            Self::Embed(_) => false,
777        }
778    }
779
780    /// Validates invariants that are independent of a provider.
781    pub fn validate(&self) -> Result<(), crate::UnllmError> {
782        if self.model().trim().is_empty() {
783            return Err(crate::UnllmError::invalid(
784                "empty_model",
785                "A model name is required",
786            ));
787        }
788        match self {
789            Self::Generate(request) => {
790                if request.messages.is_empty() && request.instructions.is_empty() {
791                    return Err(crate::UnllmError::invalid(
792                        "empty_generation_input",
793                        "A generation request requires a message or instruction",
794                    ));
795                }
796                if request.parameters.candidate_count == Some(0) {
797                    return Err(crate::UnllmError::invalid(
798                        "invalid_candidate_count",
799                        "candidate_count must be greater than zero",
800                    ));
801                }
802                for (name, value) in [
803                    ("temperature", request.parameters.temperature),
804                    ("top_p", request.parameters.top_p),
805                ] {
806                    if value.is_some_and(|value| !value.is_finite()) {
807                        return Err(crate::UnllmError::invalid(
808                            "invalid_generation_parameter",
809                            format!("{name} must be finite"),
810                        ));
811                    }
812                }
813            }
814            Self::Embed(request) if request.inputs.is_empty() => {
815                return Err(crate::UnllmError::invalid(
816                    "empty_embedding_input",
817                    "An embedding request requires at least one input",
818                ));
819            }
820            Self::Image(request)
821                if !matches!(request.task, ImageTask::Variation { .. })
822                    && request.prompt.trim().is_empty() =>
823            {
824                return Err(crate::UnllmError::invalid(
825                    "empty_image_prompt",
826                    "An image request requires a prompt",
827                ));
828            }
829            Self::Embed(_) | Self::Image(_) => {}
830        }
831        Ok(())
832    }
833}
834
835/// Any normalized response.
836#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
837#[serde(tag = "operation", content = "response", rename_all = "snake_case")]
838pub enum UnifiedResponse {
839    Generate(GenerateResponse),
840    Embed(EmbedResponse),
841    Image(ImageResponse),
842}
843
844/// Versioned serialized request contract.
845#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
846pub struct RequestEnvelope {
847    /// Canonical schema version. Version 1 is currently supported.
848    pub schema_version: u32,
849    /// Canonical request.
850    pub value: UnifiedRequest,
851}
852
853impl RequestEnvelope {
854    /// Wraps a request in the current schema version.
855    #[must_use]
856    pub const fn new(value: UnifiedRequest) -> Self {
857        Self {
858            schema_version: crate::SCHEMA_VERSION,
859            value,
860        }
861    }
862}
863
864/// Versioned serialized response contract.
865#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
866pub struct ResponseEnvelope {
867    /// Canonical schema version. Version 1 is currently supported.
868    pub schema_version: u32,
869    /// Canonical response.
870    pub value: UnifiedResponse,
871}
872
873impl ResponseEnvelope {
874    /// Wraps a response in the current schema version.
875    #[must_use]
876    pub const fn new(value: UnifiedResponse) -> Self {
877        Self {
878            schema_version: crate::SCHEMA_VERSION,
879            value,
880        }
881    }
882}
883
884mod base64_bytes {
885    use base64::{Engine as _, engine::general_purpose::STANDARD};
886    use bytes::Bytes;
887    use serde::{Deserialize, Deserializer, Serializer};
888
889    pub fn serialize<S>(bytes: &Bytes, serializer: S) -> Result<S::Ok, S::Error>
890    where
891        S: Serializer,
892    {
893        serializer.serialize_str(&STANDARD.encode(bytes))
894    }
895
896    pub fn deserialize<'de, D>(deserializer: D) -> Result<Bytes, D::Error>
897    where
898        D: Deserializer<'de>,
899    {
900        let encoded = String::deserialize(deserializer)?;
901        STANDARD
902            .decode(encoded)
903            .map(Bytes::from)
904            .map_err(serde::de::Error::custom)
905    }
906}