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