velesdb_memory/
rerank.rs

1//! Optional second-stage re-scoring of a [`MemoryService::recall_fused`]
2//! candidate pool, the layer that lifts a ranking miss (a relevant fact deep
3//! in the pool, below the fusion cutoff) into the final `k` — the lever
4//! validated on the LoCoMo ceiling diagnostic (multi-hop recall@8 = 50%,
5//! recall@64 = 89%: the gold fact is IN the pool, just outranked).
6//!
7//! Mirroring the [`crate::embedder`]/[`crate::extract`] pattern, the
8//! plug-point is dependency-free (bring your own cross-encoder or LLM by
9//! implementing [`Reranker`]) and never wired in by default: a reranker
10//! measurably helps ranking-bound corpora but can hurt on out-of-distribution
11//! conversational queries (the LoCoMo panel's own finding) — opt-in only,
12//! never a silent default.
13//!
14//! [`MemoryService::recall_fused`]: crate::service::MemoryService::recall_fused
15
16use crate::model::Recollection;
17
18/// Failure produced by a [`Reranker`] backend (e.g. a network-backed model
19/// that cannot be reached, or output that cannot be mapped back to
20/// candidates).
21#[derive(Debug, thiserror::Error)]
22pub enum RerankError {
23    /// The reranking backend (network, subprocess, …) returned an error.
24    #[error("rerank backend error: {0}")]
25    Backend(String),
26}
27
28/// Re-scores or reorders a fused candidate pool against `query`.
29///
30/// Implement this to plug in a cross-encoder, an LLM judge, or any other
31/// second-stage ranker, and pass it to
32/// [`MemoryService::recall_fused_reranked`](crate::service::MemoryService::recall_fused_reranked).
33/// A well-behaved implementation returns the same candidates (by id), just
34/// reordered or re-scored — it should not invent or drop ids.
35pub trait Reranker {
36    /// Re-score or reorder `candidates` for relevance to `query`.
37    ///
38    /// # Errors
39    /// Returns [`RerankError`] if the backend fails.
40    fn rerank(
41        &self,
42        query: &str,
43        candidates: Vec<Recollection>,
44    ) -> Result<Vec<Recollection>, RerankError>;
45}
46
47/// Forward [`Reranker`] through an [`Arc`](std::sync::Arc), so a shared `Arc<dyn Reranker>`
48/// (e.g. one held by the MCP server) satisfies the `R: Reranker` bound on
49/// [`crate::MemoryService::recall_fused_reranked`].
50impl<T: Reranker + ?Sized> Reranker for std::sync::Arc<T> {
51    fn rerank(
52        &self,
53        query: &str,
54        candidates: Vec<Recollection>,
55    ) -> Result<Vec<Recollection>, RerankError> {
56        (**self).rerank(query, candidates)
57    }
58}
59
60/// A boxed, object-safe reranker. Lets a non-generic caller (e.g. the Node
61/// binding, wrapping a JS callback) hold `Box<dyn Reranker + Send + Sync>`
62/// without threading a generic parameter through `MemoryService`.
63pub type DynReranker = Box<dyn Reranker + Send + Sync>;
64
65impl Reranker for DynReranker {
66    fn rerank(
67        &self,
68        query: &str,
69        candidates: Vec<Recollection>,
70    ) -> Result<Vec<Recollection>, RerankError> {
71        (**self).rerank(query, candidates)
72    }
73}
velesdb_memory/rerank.rs

velesdb_memory/
rerank.rs
