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    pub relevance_score: f64,
36}
37
38/// Ranked documents and normalized provider metadata.
39/// Provider-specific response data is available through [`Self::raw`].
40#[derive(Debug, Clone, Serialize, Deserialize)]
41pub struct RerankResponse {
42    /// Reranked results sorted by relevance (highest first).
43    pub results: Vec<RerankResult>,
44    /// Provider-reported model identifier, or `None` when omitted.
45    #[serde(default)]
46    pub model: Option<String>,
47    /// Token usage for this rerank request; every counter is `None` when the
48    /// provider reported none (see [`Usage`]).
49    #[serde(default)]
50    pub usage: Usage,
51    /// Stable descriptor name of the provider that produced this response,
52    /// for example `"voyageai"`. Always populated.
53    pub provider: String,
54    /// Provider-assigned response-scoped identifier, when reported.
55    #[serde(default, skip_serializing_if = "Option::is_none")]
56    pub response_id: Option<String>,
57    /// Transport request ID from HTTP headers, or `None` when unreported.
58    #[serde(default, skip_serializing_if = "Option::is_none")]
59    pub provider_request_id: Option<String>,
60    /// Provider response document. Defaults to null until populated.
61    #[serde(default, skip_serializing_if = "serde_json::Value::is_null")]
62    pub raw: serde_json::Value,
63}
64
65impl RerankResponse {
66    /// A response carrying `results`. The driver writes the provider, the
67    /// transport request id and the reply document; decoders set what the
68    /// provider reported.
69    pub fn new(results: Vec<RerankResult>) -> Self {
70        Self {
71            results,
72            model: None,
73            usage: Usage::default(),
74            provider: String::new(),
75            response_id: None,
76            provider_request_id: None,
77            raw: serde_json::Value::Null,
78        }
79    }
80}
rig_core/rerank.rs

rig_core/
rerank.rs
