Skip to main content

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}