1use 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
15const CANDIDATE_FACTOR: usize = 4;
17const MIN_CANDIDATES: usize = 20;
18const FILTERED_CANDIDATE_FACTOR: usize = 20;
21const MAX_CANDIDATES: usize = 1_000;
22
23#[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 if let Some(filter) = &request.filter {
108 hits.retain(|h| filter.matches(&h.metadata));
109 }
110 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
120async 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 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
167pub 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
197pub 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
221pub fn finalize(mut hits: Vec<Hit>, threshold: Option<f32>, top_k: usize) -> Vec<Hit> {
223 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}