Skip to main content

rig_core/providers/voyageai/
wire.rs

1//! Voyage AI configuration and embedding and reranking endpoint wires.
2//!
3//! ```no_run
4//! use rig_core::providers::voyageai::{VoyageAi, VOYAGE_3_5};
5//! let wire = VoyageAi::from_env()?.embedding(VOYAGE_3_5, None);
6//! # Ok::<(), Box<dyn std::error::Error>>(())
7//! ```
8
9use crate::client::env::{self, EnvError};
10use crate::embeddings::Embedding as Vector;
11use crate::error::EncodeError;
12use crate::error::ProviderError;
13use crate::operation::{Embedding, Rerank as RerankOp, RerankRequest};
14use crate::rerank::{RerankResponse, RerankResult};
15use crate::wire::Flow;
16use crate::wire::{
17    Body, Capabilities, Decoder, Descriptor, Encoded, Framing, Mode, Out, Secret, Wire, WireEvent,
18    WireFrame,
19};
20use serde::{Deserialize, Serialize};
21
22use super::{
23    EmbeddingResponse as VoyageEmbeddingResponse, RerankApiResponse, RerankErrorEnvelope,
24    VOYAGEAI_API_BASE_URL, model_dimensions_from_identifier,
25};
26
27/// The provider descriptor name, as records and telemetry spell it.
28const PROVIDER_NAME: &str = "voyageai";
29
30/// The environment variable carrying the API key.
31const API_KEY_ENV: &str = "VOYAGE_API_KEY";
32
33/// The most texts `POST /embeddings` accepts in one call.
34const MAX_DOCUMENTS: usize = 1024;
35
36/// The most documents `POST /rerank` orders in one call.
37const MAX_RERANK_DOCUMENTS: usize = 1000;
38
39/// The settings of a Voyage AI provider: serializable, and the credential
40/// is never serialized. [`connect`](Self::connect) puts it on a transport as
41/// a [`VoyageAi`](super::VoyageAi) client.
42#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
43pub struct VoyageAiConfig {
44    /// The API key, sent as `Authorization: Bearer`.
45    pub api_key: Secret,
46    /// The API root, without a trailing slash.
47    pub base_url: String,
48}
49
50impl VoyageAiConfig {
51    /// Voyage AI with default settings.
52    pub fn new(api_key: impl Into<Secret>) -> Self {
53        Self {
54            api_key: api_key.into(),
55            base_url: VOYAGEAI_API_BASE_URL.to_owned(),
56        }
57    }
58
59    /// Voyage AI from `VOYAGE_API_KEY`.
60    pub fn from_env() -> Result<Self, EnvError> {
61        Ok(Self::new(env::required(API_KEY_ENV)?))
62    }
63
64    /// Point the wires at another API root.
65    pub fn with_base_url(mut self, base_url: impl AsRef<str>) -> Self {
66        self.base_url = base_url.as_ref().trim_end_matches('/').to_owned();
67        self
68    }
69
70    /// Build an embedding wire reporting `ndims`, or the known model width,
71    /// or zero if unknown. This does not send an output-dimension override;
72    /// use [`Embeddings::with_output_dimension`] for that.
73    pub(crate) fn embedding(&self, model: impl Into<String>, ndims: Option<usize>) -> Embeddings {
74        let model = model.into();
75        let ndims = ndims
76            .or_else(|| model_dimensions_from_identifier(&model))
77            .unwrap_or_default();
78        Embeddings {
79            provider: self.clone(),
80            model,
81            ndims,
82            input_type: None,
83            truncation: None,
84            output_dimension: None,
85        }
86    }
87
88    /// The rerank wire for `model`.
89    pub(crate) fn rerank(&self, model: impl Into<String>) -> Rerank {
90        Rerank {
91            provider: self.clone(),
92            model: model.into(),
93            top_k: None,
94            return_documents: false,
95            truncation: None,
96        }
97    }
98
99    /// One request, authenticated and typed as JSON.
100    fn post(&self, path: &str) -> http::request::Builder {
101        http::Request::post(format!("{}{path}", self.base_url))
102            .header(http::header::CONTENT_TYPE, "application/json")
103            .header(
104                http::header::AUTHORIZATION,
105                format!("Bearer {}", self.api_key.expose()),
106            )
107    }
108}
109
110/// The embedding wire: `POST /embeddings`.
111///
112/// Every option defaults to `None`, which is Voyage's own server default:
113/// no retrieval prompt, truncation enabled, and the model's default output
114/// dimension.
115#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
116pub struct Embeddings {
117    /// The provider this wire speaks to.
118    pub provider: VoyageAiConfig,
119    /// The model to address.
120    pub model: String,
121    /// The width this wire reports, from the caller or the model's published
122    /// dimensions. `0` means neither named one.
123    pub ndims: usize,
124    /// Prepends a retrieval prompt to the input text: `"document"` when
125    /// embedding stored chunks, `"query"` when embedding search queries.
126    /// Embeddings produced with and without it are compatible.
127    pub input_type: Option<String>,
128    /// Whether to truncate inputs longer than the model's context. Voyage's
129    /// server default is `true`.
130    pub truncation: Option<bool>,
131    /// Dimensionality of the returned vectors, when overriding the model's
132    /// default output dimension.
133    pub output_dimension: Option<usize>,
134}
135
136impl Embeddings {
137    /// Prepend Voyage's retrieval prompt for this input's role.
138    pub fn with_input_type(mut self, input_type: impl Into<String>) -> Self {
139        self.input_type = Some(input_type.into());
140        self
141    }
142
143    /// Set whether overlong inputs are truncated (`true`) or rejected (`false`).
144    pub fn with_truncation(mut self, truncation: bool) -> Self {
145        self.truncation = Some(truncation);
146        self
147    }
148
149    /// Ask Voyage for vectors of this width.
150    ///
151    /// This is the width the request carries; [`Self::ndims`] is the width
152    /// the wire reports to a vector store, so they are set together.
153    pub fn with_output_dimension(mut self, output_dimension: usize) -> Self {
154        self.output_dimension = Some(output_dimension);
155        self.ndims = output_dimension;
156        self
157    }
158}
159
160impl Wire for Embeddings {
161    type Op = Embedding;
162    type Payload = crate::wire::Encoded;
163    type Frame = crate::wire::WireFrame;
164    type Decoder<'id> = EmbeddingsDecoder;
165
166    fn describe(&self) -> Descriptor<'_> {
167        Descriptor::new(PROVIDER_NAME)
168            .model(self.model.as_str())
169            .capabilities(Capabilities::embedding(MAX_DOCUMENTS, self.ndims))
170    }
171
172    fn encode(&self, texts: Vec<String>, _mode: Mode) -> Result<Encoded, EncodeError> {
173        let mut body = serde_json::Map::new();
174        body.insert("model".to_owned(), serde_json::json!(self.model));
175        body.insert("input".to_owned(), serde_json::json!(texts));
176        if let Some(input_type) = &self.input_type {
177            body.insert("input_type".to_owned(), serde_json::json!(input_type));
178        }
179        if let Some(truncation) = self.truncation {
180            body.insert("truncation".to_owned(), serde_json::json!(truncation));
181        }
182        if let Some(output_dimension) = self.output_dimension {
183            body.insert(
184                "output_dimension".to_owned(),
185                serde_json::json!(output_dimension),
186            );
187        }
188        let request = self
189            .provider
190            .post("/embeddings")
191            .body(Body::Bytes(serde_json::to_vec(&body)?))?;
192        Ok(Encoded::new(request, Framing::Whole))
193    }
194
195    fn decoder<'id>(&self) -> Self::Decoder<'id> {
196        EmbeddingsDecoder
197    }
198}
199
200/// Decodes one `/embeddings` reply.
201pub struct EmbeddingsDecoder;
202
203impl<'id> Decoder<'id, Embedding> for EmbeddingsDecoder {
204    type Event = VoyageEmbeddingResponse;
205
206    fn classify(&self, frame: WireFrame) -> WireEvent<Self::Event> {
207        crate::providers::internal::wire::classify_marker_keyed_frame(&frame.as_str(), &["data"])
208    }
209
210    fn decode(
211        &mut self,
212        reply: Self::Event,
213        out: Out<'id, Embedding>,
214    ) -> Result<Flow, ProviderError> {
215        // Voyage reports one count; every token of an embedding is input.
216        let usage = crate::completion::Usage {
217            input_tokens: Some(reply.usage.total_tokens as u64),
218            total_tokens: Some(reply.usage.total_tokens as u64),
219            ..Default::default()
220        };
221        // The vectors only; the operation's fold pairs them with the texts
222        // that were sent, which `/embeddings` does not echo back.
223        let vectors = reply
224            .data
225            .into_iter()
226            .map(|embedding| Vector {
227                document: String::new(),
228                vec: embedding.embedding,
229            })
230            .collect();
231        Ok(out.end(crate::embeddings::EmbeddingResponse {
232            model: Some(reply.model),
233            usage,
234            ..crate::embeddings::EmbeddingResponse::new(vectors)
235        }))
236    }
237}
238
239/// The rerank wire: `POST /rerank`.
240#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
241pub struct Rerank {
242    /// The provider this wire speaks to.
243    pub provider: VoyageAiConfig,
244    /// The model to address.
245    pub model: String,
246    /// Return only the `top_k` most relevant documents. `None` returns them
247    /// all.
248    pub top_k: Option<usize>,
249    /// Whether the reply echoes each document's text back.
250    pub return_documents: bool,
251    /// Whether to truncate documents longer than the model's context.
252    /// Voyage's server default is `true`.
253    pub truncation: Option<bool>,
254}
255
256impl Rerank {
257    /// Order only the `top_k` most relevant documents.
258    pub fn with_top_k(mut self, top_k: usize) -> Self {
259        self.top_k = Some(top_k);
260        self
261    }
262
263    /// Ask Voyage to echo each ordered document's text back.
264    pub fn with_return_documents(mut self, return_documents: bool) -> Self {
265        self.return_documents = return_documents;
266        self
267    }
268
269    /// Set whether overlong documents are truncated (`true`) or rejected (`false`).
270    pub fn with_truncation(mut self, truncation: bool) -> Self {
271        self.truncation = Some(truncation);
272        self
273    }
274}
275
276impl Wire for Rerank {
277    type Op = RerankOp;
278    type Payload = crate::wire::Encoded;
279    type Frame = crate::wire::WireFrame;
280    type Decoder<'id> = RerankDecoder;
281
282    fn describe(&self) -> Descriptor<'_> {
283        Descriptor::new(PROVIDER_NAME)
284            .model(self.model.as_str())
285            .capabilities(Capabilities::rerank(MAX_RERANK_DOCUMENTS))
286    }
287
288    fn encode(&self, request: RerankRequest, _mode: Mode) -> Result<Encoded, EncodeError> {
289        let mut body = serde_json::Map::new();
290        body.insert("query".to_owned(), serde_json::json!(request.query));
291        body.insert("documents".to_owned(), serde_json::json!(request.documents));
292        body.insert("model".to_owned(), serde_json::json!(self.model));
293        if let Some(top_k) = self.top_k {
294            body.insert("top_k".to_owned(), serde_json::json!(top_k));
295        }
296        body.insert(
297            "return_documents".to_owned(),
298            serde_json::json!(self.return_documents),
299        );
300        if let Some(truncation) = self.truncation {
301            body.insert("truncation".to_owned(), serde_json::json!(truncation));
302        }
303        let request = self
304            .provider
305            .post("/rerank")
306            .body(Body::Bytes(serde_json::to_vec(&body)?))?;
307        Ok(Encoded::new(request, Framing::Whole))
308    }
309
310    fn decoder<'id>(&self) -> Self::Decoder<'id> {
311        RerankDecoder
312    }
313}
314
315/// Ranking and error-envelope markers. Recognizing `message` permits fallback
316/// decoding of provider errors returned with successful HTTP status.
317const RERANK_REPLY_MARKERS: &[&str] = &["data", "message"];
318
319/// The key that recognizes the error envelope on its own.
320const RERANK_ERROR_MARKERS: &[&str] = &["message"];
321
322/// One `/rerank` reply: the ordering, or the error envelope Voyage can
323/// answer a **200** with instead.
324pub enum RerankReply {
325    /// The ordering Voyage returned.
326    Reply(RerankApiResponse),
327    /// The provider's error envelope, verbatim.
328    Failure(String),
329}
330
331/// Decodes one `/rerank` reply.
332pub struct RerankDecoder;
333
334impl<'id> Decoder<'id, RerankOp> for RerankDecoder {
335    type Event = RerankReply;
336
337    /// Decode a ranking, then an error envelope if ranking decoding fails.
338    /// Retain the ranking diagnostic when neither shape decodes.
339    fn classify(&self, frame: WireFrame) -> WireEvent<Self::Event> {
340        let data = frame.as_str();
341        crate::providers::internal::wire::classify_or(
342            &data,
343            |data| {
344                crate::providers::internal::wire::classify_marker_keyed_frame::<RerankApiResponse>(
345                    data,
346                    RERANK_REPLY_MARKERS,
347                )
348                .map(RerankReply::Reply)
349            },
350            |data| {
351                crate::providers::internal::wire::classify_marker_keyed_frame::<RerankErrorEnvelope>(
352                    data,
353                    RERANK_ERROR_MARKERS,
354                )
355                .map(|_| RerankReply::Failure(data.to_owned()))
356            },
357        )
358    }
359
360    fn decode(
361        &mut self,
362        reply: Self::Event,
363        out: Out<'id, RerankOp>,
364    ) -> Result<Flow, ProviderError> {
365        let reply = match reply {
366            RerankReply::Reply(reply) => reply,
367            // Preserve the provider body; the driver adds the actual HTTP status.
368            RerankReply::Failure(body) => {
369                return Err(ProviderError::from_provider_body(body));
370            }
371        };
372        // Voyage reports one count; every token of a rerank is input.
373        let usage = crate::completion::Usage {
374            input_tokens: Some(reply.usage.total_tokens as u64),
375            total_tokens: Some(reply.usage.total_tokens as u64),
376            ..Default::default()
377        };
378        let results = reply
379            .data
380            .into_iter()
381            .map(|result| RerankResult {
382                index: result.index,
383                document: result.document,
384                relevance_score: result.relevance_score,
385            })
386            .collect();
387        Ok(out.end(RerankResponse {
388            model: Some(reply.model),
389            usage,
390            ..RerankResponse::new(results)
391        }))
392    }
393}
394
395#[cfg(test)]
396mod tests;