feox-ann 0.1.0

Dependency-free HNSW approximate nearest neighbor index with deterministic, reproducible builds
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

//! # FeOx ANN
//!
//! A small, dependency-free HNSW (Hierarchical Navigable Small World) index for
//! approximate nearest neighbor search over cosine similarity.
//!
//! Part of the [FeOx](https://feoxdb.com) family. Pairs with
//! [`feox-vector`](https://crates.io/crates/feox-vector) for a persistent,
//! metadata-filtered vector store, or use it standalone as an in-memory index.
//!
//! ## Highlights
//!
//! - **Deterministic builds**: node levels are derived from a stable hash of the
//!   record id instead of a random number generator. The same records in the
//!   same order produce the same graph, so recall is reproducible, regressions
//!   are debuggable, and replicas that rebuild independently agree.
//! - **SIMD distance kernels**: NEON on aarch64 and AVX2+FMA on x86_64 with
//!   runtime detection and a scalar fallback.
//! - **Parallel bulk load**: [`AnnIndex::bulk_load`] runs candidate searches on
//!   worker threads against a frozen graph and applies results in fixed order.
//!   No locks, and the output does not depend on the thread count.
//! - **Checksummed persistence**: [`AnnIndex::save_to`] / [`AnnIndex::load_from`]
//!   write a compact CRC32-verified binary snapshot. Corrupted files are
//!   rejected on load.
//! - **Zero dependencies**: `thiserror` only.
//! - **Filtered search**: pass any `Fn(&str) -> bool` (or an [`AnnFilter`]
//!   implementation) to restrict results at query time.
//! - **Soft deletes and upserts**: deletes tombstone nodes without a rebuild.
//!   Upserts replace visible records in place.
//! - **Scratch reuse**: [`AnnIndex::insert_cursor`] reuses search scratch space
//!   across sequential inserts. Queries use thread-local scratch and allocate
//!   nothing per call.
//!
//! Vectors are normalized on insert and scored with the dot product, so results
//! rank by cosine similarity.
//!
//! ## Quick start
//!
//! ```
//! use feox_ann::{AnnConfig, AnnIndex, AnnQuery};
//!
//! # fn main() -> feox_ann::Result<()> {
//! let mut index = AnnIndex::new(AnnConfig::for_dimensions(2))?;
//! index.upsert("north".to_string(), &[1.0, 0.0])?;
//! index.upsert("east".to_string(), &[0.0, 1.0])?;
//!
//! let matches = index.query(AnnQuery {
//!     vector: &[0.9, 0.1],
//!     top_k: 1,
//!     ef_search: None,
//!     filter: None,
//! })?;
//! assert_eq!(matches[0].id, "north");
//! # Ok(())
//! # }
//! ```
//!
//! ## Tuning
//!
//! [`AnnConfig::for_dimensions`] gives sensible defaults. The usual HNSW
//! trade-offs apply:
//!
//! - `max_neighbors` / `max_base_neighbors`: graph degree. Raising it improves
//!   recall and costs memory and insert time.
//! - `ef_construction`: candidate breadth during insert. Raising it improves
//!   graph quality and slows builds.
//! - `ef_search`: candidate breadth during query. Raising it improves recall
//!   and adds latency. Can be set per query via [`AnnQuery::ef_search`].

mod bulk;
mod graph;
mod index;
mod insert;
mod math;
mod model;
mod persist;
mod query;

pub use index::AnnIndex;
pub use insert::AnnInsertCursor;
pub use math::dot;
pub use model::{AnnCandidate, AnnConfig, AnnError, AnnFilter, AnnQuery};

pub type Result<T> = std::result::Result<T, AnnError>;

#[cfg(test)]
mod tests;