Skip to main content

rig_core/providers/openai/wire/
modality.rs

1//! Embedding, transcription, image, speech, listing, reranking, and verification wires.
2//! Each operation consumes a whole reply, using its dialect's JSON or binary format.
3//!
4//! ```
5//! use rig_core::providers::openai::{OpenAI, TEXT_EMBEDDING_3_SMALL};
6//! let wire = OpenAI::new("key").embedding(TEXT_EMBEDDING_3_SMALL, None);
7//! ```
8
9use crate::wire::Flow;
10use serde::{Deserialize, Serialize};
11
12use crate::embeddings;
13use crate::error::EncodeError;
14use crate::error::ProviderError;
15use crate::model::{ModelInfo, ModelList};
16use crate::operation::{
17    Embedding, ModelListing, ModelPage, Rerank as RerankOp, Transcription, Verify as VerifyOp,
18};
19use crate::providers::internal::set_fields;
20use crate::providers::internal::wire::classify_untyped_line;
21use crate::providers::openai::embedding::{
22    CompatibleEmbeddingResponse, model_dimensions_from_identifier,
23};
24use crate::transcription::TranscriptionRequest;
25use crate::wire::{
26    Body, Capabilities, Decoder, Descriptor, DocumentDecoder, Encoded, Framing, Mode, Out, Wire,
27    WireEvent, WireFrame,
28};
29
30use super::OpenAIConfig;
31
32/// Paired request and response formats for image generation.
33#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
34pub enum ImageBody {
35    /// `{model, prompt, size}`, answered with `data[].b64_json`.
36    #[default]
37    OpenAi,
38    /// xAI: `{model, prompt, response_format, aspect_ratio}` and no `size`,
39    /// answered with `data[].b64_json` and no `created`.
40    Xai,
41    /// `{model_name, prompt, height, width}`, answered with `images[].image`.
42    Hyperbolic,
43    /// `{model, prompt, width, height}`, answered with base64 strings in `images`.
44    Venice,
45    /// `{inputs, parameters: {width, height}}`, answered with raw image bytes.
46    /// The model is addressed through the URL path.
47    HuggingFace,
48    /// MiniMax: `{model, prompt, response_format: "base64"}`, with `image-01`'s
49    /// size as `width` and `height` unless an `aspect_ratio` replaces it, answered
50    /// with `data.image_base64[]` beside a `base_resp` status that can report
51    /// a failure under HTTP 200.
52    MiniMax,
53}
54
55/// Which body a speech endpoint takes.
56#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
57pub enum SpeechBody {
58    /// OpenAI: `{model, input, voice, speed}`.
59    #[default]
60    OpenAi,
61    /// xAI: `{text, voice_id, language}`, with `eve` as the default voice.
62    Xai,
63    /// Hyperbolic: `{language, speaker, text, speed}`, answered with
64    /// `{"audio": "<base64>"}` rather than the audio bytes themselves.
65    ///
66    /// It addresses this endpoint by *language*, so the identifier a caller
67    /// passes as the model is the language tag (`"EN"`).
68    Hyperbolic,
69    /// MiniMax: `{model, text, stream, output_format, voice_setting: {voice_id,
70    /// speed}}`, answered with hex-encoded audio under `data.audio` beside a
71    /// `base_resp` status that can report a failure under HTTP 200.
72    MiniMax,
73}
74
75/// Which body a transcription endpoint takes.
76#[derive(Clone, Copy, Debug, PartialEq, Eq)]
77pub enum TranscriptionBody {
78    /// OpenAI: a `multipart/form-data` upload with the audio as a file part
79    /// beside `model`, `language`, `prompt` and `temperature`.
80    Multipart,
81    /// OpenRouter: a JSON body whose audio rides base64-encoded under
82    /// `input_audio`, with its container format beside it
83    /// (`{"input_audio": {"data": "…", "format": "mp3"}, "model": …}`).
84    /// The gateway's speech-to-text route serves only this shape, and has no
85    /// top-level `prompt` field at all.
86    InputAudioJson,
87}
88
89/// Which field a dialect takes an embedding width in.
90#[derive(Clone, Copy, Debug, PartialEq, Eq)]
91pub enum DimensionsField {
92    /// The OpenAI-compatible `dimensions` field.
93    Dimensions,
94    /// Mistral's `output_dimension`.
95    OutputDimension,
96    /// The server ignores any width field, so none is sent (`llama-server`
97    /// reads no such field and would answer 200 with the native width).
98    Ignored,
99}
100
101impl DimensionsField {
102    /// The body field a requested width goes in, or `None` when the dialect
103    /// reads no width field at all.
104    ///
105    /// The encoder puts a width in this field and a refusal names it, so
106    /// both spell it from here rather than from two matching literals.
107    pub const fn name(self) -> Option<&'static str> {
108        match self {
109            Self::Dimensions => Some("dimensions"),
110            Self::OutputDimension => Some("output_dimension"),
111            Self::Ignored => None,
112        }
113    }
114}
115
116/// Which widths a request may name for one embedding model.
117#[derive(Clone, Copy, Debug, PartialEq, Eq)]
118pub enum AcceptedWidths {
119    /// The model emits one width and reads no width field, so any value but
120    /// its own native width is a request for a parameter the provider does
121    /// not accept there, and is refused as a request error.
122    Fixed,
123    /// The model truncates to any width in `min..=max`, and anything else is
124    /// refused with [`requirement`](Self::Range::requirement).
125    Range {
126        /// Narrowest width the provider honours.
127        min: usize,
128        /// Widest width the provider honours.
129        max: usize,
130        /// Static error clause describing the accepted bounds.
131        /// Must agree with `min` and `max`.
132        requirement: &'static str,
133    },
134}
135
136/// One embedding model's width contract: the width it returns unasked, and
137/// the widths it will honour when asked.
138///
139/// Stated per model rather than per dialect because a dialect serves models
140/// of different widths, and a model's default is not always its maximum.
141#[derive(Clone, Copy, Debug, PartialEq, Eq)]
142#[non_exhaustive]
143pub struct ModelWidth {
144    /// The model identifier, as the `model` field spells it.
145    pub model: &'static str,
146    /// Default width reported when no width is requested, or `None` if unknown.
147    /// Unknown widths report zero as the embedding model's `ndims`.
148    pub default: Option<usize>,
149    /// The widths a request may name.
150    pub accepted: AcceptedWidths,
151}
152
153/// Reranking endpoint policy. An empty [`Self::path`] disables reranking.
154#[derive(Clone, Copy, Debug, PartialEq, Eq)]
155#[non_exhaustive]
156pub struct RerankQuirks {
157    /// The rerank path, or empty when the dialect offers none.
158    pub path: &'static str,
159    /// Most documents the provider accepts in one request.
160    pub max_documents: usize,
161    /// Whether the model is a body field.
162    pub sends_model_field: bool,
163}
164
165impl RerankQuirks {
166    /// The signal for a dialect with no reranking endpoint.
167    pub const fn unsupported() -> Self {
168        Self {
169            path: "",
170            max_documents: 0,
171            sends_model_field: true,
172        }
173    }
174}
175
176/// What a dialect's embeddings endpoint accepts.
177#[derive(Clone, Copy, Debug, PartialEq, Eq)]
178#[non_exhaustive]
179pub struct EmbeddingQuirks {
180    /// Most inputs the provider embeds in one request.
181    pub max_documents: usize,
182    /// Whether a successful reply must carry usage.
183    pub requires_usage: bool,
184    /// Whether the model is a body field (false for Azure, which addresses a
185    /// deployment through the URL).
186    pub sends_model_field: bool,
187    /// Which field a requested width goes in.
188    pub dimensions: DimensionsField,
189    /// Model width contracts used for capability reporting and request validation.
190    /// Consulted before the shared OpenAI model-width table.
191    pub widths: &'static [ModelWidth],
192    /// The `requirement` clause refusing a declared width of zero, or
193    /// `None` for a dialect that lets zero through as rig's own "unknown"
194    /// sentinel rather than a claim.
195    pub refuse_zero_width: Option<&'static str>,
196}
197
198impl EmbeddingQuirks {
199    /// OpenAI's own embeddings contract, which most dialects inherit.
200    pub const fn openai() -> Self {
201        Self {
202            max_documents: 1024,
203            requires_usage: true,
204            sends_model_field: true,
205            dimensions: DimensionsField::Dimensions,
206            // Shared OpenAI model widths are resolved separately.
207            widths: &[],
208            // Zero represents an unknown width, not a requested dimension.
209            refuse_zero_width: None,
210        }
211    }
212}
213
214impl super::SubRoute {
215    /// Whether this sub-provider serves the endpoints that address the model
216    /// through the URL (transcription, image generation).
217    pub fn serves_model_routed_endpoints(&self) -> bool {
218        matches!(self, Self::HFInference)
219    }
220}
221
222impl OpenAIConfig {
223    /// The embeddings wire for `model`.
224    pub(crate) fn embedding(&self, model: impl Into<String>, ndims: Option<usize>) -> Embeddings {
225        Embeddings::new(self.clone(), model, ndims)
226    }
227
228    /// The rerank wire for `model`.
229    pub(crate) fn rerank(&self, model: impl Into<String>) -> Rerank {
230        Rerank::new(self.clone(), model)
231    }
232
233    /// The transcription wire for `model`.
234    pub(crate) fn transcription(&self, model: impl Into<String>) -> Transcriptions {
235        Transcriptions::new(self.clone(), model)
236    }
237
238    /// The model-listing wire.
239    pub(crate) fn models(&self) -> Models {
240        Models::new(self.clone())
241    }
242
243    /// The credential-check wire.
244    pub(crate) fn verify(&self) -> Verify {
245        Verify::new(self.clone())
246    }
247
248    /// The image-generation wire for `model`.
249    pub(crate) fn image_generation(&self, model: impl Into<String>) -> Images {
250        Images::new(self.clone(), model)
251    }
252
253    /// The speech wire for `model`.
254    pub(crate) fn audio_generation(&self, model: impl Into<String>) -> Speech {
255        Speech::new(self.clone(), model)
256    }
257
258    /// The `api-version` a speech request carries.
259    pub(crate) fn speech_api_version(&self) -> Option<&str> {
260        self.audio_api_version
261            .as_deref()
262            .or(self.api_version.as_deref())
263    }
264
265    /// Resolve a fixed or model-addressed modality URL.
266    /// Return an error if the selected sub-route does not serve model-routed endpoints.
267    pub(crate) fn modality_uri(
268        &self,
269        endpoint: &str,
270        fixed: &'static str,
271        model: &str,
272    ) -> Result<String, String> {
273        if !self.dialect.quirks.model_is_modality_path {
274            return Ok(self.uri(fixed, self.deployment(model)));
275        }
276        let route = self.route();
277        if !route.serves_model_routed_endpoints() {
278            return Err(format!(
279                "{endpoint} endpoint is not supported yet for {route}"
280            ));
281        }
282        Ok(format!(
283            "{}/{}/models/{}",
284            self.base_url.trim_end_matches('/'),
285            route.slug(),
286            model.trim_start_matches('/')
287        ))
288    }
289}
290
291/// The width contract of Mistral's embedding models.
292///
293/// `mistral-embed` is fixed at 1024 and reads no width field: Mistral
294/// answers any other value with an error rather than truncating, so a
295/// request naming one is refused before it is built. Codestral Embed is
296/// configurable up to 3072, takes its width as `output_dimension`, and
297/// returns 1536-wide vectors when a request names none.
298///
299/// The dated aliases are listed beside their rolling names because a caller
300/// pinning `mistral-embed-2312` gets the same model, and a model absent from
301/// this table reports `ndims() == 0`.
302pub(super) const MISTRAL_EMBEDDING_WIDTHS: &[ModelWidth] = &[
303    ModelWidth {
304        model: crate::providers::mistral::embedding::MISTRAL_EMBED,
305        default: Some(1_024),
306        accepted: AcceptedWidths::Fixed,
307    },
308    ModelWidth {
309        model: "mistral-embed-2312",
310        default: Some(1_024),
311        accepted: AcceptedWidths::Fixed,
312    },
313    ModelWidth {
314        model: crate::providers::mistral::embedding::CODESTRAL_EMBED,
315        default: Some(1_536),
316        accepted: AcceptedWidths::Range {
317            // Mistral documents only a ceiling. The floor is rig's own
318            // "unknown" sentinel, which never reaches the wire.
319            min: 0,
320            max: 3_072,
321            requirement: "to be at most 3072 for Codestral Embed",
322        },
323    },
324    ModelWidth {
325        model: "codestral-embed-2505",
326        default: Some(1_536),
327        accepted: AcceptedWidths::Range {
328            min: 0,
329            max: 3_072,
330            requirement: "to be at most 3072 for Codestral Embed",
331        },
332    },
333];
334
335/// Doubleword embedding widths: 32 through 4096, defaulting to 4096.
336/// Validate both bounds locally because out-of-range requests can be clamped or
337/// inconsistently rejected by the service.
338pub(super) const DOUBLEWORD_EMBEDDING_WIDTHS: &[ModelWidth] = &[ModelWidth {
339    model: crate::providers::doubleword::QWEN3_EMBEDDING_8B,
340    default: Some(4_096),
341    accepted: AcceptedWidths::Range {
342        min: 32,
343        max: 4_096,
344        requirement: "to be between 32 and 4096",
345    },
346}];
347
348/// Encode an authenticated JSON POST with whole-response framing.
349pub(crate) fn json_post(
350    provider: &OpenAIConfig,
351    path: &str,
352    deployment: Option<&str>,
353    body: &serde_json::Value,
354) -> Result<Encoded, EncodeError> {
355    json_post_to(provider, provider.uri(path, deployment), body)
356}
357
358/// [`json_post`] against an already-resolved URL, for the endpoints whose
359/// URL is derived rather than a fixed path under the base.
360fn json_post_to(
361    provider: &OpenAIConfig,
362    uri: String,
363    body: &serde_json::Value,
364) -> Result<Encoded, EncodeError> {
365    let bytes = serde_json::to_vec(body)?;
366    let builder = http::Request::post(uri).header("Content-Type", "application/json");
367    encoded(provider, builder, Body::Bytes(bytes))
368}
369
370/// The `GET` whose status is the answer, for the two endpoints that send no
371/// body: the model catalogue and the credential check.
372fn get(provider: &OpenAIConfig, path: &str) -> Result<Encoded, EncodeError> {
373    encoded(
374        provider,
375        http::Request::get(provider.uri(path, None)),
376        Body::empty(),
377    )
378}
379
380/// Authenticate and build a request, then apply its modality envelope hook.
381/// Return construction or hook errors. Use whole-response framing and the
382/// dialect's request-ID header.
383pub(crate) fn encoded(
384    provider: &OpenAIConfig,
385    builder: http::request::Builder,
386    body: Body,
387) -> Result<Encoded, EncodeError> {
388    let mut request = provider.authenticate(builder).body(body)?;
389    if let Some(envelope) = provider
390        .dialect
391        .quirks
392        .hooks
393        .and_then(|hooks| hooks.modality_envelope)
394    {
395        envelope(provider, &mut request)?;
396    }
397    Ok(Encoded::new(request, Framing::Whole)
398        .with_request_id_header(provider.dialect.request_id_header))
399}
400
401/// Refuse an embeddings request parameter the dialect does not accept.
402fn unsupported_parameter(provider: &str, parameter: &str) -> EncodeError {
403    EncodeError::request(format!(
404        "{provider} embeddings do not support the `{parameter}` parameter"
405    ))
406}
407
408/// The embeddings wire.
409#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
410pub struct Embeddings {
411    /// Which provider, and how to reach it.
412    pub provider: OpenAIConfig,
413    /// The embedding model.
414    pub model: String,
415    /// The width the caller asked for, when they named one rather than
416    /// taking the model's default.
417    pub ndims: Option<usize>,
418}
419
420impl Embeddings {
421    /// The embeddings wire for `model`.
422    pub fn new(provider: OpenAIConfig, model: impl Into<String>, ndims: Option<usize>) -> Self {
423        Self {
424            provider,
425            model: model.into(),
426            ndims,
427        }
428    }
429
430    /// This model's width contract on this dialect, or `None` for a model
431    /// the dialect does not document.
432    fn model_width(&self) -> Option<&'static ModelWidth> {
433        self.provider
434            .dialect
435            .quirks
436            .embedding
437            .widths
438            .iter()
439            .find(|width| width.model == self.model)
440    }
441
442    /// Resolve width from the caller, dialect table, then shared model table.
443    /// Return zero when all are absent.
444    fn resolved_ndims(&self) -> usize {
445        self.ndims
446            .or_else(|| self.model_width().and_then(|width| width.default))
447            .or_else(|| model_dimensions_from_identifier(&self.model))
448            .unwrap_or_default()
449    }
450
451    /// Validate declared widths against the dialect's zero-width and model policies.
452    /// Return a request error for unsupported widths; unknown models are unchecked.
453    fn refuse_unhonourable_width(&self) -> Result<(), EncodeError> {
454        let quirks = &self.provider.dialect.quirks.embedding;
455        let provider = self.provider.dialect.name;
456        let invalid = |requirement, parameter| {
457            EncodeError::request(format!(
458                "{provider} embeddings require `{parameter}` {requirement}"
459            ))
460        };
461        // A dialect that reads no width field has nothing to refuse: the
462        // caller's number never reaches the wire, and the shared driver
463        // catches the disagreement against the reply instead.
464        let Some(parameter) = quirks.dimensions.name() else {
465            return Ok(());
466        };
467        let Some(declared) = self.ndims else {
468            return Ok(());
469        };
470        if declared == 0 {
471            return match quirks.refuse_zero_width {
472                Some(requirement) => Err(invalid(requirement, parameter)),
473                None => Ok(()),
474            };
475        }
476        // A model the dialect does not document: the caller's width is the
477        // only width there is, so it goes out unvalidated and the API rules.
478        let Some(width) = self.model_width() else {
479            return Ok(());
480        };
481        // Native widths require no truncation parameter.
482        if width.default == Some(declared) {
483            return Ok(());
484        }
485        match width.accepted {
486            AcceptedWidths::Fixed => Err(unsupported_parameter(provider, parameter)),
487            AcceptedWidths::Range { min, max, .. } if (min..=max).contains(&declared) => Ok(()),
488            AcceptedWidths::Range { requirement, .. } => Err(invalid(requirement, parameter)),
489        }
490    }
491
492    /// The width to send, in the field this dialect spells it with.
493    ///
494    /// OpenAI's legacy Ada model does not accept a width at all, and
495    /// `llama-server` reads no width field, so neither is sent one.
496    fn requested_width(&self) -> Option<(&'static str, usize)> {
497        let field = self.provider.dialect.quirks.embedding.dimensions.name()?;
498        if self.model == crate::providers::openai::embedding::TEXT_EMBEDDING_ADA_002 {
499            return None;
500        }
501        // Unknown widths are metadata sentinels, not request parameters.
502        let ndims = match self.resolved_ndims() {
503            0 => return None,
504            ndims => ndims,
505        };
506        // A fixed-width model reads no width field, and a documented model
507        // asked for nothing emits its native width unasked. A width the
508        // caller named goes out as asked.
509        if self.model_width().is_some_and(|width| {
510            width.accepted == AcceptedWidths::Fixed
511                || (self.ndims.is_none() && width.default == Some(ndims))
512        }) {
513            return None;
514        }
515        Some((field, ndims))
516    }
517}
518
519/// Decode embedding vectors and usage, enforcing the dialect's usage requirement.
520#[derive(Default)]
521pub struct EmbeddingsDecoder {
522    /// Whether this dialect's reply must carry usage.
523    requires_usage: bool,
524    provider: &'static str,
525    model: String,
526}
527
528impl<'id> Decoder<'id, Embedding> for EmbeddingsDecoder {
529    type Event = CompatibleEmbeddingResponse;
530
531    fn classify(&self, frame: WireFrame) -> WireEvent<Self::Event> {
532        classify_untyped_line(frame.as_str().as_bytes())
533    }
534
535    fn decode(
536        &mut self,
537        event: Self::Event,
538        out: Out<'id, Embedding>,
539    ) -> Result<Flow, ProviderError> {
540        if event.usage.is_none() && self.requires_usage {
541            return Err(ProviderError::Response(format!(
542                "{} embedding response omitted required usage",
543                self.provider
544            )));
545        }
546        let usage = event.usage.as_ref().map(Into::into).unwrap_or_default();
547        let vectors = event.data.into_iter().map(|datum| datum.embedding);
548        let model = if event.model.is_empty() {
549            self.model.clone()
550        } else {
551            event.model
552        };
553        Ok(out.end(embeddings::EmbeddingResponse {
554            model: Some(model),
555            usage,
556            ..embeddings::EmbeddingResponse::from_vectors(vectors)
557        }))
558    }
559}
560
561impl Wire for Embeddings {
562    type Op = Embedding;
563    type Payload = crate::wire::Encoded;
564    type Frame = crate::wire::WireFrame;
565    type Event = CompatibleEmbeddingResponse;
566    type Decoder<'id> = EmbeddingsDecoder;
567    type Reassembler = crate::wire::document::Unreassembled;
568
569    /// Only an explicit nonzero declaration permits reply-width mismatch checks.
570    fn describe(&self) -> Descriptor<'_> {
571        Descriptor::new(self.provider.dialect.name)
572            .model(self.model.as_str())
573            .capabilities(
574                Capabilities::embedding(
575                    self.provider.dialect.quirks.embedding.max_documents,
576                    self.resolved_ndims(),
577                )
578                .declaring(self.ndims),
579            )
580    }
581
582    fn encode(&self, request: Vec<String>, _mode: Mode) -> Result<Encoded, EncodeError> {
583        let quirks = &self.provider.dialect.quirks.embedding;
584        self.refuse_unhonourable_width()?;
585
586        let mut body = set_fields([
587            ("input", Some(serde_json::json!(request))),
588            (
589                "model",
590                quirks
591                    .sends_model_field
592                    .then(|| serde_json::json!(self.model)),
593            ),
594        ]);
595        if let Some((field, ndims)) = self.requested_width() {
596            body.insert(field.to_owned(), serde_json::json!(ndims));
597        }
598
599        json_post(
600            &self.provider,
601            self.provider.dialect.quirks.embeddings_path,
602            self.provider.deployment(&self.model),
603            &serde_json::Value::Object(body),
604        )
605    }
606
607    fn decoder<'id>(&self) -> Self::Decoder<'id> {
608        EmbeddingsDecoder {
609            requires_usage: self.provider.dialect.quirks.embedding.requires_usage,
610            provider: self.provider.dialect.name,
611            model: self.model.clone(),
612        }
613    }
614}
615
616/// Transcription requests encoded as multipart or input-audio JSON.
617#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
618pub struct Transcriptions {
619    /// Which provider, and how to reach it.
620    pub provider: OpenAIConfig,
621    /// Transcription model or Azure deployment identifier.
622    pub model: String,
623}
624
625impl Transcriptions {
626    /// The transcription wire for `model`.
627    pub fn new(provider: OpenAIConfig, model: impl Into<String>) -> Self {
628        Self {
629            provider,
630            model: model.into(),
631        }
632    }
633
634    /// OpenAI's multipart upload: the audio as a file part beside the
635    /// per-request options.
636    fn multipart_body(&self, request: TranscriptionRequest) -> Result<Body, EncodeError> {
637        use crate::http_client::MultipartForm;
638        use crate::http_client::multipart::Part;
639
640        let mut form = MultipartForm::new();
641        // Azure addresses its deployment through the URL rather than the form.
642        if self.provider.deployment(&self.model).is_none() {
643            form = form.text("model", self.model.clone());
644        }
645        form = form.part(Part::bytes("file", request.data).filename(request.filename));
646        if let Some(language) = request.language {
647            form = form.text("language", language);
648        }
649        if let Some(prompt) = request.prompt {
650            form = form.text("prompt", prompt);
651        }
652        if let Some(temperature) = request.temperature {
653            form = form.text("temperature", temperature.to_string());
654        }
655        if let Some(additional_params) = request.additional_params {
656            for (name, value) in additional_params_object(&additional_params)? {
657                match value {
658                    // Arrays go as one `name[]` field per item, the form
659                    // encoding these endpoints read for lists such as
660                    // `timestamp_granularities`.
661                    serde_json::Value::Array(items) => {
662                        for item in items {
663                            form = form.text(format!("{name}[]"), form_text(item));
664                        }
665                    }
666                    other => form = form.text(name.clone(), form_text(other)),
667                }
668            }
669        }
670        Ok(Body::Multipart(form))
671    }
672
673    /// Encode base64 audio under `input_audio`, inferring format from the filename.
674    /// Reject top-level prompts and non-object additional parameters.
675    fn input_audio_body(&self, request: TranscriptionRequest) -> Result<Body, EncodeError> {
676        use base64::Engine;
677
678        if request.prompt.is_some() {
679            return Err(EncodeError::request(std::io::Error::new(
680                std::io::ErrorKind::InvalidInput,
681                "OpenRouter STT does not support a top-level prompt field. \
682                     Provider-specific prompt options can be passed via `additional_params`. \
683                     Example: {\"provider\": {\"options\": {\"<provider>\": {\"prompt\": \"<text>\"}}}}",
684            )));
685        }
686
687        let mut body = serde_json::Map::new();
688        body.insert("model".to_owned(), serde_json::json!(self.model));
689        body.insert(
690            "input_audio".to_owned(),
691            serde_json::json!({
692                "data": base64::engine::general_purpose::STANDARD.encode(&request.data),
693                "format": audio_format_of(&request.filename),
694            }),
695        );
696        if let Some(language) = request.language {
697            body.insert("language".to_owned(), serde_json::json!(language));
698        }
699        if let Some(temperature) = request.temperature {
700            body.insert("temperature".to_owned(), serde_json::json!(temperature));
701        }
702        if let Some(additional_params) = request.additional_params {
703            for (name, value) in additional_params_object(&additional_params)? {
704                body.insert(name.clone(), value.clone());
705            }
706        }
707        Ok(Body::Bytes(serde_json::to_vec(
708            &serde_json::Value::Object(body),
709        )?))
710    }
711}
712
713/// A form field's text: strings as they are, without JSON quotation marks,
714/// and other values as JSON.
715fn form_text(value: &serde_json::Value) -> String {
716    match value {
717        serde_json::Value::String(value) => value.clone(),
718        other => other.to_string(),
719    }
720}
721
722/// A transcription request's `additional_params`, as an object.
723fn additional_params_object(
724    params: &serde_json::Value,
725) -> Result<&serde_json::Map<String, serde_json::Value>, EncodeError> {
726    params.as_object().ok_or_else(|| {
727        EncodeError::request(std::io::Error::new(
728            std::io::ErrorKind::InvalidInput,
729            "additional transcription parameters must be a JSON object",
730        ))
731    })
732}
733
734/// Infer the audio container from a case-insensitive filename extension.
735/// Unknown or absent extensions default to `wav`.
736fn audio_format_of(filename: &str) -> &'static str {
737    let extension = std::path::Path::new(filename)
738        .extension()
739        .and_then(std::ffi::OsStr::to_str)
740        .map(str::to_ascii_lowercase);
741    match extension.as_deref() {
742        Some("mp3") => "mp3",
743        Some("flac") => "flac",
744        Some("m4a") => "m4a",
745        Some("ogg") => "ogg",
746        Some("webm") => "webm",
747        Some("aac") => "aac",
748        _ => "wav",
749    }
750}
751
752impl Wire for Transcriptions {
753    type Op = Transcription;
754    type Payload = crate::wire::Encoded;
755    type Frame = crate::wire::WireFrame;
756    type Event = crate::providers::openai::transcription::TranscriptionResponse;
757    type Decoder<'id> = DocumentDecoder<Transcription, Self::Event>;
758    type Reassembler = crate::wire::document::Unreassembled;
759
760    fn describe(&self) -> Descriptor<'_> {
761        Descriptor::new(self.provider.dialect.name).model(self.model.as_str())
762    }
763
764    fn encode(&self, request: TranscriptionRequest, _mode: Mode) -> Result<Encoded, EncodeError> {
765        let uri = self
766            .provider
767            .modality_uri(
768                "transcription",
769                self.provider.dialect.quirks.transcription_path,
770                &self.model,
771            )
772            .map_err(EncodeError::request)?;
773        let builder = http::Request::post(uri);
774        let (builder, body) = match self.provider.dialect.quirks.transcription_body {
775            TranscriptionBody::Multipart => (builder, self.multipart_body(request)?),
776            TranscriptionBody::InputAudioJson => (
777                builder.header(http::header::CONTENT_TYPE, "application/json"),
778                self.input_audio_body(request)?,
779            ),
780        };
781        encoded(&self.provider, builder, body)
782    }
783
784    fn decoder<'id>(&self) -> Self::Decoder<'id> {
785        DocumentDecoder::new(
786            |body| classify_untyped_line(body.as_bytes()),
787            |event| event.normalize(),
788        )
789    }
790}
791
792/// The image-generation wire.
793#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
794pub struct Images {
795    /// Which provider, and how to reach it.
796    pub provider: OpenAIConfig,
797    /// The image model.
798    pub model: String,
799}
800
801impl Images {
802    /// The image-generation wire for `model`.
803    pub fn new(provider: OpenAIConfig, model: impl Into<String>) -> Self {
804        Self {
805            provider,
806            model: model.into(),
807        }
808    }
809}
810
811/// The image-generation decoder.
812///
813/// Carries the dialect's [`ImageBody`] because the request shape names the
814/// reply shape: most of this family answers with a JSON envelope, and
815/// Hugging Face's router answers with the image bytes themselves.
816#[derive(Default)]
817pub struct ImagesDecoder {
818    /// Which reply shape this dialect answers with.
819    body: ImageBody,
820}
821
822/// One generated image, as every dialect on this wire returns it.
823#[derive(Debug, Clone, Serialize, Deserialize)]
824pub struct ImageDatum {
825    /// The image, base64-encoded.
826    pub b64_json: String,
827}
828
829/// Base64 image represented as a string or an object with an `image` field.
830#[derive(Debug, Clone, Serialize, Deserialize)]
831#[serde(untagged)]
832pub enum ImagesReplyImage {
833    /// Hyperbolic: `{"image": "<base64>"}`.
834    Keyed {
835        /// The image, base64-encoded.
836        image: String,
837    },
838    /// Venice: the base64 payload itself.
839    Bare(String),
840}
841
842impl ImagesReplyImage {
843    /// The image's base64 payload, whichever form the dialect sent.
844    pub fn base64(&self) -> &str {
845        match self {
846            Self::Keyed { image } => image,
847            Self::Bare(image) => image,
848        }
849    }
850}
851
852/// JSON image reply accepting `data` and `images` arrays with optional metadata.
853#[derive(Debug, Clone, Serialize, Deserialize)]
854pub struct ImagesReply {
855    /// The generated images, as OpenAI and xAI key them.
856    #[serde(default)]
857    pub data: Vec<ImageDatum>,
858    /// The generated images, as Hyperbolic and Venice key them.
859    #[serde(default)]
860    pub images: Vec<ImagesReplyImage>,
861    /// Whatever else the dialect sent (`created`, Venice's `id`/`timing`, and
862    /// any field this build does not model), so the raw payload loses
863    /// nothing.
864    #[serde(flatten)]
865    pub extra: serde_json::Map<String, serde_json::Value>,
866}
867
868impl ImagesReply {
869    /// The first image's base64 payload, whichever key the dialect used.
870    pub fn first_base64(&self) -> Option<&str> {
871        self.data
872            .first()
873            .map(|image| image.b64_json.as_str())
874            .or_else(|| self.images.first().map(ImagesReplyImage::base64))
875            .filter(|encoded| !encoded.is_empty())
876    }
877}
878
879/// Generated images in a decoded JSON envelope or as raw bytes.
880#[derive(Debug, Clone)]
881pub enum ImagesEvent {
882    /// A JSON envelope, as OpenAI, xAI and Hyperbolic answer.
883    Json(ImagesReply),
884    /// The image bytes themselves, with no envelope at all.
885    Raw(Vec<u8>),
886    /// A MiniMax reply body, decoded once its status envelope is checked.
887    MiniMax(Vec<u8>),
888}
889
890impl<'id> Decoder<'id, crate::operation::ImageGeneration> for ImagesDecoder {
891    type Event = ImagesEvent;
892
893    fn classify(&self, frame: WireFrame) -> WireEvent<Self::Event> {
894        match self.body {
895            // Preserve raw image bytes even when framing recognized valid UTF-8.
896            ImageBody::HuggingFace => WireEvent::Known(ImagesEvent::Raw(frame.into_bytes())),
897            ImageBody::MiniMax => WireEvent::Known(ImagesEvent::MiniMax(frame.into_bytes())),
898            ImageBody::OpenAi | ImageBody::Xai | ImageBody::Hyperbolic | ImageBody::Venice => {
899                classify_untyped_line(frame.as_str().as_bytes()).map(ImagesEvent::Json)
900            }
901        }
902    }
903
904    fn decode(
905        &mut self,
906        event: Self::Event,
907        out: Out<'id, crate::operation::ImageGeneration>,
908    ) -> Result<Flow, ProviderError> {
909        use crate::image_generation::ImageGenerationResponse;
910        use base64::Engine;
911
912        let reply = match event {
913            // The image is already the payload, and the reply is not a
914            // document, so `raw` stays null rather than restating the bytes.
915            ImagesEvent::Raw(image) => {
916                return Ok(out.end(ImageGenerationResponse::new(image)));
917            }
918            ImagesEvent::MiniMax(body) => {
919                let reply = crate::providers::minimax::decode_reply::<
920                    crate::providers::minimax::image_generation::ImageGenerationReply,
921                >(&body)?;
922                return Ok(out.end(reply.into_response()?));
923            }
924            ImagesEvent::Json(reply) => reply,
925        };
926        let Some(encoded) = reply.first_base64() else {
927            return Err(ProviderError::Response("missing image data".to_owned()));
928        };
929        let image = base64::prelude::BASE64_STANDARD
930            .decode(encoded)
931            .map_err(|error| ProviderError::Response(error.to_string()))?;
932        Ok(out.end(ImageGenerationResponse::new(image)))
933    }
934}
935
936impl Wire for Images {
937    type Op = crate::operation::ImageGeneration;
938    type Payload = crate::wire::Encoded;
939    type Frame = crate::wire::WireFrame;
940    type Event = ImagesEvent;
941    type Decoder<'id> = ImagesDecoder;
942    type Reassembler = crate::wire::document::Unreassembled;
943
944    fn describe(&self) -> Descriptor<'_> {
945        Descriptor::new(self.provider.dialect.name).model(self.model.as_str())
946    }
947
948    fn encode(
949        &self,
950        request: crate::image_generation::ImageGenerationRequest,
951        _mode: Mode,
952    ) -> Result<Encoded, EncodeError> {
953        if !request.images.is_empty() {
954            return Err(EncodeError::request(
955                "this image generation endpoint takes no reference images",
956            ));
957        }
958        let mut body = match self.provider.dialect.quirks.image_body {
959            // `response_format` is deliberately absent: it is no longer part
960            // of OpenAI's request schema, which rejects it before it even
961            // looks at the model. A compatible endpoint that still takes the
962            // field gets it through `additional_params`.
963            ImageBody::OpenAi => serde_json::json!({
964                "model": self.model,
965                "prompt": request.prompt,
966                "size": format!("{}x{}", request.width, request.height),
967            }),
968            // xAI takes no `size` and answers with a URL unless asked for
969            // base64, which is the only form this wire decodes.
970            ImageBody::Xai => serde_json::json!({
971                "model": self.model,
972                "prompt": request.prompt,
973                "response_format": "b64_json",
974                "aspect_ratio": "1:1",
975            }),
976            ImageBody::Hyperbolic => serde_json::json!({
977                "model_name": self.model,
978                "prompt": request.prompt,
979                "height": request.height,
980                "width": request.width,
981            }),
982            ImageBody::Venice => serde_json::json!({
983                "model": self.model,
984                "prompt": request.prompt,
985                "width": request.width,
986                "height": request.height,
987            }),
988            ImageBody::MiniMax => {
989                crate::providers::minimax::image_generation::request_body(&self.model, &request)?
990            }
991            // The model is addressed through the URL, not the body.
992            ImageBody::HuggingFace => serde_json::json!({
993                "inputs": request.prompt,
994                "parameters": {
995                    "width": request.width,
996                    "height": request.height,
997                },
998            }),
999        };
1000        // Merged last, so a caller can reach the endpoint's other parameters
1001        // and override what is derived above.
1002        if let Some(additional_params) = request.additional_params {
1003            body = crate::json_utils::merge(body, additional_params);
1004        }
1005
1006        let uri = self
1007            .provider
1008            .modality_uri(
1009                "image generation",
1010                self.provider.dialect.quirks.image_generation_path,
1011                &self.model,
1012            )
1013            .map_err(EncodeError::request)?;
1014        json_post_to(&self.provider, uri, &body)
1015    }
1016
1017    fn decoder<'id>(&self) -> Self::Decoder<'id> {
1018        ImagesDecoder {
1019            body: self.provider.dialect.quirks.image_body,
1020        }
1021    }
1022}
1023
1024/// The speech wire.
1025#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1026pub struct Speech {
1027    /// Which provider, and how to reach it.
1028    pub provider: OpenAIConfig,
1029    /// The speech model.
1030    pub model: String,
1031}
1032
1033impl Speech {
1034    /// The speech wire for `model`.
1035    pub fn new(provider: OpenAIConfig, model: impl Into<String>) -> Self {
1036        Self {
1037            provider,
1038            model: model.into(),
1039        }
1040    }
1041}
1042
1043/// Decode raw audio or the dialect's base64 JSON envelope.
1044#[derive(Default)]
1045pub struct SpeechDecoder {
1046    /// Which reply shape this dialect answers with.
1047    body: SpeechBody,
1048}
1049
1050/// Hyperbolic's speech reply: base64 in a JSON envelope rather than the
1051/// audio bytes themselves.
1052#[derive(Debug, Clone, Serialize, Deserialize)]
1053pub struct SpeechReply {
1054    /// The audio, base64-encoded.
1055    pub audio: String,
1056}
1057
1058impl<'id> Decoder<'id, crate::operation::AudioGeneration> for SpeechDecoder {
1059    type Event = Vec<u8>;
1060
1061    fn classify(&self, frame: WireFrame) -> WireEvent<Self::Event> {
1062        // Interpretation selects raw audio or JSON decoding from the dialect.
1063        WireEvent::Known(frame.into_bytes())
1064    }
1065
1066    fn decode(
1067        &mut self,
1068        event: Self::Event,
1069        out: Out<'id, crate::operation::AudioGeneration>,
1070    ) -> Result<Flow, ProviderError> {
1071        use base64::Engine;
1072
1073        let audio = match self.body {
1074            // OpenAI and xAI answer with the audio itself.
1075            SpeechBody::OpenAi | SpeechBody::Xai => event,
1076            SpeechBody::MiniMax => {
1077                let reply = crate::providers::minimax::decode_reply::<
1078                    crate::providers::minimax::audio_generation::SpeechReply,
1079                >(&event)?;
1080                return Ok(out.end(reply.into_response()?));
1081            }
1082            // Hyperbolic wraps it, base64-encoded, in a JSON envelope.
1083            SpeechBody::Hyperbolic => {
1084                let reply = serde_json::from_slice::<SpeechReply>(&event)
1085                    .map_err(|error| ProviderError::Response(error.to_string()))?;
1086                base64::prelude::BASE64_STANDARD
1087                    .decode(&reply.audio)
1088                    .map_err(|error| ProviderError::Response(error.to_string()))?
1089            }
1090        };
1091        Ok(out.end(crate::audio_generation::AudioGenerationResponse::new(audio)))
1092    }
1093}
1094
1095impl Wire for Speech {
1096    type Op = crate::operation::AudioGeneration;
1097    type Payload = crate::wire::Encoded;
1098    type Frame = crate::wire::WireFrame;
1099    type Event = Vec<u8>;
1100    type Decoder<'id> = SpeechDecoder;
1101    type Reassembler = crate::wire::document::Unreassembled;
1102
1103    fn describe(&self) -> Descriptor<'_> {
1104        Descriptor::new(self.provider.dialect.name).model(self.model.as_str())
1105    }
1106
1107    fn encode(
1108        &self,
1109        request: crate::audio_generation::AudioGenerationRequest,
1110        _mode: Mode,
1111    ) -> Result<Encoded, EncodeError> {
1112        let mut additional_params = request.additional_params;
1113        let mut body = match self.provider.dialect.quirks.speech_body {
1114            SpeechBody::OpenAi => serde_json::json!({
1115                "model": self.model,
1116                "input": request.text,
1117                "voice": request.voice,
1118                "speed": request.speed,
1119            }),
1120            // xAI requires a default voice when the caller leaves it empty.
1121            SpeechBody::Xai => serde_json::json!({
1122                "text": request.text,
1123                "voice_id": if request.voice.is_empty() { "eve" } else { request.voice.as_str() },
1124                "language": "en",
1125            }),
1126            // Hyperbolic addresses this endpoint by language, so the
1127            // identifier the caller passes as the model IS the language tag.
1128            SpeechBody::Hyperbolic => serde_json::json!({
1129                "language": self.model,
1130                "speaker": request.voice,
1131                "text": request.text,
1132                "speed": request.speed,
1133            }),
1134            // Only the non-streaming reply's hex audio is decoded.
1135            SpeechBody::MiniMax => serde_json::json!({
1136                "model": self.model,
1137                "text": request.text,
1138                "stream": false,
1139                "output_format": "hex",
1140                "voice_setting": {
1141                    "voice_id": request.voice,
1142                    "speed": request.speed,
1143                },
1144            }),
1145        };
1146        // A caller's `voice_setting` adds to the derived one, so setting the
1147        // volume keeps the voice.
1148        if let Some(derived) = body
1149            .get_mut("voice_setting")
1150            .and_then(serde_json::Value::as_object_mut)
1151            && let Some(params) = additional_params
1152                .as_mut()
1153                .and_then(serde_json::Value::as_object_mut)
1154            && let Some(serde_json::Value::Object(caller)) = params.get("voice_setting")
1155        {
1156            derived.extend(caller.clone());
1157            crate::json_utils::remove_preserving_order(params, "voice_setting");
1158        }
1159        // Caller parameters take precedence, including response format and instructions.
1160        if let Some(additional_params) = additional_params {
1161            body = crate::json_utils::merge(body, additional_params);
1162        }
1163
1164        // Azure versions its speech endpoint separately from every other
1165        // route, so this one request carries its own `api-version`.
1166        let uri = self.provider.uri_versioned(
1167            self.provider.dialect.quirks.audio_generation_path,
1168            self.provider.deployment(&self.model),
1169            self.provider.speech_api_version(),
1170        );
1171        json_post_to(&self.provider, uri, &body)
1172    }
1173
1174    fn decoder<'id>(&self) -> Self::Decoder<'id> {
1175        SpeechDecoder {
1176            body: self.provider.dialect.quirks.speech_body,
1177        }
1178    }
1179}
1180
1181/// The model-listing wire.
1182#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1183pub struct Models {
1184    /// Which provider, and how to reach it.
1185    pub provider: OpenAIConfig,
1186}
1187
1188impl Models {
1189    /// The model-listing wire.
1190    pub fn new(provider: OpenAIConfig) -> Self {
1191        Self { provider }
1192    }
1193}
1194
1195/// Model-list entry with required `id` and optional metadata.
1196/// Context length prefers `context_window`, then `context_length`, then
1197/// `max_context_length`. Top-level output limits take precedence over `top_provider`.
1198#[derive(Debug, Deserialize)]
1199pub struct ModelEntry {
1200    pub id: String,
1201    #[serde(default)]
1202    pub name: Option<String>,
1203    #[serde(default)]
1204    pub description: Option<String>,
1205    /// Mistral labels the model kind `type` (`base`, `fine-tuned`).
1206    #[serde(default, rename = "type")]
1207    pub kind: Option<String>,
1208    #[serde(default)]
1209    pub created: Option<u64>,
1210    #[serde(default)]
1211    pub owned_by: Option<String>,
1212    #[serde(default)]
1213    pub context_window: Option<u32>,
1214    #[serde(default)]
1215    pub context_length: Option<u32>,
1216    #[serde(default)]
1217    pub max_context_length: Option<u32>,
1218    #[serde(default)]
1219    pub max_completion_tokens: Option<u32>,
1220    #[serde(default)]
1221    pub top_provider: Option<TopProvider>,
1222}
1223
1224/// OpenRouter's per-entry routing block. Only the output ceiling is read;
1225/// the rest of the block is routing detail [`ModelInfo`] has no slot for.
1226#[derive(Debug, Deserialize)]
1227pub struct TopProvider {
1228    #[serde(default)]
1229    pub max_completion_tokens: Option<u32>,
1230}
1231
1232impl From<ModelEntry> for ModelInfo {
1233    fn from(entry: ModelEntry) -> Self {
1234        let mut model = ModelInfo::from_id(entry.id);
1235        model.name = entry.name;
1236        model.description = entry.description;
1237        model.r#type = entry.kind;
1238        model.created_at = entry.created;
1239        model.owned_by = entry.owned_by;
1240        model.context_length = entry
1241            .context_window
1242            .or(entry.context_length)
1243            .or(entry.max_context_length);
1244        model.max_output_tokens = entry.max_completion_tokens.or_else(|| {
1245            entry
1246                .top_provider
1247                .and_then(|provider| provider.max_completion_tokens)
1248        });
1249        model
1250    }
1251}
1252
1253/// The `{ "data": [...] }` envelope.
1254#[derive(Debug, Deserialize)]
1255pub struct ModelsReply {
1256    #[serde(default)]
1257    pub data: Vec<ModelEntry>,
1258}
1259
1260/// Reads a listing reply with the dialect's `model_listing` hook, or as
1261/// the `{ "data": [...] }` envelope when the dialect has none.
1262pub struct ModelsDecoder(Option<super::ModelCatalogue>);
1263
1264impl<'id> Decoder<'id, ModelListing> for ModelsDecoder {
1265    type Event = ModelList;
1266
1267    fn classify(&self, frame: WireFrame) -> WireEvent<Self::Event> {
1268        let body = frame.as_str();
1269        match self.0 {
1270            Some(read) => classify_untyped_line(body.as_bytes()).map(read),
1271            None => classify_untyped_line::<ModelsReply>(body.as_bytes())
1272                .map(|reply| reply.data.into_iter().map(ModelInfo::from).collect())
1273                .map(ModelList::new),
1274        }
1275    }
1276
1277    fn decode(
1278        &mut self,
1279        models: Self::Event,
1280        out: Out<'id, ModelListing>,
1281    ) -> Result<Flow, ProviderError> {
1282        Ok(out.end(ModelPage { models, next: None }))
1283    }
1284}
1285
1286impl Wire for Models {
1287    type Op = ModelListing;
1288    type Payload = crate::wire::Encoded;
1289    type Frame = crate::wire::WireFrame;
1290    type Event = ModelList;
1291    type Decoder<'id> = ModelsDecoder;
1292    type Reassembler = crate::wire::document::Unreassembled;
1293
1294    fn describe(&self) -> Descriptor<'_> {
1295        Descriptor::new(self.provider.dialect.name)
1296    }
1297
1298    /// The catalogue is one page, so a cursor never follows.
1299    fn encode(&self, _cursor: Option<String>, _mode: Mode) -> Result<Encoded, EncodeError> {
1300        get(&self.provider, self.provider.dialect.quirks.models_path)
1301    }
1302
1303    fn decoder<'id>(&self) -> Self::Decoder<'id> {
1304        ModelsDecoder(
1305            self.provider
1306                .dialect
1307                .quirks
1308                .hooks
1309                .and_then(|hooks| hooks.model_listing),
1310        )
1311    }
1312}
1313
1314/// Rerank documents with `{model, query, documents, top_n}` requests.
1315/// The dialect must configure a nonempty reranking path.
1316#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1317pub struct Rerank {
1318    /// Which provider, and how to reach it.
1319    pub provider: OpenAIConfig,
1320    /// The reranker model.
1321    pub model: String,
1322    /// Return only the `top_n` highest-scoring documents, when the caller
1323    /// asked for a cut.
1324    pub top_n: Option<usize>,
1325}
1326
1327impl Rerank {
1328    /// The rerank wire for `model`.
1329    pub fn new(provider: OpenAIConfig, model: impl Into<String>) -> Self {
1330        Self {
1331            provider,
1332            model: model.into(),
1333            top_n: None,
1334        }
1335    }
1336
1337    /// Ask the server to return only the `top_n` highest-scoring documents.
1338    pub fn with_top_n(mut self, top_n: usize) -> Self {
1339        self.top_n = Some(top_n);
1340        self
1341    }
1342}
1343
1344/// Scored input document accepting `relevance_score` or `score` as its score key.
1345#[derive(Debug, Clone, Serialize, Deserialize)]
1346pub struct RerankResultEntry {
1347    /// Which input document this scored.
1348    pub index: usize,
1349    /// The score.
1350    #[serde(alias = "score")]
1351    pub relevance_score: f64,
1352    /// Present only on servers that echo the document back; llama.cpp does
1353    /// not on this path.
1354    #[serde(default, alias = "text")]
1355    pub document: Option<String>,
1356}
1357
1358/// What a rerank reply reports besides its ranking.
1359#[derive(Debug, Clone, Serialize, Deserialize, Default)]
1360pub struct RerankUsage {
1361    /// Tokens the query and documents cost.
1362    #[serde(default)]
1363    pub prompt_tokens: u64,
1364    /// Total tokens, as the provider reported them.
1365    #[serde(default)]
1366    pub total_tokens: u64,
1367}
1368
1369/// The rerank reply.
1370#[derive(Debug, Clone, Serialize, Deserialize)]
1371pub struct RerankReply {
1372    /// The model the server ranked with, when it named one.
1373    #[serde(default)]
1374    pub model: Option<String>,
1375    /// The ranking.
1376    pub results: Vec<RerankResultEntry>,
1377    /// What it cost.
1378    #[serde(default)]
1379    pub usage: Option<RerankUsage>,
1380}
1381
1382impl Wire for Rerank {
1383    type Op = RerankOp;
1384    type Payload = crate::wire::Encoded;
1385    type Frame = crate::wire::WireFrame;
1386    type Event = RerankReply;
1387    type Decoder<'id> = DocumentDecoder<RerankOp, Self::Event>;
1388    type Reassembler = crate::wire::document::Unreassembled;
1389
1390    fn describe(&self) -> Descriptor<'_> {
1391        Descriptor::new(self.provider.dialect.name)
1392            .model(self.model.as_str())
1393            .capabilities(Capabilities::rerank(
1394                self.provider.dialect.quirks.rerank.max_documents,
1395            ))
1396    }
1397
1398    fn encode(
1399        &self,
1400        request: crate::operation::RerankRequest,
1401        _mode: Mode,
1402    ) -> Result<Encoded, EncodeError> {
1403        let quirks = &self.provider.dialect.quirks.rerank;
1404        // An empty path explicitly disables reranking.
1405        if quirks.path.is_empty() {
1406            return Err(EncodeError::request(format!(
1407                "{} offers no reranking endpoint",
1408                self.provider.dialect.name
1409            )));
1410        }
1411        let body = set_fields([
1412            ("query", Some(serde_json::json!(request.query))),
1413            ("documents", Some(serde_json::json!(request.documents))),
1414            (
1415                "model",
1416                quirks
1417                    .sends_model_field
1418                    .then(|| serde_json::json!(self.model)),
1419            ),
1420            ("top_n", self.top_n.map(|top_n| serde_json::json!(top_n))),
1421        ]);
1422
1423        json_post(
1424            &self.provider,
1425            quirks.path,
1426            self.provider.deployment(&self.model),
1427            &serde_json::Value::Object(body),
1428        )
1429    }
1430
1431    fn decoder<'id>(&self) -> Self::Decoder<'id> {
1432        DocumentDecoder::new(
1433            |body| classify_untyped_line(body.as_bytes()),
1434            |event| {
1435                let usage = event
1436                    .usage
1437                    .map(|usage| crate::completion::Usage {
1438                        input_tokens: Some(usage.prompt_tokens),
1439                        total_tokens: Some(usage.total_tokens),
1440                        ..Default::default()
1441                    })
1442                    .unwrap_or_default();
1443                let results = event
1444                    .results
1445                    .into_iter()
1446                    .map(|result| crate::rerank::RerankResult {
1447                        index: result.index,
1448                        document: result.document,
1449                        relevance_score: result.relevance_score,
1450                    })
1451                    .collect();
1452                Ok(crate::rerank::RerankResponse {
1453                    model: event.model,
1454                    usage,
1455                    ..crate::rerank::RerankResponse::new(results)
1456                })
1457            },
1458        )
1459    }
1460}
1461
1462/// The credential-check wire: a `GET` whose status is the answer.
1463#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1464pub struct Verify {
1465    /// Which provider, and how to reach it.
1466    pub provider: OpenAIConfig,
1467}
1468
1469impl Verify {
1470    /// The credential-check wire.
1471    pub fn new(provider: OpenAIConfig) -> Self {
1472        Self { provider }
1473    }
1474}
1475
1476pub use crate::operation::VerifyDecoder;
1477
1478impl Wire for Verify {
1479    type Op = VerifyOp;
1480    type Payload = crate::wire::Encoded;
1481    type Frame = crate::wire::WireFrame;
1482    type Event = ();
1483    type Decoder<'id> = VerifyDecoder;
1484    type Reassembler = crate::wire::document::Unreassembled;
1485
1486    fn describe(&self) -> Descriptor<'_> {
1487        Descriptor::new(self.provider.dialect.name)
1488    }
1489
1490    fn encode(&self, _request: (), _mode: Mode) -> Result<Encoded, EncodeError> {
1491        let path = self.provider.dialect.quirks.verify_path;
1492        if path.is_empty() {
1493            return Err(EncodeError::request(format!(
1494                "{} offers no endpoint that checks a credential without consuming tokens",
1495                self.provider.dialect.name
1496            )));
1497        }
1498        get(&self.provider, path)
1499    }
1500
1501    fn decoder<'id>(&self) -> Self::Decoder<'id> {
1502        VerifyDecoder
1503    }
1504}
1505
1506#[cfg(test)]
1507mod tests;