velesdb_core/

lib.rs

//! # `VelesDB` Core
//!
//! Local-first **tri-engine** database for AI agents, written in Rust:
//! **vector** (HNSW + SIMD) + **graph** (typed edges, traversal, `MATCH`) +
//! **columnar** (typed metadata filters), queried together through
//! **`VelesQL`** — parse with [`velesql::Parser`] and run with
//! `Database::execute_query`, mixing `NEAR $v`, `WHERE` predicates, and
//! `MATCH` graph patterns in one statement (see the repository guide
//! `docs/guides/MULTIMODEL_QUERIES.md` for the full multi-model tour).
//! Designed for semantic search, agent memory, recommendation, and RAG.
//!
//! ## Features
//!
//! - **Blazing Fast**: HNSW index with explicit SIMD (4x faster)
//! - **5 Distance Metrics**: Cosine, Euclidean, Dot Product, Hamming, Jaccard
//! - **Hybrid Search**: Vector + BM25 full-text with RRF fusion
//! - **Graph Engine**: typed edges on any collection, BFS/DFS, `MATCH` patterns
//! - **`VelesQL`**: one SQL-like language across all three engines
//! - **Quantization**: SQ8 (4x) and Binary (32x) memory compression
//! - **Persistent Storage**: Memory-mapped files for efficient disk access
//!
//! ## Quick Start
//!
//! ```rust,no_run
//! use velesdb_core::{Database, DistanceMetric, Point, StorageMode};
//! use serde_json::json;
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Create a new database
//!     let db = Database::open("./data")?;
//!
//!     // Create a collection (all 5 metrics available)
//!     db.create_collection("documents", 768, DistanceMetric::Cosine)?;
//!     // Or with quantization: DistanceMetric::Hamming + StorageMode::Binary
//!
//!     let collection = db.get_vector_collection("documents").ok_or("Collection not found")?;
//!
//!     // Insert vectors (upsert takes ownership)
//!     collection.upsert(vec![
//!         Point::new(1, vec![0.1; 768], Some(json!({"title": "Hello World"}))),
//!     ])?;
//!
//!     // Search for similar vectors
//!     let query_vector = vec![0.1; 768];
//!     let results = collection.search(&query_vector, 10)?;
//!
//!     // Hybrid search (vector + text)
//!     let hybrid = collection.hybrid_search(&query_vector, "hello", 5, Some(0.7))?;
//!     # Ok(())
//! }
//! ```

#![warn(missing_docs)]
// Clippy lints configured in workspace Cargo.toml [workspace.lints.clippy]
#![cfg_attr(
    test,
    allow(
        clippy::large_stack_arrays,
        clippy::doc_markdown,
        clippy::uninlined_format_args,
        clippy::single_match_else,
        clippy::cast_lossless,
        clippy::manual_assert
    )
)]

#[cfg(feature = "persistence")]
pub mod agent;
pub mod alloc_guard;
#[cfg(test)]
mod alloc_guard_tests;
pub mod api_types;
pub mod cache;
// `collection` is declared unconditionally: its `stats` and `query_cost` leaves are
// persistence-free and feed the `VelesQL` query planner (P1.4). The storage/index-coupled
// submodules remain individually gated inside `collection/mod.rs`.
pub mod collection;
#[cfg(feature = "persistence")]
pub mod column_store;
#[cfg(all(test, feature = "persistence"))]
mod column_store_tests;
pub mod compression;
pub mod config;
pub mod config_quantization;
#[cfg(test)]
mod config_tests;
mod config_validation;
/// Cross-implementation conformance harness (frozen golden reference vectors).
pub mod conformance;
pub mod contiguous_ops;
mod contiguous_resize;
pub mod distance;
#[cfg(test)]
mod distance_tests;
pub mod error;
#[cfg(test)]
mod error_tests;
#[cfg(feature = "test-fault-injection")]
pub mod fault_injection;
pub mod filter;
#[cfg(test)]
mod filter_like_tests;
#[cfg(test)]
mod filter_tests;
pub mod fusion;
pub mod gpu;
#[cfg(test)]
mod gpu_tests;
#[cfg(feature = "persistence")]
pub mod guardrails;
#[cfg(all(test, feature = "persistence"))]
mod guardrails_tests;
pub mod half_precision;
#[cfg(test)]
mod half_precision_tests;
#[cfg(feature = "persistence")]
pub mod index;
#[cfg(feature = "internal-bench")]
#[doc(hidden)]
pub mod internal_bench;
#[cfg(all(test, feature = "internal-bench"))]
mod internal_bench_tests;
pub mod lock_rank;
pub mod metrics;
#[cfg(test)]
mod metrics_tests;
pub mod perf_optimizations;
#[cfg(test)]
mod perf_optimizations_tests;
pub mod point;
#[cfg(test)]
mod point_tests;
pub mod quantization;
#[cfg(test)]
mod quantization_tests;
pub mod scored_result;
pub mod simd_dispatch;
#[cfg(test)]
mod simd_dispatch_tests;
#[cfg(test)]
mod simd_epic073_tests;
/// Sparse vector types, inverted index, and search -- always compiled (no persistence dependency).
pub mod sparse_index;
// simd_explicit removed - consolidated into simd_native (EPIC-075)
pub mod simd_native;
#[cfg(test)]
mod simd_native_tests;
#[cfg(target_arch = "aarch64")]
pub mod simd_neon;
#[cfg(target_arch = "aarch64")]
pub mod simd_neon_prefetch;
// simd_ops removed - direct dispatch via simd_native (EPIC-CLEANUP)
#[cfg(test)]
mod simd_prefetch_x86_tests;
#[cfg(test)]
mod simd_tests;
#[cfg(feature = "persistence")]
pub mod storage;
pub mod sync;
#[cfg(all(test, feature = "persistence"))]
mod test_fixtures;
#[cfg(all(not(target_arch = "wasm32"), feature = "update-check"))]
pub mod update_check;
pub mod validation;
pub mod vector_ref;
#[cfg(test)]
mod vector_ref_tests;
pub mod velesql;
/// Binary wire formats (VRB1 raw-bulk) — pure, persistence-free, wasm-safe.
pub mod wire;

#[cfg(all(not(target_arch = "wasm32"), feature = "update-check"))]
pub use update_check::{check_for_updates, spawn_update_check};
#[cfg(all(not(target_arch = "wasm32"), feature = "update-check"))]
pub use update_check::{compute_instance_hash, UpdateCheckConfig};

#[cfg(feature = "persistence")]
pub use index::{HnswIndex, HnswParams, SearchQuality, VectorIndex};

#[cfg(feature = "persistence")]
pub use collection::streaming::{BackpressureError, StreamIngester, StreamingConfig};
#[cfg(feature = "persistence")]
pub use collection::{
    // Type-erased collection handle (v2.0.0)
    AnyCollection,
    // Diagnostics (US-006: embedded SDK health checks)
    CollectionDiagnostics,
    // Public user-facing types — 3 typed collections replace Collection as primary API
    CollectionType,
    // Graph API types (user-visible)
    EdgeType,
    GraphCollection,
    GraphEdge,
    GraphNode,
    GraphSchema,
    // Diagnostics (US-006: embedded SDK health checks)
    IndexHealth,
    IndexInfo,
    MetadataCollection,
    NodeType,
    // Ordered-index ORDER BY advisor (EPIC-081 phase 3a)
    OrderByIndexState,
    OrderByIndexSuggestion,
    // Scroll cursor (Issue #429)
    ScrollBatch,
    TraversalConfig,
    TraversalPath,
    TraversalResult,
    ValueType,
    VectorCollection,
    // Durable TTL payload key (shared across all collection types and external crates)
    EXPIRES_AT_KEY,
};
pub use contiguous_ops::pad_to_simd_width;
pub use distance::{DistanceMetric, CONDITION_TYPE_NAMES, DISTANCE_METRIC_NAMES};
pub use error::{Error, Result};
pub use filter::{Condition, Filter};
pub use lock_rank::{assert_lock_order, LockRank};
pub use point::{ComponentScores, Point, SearchResult};
pub use quantization::{
    cosine_similarity_quantized, cosine_similarity_quantized_simd, dot_product_quantized,
    dot_product_quantized_simd, euclidean_squared_quantized, euclidean_squared_quantized_simd,
    BinaryQuantizedVector, QuantizationCodec, QuantizedVector, StorageMode, STORAGE_MODE_NAMES,
};
pub use scored_result::ScoredResult;
pub use validation::{
    validate_collection_name, validate_dimension, validate_dimension_match,
    MAX_COLLECTION_NAME_LENGTH, MAX_DIMENSION, MIN_DIMENSION,
};
// Canonical cross-engine stable hashing (FNV-1a). Lives in `wire::stable_hash`
// so persistence-free targets (WASM) can delegate to it. Consumers deriving a
// numeric ID from a string for persisted or interoperable use MUST call
// `hash_id` (never a std `DefaultHasher`, which is not stable across runs).
// `hash_id_bytes` is the bytes-level counterpart, exported so other
// `VelesDB` crates (velesdb-memory, velesdb-migrate) can delegate their own
// FNV-1a derivations to this single implementation instead of re-declaring
// the constants (issue #1542).
pub use wire::stable_hash::{hash_edge_id, hash_id, hash_id_bytes};

#[cfg(feature = "persistence")]
pub use column_store::{
    BatchUpdate, BatchUpdateResult, BatchUpsertResult, ColumnStore, ColumnStoreError, ColumnType,
    ColumnValue, ExpireResult, StringId, StringTable, TypedColumn, UpsertResult,
};
// Observability and guardrail surfaces (audit-2026q2 H2): these were previously
// reachable only via deep paths (`velesdb_core::metrics::*`,
// `velesdb_core::guardrails::limits::QueryLimits`), forcing wrapper crates
// to depend on the internal module layout. Re-exporting at the crate root
// applies the Facade pattern so the public API can evolve independently
// of the internal organisation.
pub use config::{
    ConfigError, HnswConfig, LimitsConfig, QuantizationConfig, QuantizationType, SearchConfig,
    SearchMode, VelesConfig,
};
#[cfg(feature = "persistence")]
pub use config::{LoggingConfig, ServerConfig, StorageConfig};
pub use fusion::{
    FusionError, FusionStrategy, DEFAULT_WEIGHTED_AVG_WEIGHT, DEFAULT_WEIGHTED_HIT_WEIGHT,
    DEFAULT_WEIGHTED_MAX_WEIGHT,
};
#[cfg(feature = "persistence")]
pub use guardrails::QueryLimits;
pub use metrics::{
    average_metrics, compute_latency_percentiles, hit_rate, mean_average_precision, mrr, ndcg_at_k,
    precision_at_k, recall_at_k, LatencyStats,
};
pub use metrics::{
    DurationHistogram, GuardRailsMetrics, OperationalMetrics, QueryStats, TraversalMetrics,
};

#[cfg(feature = "persistence")]
mod database;
#[cfg(feature = "persistence")]
pub mod observer;

#[cfg(feature = "persistence")]
pub use database::{Database, GatedRead};
#[cfg(feature = "persistence")]
pub use observer::DatabaseObserver;
#[cfg(feature = "persistence")]
pub use observer::{AccessDecision, AccessScope, QueryAccessContext, QueryOperationKind};
#[cfg(feature = "persistence")]
pub use storage::DurabilityMode;