ruvector_core/
lib.rs

1//! # Ruvector Core
2//!
3//! High-performance Rust-native vector database with HNSW indexing and SIMD-optimized operations.
4//!
5//! ## Working Features (Tested & Benchmarked)
6//!
7//! - **HNSW Indexing**: Approximate nearest neighbor search with O(log n) complexity
8//! - **SIMD Distance**: SimSIMD-powered distance calculations (~16M ops/sec for 512-dim)
9//! - **Quantization**: Scalar (4x), Int4 (8x), Product (8-16x), and binary (32x) compression with distance support
10//! - **Persistence**: REDB-based storage with config persistence
11//! - **Search**: ~2.5K queries/sec on 10K vectors (benchmarked)
12//!
13//! ## ⚠️ Experimental/Incomplete Features - READ BEFORE USE
14//!
15//! - **AgenticDB**: ⚠️⚠️⚠️ **CRITICAL WARNING** ⚠️⚠️⚠️
16//!   - Uses PLACEHOLDER hash-based embeddings by default, NOT real semantic embeddings
17//!   - "dog" and "cat" will NOT be similar (different characters)
18//!   - "dog" and "god" WILL be similar (same characters) - **This is wrong!**
19//!   - **Use `OnnxEmbedding` for production** (feature: `onnx-embeddings`)
20//!   - See [`embeddings::OnnxEmbedding`] for real semantic embeddings
21//! - **Advanced Features**: Conformal prediction, hybrid search - functional but less tested
22//!
23//! ## What This Is NOT
24//!
25//! - This is NOT a complete RAG solution - you need external embedding models
26//! - Examples use mock embeddings for demonstration only
27
28#![allow(missing_docs)]
29#![allow(clippy::all)]
30#![allow(clippy::incompatible_msrv)]
31
32pub mod advanced_features;
33
34// AgenticDB requires storage feature
35#[cfg(feature = "storage")]
36pub mod agenticdb;
37
38pub mod distance;
39pub mod embeddings;
40pub mod error;
41pub mod index;
42pub mod quantization;
43
44// Storage backends - conditional compilation based on features
45#[cfg(feature = "storage")]
46pub mod storage;
47
48#[cfg(not(feature = "storage"))]
49pub mod storage_memory;
50
51#[cfg(not(feature = "storage"))]
52pub use storage_memory as storage;
53
54pub mod types;
55pub mod vector_db;
56
57// Performance optimization modules
58pub mod arena;
59pub mod cache_optimized;
60#[cfg(all(feature = "parallel", not(target_arch = "wasm32")))]
61pub mod lockfree;
62pub mod simd_intrinsics;
63
64/// Unified Memory Pool and Paging System (ADR-006)
65///
66/// High-performance paged memory management for LLM inference:
67/// - 2MB page-granular allocation with best-fit strategy
68/// - Reference-counted pinning with RAII guards
69/// - LRU eviction with hysteresis for thrash prevention
70/// - Multi-tenant isolation with Hot/Warm/Cold residency tiers
71pub mod memory;
72
73/// Advanced techniques: hypergraphs, learned indexes, neural hashing, TDA (Phase 6)
74pub mod advanced;
75
76/// Cross-integration helpers for the ruvnet crate ecosystem.
77///
78/// Provides [`integration::FannAdapter`] for ruv-FANN layer-embedding storage
79/// and [`integration::SemanticSearchAdapter`] for sparc semantic file search.
80pub mod integration;
81
82// Re-exports
83pub use advanced_features::{
84    fuse_rankings, ConformalConfig, ConformalPredictor, EnhancedPQ, FilterExpression,
85    FilterStrategy, FilteredSearch, FusionConfig, FusionStrategy, HybridConfig, HybridSearch,
86    MMRConfig, MMRSearch, PQConfig, PredictionSet, ScoredDoc, SparseIndex, SparseVector, BM25,
87};
88
89#[cfg(feature = "storage")]
90pub use agenticdb::{
91    AgenticDB, PolicyAction, PolicyEntry, PolicyMemoryStore, SessionStateIndex, SessionTurn,
92    WitnessEntry, WitnessLog,
93};
94
95#[cfg(feature = "api-embeddings")]
96pub use embeddings::ApiEmbedding;
97pub use embeddings::{BoxedEmbeddingProvider, EmbeddingProvider, HashEmbedding};
98
99#[cfg(feature = "real-embeddings")]
100pub use embeddings::CandleEmbedding;
101
102#[cfg(feature = "onnx-embeddings")]
103pub use embeddings::OnnxEmbedding;
104
105#[cfg(feature = "lattice-embeddings")]
106pub use embeddings::LatticeEmbedding;
107
108// Compile-time warning about AgenticDB limitations
109#[cfg(feature = "storage")]
110#[allow(deprecated, clippy::let_unit_value)]
111const _: () = {
112    #[deprecated(
113        since = "0.1.0",
114        note = "AgenticDB uses placeholder hash-based embeddings. For semantic search, use OnnxEmbedding (feature: onnx-embeddings) or ApiEmbedding. See ADR-114 for details."
115    )]
116    const AGENTICDB_EMBEDDING_WARNING: () = ();
117    let _ = AGENTICDB_EMBEDDING_WARNING;
118};
119
120pub use error::{Result, RuvectorError};
121pub use types::{DistanceMetric, SearchQuery, SearchResult, VectorEntry, VectorId};
122pub use vector_db::VectorDB;
123
124// Quantization types (ADR-001)
125pub use quantization::{
126    BinaryQuantized, Int4Quantized, ProductQuantized, QuantizedVector, ScalarQuantized,
127};
128
129// Memory management types (ADR-001)
130pub use arena::{Arena, ArenaVec, BatchVectorAllocator, CacheAlignedVec, CACHE_LINE_SIZE};
131
132// Lock-free structures (requires parallel feature)
133#[cfg(all(feature = "parallel", not(target_arch = "wasm32")))]
134pub use lockfree::{
135    AtomicVectorPool, BatchItem, BatchResult, LockFreeBatchProcessor, LockFreeCounter,
136    LockFreeStats, LockFreeWorkQueue, ObjectPool, PooledObject, PooledVector, StatsSnapshot,
137    VectorPoolStats,
138};
139
140// Cache-optimized storage
141pub use cache_optimized::SoAVectorStorage;
142
143#[cfg(test)]
144mod tests {
145    use super::*;
146
147    #[test]
148    fn test_version() {
149        // Verify version matches workspace - use dynamic check instead of hardcoded value
150        let version = env!("CARGO_PKG_VERSION");
151        assert!(!version.is_empty(), "Version should not be empty");
152        // Version 2.x is the current major version
153        assert!(
154            version.starts_with("2.") || version.starts_with("0.1."),
155            "Version should be 2.x or 0.1.x, got: {}",
156            version
157        );
158    }
159}
ruvector_core/lib.rs

ruvector_core/
lib.rs
