ruvector-core 2.2.0

High-performance Rust vector database core with HNSW indexing
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

//! # Ruvector Core
//!
//! High-performance Rust-native vector database with HNSW indexing and SIMD-optimized operations.
//!
//! ## Working Features (Tested & Benchmarked)
//!
//! - **HNSW Indexing**: Approximate nearest neighbor search with O(log n) complexity
//! - **SIMD Distance**: SimSIMD-powered distance calculations (~16M ops/sec for 512-dim)
//! - **Quantization**: Scalar (4x), Int4 (8x), Product (8-16x), and binary (32x) compression with distance support
//! - **Persistence**: REDB-based storage with config persistence
//! - **Search**: ~2.5K queries/sec on 10K vectors (benchmarked)
//!
//! ## ⚠️ Experimental/Incomplete Features - READ BEFORE USE
//!
//! - **AgenticDB**: ⚠️⚠️⚠️ **CRITICAL WARNING** ⚠️⚠️⚠️
//!   - Uses PLACEHOLDER hash-based embeddings by default, NOT real semantic embeddings
//!   - "dog" and "cat" will NOT be similar (different characters)
//!   - "dog" and "god" WILL be similar (same characters) - **This is wrong!**
//!   - **Use `OnnxEmbedding` for production** (feature: `onnx-embeddings`)
//!   - See [`embeddings::OnnxEmbedding`] for real semantic embeddings
//! - **Advanced Features**: Conformal prediction, hybrid search - functional but less tested
//!
//! ## What This Is NOT
//!
//! - This is NOT a complete RAG solution - you need external embedding models
//! - Examples use mock embeddings for demonstration only

#![allow(missing_docs)]
#![warn(clippy::all)]
#![allow(clippy::incompatible_msrv)]

pub mod advanced_features;

// AgenticDB requires storage feature
#[cfg(feature = "storage")]
pub mod agenticdb;

pub mod distance;
pub mod embeddings;
pub mod error;
pub mod index;
pub mod quantization;

// Storage backends - conditional compilation based on features
#[cfg(feature = "storage")]
pub mod storage;

#[cfg(not(feature = "storage"))]
pub mod storage_memory;

#[cfg(not(feature = "storage"))]
pub use storage_memory as storage;

pub mod types;
pub mod vector_db;

// Performance optimization modules
pub mod arena;
pub mod cache_optimized;
#[cfg(all(feature = "parallel", not(target_arch = "wasm32")))]
pub mod lockfree;
pub mod simd_intrinsics;

/// Unified Memory Pool and Paging System (ADR-006)
///
/// High-performance paged memory management for LLM inference:
/// - 2MB page-granular allocation with best-fit strategy
/// - Reference-counted pinning with RAII guards
/// - LRU eviction with hysteresis for thrash prevention
/// - Multi-tenant isolation with Hot/Warm/Cold residency tiers
pub mod memory;

/// Advanced techniques: hypergraphs, learned indexes, neural hashing, TDA (Phase 6)
pub mod advanced;

// Re-exports
pub use advanced_features::{
    ConformalConfig, ConformalPredictor, EnhancedPQ, FilterExpression, FilterStrategy,
    FilteredSearch, FusionConfig, FusionStrategy, HybridConfig, HybridSearch, MMRConfig,
    MMRSearch, PQConfig, PredictionSet, ScoredDoc, SparseIndex, SparseVector, BM25,
    fuse_rankings,
};

#[cfg(feature = "storage")]
pub use agenticdb::{
    AgenticDB, PolicyAction, PolicyEntry, PolicyMemoryStore, SessionStateIndex, SessionTurn,
    WitnessEntry, WitnessLog,
};

#[cfg(feature = "api-embeddings")]
pub use embeddings::ApiEmbedding;
pub use embeddings::{BoxedEmbeddingProvider, EmbeddingProvider, HashEmbedding};

#[cfg(feature = "real-embeddings")]
pub use embeddings::CandleEmbedding;

#[cfg(feature = "onnx-embeddings")]
pub use embeddings::OnnxEmbedding;

// Compile-time warning about AgenticDB limitations
#[cfg(feature = "storage")]
#[allow(deprecated, clippy::let_unit_value)]
const _: () = {
    #[deprecated(
        since = "0.1.0",
        note = "AgenticDB uses placeholder hash-based embeddings. For semantic search, use OnnxEmbedding (feature: onnx-embeddings) or ApiEmbedding. See ADR-114 for details."
    )]
    const AGENTICDB_EMBEDDING_WARNING: () = ();
    let _ = AGENTICDB_EMBEDDING_WARNING;
};

pub use error::{Result, RuvectorError};
pub use types::{DistanceMetric, SearchQuery, SearchResult, VectorEntry, VectorId};
pub use vector_db::VectorDB;

// Quantization types (ADR-001)
pub use quantization::{
    BinaryQuantized, Int4Quantized, ProductQuantized, QuantizedVector, ScalarQuantized,
};

// Memory management types (ADR-001)
pub use arena::{Arena, ArenaVec, BatchVectorAllocator, CacheAlignedVec, CACHE_LINE_SIZE};

// Lock-free structures (requires parallel feature)
#[cfg(all(feature = "parallel", not(target_arch = "wasm32")))]
pub use lockfree::{
    AtomicVectorPool, BatchItem, BatchResult, LockFreeBatchProcessor, LockFreeCounter,
    LockFreeStats, LockFreeWorkQueue, ObjectPool, PooledObject, PooledVector, StatsSnapshot,
    VectorPoolStats,
};

// Cache-optimized storage
pub use cache_optimized::SoAVectorStorage;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_version() {
        // Verify version matches workspace - use dynamic check instead of hardcoded value
        let version = env!("CARGO_PKG_VERSION");
        assert!(!version.is_empty(), "Version should not be empty");
        // Version 2.x is the current major version
        assert!(
            version.starts_with("2.") || version.starts_with("0.1."),
            "Version should be 2.x or 0.1.x, got: {}",
            version
        );
    }
}