velesdb_core/
lib.rs

1//! # `VelesDB` Core
2//!
3//! High-performance vector database engine written in Rust.
4//!
5//! `VelesDB` is a local-first vector database designed for semantic search,
6//! recommendation systems, and RAG (Retrieval-Augmented Generation) applications.
7//!
8//! ## Features
9//!
10//! - **Blazing Fast**: HNSW index with explicit SIMD (4x faster)
11//! - **5 Distance Metrics**: Cosine, Euclidean, Dot Product, Hamming, Jaccard
12//! - **Hybrid Search**: Vector + BM25 full-text with RRF fusion
13//! - **Quantization**: SQ8 (4x) and Binary (32x) memory compression
14//! - **Persistent Storage**: Memory-mapped files for efficient disk access
15//!
16//! ## Quick Start
17//!
18//! ```rust,no_run
19//! use velesdb_core::{Database, DistanceMetric, Point, StorageMode};
20//! use serde_json::json;
21//!
22//! fn main() -> Result<(), Box<dyn std::error::Error>> {
23//!     // Create a new database
24//!     let db = Database::open("./data")?;
25//!
26//!     // Create a collection (all 5 metrics available)
27//!     db.create_collection("documents", 768, DistanceMetric::Cosine)?;
28//!     // Or with quantization: DistanceMetric::Hamming + StorageMode::Binary
29//!
30//!     let collection = db.get_vector_collection("documents").ok_or("Collection not found")?;
31//!
32//!     // Insert vectors (upsert takes ownership)
33//!     collection.upsert(vec![
34//!         Point::new(1, vec![0.1; 768], Some(json!({"title": "Hello World"}))),
35//!     ])?;
36//!
37//!     // Search for similar vectors
38//!     let query_vector = vec![0.1; 768];
39//!     let results = collection.search(&query_vector, 10)?;
40//!
41//!     // Hybrid search (vector + text)
42//!     let hybrid = collection.hybrid_search(&query_vector, "hello", 5, Some(0.7))?;
43//!     # Ok(())
44//! }
45//! ```
46
47#![warn(missing_docs)]
48// Clippy lints configured in workspace Cargo.toml [workspace.lints.clippy]
49#![cfg_attr(
50    test,
51    allow(
52        clippy::large_stack_arrays,
53        clippy::doc_markdown,
54        clippy::uninlined_format_args,
55        clippy::single_match_else,
56        clippy::cast_lossless,
57        clippy::manual_assert
58    )
59)]
60
61#[cfg(feature = "persistence")]
62pub mod agent;
63pub mod alloc_guard;
64#[cfg(test)]
65mod alloc_guard_tests;
66pub mod api_types;
67pub mod cache;
68#[cfg(feature = "persistence")]
69pub mod collection;
70#[cfg(feature = "persistence")]
71pub mod column_store;
72#[cfg(all(test, feature = "persistence"))]
73mod column_store_tests;
74pub mod compression;
75pub mod config;
76#[cfg(test)]
77mod config_tests;
78pub mod distance;
79#[cfg(test)]
80mod distance_tests;
81pub mod error;
82#[cfg(test)]
83mod error_tests;
84pub mod filter;
85#[cfg(test)]
86mod filter_like_tests;
87#[cfg(test)]
88mod filter_tests;
89pub mod fusion;
90pub mod gpu;
91#[cfg(test)]
92mod gpu_tests;
93#[cfg(feature = "persistence")]
94pub mod guardrails;
95#[cfg(all(test, feature = "persistence"))]
96mod guardrails_tests;
97pub mod half_precision;
98#[cfg(test)]
99mod half_precision_tests;
100#[cfg(feature = "persistence")]
101pub mod index;
102#[cfg(feature = "internal-bench")]
103#[doc(hidden)]
104pub mod internal_bench;
105#[cfg(all(test, feature = "internal-bench"))]
106mod internal_bench_tests;
107pub mod metrics;
108#[cfg(test)]
109mod metrics_tests;
110pub mod perf_optimizations;
111#[cfg(test)]
112mod perf_optimizations_tests;
113pub mod point;
114#[cfg(test)]
115mod point_tests;
116pub mod quantization;
117#[cfg(test)]
118mod quantization_tests;
119pub mod scored_result;
120pub mod simd_dispatch;
121#[cfg(test)]
122mod simd_dispatch_tests;
123#[cfg(test)]
124mod simd_epic073_tests;
125/// Sparse vector types, inverted index, and search -- always compiled (no persistence dependency).
126pub mod sparse_index;
127// simd_explicit removed - consolidated into simd_native (EPIC-075)
128pub mod simd_native;
129#[cfg(test)]
130mod simd_native_tests;
131#[cfg(target_arch = "aarch64")]
132pub mod simd_neon;
133#[cfg(target_arch = "aarch64")]
134pub mod simd_neon_prefetch;
135// simd_ops removed - direct dispatch via simd_native (EPIC-CLEANUP)
136#[cfg(test)]
137mod simd_prefetch_x86_tests;
138#[cfg(test)]
139mod simd_tests;
140#[cfg(feature = "persistence")]
141pub mod storage;
142pub mod sync;
143#[cfg(all(not(target_arch = "wasm32"), feature = "update-check"))]
144pub mod update_check;
145pub mod validation;
146pub mod vector_ref;
147#[cfg(test)]
148mod vector_ref_tests;
149pub mod velesql;
150
151#[cfg(all(not(target_arch = "wasm32"), feature = "update-check"))]
152pub use update_check::{check_for_updates, spawn_update_check};
153#[cfg(all(not(target_arch = "wasm32"), feature = "update-check"))]
154pub use update_check::{compute_instance_hash, UpdateCheckConfig};
155
156#[cfg(feature = "persistence")]
157pub use index::{HnswIndex, HnswParams, SearchQuality, VectorIndex};
158
159#[cfg(feature = "persistence")]
160pub use collection::streaming::BackpressureError;
161// MIGRATION: Collection is deprecated since 2.0.0.
162// Use VectorCollection, GraphCollection, or MetadataCollection instead.
163// The deprecated re-export is separated so #[allow(deprecated)] targets only
164// the single item — a block-level allow on a grouped `use` is flagged by
165// llvm-cov instrumentation (issue #329).
166#[cfg(feature = "persistence")]
167#[allow(deprecated)]
168pub use collection::Collection;
169
170#[cfg(feature = "persistence")]
171pub use collection::{
172    // Diagnostics (US-006: embedded SDK health checks)
173    CollectionDiagnostics,
174    // Public user-facing types — 3 typed collections replace Collection as primary API
175    CollectionType,
176    // Graph API types (user-visible)
177    EdgeType,
178    GraphCollection,
179    GraphEdge,
180    GraphNode,
181    GraphSchema,
182    // Diagnostics (US-006: embedded SDK health checks)
183    IndexHealth,
184    IndexInfo,
185    MetadataCollection,
186    NodeType,
187    TraversalResult,
188    ValueType,
189    VectorCollection,
190};
191pub use distance::DistanceMetric;
192pub use error::{Error, Result};
193pub use filter::{Condition, Filter};
194pub use perf_optimizations::pad_to_simd_width;
195pub use point::{Point, SearchResult};
196pub use quantization::{
197    cosine_similarity_quantized, cosine_similarity_quantized_simd, dot_product_quantized,
198    dot_product_quantized_simd, euclidean_squared_quantized, euclidean_squared_quantized_simd,
199    BinaryQuantizedVector, QuantizationCodec, QuantizedVector, StorageMode,
200};
201pub use scored_result::ScoredResult;
202pub use validation::{
203    validate_collection_name, validate_dimension, validate_dimension_match,
204    MAX_COLLECTION_NAME_LENGTH, MAX_DIMENSION, MIN_DIMENSION,
205};
206
207#[cfg(feature = "persistence")]
208pub use column_store::{
209    BatchUpdate, BatchUpdateResult, BatchUpsertResult, ColumnStore, ColumnStoreError, ColumnType,
210    ColumnValue, ExpireResult, StringId, StringTable, TypedColumn, UpsertResult,
211};
212pub use config::{
213    ConfigError, HnswConfig, LimitsConfig, QuantizationConfig, QuantizationType, SearchConfig,
214    SearchMode, VelesConfig,
215};
216#[cfg(feature = "persistence")]
217pub use config::{LoggingConfig, ServerConfig, StorageConfig};
218pub use fusion::{FusionError, FusionStrategy};
219pub use metrics::{
220    average_metrics, compute_latency_percentiles, hit_rate, mean_average_precision, mrr, ndcg_at_k,
221    precision_at_k, recall_at_k, LatencyStats,
222};
223
224#[cfg(feature = "persistence")]
225mod database;
226#[cfg(feature = "persistence")]
227pub mod observer;
228
229#[cfg(feature = "persistence")]
230pub use database::Database;
231#[cfg(feature = "persistence")]
232pub use observer::DatabaseObserver;
233#[cfg(feature = "persistence")]
234pub use storage::DurabilityMode;
velesdb_core/lib.rs

velesdb_core/
lib.rs
