rig_core/rerank.rs
1//! Provider-agnostic reranking abstractions.
2//!
3//! Reranking models reorder a list of documents by relevance to a query.
4//! A [`Model`](crate::driver::Model) over a rerank wire calls one, and
5//! [`RerankResponse`] carries both the scored results and token usage.
6//!
7//! ```no_run
8//! use rig_core::DynModel;
9//! use rig_core::operation::{Rerank, RerankRequest};
10//!
11//! # async fn example(model: &DynModel<Rerank>) -> Result<(), Box<dyn std::error::Error>> {
12//! let request = RerankRequest {
13//! query: "Rust".into(),
14//! documents: vec!["A systems programming language".into()],
15//! };
16//! let response = model.call(request).await?;
17//! # let _ = response;
18//! # Ok(())
19//! # }
20//! ```
21
22use crate::completion::Usage;
23use serde::{Deserialize, Serialize};
24
25/// A single reranked document result.
26#[derive(Debug, Clone, Serialize, Deserialize)]
27pub struct RerankResult {
28 /// Index of the document in the original input list.
29 pub index: usize,
30 /// The document text, if requested via `return_documents`.
31 pub document: Option<String>,
32 /// Relevance score, with higher values more relevant within this response.
33 /// The range is provider-specific and may include negative values. Do not
34 /// interpret it as a probability or compare scores across responses.
35 #[serde(deserialize_with = "crate::json_utils::floats")]
36 pub relevance_score: f64,
37}
38
39/// Ranked documents and normalized provider metadata.
40/// Provider-specific response data is available through [`Self::raw`].
41#[derive(Debug, Clone, Serialize, Deserialize)]
42pub struct RerankResponse {
43 /// Reranked results sorted by relevance (highest first).
44 pub results: Vec<RerankResult>,
45 /// Provider-reported model identifier, or `None` when omitted.
46 #[serde(default)]
47 pub model: Option<String>,
48 /// Token usage for this rerank request; every counter is `None` when the
49 /// provider reported none (see [`Usage`]).
50 #[serde(default)]
51 pub usage: Usage,
52 /// Stable descriptor name of the provider that produced this response,
53 /// for example `"voyageai"`. Always populated.
54 pub provider: String,
55 /// Provider-assigned response-scoped identifier, when reported.
56 #[serde(default, skip_serializing_if = "Option::is_none")]
57 pub response_id: Option<String>,
58 /// Transport request ID from HTTP headers, or `None` when unreported.
59 #[serde(default, skip_serializing_if = "Option::is_none")]
60 pub provider_request_id: Option<String>,
61 /// Provider response document. Defaults to null until populated.
62 #[serde(default, skip_serializing_if = "serde_json::Value::is_null")]
63 pub raw: serde_json::Value,
64}
65
66impl RerankResponse {
67 /// A response carrying `results`. The driver writes the provider, the
68 /// transport request id and the reply document; decoders set what the
69 /// provider reported.
70 pub fn new(results: Vec<RerankResult>) -> Self {
71 Self {
72 results,
73 model: None,
74 usage: Usage::default(),
75 provider: String::new(),
76 response_id: None,
77 provider_request_id: None,
78 raw: serde_json::Value::Null,
79 }
80 }
81}