vector_index/lib.rs
1//! # vector-index
2//!
3//! Generic HNSW (Hierarchical Navigable Small World) index with pluggable
4//! distance metrics.
5//!
6//! This crate provides the *index structure* and a *metric trait*. It does
7//! not bundle exotic metrics — implement [`Metric`] for your own type, or
8//! use a companion crate (e.g. `sliced-wasserstein`) that already does.
9//!
10//! ## Quickstart
11//!
12//! ```
13//! use vector_index::{HnswIndex, HnswConfig, metric::L2};
14//!
15//! let mut index = HnswIndex::<Vec<f32>, L2>::new(HnswConfig::default(), L2).expect("default config is valid");
16//! index.insert(0, vec![1.0, 0.0, 0.0]).unwrap();
17//! index.insert(1, vec![0.0, 1.0, 0.0]).unwrap();
18//! index.insert(2, vec![1.0, 1.0, 0.0]).unwrap();
19//!
20//! let neighbors = index.search(&vec![1.0, 0.1, 0.0], 2);
21//! assert_eq!(neighbors[0].id, 0); // closest point
22//! ```
23//!
24//! ## Concurrency
25//!
26//! [`HnswIndex`] is not internally synchronized; wrap it in
27//! [`ConcurrentHnsw`](concurrent::ConcurrentHnsw) for the
28//! `Arc<RwLock<_>>` pattern with append-mostly write semantics.
29
30#![cfg_attr(not(feature = "std"), no_std)]
31#![warn(missing_docs)]
32#![warn(clippy::all)]
33// pedantic re-enabled when implementation matures.
34#![allow(clippy::module_name_repetitions)]
35
36extern crate alloc;
37
38pub mod concurrent;
39pub mod error;
40pub mod hnsw;
41pub mod metric;
42
43pub use error::{IndexError, IndexResult};
44pub use hnsw::{HnswConfig, HnswIndex, Neighbor};
45pub use metric::Metric;
46
47/// Stable identifier for a point in the index.
48///
49/// Chosen as `u64` rather than `usize` so that on-disk index serialization
50/// is portable across 32-bit and 64-bit targets, and so the ID space is
51/// large enough for write-heavy workloads where IDs are never reused.
52pub type PointId = u64;