bifrost/lib.rs
1//! Compact Hierarchical Navigable Small World (HNSW) index for unit `f32` vectors.
2//!
3//! The crates.io package is `bifrost-index`. The library crate path is `bifrost`,
4//! so callers and doctests import `bifrost::{Config, HnswIndex, ...}`.
5//!
6//! # Overview
7//!
8//! [`HnswIndex`] builds a graph by incremental [`HnswIndex::insert`] (or a
9//! one-shot [`HnswIndex::build`] on an empty index). [`HnswIndex::search`]
10//! returns approximate nearest neighbors under cosine distance. Construction
11//! parameters such as [`Config::m`] and [`Config::dim`] are fixed at
12//! [`HnswIndex::new`]. Query width is `max(ef_search, k)` on both
13//! [`HnswIndex::search`] and [`LoadedHnsw::search`]; [`HnswIndex::search_with_ef`]
14//! and [`LoadedHnsw::search_with_ef`] override the stored candidate width for
15//! one query.
16//!
17//! # Distance contract
18//!
19//! Insert and search treat vectors as unit-normalized `f32`. Cosine distance
20//! is `1 - dot` and does not renormalize. Public [`vector::dot`],
21//! [`vector::cosine_distance`], and [`vector::cosine_similarity`] return
22//! [`Error::DimensionMismatch`] when the arguments have different lengths.
23//! Insert and search `debug_assert` finite, near-unit vectors;
24//! [`Config::check_vectors`] returns [`Error::InvalidVector`] for the same
25//! failures.
26//!
27//! # Persistence
28//!
29//! [`HnswIndex::save`] writes a `.hnsw` v3 snapshot (temp + `sync_all` +
30//! `rename`). [`load_file`] / [`LoadedHnsw::open`] map that file and
31//! [`LoadedHnsw::search`] walks it in place. Valid v2 files are rewritten to
32//! v3 on load. Do not mutate a mapped file while [`LoadedHnsw`] lives.
33//!
34//! # Limits
35//!
36//! There is no delete, update, filter, quantization, or concurrent-mutation
37//! API. [`HnswIndex::build`] assigns IDs `0..n-1` and is a convenience for an
38//! empty index; a second `build` or any colliding ID returns
39//! [`Error::DuplicateExternalId`].
40//!
41//! # Examples
42//!
43//! ```
44//! use bifrost::{load_file, Config, HnswIndex};
45//!
46//! let mut index = HnswIndex::new(Config {
47//! dim: 4,
48//! rng_seed: Some(42),
49//! ..Config::default()
50//! })?;
51//! index.insert(100, &[1.0, 0.0, 0.0, 0.0])?;
52//! index.insert(200, &[0.0, 1.0, 0.0, 0.0])?;
53//! let hits = index.search(&[1.0, 0.0, 0.0, 0.0], 10)?;
54//! assert_eq!(hits[0].id, 100);
55//!
56//! let path = std::env::temp_dir().join(format!(
57//! "bifrost-overview-{}.hnsw",
58//! std::process::id()
59//! ));
60//! index.save(&path)?;
61//! let loaded = load_file(&path)?;
62//! assert_eq!(loaded.search(&[1.0, 0.0, 0.0, 0.0], 1)?[0].id, 100);
63//! # let _ = std::fs::remove_file(&path);
64//! # Ok::<(), bifrost::Error>(())
65//! ```
66
67#![forbid(unsafe_op_in_unsafe_fn)]
68
69mod config;
70mod error;
71mod graph;
72mod index;
73mod layer;
74pub mod serialize;
75pub mod vector;
76
77pub use config::Config;
78pub use error::{Error, Result};
79pub use graph::{ExternalId, Graph, NodeIndex, NodeMeta};
80pub use index::{HnswIndex, SearchHit};
81pub use serialize::{
82 HEADER_SIZE, Header, LoadedHnsw, MAGIC, MIGRATABLE_VERSION, NODE_META_SIZE, VERSION, load_file,
83 save_file,
84};