Skip to main content

second_brain_core/retrieval/
raw_fallback.rs

1use 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    /// The cross-encoder score the passage was admitted on.
17    pub relevance: f32,
18}
19
20/// The fused vector and BM25 candidates for `query`, at most twenty, for
21/// `judge` to score. Split from judging so a caller can release the index
22/// before the cross-encoder runs.
23pub 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
48/// The candidates the cross-encoder scores at `ABSTAIN_RERANK_BAR` or above,
49/// best first and one per text, so an empty answer stays empty for a
50/// question nothing stored can answer. Not truncated: the caller filters
51/// first, then applies its limit.
52pub 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}