feox_ann/lib.rs
1//! # FeOx ANN
2//!
3//! A small, dependency-free HNSW (Hierarchical Navigable Small World) index for
4//! approximate nearest neighbor search over cosine similarity.
5//!
6//! Part of the [FeOx](https://feoxdb.com) family. Pairs with
7//! [`feox-vector`](https://crates.io/crates/feox-vector) for a persistent,
8//! metadata-filtered vector store, or use it standalone as an in-memory index.
9//!
10//! ## Highlights
11//!
12//! - **Deterministic builds**: node levels are derived from a stable hash of the
13//! record id instead of a random number generator. The same records in the
14//! same order produce the same graph, so recall is reproducible, regressions
15//! are debuggable, and replicas that rebuild independently agree.
16//! - **SIMD distance kernels**: NEON on aarch64 and AVX2+FMA on x86_64 with
17//! runtime detection and a scalar fallback.
18//! - **Parallel bulk load**: [`AnnIndex::bulk_load`] runs candidate searches on
19//! worker threads against a frozen graph and applies results in fixed order.
20//! No locks, and the output does not depend on the thread count.
21//! - **Checksummed persistence**: [`AnnIndex::save_to`] / [`AnnIndex::load_from`]
22//! write a compact CRC32-verified binary snapshot. Corrupted files are
23//! rejected on load.
24//! - **Zero dependencies**: `thiserror` only.
25//! - **Filtered search**: pass any `Fn(&str) -> bool` (or an [`AnnFilter`]
26//! implementation) to restrict results at query time.
27//! - **Soft deletes and upserts**: deletes tombstone nodes without a rebuild.
28//! Upserts replace visible records in place.
29//! - **Scratch reuse**: [`AnnIndex::insert_cursor`] reuses search scratch space
30//! across sequential inserts. Queries use thread-local scratch and allocate
31//! nothing per call.
32//!
33//! Vectors are normalized on insert and scored with the dot product, so results
34//! rank by cosine similarity.
35//!
36//! ## Quick start
37//!
38//! ```
39//! use feox_ann::{AnnConfig, AnnIndex, AnnQuery};
40//!
41//! # fn main() -> feox_ann::Result<()> {
42//! let mut index = AnnIndex::new(AnnConfig::for_dimensions(2))?;
43//! index.upsert("north".to_string(), &[1.0, 0.0])?;
44//! index.upsert("east".to_string(), &[0.0, 1.0])?;
45//!
46//! let matches = index.query(AnnQuery {
47//! vector: &[0.9, 0.1],
48//! top_k: 1,
49//! ef_search: None,
50//! filter: None,
51//! })?;
52//! assert_eq!(matches[0].id, "north");
53//! # Ok(())
54//! # }
55//! ```
56//!
57//! ## Tuning
58//!
59//! [`AnnConfig::for_dimensions`] gives sensible defaults. The usual HNSW
60//! trade-offs apply:
61//!
62//! - `max_neighbors` / `max_base_neighbors`: graph degree. Raising it improves
63//! recall and costs memory and insert time.
64//! - `ef_construction`: candidate breadth during insert. Raising it improves
65//! graph quality and slows builds.
66//! - `ef_search`: candidate breadth during query. Raising it improves recall
67//! and adds latency. Can be set per query via [`AnnQuery::ef_search`].
68
69mod bulk;
70mod graph;
71mod index;
72mod insert;
73mod math;
74mod model;
75mod persist;
76mod query;
77
78pub use index::AnnIndex;
79pub use insert::AnnInsertCursor;
80pub use math::dot;
81pub use model::{AnnCandidate, AnnConfig, AnnError, AnnFilter, AnnQuery};
82
83pub type Result<T> = std::result::Result<T, AnnError>;
84
85#[cfg(test)]
86mod tests;