Skip to main content

graphrt_rag/
pipeline.rs

1//! The built-in retrieval pipeline: vector + keyword search, weighted merge,
2//! optional reranking, threshold and top-k.
3
4use std::collections::HashMap;
5use std::sync::Arc;
6
7use futures::future::BoxFuture;
8
9use crate::error::RagError;
10use crate::types::{Embedder, Hit, KeywordQuery, Reranker, RetrievalRequest, Retriever, VectorQuery, VectorStore};
11
12/// How many candidates each search returns before merging (multiple of `top_k`).
13const CANDIDATE_FACTOR: usize = 4;
14const MIN_CANDIDATES: usize = 20;
15/// With a metadata filter, stores may apply only part of it before ranking; fetch
16/// more candidates so the post-filter still has enough to choose from.
17const FILTERED_CANDIDATE_FACTOR: usize = 20;
18const MAX_CANDIDATES: usize = 1_000;
19
20/// A [`Retriever`] over a [`VectorStore`] + [`Embedder`] (+ optional [`Reranker`]).
21#[derive(Clone, Debug)]
22pub struct StoreRetriever {
23    store: Arc<dyn VectorStore>,
24    embedder: Arc<dyn Embedder>,
25    reranker: Option<Arc<dyn Reranker>>,
26}
27
28impl StoreRetriever {
29    pub fn new(store: Arc<dyn VectorStore>, embedder: Arc<dyn Embedder>) -> Self {
30        Self { store, embedder, reranker: None }
31    }
32
33    pub fn with_reranker(mut self, reranker: Option<Arc<dyn Reranker>>) -> Self {
34        self.reranker = reranker;
35        self
36    }
37
38    pub fn store(&self) -> &Arc<dyn VectorStore> {
39        &self.store
40    }
41
42    pub fn embedder(&self) -> &Arc<dyn Embedder> {
43        &self.embedder
44    }
45}
46
47impl Retriever for StoreRetriever {
48    fn retrieve<'a>(&'a self, request: &'a RetrievalRequest) -> BoxFuture<'a, Result<Vec<Hit>, RagError>> {
49        Box::pin(async move {
50            let query = request.query.trim();
51            if query.is_empty() || request.top_k == 0 {
52                return Ok(Vec::new());
53            }
54            let factor = if request.filter.is_some() { FILTERED_CANDIDATE_FACTOR } else { CANDIDATE_FACTOR };
55            let candidates =
56                request.top_k.saturating_mul(factor).max(MIN_CANDIDATES).min(MAX_CANDIDATES.max(request.top_k));
57            let weights = request.weights;
58            if weights.keyword > 0.0 && !self.store.supports_keyword() {
59                return Err(RagError::Config(
60                    "keyword (hybrid) weight requested, but this dataset's store has no keyword index".into(),
61                ));
62            }
63            if request.rerank && self.reranker.is_none() {
64                return Err(RagError::Config(
65                    "reranking requested, but this dataset has no reranker configured".into(),
66                ));
67            }
68            let use_keyword = weights.keyword > 0.0;
69            let use_vector = weights.vector > 0.0 || !use_keyword;
70
71            let vector_hits = if use_vector {
72                let vector = self.embedder.embed_query(query).await?;
73                self.store
74                    .search(VectorQuery {
75                        datasets: &request.datasets,
76                        vector: &vector,
77                        top_k: candidates,
78                        filter: request.filter.as_ref(),
79                    })
80                    .await?
81            } else {
82                Vec::new()
83            };
84            let keyword_hits = if use_keyword {
85                self.store
86                    .keyword_search(KeywordQuery {
87                        datasets: &request.datasets,
88                        text: query,
89                        top_k: candidates,
90                        filter: request.filter.as_ref(),
91                    })
92                    .await?
93            } else {
94                Vec::new()
95            };
96
97            let mut hits = if use_keyword {
98                let vector_weight = if use_vector { weights.vector } else { 0.0 };
99                merge_weighted(vector_hits, keyword_hits, vector_weight, weights.keyword)
100            } else {
101                vector_hits
102            };
103            // Stores may push filters down partially; enforce them fully here.
104            if let Some(filter) = &request.filter {
105                hits.retain(|h| filter.matches(&h.metadata));
106            }
107            if let (true, Some(reranker)) = (request.rerank, &self.reranker) {
108                hits = rerank(reranker.as_ref(), query, hits).await?;
109            }
110            Ok(finalize(hits, request.score_threshold, request.top_k))
111        })
112    }
113}
114
115/// Blend vector (cosine, clamped to `[0, 1]`) and keyword (BM25 divided by the
116/// best BM25 score) scores by id: `score = wv * vector + wk * keyword`, with weights
117/// normalized to sum to 1. Missing components count as 0.
118pub fn merge_weighted(vector: Vec<Hit>, keyword: Vec<Hit>, vector_weight: f32, keyword_weight: f32) -> Vec<Hit> {
119    let total = (vector_weight + keyword_weight).max(f32::EPSILON);
120    let (wv, wk) = (vector_weight / total, keyword_weight / total);
121    let max_kw = keyword.iter().map(|h| h.score).fold(0.0f32, f32::max);
122
123    let mut merged: Vec<Hit> = Vec::with_capacity(vector.len() + keyword.len());
124    let mut index: HashMap<String, usize> = HashMap::new();
125    for mut hit in vector {
126        hit.score = wv * hit.score.clamp(0.0, 1.0);
127        index.insert(hit.id.clone(), merged.len());
128        merged.push(hit);
129    }
130    for mut hit in keyword {
131        let normalized = if max_kw > 0.0 { hit.score / max_kw } else { 0.0 };
132        match index.get(&hit.id).and_then(|&ix| merged.get_mut(ix)) {
133            Some(existing) => existing.score += wk * normalized,
134            None => {
135                hit.score = wk * normalized;
136                index.insert(hit.id.clone(), merged.len());
137                merged.push(hit);
138            }
139        }
140    }
141    merged.sort_by(|a, b| b.score.total_cmp(&a.score));
142    merged
143}
144
145/// Replace scores with reranker scores and re-sort.
146pub async fn rerank(reranker: &dyn Reranker, query: &str, mut hits: Vec<Hit>) -> Result<Vec<Hit>, RagError> {
147    if hits.is_empty() {
148        return Ok(hits);
149    }
150    let docs: Vec<String> = hits.iter().map(|h| h.content.clone()).collect();
151    let scores = reranker.rerank(query, &docs).await?;
152    if scores.len() != hits.len() {
153        return Err(RagError::Decode(format!(
154            "reranker returned {} scores for {} documents",
155            scores.len(),
156            hits.len()
157        )));
158    }
159    for (hit, score) in hits.iter_mut().zip(scores) {
160        if !score.is_finite() {
161            return Err(RagError::Decode("reranker returned a non-finite score".into()));
162        }
163        hit.score = score;
164    }
165    hits.sort_by(|a, b| b.score.total_cmp(&a.score));
166    Ok(hits)
167}
168
169/// Apply the score threshold, then keep the best `top_k`.
170pub fn finalize(mut hits: Vec<Hit>, threshold: Option<f32>, top_k: usize) -> Vec<Hit> {
171    // A NaN would sort first with `total_cmp`; such scores carry no ranking information.
172    hits.retain(|h| h.score.is_finite());
173    if let Some(t) = threshold {
174        hits.retain(|h| h.score >= t);
175    }
176    hits.sort_by(|a, b| b.score.total_cmp(&a.score));
177    hits.truncate(top_k);
178    hits
179}
180
181#[cfg(test)]
182mod tests {
183    use super::*;
184
185    fn hit(id: &str, score: f32) -> Hit {
186        Hit {
187            id: id.into(),
188            dataset_id: "d".into(),
189            document_id: String::new(),
190            title: String::new(),
191            content: id.into(),
192            score,
193            metadata: serde_json::Map::new(),
194        }
195    }
196
197    #[test]
198    fn weighted_merge_combines_by_id() {
199        let vector = vec![hit("a", 0.9), hit("b", 0.5)];
200        let keyword = vec![hit("b", 10.0), hit("c", 5.0)];
201        let merged = merge_weighted(vector, keyword, 0.5, 0.5);
202        let ids: Vec<&str> = merged.iter().map(|h| h.id.as_str()).collect();
203        assert_eq!(ids, vec!["b", "a", "c"]);
204        assert!((merged[0].score - 0.75).abs() < 1e-6);
205        assert!((merged[1].score - 0.45).abs() < 1e-6);
206        assert!((merged[2].score - 0.25).abs() < 1e-6);
207    }
208
209    #[test]
210    fn finalize_thresholds_and_truncates() {
211        let out = finalize(vec![hit("a", 0.2), hit("b", 0.8), hit("c", 0.5)], Some(0.4), 1);
212        assert_eq!(out.len(), 1);
213        assert_eq!(out[0].id, "b");
214    }
215}