1use 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
12const CANDIDATE_FACTOR: usize = 4;
14const MIN_CANDIDATES: usize = 20;
15const FILTERED_CANDIDATE_FACTOR: usize = 20;
18const MAX_CANDIDATES: usize = 1_000;
19
20#[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 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
115pub 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
145pub 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
169pub fn finalize(mut hits: Vec<Hit>, threshold: Option<f32>, top_k: usize) -> Vec<Hit> {
171 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}