Skip to main content

rig_core/operation/
modality.rs

1//! Buffered embedding, reranking, transcription, image, and audio operations.
2//!
3//! ```
4//! use rig_core::wire::Capabilities;
5//!
6//! let capabilities = Capabilities::embedding(32, 768).declaring(Some(768));
7//! assert_eq!(capabilities.declared, Some(768));
8//! ```
9
10use std::convert::Infallible;
11
12use super::Whole;
13use crate::embeddings::Embedding as Vector;
14use crate::error::ProviderError;
15use crate::telemetry::{GenAiOperation, SpanBuilder, SpanCombinator};
16use crate::wire::{Call, Capabilities, Fold, Free, Operation, Reply};
17
18/// A reranking request: the query, the documents to order, and the batch
19/// limit's subject.
20///
21/// The consumer trait takes `(&str, Vec<String>)`; the operation takes one
22/// request value, as every other operation does. It is also the rerank
23/// effect's payload.
24#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
25pub struct RerankRequest {
26    /// What the documents are ordered against.
27    pub query: String,
28    /// The documents to order, in input order.
29    pub documents: Vec<String>,
30}
31
32/// Declare one unary modality operation.
33macro_rules! modality_operation {
34    (
35        $(#[$doc:meta])*
36        $op:ident {
37            request: $request:ty,
38            response: $response:ty,
39            telemetry: $telemetry:ident,
40            fold: $fold:ty,
41            seed: $seed:expr,
42        }
43    ) => {
44        $(#[$doc])*
45        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
46        pub struct $op;
47
48        impl Operation for $op {
49            type Request = $request;
50            type Event = Infallible;
51            type End = $response;
52            type Response = $response;
53            type Fold = Traced<Self, $fold>;
54            type Emit = Free;
55
56            fn fold(request: &Self::Request, call: &mut Call<'_>) -> Self::Fold {
57                let telemetry = call
58                    .wire
59                    .telemetry
60                    .map_or(GenAiOperation::$telemetry, |telemetry| telemetry(call.mode));
61                debug_assert!(!telemetry.is_completion());
62                let span = SpanBuilder::new(
63                    call.wire.name,
64                    call.wire.model.unwrap_or_default(),
65                    telemetry,
66                )
67                .build();
68                call.instrument(span.clone());
69                #[allow(clippy::redundant_closure_call)]
70                let inner = ($seed)(request, &*call);
71                Traced {
72                    inner,
73                    span,
74                    record: |span, response| {
75                        span.record_response(
76                            response.response_id.as_deref(),
77                            response.model.as_deref(),
78                            &response.usage,
79                        )
80                    },
81                }
82            }
83        }
84    };
85}
86
87/// A fold whose response is recorded on the call's telemetry span.
88pub struct Traced<Op: Operation, F> {
89    inner: F,
90    span: tracing::Span,
91    record: fn(&tracing::Span, &Op::Response),
92}
93
94impl<Op, F> Fold<Op> for Traced<Op, F>
95where
96    Op: Operation,
97    F: Fold<Op>,
98{
99    fn absorb(&mut self, event: &Op::Event) -> Result<(), ProviderError> {
100        self.inner.absorb(event)
101    }
102
103    fn finish(self, end: Op::End, reply: Reply) -> Result<Op::Response, ProviderError> {
104        let response = self.inner.finish(end, reply)?;
105        (self.record)(&self.span, &response);
106        Ok(response)
107    }
108}
109
110/// A modality response the driver writes its facts onto.
111pub(crate) trait Stamp {
112    /// Write the provider, the transport request id and the reply document,
113    /// and drop a model or id reported empty.
114    fn stamp(&mut self, reply: &Reply);
115}
116
117macro_rules! stamp {
118    ($($response:ty),*) => {$(
119        impl Stamp for $response {
120            fn stamp(&mut self, reply: &Reply) {
121                use crate::provider_response::reported;
122                self.provider.clone_from(&reply.provider);
123                self.provider_request_id = reported(reply.provider_request_id.clone());
124                self.raw.clone_from(&reply.raw);
125                self.model = reported(self.model.take());
126                self.response_id = reported(self.response_id.take());
127            }
128        }
129    )*};
130}
131
132stamp!(
133    crate::embeddings::EmbeddingResponse,
134    crate::rerank::RerankResponse,
135    crate::transcription::TranscriptionResponse
136);
137stamp!(crate::image_generation::ImageGenerationResponse);
138stamp!(crate::audio_generation::AudioGenerationResponse);
139
140modality_operation!(
141    /// Embedding a batch of texts.
142    Embedding {
143        request: Vec<String>,
144        response: crate::embeddings::EmbeddingResponse,
145        telemetry: Embeddings,
146        fold: Embedded,
147        seed: |texts: &Vec<String>, call: &Call<'_>| Embedded::over(texts.clone(), call),
148    }
149);
150
151modality_operation!(
152    /// Embedding a batch of images from their encoded file bytes.
153    ImageEmbedding {
154        request: Vec<Vec<u8>>,
155        response: crate::embeddings::EmbeddingResponse,
156        telemetry: Embeddings,
157        fold: Embedded,
158        seed: |images: &Vec<Vec<u8>>, call: &Call<'_>| Embedded::over(
159            images.iter().map(|bytes| crate::embeddings::image_document(bytes)).collect(),
160            call,
161        ),
162    }
163);
164
165modality_operation!(
166    /// Ordering documents by relevance to a query.
167    Rerank {
168        request: RerankRequest,
169        response: crate::rerank::RerankResponse,
170        telemetry: Rerank,
171        fold: Whole<Self>,
172        seed: |_: &_, _: &Call<'_>| Whole::stamping(<crate::rerank::RerankResponse as Stamp>::stamp),
173    }
174);
175
176modality_operation!(
177    /// Transcribes audio using provider-specific request encoding.
178    Transcription {
179        request: crate::transcription::TranscriptionRequest,
180        response: crate::transcription::TranscriptionResponse,
181        telemetry: Transcription,
182        fold: Whole<Self>,
183        seed: |_: &_, _: &Call<'_>| Whole::stamping(<crate::transcription::TranscriptionResponse as Stamp>::stamp),
184    }
185);
186
187modality_operation!(
188    /// Generating an image.
189    ImageGeneration {
190        request: crate::image_generation::ImageGenerationRequest,
191        response: crate::image_generation::ImageGenerationResponse,
192        telemetry: ImageGeneration,
193        fold: Whole<Self>,
194        seed: |_: &_, _: &Call<'_>| Whole::stamping(<crate::image_generation::ImageGenerationResponse as Stamp>::stamp),
195    }
196);
197
198modality_operation!(
199    /// Generating speech.
200    AudioGeneration {
201        request: crate::audio_generation::AudioGenerationRequest,
202        response: crate::audio_generation::AudioGenerationResponse,
203        telemetry: AudioGeneration,
204        fold: Whole<Self>,
205        seed: |_: &_, _: &Call<'_>| Whole::stamping(<crate::audio_generation::AudioGenerationResponse as Stamp>::stamp),
206    }
207);
208
209/// Pairs a reply's vectors positionally with the request's documents.
210/// Finishing rejects unequal vector and document counts, and widths that
211/// contradict the width the caller declared.
212pub struct Embedded {
213    documents: Vec<String>,
214    /// The provider and capabilities the reply is checked against.
215    provider: String,
216    capabilities: Capabilities,
217}
218
219impl Embedded {
220    /// A fold that will zip its vectors onto `documents`, for the model
221    /// `call` describes.
222    pub fn over(documents: Vec<String>, call: &Call<'_>) -> Self {
223        Self {
224            documents,
225            provider: call.wire.name.to_owned(),
226            capabilities: call.wire.capabilities,
227        }
228    }
229
230    /// The reply's vectors, paired with the inputs they belong to.
231    fn zipped(self, vectors: Vec<Vector>) -> Result<Vec<Vector>, ProviderError> {
232        self.capabilities.honour_declaration(
233            &self.provider,
234            vectors.iter().map(|vector| vector.vec.len()),
235        )?;
236        if vectors.len() != self.documents.len() {
237            return Err(ProviderError::Response(format!(
238                "provider returned {} embeddings for {} documents",
239                vectors.len(),
240                self.documents.len()
241            )));
242        }
243        Ok(self
244            .documents
245            .into_iter()
246            .zip(vectors)
247            .map(|(document, vector)| Vector {
248                document,
249                vec: vector.vec,
250            })
251            .collect())
252    }
253}
254
255impl<Op> Fold<Op> for Embedded
256where
257    Op: Operation<
258            Event = Infallible,
259            End = crate::embeddings::EmbeddingResponse,
260            Response = crate::embeddings::EmbeddingResponse,
261        >,
262{
263    fn absorb(&mut self, event: &Infallible) -> Result<(), ProviderError> {
264        match *event {}
265    }
266
267    fn finish(
268        self,
269        mut response: crate::embeddings::EmbeddingResponse,
270        reply: Reply,
271    ) -> Result<crate::embeddings::EmbeddingResponse, ProviderError> {
272        response.embeddings = self.zipped(std::mem::take(&mut response.embeddings))?;
273        response.stamp(&reply);
274        Ok(response)
275    }
276}