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

velesdb_core/
lib.rs
