velesdb-core 7.0.0

//! Native HNSW implementation.
//!
//! Custom HNSW implementation optimized for VelesDB use cases.
//! Goal: Remove dependency on external hnsw_rs library.
//!
//! # Status
//!
//! Active native implementation used by the HNSW index internals.
//! This module is performance-critical and continuously optimized.
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────┐
//! │           NativeHnsw<D>                 │
//! │  D: DistanceEngine (CPU/GPU/SIMD)      │
//! ├─────────────────────────────────────────┤
//! │  layers: Vec<Layer>                     │
//! │  entry_point: AtomicUsize (NO_ENTRY_POINT sentinel)│
//! │  params: HnswParams                     │
//! └─────────────────────────────────────────┘
//! ```
//!
//! # References
//!
//! - Paper: "Efficient and robust approximate nearest neighbor search
//!   using Hierarchical Navigable Small World graphs" (Malkov & Yashunin, 2016)
//! - arXiv: <https://arxiv.org/abs/1603.09320>

// Low-level HNSW internals: precision-loss casts are validated, doc_markdown
// flags false positives on algorithm names (HNSW, RaBitQ, VAMANA).
#![allow(clippy::doc_markdown)]
#![allow(clippy::cast_precision_loss)]
#![allow(clippy::cast_possible_truncation)]
#![allow(clippy::cast_sign_loss)]

pub(in crate::index::hnsw) mod arena_home;
mod backend_adapter;
mod batch_schedule;
mod distance;
mod graph;
mod graph_io;
pub(crate) mod layer;
mod ordered_float;
mod quantization;
mod quantized_precision;
mod quantized_traversal;
pub(crate) mod rabitq_precision;
mod search;
pub(crate) mod sq8_precision;

/// Re-exported for `index/batch.rs`: the same threshold decides whether
/// `place_batch` enters rayon and whether `insert_batch_parallel` needs the
/// dedicated pool, so both read one constant.
pub(crate) use backend_adapter::PARALLEL_BATCH_MIN;
pub use backend_adapter::{NativeHnswBackend, NativeNeighbour};
pub use distance::{CachedSimdDistance, CpuDistance, DistanceEngine};
pub(crate) use graph::ResumableSearch;
pub use graph::{NativeHnsw, DEFAULT_ALPHA, NO_ENTRY_POINT};
// Re-exported so sibling modules (notably `crate::gpu::gpu_csr` and its
// tests) can document and assert the caller contract of rebuilders that
// depend on a held layers lock, without widening `mod graph` itself to
// `pub(crate)`.
#[cfg(feature = "gpu")]
pub(crate) use graph::locking::{holds_lock as hnsw_holds_lock, LockRank as HnswLockRank};
// Test-only re-exports: only `gpu_csr` tests need to synthesise a held
// layers rank. Production code inside `native/` acquires ranks through
// the `with_*` helpers, never via these symbols directly.
#[cfg(all(test, feature = "gpu"))]
pub(crate) use graph::locking::{
    record_lock_acquire as hnsw_record_lock_acquire,
    record_lock_release as hnsw_record_lock_release,
};
pub use layer::{Layer, NodeId};
pub use ordered_float::OrderedFloat;
pub use quantization::{QuantizedVector, QuantizedVectorStore, ScalarQuantizer};
pub use quantized_precision::{QuantizedPrecisionHnsw, TraversalCodec};
pub use rabitq_precision::{RaBitQCodec, RaBitQPrecisionConfig, RaBitQPrecisionHnsw};
pub use search::SearchResult;
pub use sq8_precision::{Sq8Codec, Sq8PrecisionConfig, Sq8PrecisionHnsw};

#[cfg(test)]
mod backend_adapter_tests;
#[cfg(test)]
mod batch_connect_tests;
#[cfg(test)]
mod distance_tests;
#[cfg(test)]
mod graph_tests;
#[cfg(test)]
mod layer_tests;
#[cfg(test)]
mod ordered_float_tests;
#[cfg(test)]
mod precision_contract_tests;
#[cfg(test)]
mod quantization_tests;
#[cfg(test)]
mod rabitq_precision_tests;
#[cfg(test)]
mod search_pipeline_tests;
#[cfg(test)]
mod sq8_precision_tests;
#[cfg(test)]
mod tests;