edgevec/
lib.rs

1//! # EdgeVec
2//!
3//! High-performance embedded vector database for Browser, Node, and Edge.
4//!
5//! ## Current Status
6//!
7//! **PHASE 3: Implementation (Week 7 Complete)**
8//!
9//! **Status:** Week 7 Complete — Persistence Hardened
10//!
11//! Core vector storage, HNSW graph indexing, and full durability (WAL + Snapshots) are implemented and verified.
12//!
13//! ## Implemented Features
14//!
15//! - **HNSW Graph**: Full insertion and search implementation with heuristic optimization.
16//! - **Vector Storage**: Contiguous memory layout for fast access.
17//! - **Scalar Quantization (SQ8)**: 4x memory reduction (f32 -> u8) with high accuracy.
18//! - **Durability**: Write-Ahead Log (WAL) with CRC32 checksums, crash recovery, and atomic snapshots.
19//! - **Metrics**: L2 (Euclidean), Cosine, and Dot Product distance functions.
20//!
21//! ## Development Protocol
22//!
23//! `EdgeVec` follows a military-grade development protocol:
24//!
25//! 1. **Architecture Phase** — Design docs must be approved before planning
26//! 2. **Planning Phase** — Roadmap must be approved before coding
27//! 3. **Implementation Phase** — Weekly tasks must be approved before coding
28//! 4. **All gates require `HOSTILE_REVIEWER` approval**
29//!
30//! ## Example
31//!
32//! ```rust
33//! use edgevec::{HnswConfig, HnswIndex, Metric, VectorStorage};
34//!
35//! // 1. Create Config
36//! let config = HnswConfig::new(128);
37//!
38//! // 2. Initialize Storage and Index
39//! let mut storage = VectorStorage::new(&config, None);
40//! let mut index = HnswIndex::new(config, &storage).expect("failed to create index");
41//!
42//! // 3. Insert Vectors
43//! let vector = vec![0.5; 128];
44//! let id = index.insert(&vector, &mut storage).expect("failed to insert");
45//!
46//! // 4. Search
47//! let query = vec![0.5; 128];
48//! let results = index.search(&query, 10, &storage).expect("failed to search");
49//!
50//! assert!(!results.is_empty());
51//! assert_eq!(results[0].vector_id, id);
52//! ```
53//!
54//! ## Persistence Example
55//!
56//! ```rust,no_run
57//! use edgevec::{HnswConfig, HnswIndex, VectorStorage};
58//! use edgevec::persistence::{write_snapshot, read_snapshot, MemoryBackend};
59//!
60//! // Create index and storage
61//! let config = HnswConfig::new(128);
62//! let mut storage = VectorStorage::new(&config, None);
63//! let mut index = HnswIndex::new(config, &storage).expect("failed to create");
64//!
65//! // Save snapshot using storage backend
66//! let mut backend = MemoryBackend::new();
67//! write_snapshot(&index, &storage, &mut backend).expect("failed to save");
68//!
69//! // Load snapshot
70//! let (loaded_index, loaded_storage) = read_snapshot(&backend).expect("failed to load");
71//! ```
72//!
73//! ## Next Steps (Phase 5)
74//!
75//! 1. **Documentation**: Finalize API docs.
76//! 2. **NPM Package**: Release to npm registry.
77//! 3. **Performance**: Final tuning and benchmarks.
78//!
79//! ## Documentation
80//!
81//! - [Genesis Workflow](docs/GENESIS_WORKFLOW.md)
82//! - [Agent Commands](.cursor/commands/README.md)
83//! - [Supreme Rules](.cursorrules)
84
85#![doc = include_str!("../README.md")]
86#![deny(missing_docs)]
87#![deny(clippy::all)]
88#![warn(clippy::pedantic)]
89#![allow(clippy::module_name_repetitions)]
90#![allow(clippy::doc_markdown)]
91#![allow(clippy::pub_underscore_fields)]
92#![allow(clippy::too_many_lines)]
93
94/// Persistence and file format definitions.
95pub mod persistence;
96
97/// Unified error handling.
98pub mod error;
99
100/// Batch insertion API.
101pub mod batch;
102
103/// HNSW Graph implementation.
104pub mod hnsw;
105
106/// Distance metrics.
107pub mod metric;
108
109/// Vector storage.
110pub mod storage;
111
112/// WASM bindings.
113pub mod wasm;
114
115/// Quantization support.
116pub mod quantization;
117
118/// SIMD capability detection and runtime optimization.
119pub mod simd;
120
121pub use batch::BatchInsertable;
122pub use error::BatchError;
123pub use hnsw::{BatchDeleteError, BatchDeleteResult, HnswConfig, HnswIndex, SearchResult};
124pub use metric::Metric;
125pub use persistence::ChunkedWriter;
126pub use quantization::{BinaryQuantizer, QuantizedVector, QuantizerConfig, ScalarQuantizer};
127pub use simd::{capabilities, warn_if_suboptimal, SimdCapabilities};
128pub use storage::VectorStorage;
129
130/// The crate version string.
131pub const VERSION: &str = env!("CARGO_PKG_VERSION");
132
133/// Returns the crate version string.
134///
135/// # Returns
136///
137/// The crate version string.
138///
139/// # Example
140///
141/// ```rust
142/// let version = edgevec::version();
143/// assert!(!version.is_empty());
144/// ```
145#[must_use]
146pub fn version() -> &'static str {
147    VERSION
148}
149
150#[cfg(test)]
151mod tests {
152    use super::*;
153
154    #[test]
155    fn test_version_not_empty() {
156        assert!(!version().is_empty());
157    }
158}
edgevec/lib.rs

edgevec/
lib.rs
