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 encoding;
41pub mod error;
42pub mod index;
43pub mod pdx;
44pub mod quantization;
45
46// Storage backends - conditional compilation based on features
47#[cfg(feature = "storage")]
48pub mod storage;
49
50pub mod storage_memory;
51
52#[cfg(not(feature = "storage"))]
53pub use storage_memory as storage;
54
55pub mod types;
56pub mod vector_db;
57
58// Performance optimization modules
59pub mod arena;
60pub mod cache_optimized;
61#[cfg(all(feature = "parallel", not(target_arch = "wasm32")))]
62pub mod lockfree;
63pub mod simd_intrinsics;
64
65/// Unified Memory Pool and Paging System (ADR-006)
66///
67/// High-performance paged memory management for LLM inference:
68/// - 2MB page-granular allocation with best-fit strategy
69/// - Reference-counted pinning with RAII guards
70/// - LRU eviction with hysteresis for thrash prevention
71/// - Multi-tenant isolation with Hot/Warm/Cold residency tiers
72pub mod memory;
73
74/// Advanced techniques: hypergraphs, learned indexes, neural hashing, TDA (Phase 6)
75pub mod advanced;
76
77/// Cross-integration helpers for the ruvnet crate ecosystem.
78///
79/// Provides [`integration::FannAdapter`] for ruv-FANN layer-embedding storage
80/// and [`integration::SemanticSearchAdapter`] for sparc semantic file search.
81pub mod integration;
82
83// Re-exports
84pub use advanced_features::{
85    fuse_rankings, ConformalConfig, ConformalPredictor, EnhancedPQ, FilterExpression,
86    FilterStrategy, FilteredSearch, FusionConfig, FusionStrategy, HybridConfig, HybridSearch,
87    MMRConfig, MMRSearch, PQConfig, PredictionSet, ScoredDoc, SparseIndex, SparseVector, BM25,
88};
89
90#[cfg(feature = "storage")]
91pub use agenticdb::{
92    AgenticDB, PolicyAction, PolicyEntry, PolicyMemoryStore, SessionStateIndex, SessionTurn,
93    WitnessEntry, WitnessLog,
94};
95
96#[cfg(feature = "api-embeddings")]
97pub use embeddings::ApiEmbedding;
98pub use embeddings::{
99    BoxedEmbeddingProvider, EmbeddingDistanceMetric, EmbeddingProvider, EmbeddingRole,
100    EmbeddingRolePolicy, EmbeddingSpaceIdentity, HashEmbedding, OutputDtype, PoolingStrategy,
101    PoolingStrategyName, PrefixPolicy,
102};
103
104#[cfg(feature = "real-embeddings")]
105pub use embeddings::CandleEmbedding;
106
107#[cfg(feature = "onnx-embeddings")]
108pub use embeddings::OnnxEmbedding;
109
110#[cfg(feature = "lattice-embeddings")]
111pub use embeddings::LatticeEmbedding;
112
113// Compile-time warning about AgenticDB limitations
114#[cfg(feature = "storage")]
115#[allow(deprecated, clippy::let_unit_value)]
116const _: () = {
117    #[deprecated(
118        since = "0.1.0",
119        note = "AgenticDB uses placeholder hash-based embeddings. For semantic search, use OnnxEmbedding (feature: onnx-embeddings) or ApiEmbedding. See ADR-114 for details."
120    )]
121    const AGENTICDB_EMBEDDING_WARNING: () = ();
122    let _ = AGENTICDB_EMBEDDING_WARNING;
123};
124
125pub use error::{Result, RuvectorError};
126pub use types::{DistanceMetric, SearchQuery, SearchResult, VectorEntry, VectorId};
127pub use vector_db::VectorDB;
128
129// Quantization types (ADR-001)
130pub use quantization::{
131    BinaryQuantized, Int4Quantized, ProductQuantized, QuantizedVector, ScalarQuantized,
132};
133
134// Memory management types (ADR-001)
135pub use arena::{Arena, ArenaVec, BatchVectorAllocator, CacheAlignedVec, CACHE_LINE_SIZE};
136
137// Lock-free structures (requires parallel feature)
138#[cfg(all(feature = "parallel", not(target_arch = "wasm32")))]
139pub use lockfree::{
140    AtomicVectorPool, BatchItem, BatchResult, LockFreeBatchProcessor, LockFreeCounter,
141    LockFreeStats, LockFreeWorkQueue, ObjectPool, PooledObject, PooledVector, StatsSnapshot,
142    VectorPoolStats,
143};
144
145// Cache-optimized storage
146pub use cache_optimized::SoAVectorStorage;
147
148#[cfg(test)]
149mod tests {
150    use super::*;
151
152    #[test]
153    fn test_version() {
154        // Verify version matches workspace - use dynamic check instead of hardcoded value
155        let version = env!("CARGO_PKG_VERSION");
156        assert!(!version.is_empty(), "Version should not be empty");
157        // Version 2.x is the current major version
158        assert!(
159            version.starts_with("2.") || version.starts_with("0.1."),
160            "Version should be 2.x or 0.1.x, got: {}",
161            version
162        );
163    }
164}
ruvector_core/lib.rs

ruvector_core/
lib.rs
