superbit/lib.rs
1//! # superbit
2//!
3//! A lightweight, in-memory vector index for approximate nearest-neighbor (ANN)
4//! search using Locality-Sensitive Hashing (LSH).
5//!
6//! Designed for prototyping ML applications such as retrieval-augmented
7//! generation (RAG) or recommendation systems, without the overhead of a full
8//! vector database.
9//!
10//! ## Quick start
11//!
12//! ```rust
13//! use superbit::{LshIndex, DistanceMetric};
14//!
15//! let index = LshIndex::builder()
16//! .dim(128)
17//! .num_hashes(8)
18//! .num_tables(16)
19//! .distance_metric(DistanceMetric::Cosine)
20//! .seed(42)
21//! .build()
22//! .unwrap();
23//!
24//! // Insert a vector.
25//! let v = vec![0.1_f32; 128];
26//! index.insert(0, &v).unwrap();
27//!
28//! // Query for similar vectors.
29//! let results = index.query(&v, 5).unwrap();
30//! for r in &results {
31//! println!("id={} dist={:.4}", r.id, r.distance);
32//! }
33//! ```
34//!
35//! ## Feature flags
36//!
37//! | Flag | Effect |
38//! |---------------|----------------------------------------------|
39//! | `parallel` | Parallel bulk insert/query via rayon |
40//! | `persistence` | Save/load index to disk (serde + bincode) |
41//! | `python` | Python bindings via PyO3 |
42//! | `full` | Enables `parallel` + `persistence` |
43
44pub mod distance;
45pub mod error;
46pub mod hash;
47pub mod index;
48pub mod metrics;
49pub mod tuning;
50
51#[cfg(feature = "persistence")]
52pub mod persistence;
53
54#[cfg(feature = "python")]
55pub mod python;
56
57// Re-exports for convenience.
58pub use distance::DistanceMetric;
59pub use error::{LshError, Result};
60pub use index::{IndexConfig, IndexStats, LshIndex, LshIndexBuilder, QueryResult};
61pub use metrics::{MetricsCollector, MetricsSnapshot};
62pub use tuning::{estimate_recall, suggest_params, SuggestedParams};