second_brain_core/retrieval/
raw_fallback.rs1use std::collections::HashSet;
2
3use anyhow::Result;
4
5use super::blend::ABSTAIN_RERANK_BAR;
6use super::rerank::RerankScorer;
7use super::rrf::{RRF_K, fuse};
8use crate::index::raw::{RawHit, RawIndex};
9
10const SEARCH_K: usize = 50;
11const RERANK_TOP: usize = 20;
12
13#[derive(Debug, Clone)]
14pub struct RawAnswer {
15 pub hit: RawHit,
16 pub relevance: f32,
18}
19
20pub fn raw_candidates(
24 index: &RawIndex,
25 query: &str,
26 query_embedding: &[f32],
27 project: Option<&str>,
28) -> Result<Vec<RawHit>> {
29 let dense: Vec<u64> = index
30 .vector_search(query_embedding, SEARCH_K, project)?
31 .into_iter()
32 .map(|(key, _)| key)
33 .collect();
34 let lexical: Vec<u64> = index
35 .bm25_search(query, SEARCH_K, project)?
36 .into_iter()
37 .map(|(key, _)| key)
38 .collect();
39 let mut hits = Vec::new();
40 for (key, _) in fuse(&[&dense, &lexical], RRF_K, RERANK_TOP) {
41 if let Some(hit) = index.passage(key)? {
42 hits.push(hit);
43 }
44 }
45 Ok(hits)
46}
47
48pub fn judge(
53 query: &str,
54 hits: Vec<RawHit>,
55 reranker: &dyn RerankScorer,
56) -> Result<Vec<RawAnswer>> {
57 if hits.is_empty() {
58 return Ok(Vec::new());
59 }
60 let texts: Vec<&str> = hits.iter().map(|h| h.text.as_str()).collect();
61 let scores = reranker.rerank(query, &texts)?;
62 if scores.len() != hits.len() {
63 anyhow::bail!(
64 "reranker returned {} scores for {} raw passages",
65 scores.len(),
66 hits.len()
67 );
68 }
69 let mut answers: Vec<RawAnswer> = hits
70 .into_iter()
71 .zip(scores)
72 .filter(|(_, score)| *score >= ABSTAIN_RERANK_BAR)
73 .map(|(hit, relevance)| RawAnswer { hit, relevance })
74 .collect();
75 answers.sort_by(|a, b| b.relevance.total_cmp(&a.relevance));
76 let mut seen = HashSet::new();
77 answers.retain(|a| seen.insert(a.hit.text.trim().to_string()));
78 Ok(answers)
79}
80
81#[cfg(test)]
82mod tests {
83 use super::*;
84 use crate::index::EMBEDDING_DIM;
85 use crate::index::raw::{RawOrigin, RawPassage};
86
87 fn raw_fallback(
88 index: &RawIndex,
89 query: &str,
90 query_embedding: &[f32],
91 project: Option<&str>,
92 reranker: &dyn RerankScorer,
93 limit: usize,
94 ) -> Result<Vec<RawAnswer>> {
95 let hits = raw_candidates(index, query, query_embedding, project)?;
96 let mut answers = judge(query, hits, reranker)?;
97 answers.truncate(limit);
98 Ok(answers)
99 }
100
101 struct TableScorer(Vec<(&'static str, f32)>);
102
103 impl RerankScorer for TableScorer {
104 fn rerank(&self, _: &str, docs: &[&str]) -> Result<Vec<f32>> {
105 Ok(docs
106 .iter()
107 .map(|d| {
108 self.0
109 .iter()
110 .find(|(key, _)| d.contains(key))
111 .map_or(0.0, |(_, score)| *score)
112 })
113 .collect())
114 }
115 }
116
117 fn unit(i: usize) -> Vec<f32> {
118 let mut v = vec![0.0; EMBEDDING_DIM];
119 v[i] = 1.0;
120 v
121 }
122
123 fn index_with(passages: &[(&str, Option<&str>, usize)]) -> (tempfile::TempDir, RawIndex) {
124 let dir = tempfile::tempdir().unwrap();
125 let mut index = RawIndex::open(dir.path()).unwrap();
126 let passages: Vec<_> = passages
127 .iter()
128 .map(|(text, project, axis)| {
129 (
130 RawPassage {
131 text: text.to_string(),
132 at: None,
133 project: project.map(str::to_string),
134 memory: None,
135 },
136 unit(*axis),
137 )
138 })
139 .collect();
140 index
141 .add_source(
142 &RawOrigin::Transcript {
143 sha256: "aa".to_string(),
144 },
145 &passages,
146 )
147 .unwrap();
148 index.commit().unwrap();
149 (dir, index)
150 }
151
152 #[test]
153 fn only_passages_the_cross_encoder_scores_at_the_bar_are_returned_best_first() {
154 let (_dir, index) = index_with(&[
155 ("the daemon port is 7200", None, 1),
156 ("the daemon port was discussed", None, 1),
157 ("the daemon runs on the pi", None, 1),
158 ]);
159 let scorer = TableScorer(vec![
160 ("is 7200", 0.9),
161 ("runs on the pi", ABSTAIN_RERANK_BAR + 0.01),
162 ("discussed", ABSTAIN_RERANK_BAR - 0.01),
163 ]);
164
165 let answers = raw_fallback(&index, "daemon port", &unit(1), None, &scorer, 5).unwrap();
166
167 let texts: Vec<&str> = answers.iter().map(|a| a.hit.text.as_str()).collect();
168 assert_eq!(
169 texts,
170 vec!["the daemon port is 7200", "the daemon runs on the pi"]
171 );
172 assert!((answers[0].relevance - 0.9).abs() < 1e-6);
173 }
174
175 #[test]
176 fn nothing_at_the_bar_is_an_empty_answer() {
177 let (_dir, index) = index_with(&[("lunch was soup", None, 1)]);
178 let scorer = TableScorer(vec![("soup", ABSTAIN_RERANK_BAR - 0.2)]);
179 let answers = raw_fallback(&index, "daemon port", &unit(1), None, &scorer, 5).unwrap();
180 assert!(answers.is_empty());
181 }
182
183 #[test]
184 fn a_project_keeps_the_fallback_inside_it() {
185 let (_dir, index) = index_with(&[
186 ("deploy uses argo in garden", Some("-srv-garden"), 1),
187 ("deploy uses argo in orchard", Some("-srv-orchard"), 1),
188 ]);
189 let scorer = TableScorer(vec![("deploy", 0.9)]);
190 let answers = raw_fallback(
191 &index,
192 "deploy argo",
193 &unit(1),
194 Some("-srv-orchard"),
195 &scorer,
196 5,
197 )
198 .unwrap();
199 assert_eq!(answers.len(), 1);
200 assert_eq!(answers[0].hit.project.as_deref(), Some("-srv-orchard"));
201 }
202
203 #[test]
204 fn an_empty_index_answers_nothing_without_calling_the_reranker() {
205 struct Refuses;
206 impl RerankScorer for Refuses {
207 fn rerank(&self, _: &str, _: &[&str]) -> Result<Vec<f32>> {
208 anyhow::bail!("must not be called")
209 }
210 }
211 let dir = tempfile::tempdir().unwrap();
212 let index = RawIndex::open(dir.path()).unwrap();
213 assert!(
214 raw_fallback(&index, "q", &unit(1), None, &Refuses, 5)
215 .unwrap()
216 .is_empty()
217 );
218 }
219
220 #[test]
221 fn a_reranker_that_drops_scores_is_an_error_not_a_shorter_answer() {
222 struct Short;
223 impl RerankScorer for Short {
224 fn rerank(&self, _: &str, _: &[&str]) -> Result<Vec<f32>> {
225 Ok(vec![0.99])
226 }
227 }
228 let (_dir, index) = index_with(&[("alpha fact one", None, 1), ("alpha fact two", None, 1)]);
229 let hits = raw_candidates(&index, "alpha fact", &unit(1), None).unwrap();
230 assert_eq!(hits.len(), 2);
231 assert!(judge("alpha fact", hits, &Short).is_err());
232 }
233
234 #[test]
235 fn the_limit_caps_the_answer() {
236 let (_dir, index) = index_with(&[
237 ("alpha fact one", None, 1),
238 ("alpha fact two", None, 2),
239 ("alpha fact three", None, 3),
240 ]);
241 let scorer = TableScorer(vec![("alpha", 0.9)]);
242 let answers = raw_fallback(&index, "alpha fact", &unit(1), None, &scorer, 2).unwrap();
243 assert_eq!(answers.len(), 2);
244 }
245}