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;
76pub mod config_quantization;
77#[cfg(test)]
78mod config_tests;
79mod config_validation;
80/// Cross-implementation conformance harness (frozen golden reference vectors).
81pub mod conformance;
82pub mod contiguous_ops;
83mod contiguous_resize;
84pub mod distance;
85#[cfg(test)]
86mod distance_tests;
87pub mod error;
88#[cfg(test)]
89mod error_tests;
90#[cfg(feature = "test-fault-injection")]
91pub mod fault_injection;
92pub mod filter;
93#[cfg(test)]
94mod filter_like_tests;
95#[cfg(test)]
96mod filter_tests;
97pub mod fusion;
98pub mod gpu;
99#[cfg(test)]
100mod gpu_tests;
101#[cfg(feature = "persistence")]
102pub mod guardrails;
103#[cfg(all(test, feature = "persistence"))]
104mod guardrails_tests;
105pub mod half_precision;
106#[cfg(test)]
107mod half_precision_tests;
108#[cfg(feature = "persistence")]
109pub mod index;
110#[cfg(feature = "internal-bench")]
111#[doc(hidden)]
112pub mod internal_bench;
113#[cfg(all(test, feature = "internal-bench"))]
114mod internal_bench_tests;
115pub mod lock_rank;
116pub mod metrics;
117#[cfg(test)]
118mod metrics_tests;
119pub mod perf_optimizations;
120#[cfg(test)]
121mod perf_optimizations_tests;
122pub mod point;
123#[cfg(test)]
124mod point_tests;
125pub mod quantization;
126#[cfg(test)]
127mod quantization_tests;
128pub mod scored_result;
129pub mod simd_dispatch;
130#[cfg(test)]
131mod simd_dispatch_tests;
132#[cfg(test)]
133mod simd_epic073_tests;
134/// Sparse vector types, inverted index, and search -- always compiled (no persistence dependency).
135pub mod sparse_index;
136// simd_explicit removed - consolidated into simd_native (EPIC-075)
137pub mod simd_native;
138#[cfg(test)]
139mod simd_native_tests;
140#[cfg(target_arch = "aarch64")]
141pub mod simd_neon;
142#[cfg(target_arch = "aarch64")]
143pub mod simd_neon_prefetch;
144// simd_ops removed - direct dispatch via simd_native (EPIC-CLEANUP)
145#[cfg(test)]
146mod simd_prefetch_x86_tests;
147#[cfg(test)]
148mod simd_tests;
149#[cfg(feature = "persistence")]
150pub mod storage;
151pub mod sync;
152#[cfg(all(test, feature = "persistence"))]
153mod test_fixtures;
154#[cfg(all(not(target_arch = "wasm32"), feature = "update-check"))]
155pub mod update_check;
156pub mod validation;
157pub mod vector_ref;
158#[cfg(test)]
159mod vector_ref_tests;
160pub mod velesql;
161/// Binary wire formats (VRB1 raw-bulk) — pure, persistence-free, wasm-safe.
162pub mod wire;
163
164#[cfg(all(not(target_arch = "wasm32"), feature = "update-check"))]
165pub use update_check::{check_for_updates, spawn_update_check};
166#[cfg(all(not(target_arch = "wasm32"), feature = "update-check"))]
167pub use update_check::{compute_instance_hash, UpdateCheckConfig};
168
169#[cfg(feature = "persistence")]
170pub use index::{HnswIndex, HnswParams, SearchQuality, VectorIndex};
171
172#[cfg(feature = "persistence")]
173pub use collection::streaming::{BackpressureError, StreamIngester, StreamingConfig};
174#[cfg(feature = "persistence")]
175pub use collection::{
176    // Type-erased collection handle (v2.0.0)
177    AnyCollection,
178    // Diagnostics (US-006: embedded SDK health checks)
179    CollectionDiagnostics,
180    // Public user-facing types — 3 typed collections replace Collection as primary API
181    CollectionType,
182    // Graph API types (user-visible)
183    EdgeType,
184    GraphCollection,
185    GraphEdge,
186    GraphNode,
187    GraphSchema,
188    // Diagnostics (US-006: embedded SDK health checks)
189    IndexHealth,
190    IndexInfo,
191    MetadataCollection,
192    NodeType,
193    // Ordered-index ORDER BY advisor (EPIC-081 phase 3a)
194    OrderByIndexState,
195    OrderByIndexSuggestion,
196    // Scroll cursor (Issue #429)
197    ScrollBatch,
198    TraversalConfig,
199    TraversalPath,
200    TraversalResult,
201    ValueType,
202    VectorCollection,
203    // Durable TTL payload key (shared across all collection types and external crates)
204    EXPIRES_AT_KEY,
205};
206pub use contiguous_ops::pad_to_simd_width;
207pub use distance::{DistanceMetric, CONDITION_TYPE_NAMES, DISTANCE_METRIC_NAMES};
208pub use error::{Error, Result};
209pub use filter::{Condition, Filter};
210pub use lock_rank::{assert_lock_order, LockRank};
211pub use point::{ComponentScores, Point, SearchResult};
212pub use quantization::{
213    cosine_similarity_quantized, cosine_similarity_quantized_simd, dot_product_quantized,
214    dot_product_quantized_simd, euclidean_squared_quantized, euclidean_squared_quantized_simd,
215    BinaryQuantizedVector, QuantizationCodec, QuantizedVector, StorageMode, STORAGE_MODE_NAMES,
216};
217pub use scored_result::ScoredResult;
218pub use validation::{
219    validate_collection_name, validate_dimension, validate_dimension_match,
220    MAX_COLLECTION_NAME_LENGTH, MAX_DIMENSION, MIN_DIMENSION,
221};
222// Canonical cross-engine stable hashing (FNV-1a). Lives in `wire::stable_hash`
223// so persistence-free targets (WASM) can delegate to it. Consumers deriving a
224// numeric ID from a string for persisted or interoperable use MUST call
225// `hash_id` (never a std `DefaultHasher`, which is not stable across runs).
226pub use wire::stable_hash::{hash_edge_id, hash_id};
227
228#[cfg(feature = "persistence")]
229pub use column_store::{
230    BatchUpdate, BatchUpdateResult, BatchUpsertResult, ColumnStore, ColumnStoreError, ColumnType,
231    ColumnValue, ExpireResult, StringId, StringTable, TypedColumn, UpsertResult,
232};
233// Observability and guardrail surfaces (audit-2026q2 H2): these were previously
234// reachable only via deep paths (`velesdb_core::metrics::*`,
235// `velesdb_core::guardrails::limits::QueryLimits`), forcing wrapper crates
236// to depend on the internal module layout. Re-exporting at the crate root
237// applies the Facade pattern so the public API can evolve independently
238// of the internal organisation.
239pub use config::{
240    ConfigError, HnswConfig, LimitsConfig, QuantizationConfig, QuantizationType, SearchConfig,
241    SearchMode, VelesConfig,
242};
243#[cfg(feature = "persistence")]
244pub use config::{LoggingConfig, ServerConfig, StorageConfig};
245pub use fusion::{FusionError, FusionStrategy};
246#[cfg(feature = "persistence")]
247pub use guardrails::QueryLimits;
248pub use metrics::{
249    average_metrics, compute_latency_percentiles, hit_rate, mean_average_precision, mrr, ndcg_at_k,
250    precision_at_k, recall_at_k, LatencyStats,
251};
252pub use metrics::{
253    DurationHistogram, GuardRailsMetrics, OperationalMetrics, QueryStats, TraversalMetrics,
254};
255
256#[cfg(feature = "persistence")]
257mod database;
258#[cfg(feature = "persistence")]
259pub mod observer;
260
261#[cfg(feature = "persistence")]
262pub use database::Database;
263#[cfg(feature = "persistence")]
264pub use observer::DatabaseObserver;
265#[cfg(feature = "persistence")]
266pub use observer::{AccessDecision, AccessScope, QueryAccessContext, QueryOperationKind};
267#[cfg(feature = "persistence")]
268pub use storage::DurabilityMode;
velesdb_core/lib.rs

velesdb_core/
lib.rs
