coding_agent_search/search/
ann_index.rs

1//! Approximate nearest-neighbor (ANN) reporting types.
2//!
3//! cass uses frankensearch's HNSW implementation for approximate semantic search.
4//! This module intentionally stays small: it defines the stats payload surfaced
5//! in robot output and TUI diagnostics.
6
7use std::path::{Path, PathBuf};
8
9use crate::search::vector_index::VECTOR_INDEX_DIR;
10
11/// Statistics from an ANN search operation.
12///
13/// These metrics help users understand the quality/speed tradeoff of approximate search.
14#[derive(Debug, Clone, Default, serde::Serialize)]
15pub struct AnnSearchStats {
16    /// Total vectors in the HNSW index.
17    pub index_size: usize,
18    /// Dimension of vectors.
19    pub dimension: usize,
20    /// ef parameter used for this search (higher = more accurate but slower).
21    pub ef_search: usize,
22    /// Number of results requested (k).
23    pub k_requested: usize,
24    /// Number of results returned.
25    pub k_returned: usize,
26    /// Search time in microseconds.
27    pub search_time_us: u64,
28    /// Estimated recall based on ef/k ratio.
29    ///
30    /// Formula: min(1.0, 0.9 + 0.1 * log2(ef / k))
31    /// This is an empirical estimate; actual recall depends on data distribution.
32    pub estimated_recall: f32,
33    /// Whether this was an approximate (HNSW) or exact search.
34    pub is_approximate: bool,
35}
36
37/// Default on-disk location for the HNSW index for a given embedder.
38#[must_use]
39pub fn hnsw_index_path(data_dir: &Path, embedder_id: &str) -> PathBuf {
40    data_dir
41        .join(VECTOR_INDEX_DIR)
42        .join(format!("hnsw-{embedder_id}.chsw"))
43}
44
45#[cfg(test)]
46mod tests {
47    use super::*;
48
49    #[test]
50    fn hnsw_index_path_uses_expected_layout() {
51        let p = hnsw_index_path(Path::new("/tmp/cass"), "minilm-384");
52        assert!(p.ends_with("vector_index/hnsw-minilm-384.chsw"));
53    }
54}
coding_agent_search/search/ann_index.rs

coding_agent_search/search/
ann_index.rs
