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_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(feature = "persistence")]
50pub mod agent;
51pub mod alloc_guard;
52#[cfg(test)]
53mod alloc_guard_tests;
54pub mod cache;
55#[cfg(feature = "persistence")]
56pub mod collection;
57#[cfg(feature = "persistence")]
58pub mod column_store;
59#[cfg(all(test, feature = "persistence"))]
60mod column_store_tests;
61pub mod compression;
62pub mod config;
63#[cfg(test)]
64mod config_tests;
65pub mod database;
66pub mod distance;
67#[cfg(test)]
68mod distance_tests;
69pub mod error;
70#[cfg(test)]
71mod error_tests;
72pub mod filter;
73#[cfg(test)]
74mod filter_like_tests;
75#[cfg(test)]
76mod filter_tests;
77pub mod fusion;
78pub mod gpu;
79#[cfg(test)]
80mod gpu_tests;
81#[cfg(feature = "persistence")]
82pub mod guardrails;
83#[cfg(all(test, feature = "persistence"))]
84mod guardrails_tests;
85pub mod half_precision;
86#[cfg(test)]
87mod half_precision_tests;
88#[cfg(feature = "persistence")]
89pub mod index;
90pub mod metrics;
91#[cfg(test)]
92mod metrics_tests;
93pub mod perf_optimizations;
94#[cfg(test)]
95mod perf_optimizations_tests;
96pub mod point;
97#[cfg(test)]
98mod point_tests;
99pub mod quantization;
100#[cfg(test)]
101mod quantization_tests;
102pub mod simd_dispatch;
103#[cfg(test)]
104mod simd_dispatch_tests;
105#[cfg(test)]
106mod simd_epic073_tests;
107// simd_explicit removed - consolidated into simd_native (EPIC-075)
108pub mod simd_native;
109#[cfg(test)]
110mod simd_native_tests;
111#[cfg(target_arch = "aarch64")]
112pub mod simd_neon;
113#[cfg(target_arch = "aarch64")]
114pub mod simd_neon_prefetch;
115// simd_ops removed - direct dispatch via simd_native (EPIC-CLEANUP)
116#[cfg(test)]
117mod simd_prefetch_x86_tests;
118#[cfg(test)]
119mod simd_tests;
120#[cfg(feature = "persistence")]
121pub mod storage;
122pub mod sync;
123#[cfg(not(target_arch = "wasm32"))]
124pub mod update_check;
125pub mod vector_ref;
126#[cfg(test)]
127mod vector_ref_tests;
128pub mod velesql;
129
130#[cfg(all(not(target_arch = "wasm32"), feature = "update-check"))]
131pub use update_check::{check_for_updates, spawn_update_check};
132#[cfg(not(target_arch = "wasm32"))]
133pub use update_check::{compute_instance_hash, UpdateCheckConfig};
134
135#[cfg(feature = "persistence")]
136pub use index::{HnswIndex, HnswParams, SearchQuality, VectorIndex};
137
138#[cfg(feature = "persistence")]
139pub use collection::{
140    Collection, CollectionType, ConcurrentEdgeStore, EdgeStore, EdgeType, Element, GraphEdge,
141    GraphNode, GraphSchema, IndexInfo, NodeType, TraversalResult, ValueType,
142};
143pub use database::Database;
144pub use distance::DistanceMetric;
145pub use error::{Error, Result};
146pub use filter::{Condition, Filter};
147pub use point::{Point, SearchResult};
148pub use quantization::{
149    cosine_similarity_quantized, cosine_similarity_quantized_simd, distance_pq,
150    dot_product_quantized, dot_product_quantized_simd, euclidean_squared_quantized,
151    euclidean_squared_quantized_simd, BinaryQuantizedVector, PQCodebook, PQVector,
152    ProductQuantizer, QuantizedVector, StorageMode,
153};
154
155#[cfg(feature = "persistence")]
156pub use column_store::{
157    BatchUpdate, BatchUpdateResult, BatchUpsertResult, ColumnStore, ColumnStoreError, ColumnType,
158    ColumnValue, ExpireResult, StringId, StringTable, TypedColumn, UpsertResult,
159};
160pub use config::{
161    ConfigError, HnswConfig, LimitsConfig, LoggingConfig, QuantizationConfig, SearchConfig,
162    SearchMode, ServerConfig, StorageConfig, VelesConfig,
163};
164pub use fusion::{FusionError, FusionStrategy};
165pub use metrics::{
166    average_metrics, compute_latency_percentiles, hit_rate, mean_average_precision, mrr, ndcg_at_k,
167    precision_at_k, recall_at_k, LatencyStats,
168};
velesdb_core/lib.rs

velesdb_core/
lib.rs
