Crate feox_ann 

FeOx ANN

A small, dependency-free HNSW (Hierarchical Navigable Small World) index for approximate nearest neighbor search over cosine similarity.

Part of the FeOx family. Pairs with feox-vector for a persistent, metadata-filtered vector store, or use it standalone as an in-memory index.

Highlights

• Deterministic builds: node levels are derived from a stable hash of the record id instead of a random number generator. The same records in the same order produce the same graph, so recall is reproducible, regressions are debuggable, and replicas that rebuild independently agree.
• SIMD distance kernels: NEON on aarch64 and AVX2+FMA on x86_64 with runtime detection and a scalar fallback.
• Parallel bulk load: AnnIndex::bulk_load runs candidate searches on worker threads against a frozen graph and applies results in fixed order. No locks, and the output does not depend on the thread count.
• Checksummed persistence: AnnIndex::save_to / AnnIndex::load_from write a compact CRC32-verified binary snapshot. Corrupted files are rejected on load.
• Zero dependencies: thiserror only.
• Filtered search: pass any Fn(&str) -> bool (or an AnnFilter implementation) to restrict results at query time.
• Soft deletes and upserts: deletes tombstone nodes without a rebuild. Upserts replace visible records in place.
• Scratch reuse: AnnIndex::insert_cursor reuses search scratch space across sequential inserts. Queries use thread-local scratch and allocate nothing per call.

Vectors are normalized on insert and scored with the dot product, so results rank by cosine similarity.

Quick start

use feox_ann::{AnnConfig, AnnIndex, AnnQuery};

let mut index = AnnIndex::new(AnnConfig::for_dimensions(2))?;
index.upsert("north".to_string(), &[1.0, 0.0])?;
index.upsert("east".to_string(), &[0.0, 1.0])?;

let matches = index.query(AnnQuery {
    vector: &[0.9, 0.1],
    top_k: 1,
    ef_search: None,
    filter: None,
})?;
assert_eq!(matches[0].id, "north");

Tuning

AnnConfig::for_dimensions gives sensible defaults. The usual HNSW trade-offs apply:

• max_neighbors / max_base_neighbors: graph degree. Raising it improves recall and costs memory and insert time.
• ef_construction: candidate breadth during insert. Raising it improves graph quality and slows builds.
• ef_search: candidate breadth during query. Raising it improves recall and adds latency. Can be set per query via AnnQuery::ef_search.

Structs

AnnCandidate

AnnConfig

AnnIndex

AnnInsertCursor

AnnQuery

Enums

AnnError

Traits

AnnFilter

Functions

dot

SIMD dot product over two f32 slices, using NEON on aarch64 and AVX2+FMA on x86_64 when available, with a scalar fallback. Slices are truncated to the shorter length.

Type Aliases

Result