1use std::collections::{BTreeMap, BTreeSet};
2
3use bytes::Bytes;
4use schemars::JsonSchema;
5use serde::{Deserialize, Serialize};
6use serde_json::Value;
7
8pub type Extensions = BTreeMap<String, Value>;
10
11#[derive(
13 Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema,
14)]
15#[serde(rename_all = "snake_case")]
16pub enum Protocol {
17 OpenAiChatCompletions,
19 OpenAiResponses,
21 AnthropicMessages,
23 Gemini,
25}
26
27impl Protocol {
28 #[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#[derive(
41 Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema,
42)]
43#[serde(rename_all = "snake_case")]
44pub enum Operation {
45 Generate,
47 Embed,
49 Image,
51}
52
53#[derive(
55 Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema,
56)]
57#[serde(rename_all = "snake_case")]
58pub enum Capability {
59 Streaming,
61 Text,
63 Image,
65 Audio,
67 Video,
69 File,
71 FunctionTools,
73 StructuredOutput,
75 Reasoning,
77 MultipleCandidates,
79 Embeddings,
81 ImageEdit,
83 ImageVariation,
85 FileUpload,
87}
88
89#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
91pub struct Capabilities {
92 pub operations: BTreeSet<Operation>,
94 pub features: BTreeSet<Capability>,
96}
97
98impl Capabilities {
99 #[must_use]
101 pub fn contains_all(&self, requested: &BTreeSet<Capability>) -> bool {
102 requested.is_subset(&self.features)
103 }
104
105 #[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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
125pub struct MediaAsset {
126 pub source: MediaSource,
128 #[serde(skip_serializing_if = "Option::is_none")]
130 pub width: Option<u32>,
131 #[serde(skip_serializing_if = "Option::is_none")]
133 pub height: Option<u32>,
134 #[serde(skip_serializing_if = "Option::is_none")]
136 pub sha256: Option<String>,
137 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
139 pub extensions: Extensions,
140}
141
142impl MediaAsset {
143 #[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 #[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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
176#[serde(tag = "kind", rename_all = "snake_case")]
177pub enum MediaSource {
178 Inline {
180 mime_type: String,
182 #[serde(with = "base64_bytes")]
184 #[schemars(with = "String")]
185 data: Bytes,
186 },
187 Url {
189 url: String,
191 #[serde(skip_serializing_if = "Option::is_none")]
193 mime_type: Option<String>,
194 },
195 ProviderFile {
197 provider: String,
199 id: String,
201 #[serde(skip_serializing_if = "Option::is_none")]
203 mime_type: Option<String>,
204 },
205}
206
207#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
209#[serde(rename_all = "snake_case")]
210pub enum Role {
211 User,
213 Assistant,
215 Tool,
217}
218
219#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
221#[serde(rename_all = "snake_case")]
222pub enum InstructionKind {
223 System,
225 Developer,
227}
228
229#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
231pub struct Instruction {
232 pub kind: InstructionKind,
234 #[serde(default)]
236 pub priority: i32,
237 pub content: Vec<ContentPart>,
239 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
241 pub extensions: Extensions,
242}
243
244impl Instruction {
245 #[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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
259pub struct Message {
260 pub role: Role,
262 pub content: Vec<ContentPart>,
264 #[serde(skip_serializing_if = "Option::is_none")]
266 pub id: Option<String>,
267 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
269 pub extensions: Extensions,
270}
271
272impl Message {
273 #[must_use]
275 pub fn user(text: impl Into<String>) -> Self {
276 Self::text(Role::User, text)
277 }
278
279 #[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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
297#[serde(tag = "type", rename_all = "snake_case")]
298pub enum ContentPart {
299 Text {
301 text: String,
303 #[serde(default, skip_serializing_if = "Vec::is_empty")]
305 annotations: Vec<Annotation>,
306 },
307 Image { asset: MediaAsset },
309 Audio { asset: MediaAsset },
311 Video { asset: MediaAsset },
313 File {
315 asset: MediaAsset,
316 #[serde(skip_serializing_if = "Option::is_none")]
317 filename: Option<String>,
318 },
319 ToolCall { call: ToolCall },
321 ToolResult { result: ToolResult },
323 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 Refusal { reason: String },
332}
333
334impl ContentPart {
335 #[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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
347#[serde(tag = "type", rename_all = "snake_case")]
348pub enum Annotation {
349 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 Safety {
361 category: String,
362 #[serde(skip_serializing_if = "Option::is_none")]
363 probability: Option<f32>,
364 blocked: bool,
365 },
366 Refusal { reason: String },
368}
369
370#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
372pub struct ToolDefinition {
373 pub name: String,
375 #[serde(skip_serializing_if = "Option::is_none")]
377 pub description: Option<String>,
378 pub input_schema: Value,
380 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
382 pub extensions: Extensions,
383}
384
385#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
387#[serde(tag = "type", rename_all = "snake_case")]
388pub enum ToolChoice {
389 Auto,
391 None,
393 Required,
395 Function { name: String },
397}
398
399#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
401pub struct ToolCall {
402 pub id: String,
404 pub name: String,
406 pub arguments: Value,
408 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
410 pub extensions: Extensions,
411}
412
413#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
415pub struct ToolResult {
416 pub call_id: String,
418 pub content: Vec<ContentPart>,
420 #[serde(default)]
422 pub is_error: bool,
423 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
425 pub extensions: Extensions,
426}
427
428#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
430#[serde(tag = "type", rename_all = "snake_case")]
431pub enum ResponseFormat {
432 Text,
434 JsonObject,
436 JsonSchema {
438 name: String,
439 schema: Value,
440 #[serde(default)]
441 strict: bool,
442 },
443}
444
445#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
447pub struct ReasoningConfig {
448 #[serde(skip_serializing_if = "Option::is_none")]
450 pub effort: Option<String>,
451 #[serde(skip_serializing_if = "Option::is_none")]
453 pub budget_tokens: Option<u64>,
454 #[serde(skip_serializing_if = "Option::is_none")]
456 pub include_summary: Option<bool>,
457}
458
459#[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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
486pub struct GenerateRequest {
487 pub model: String,
489 #[serde(default, skip_serializing_if = "Vec::is_empty")]
491 pub instructions: Vec<Instruction>,
492 pub messages: Vec<Message>,
494 #[serde(default, skip_serializing_if = "Vec::is_empty")]
496 pub tools: Vec<ToolDefinition>,
497 #[serde(skip_serializing_if = "Option::is_none")]
499 pub tool_choice: Option<ToolChoice>,
500 #[serde(skip_serializing_if = "Option::is_none")]
502 pub response_format: Option<ResponseFormat>,
503 #[serde(skip_serializing_if = "Option::is_none")]
505 pub reasoning: Option<ReasoningConfig>,
506 #[serde(default)]
508 pub parameters: GenerationParameters,
509 #[serde(default)]
511 pub stream: bool,
512 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
514 pub extensions: Extensions,
515}
516
517impl GenerateRequest {
518 #[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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
538pub struct Candidate {
539 pub index: u32,
541 #[serde(skip_serializing_if = "Option::is_none")]
543 pub id: Option<String>,
544 pub content: Vec<ContentPart>,
546 #[serde(skip_serializing_if = "Option::is_none")]
548 pub finish_reason: Option<FinishReason>,
549 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
551 pub extensions: Extensions,
552}
553
554#[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#[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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
585pub struct GenerateResponse {
586 #[serde(skip_serializing_if = "Option::is_none")]
588 pub id: Option<String>,
589 pub model: String,
591 pub candidates: Vec<Candidate>,
593 #[serde(skip_serializing_if = "Option::is_none")]
595 pub usage: Option<Usage>,
596 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
598 pub extensions: Extensions,
599}
600
601#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
603#[serde(tag = "type", rename_all = "snake_case")]
604pub enum EmbeddingInput {
605 Text { text: String },
607 Content { content: Vec<ContentPart> },
609}
610
611#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
613pub struct EmbedRequest {
614 pub model: String,
615 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 #[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#[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#[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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
661#[serde(tag = "type", rename_all = "snake_case")]
662pub enum ImageTask {
663 Generate,
665 Edit {
667 image: MediaAsset,
668 #[serde(skip_serializing_if = "Option::is_none")]
669 mask: Option<MediaAsset>,
670 },
671 Variation { image: MediaAsset },
673}
674
675#[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 #[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#[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#[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 #[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 #[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 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 #[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 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#[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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
846pub struct RequestEnvelope {
847 pub schema_version: u32,
849 pub value: UnifiedRequest,
851}
852
853impl RequestEnvelope {
854 #[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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
866pub struct ResponseEnvelope {
867 pub schema_version: u32,
869 pub value: UnifiedResponse,
871}
872
873impl ResponseEnvelope {
874 #[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}