Changelog

Copy Markdown View Source

All notable changes to Vettore are documented here. The project follows Semantic Versioning.

[Unreleased]

[0.3.5] - 2026-08-25

Added

  • Added Vettore.Vector as a validated interchange layer for numeric lists, little-endian f32 binaries, dimensioned vector wrappers, and host-provided Nx tensors.
  • Added native metrics, normalization, and row-selective mean pooling directly over little-endian f32 binaries, including Model2Vec-style token-table pooling without materializing the full matrix on the BEAM.
  • Added the zero-dependency Vettore.Interop.Nx runtime adapter. Vettore does not declare Nx as a dependency; applications that already use Nx can opt into tensor conversion without changing Vettore's core runtime.
  • Added native wgpu compute kernels for every dense metric, L2/z-score/min-max normalization, and row-selective mean pooling. CPU SIMD remains the default; gpu: true and gpu: :auto can be configured globally or per call with an explicit CPU/error fallback policy.
  • Added Vettore.gpu_detected?/0, Vettore.gpu_info/0, and Vettore.Compute.info/0 for hardware detection and runtime diagnostics.
  • Added shape-preserving wrappers and Nx conversion, backend transfer/type helpers, plus matrix stack/2, take_rows_f32/4, shape, and full-validation APIs.
  • Added an exact GPU Flat search path with a generation-aware resident embedding matrix, one-query-by-all-rows scoring shaders for every metric, device-side two-stage top-k reduction, and readback of only the final ids and scores.
  • Added batched GPU scoring for exact adaptive/hybrid reranks and a dedicated cold-upload versus warm-query Flat benchmark.

Changed

  • Replaced the Flat index's fragmented vector map with a contiguous row-major matrix plus id-to-row map. CPU exact scans retain portable SIMD kernels with improved locality, while mutations atomically invalidate the optional GPU snapshot.
  • Extended every Vettore.Distance dense metric and normalization helper with per-call compute options while preserving existing arities.
  • Nx remains runtime-only and absent from both Mix and Cargo dependencies; GPU execution is implemented entirely in Rust and does not use Nx.
  • Vectorized the f64 accumulation used by stable cosine scoring and exceptional overflow recovery, so numerical safeguards no longer force those hot loops back to scalar iteration.
  • Flat index options now accept :gpu, :gpu_min_size, and :gpu_fallback. Automatic selection uses the real rows * dimensions search workload.
  • GPU Flat queries reuse bounded pools of query, score, top-k, uniform, bind group, and staging resources. Concurrent warm searches do not hold the cache construction lock while dispatching.
  • GPU calls run concurrently without a process-wide execution mutex. Runtime failures invalidate the cached device, initialization failures use a bounded retry window, and readback waits default to a configurable 10-second timeout.

Fixed

  • Stabilized GPU metrics across the finite f32 range by scaling operands before shader reduction and rescaling checked results on the host. This fixes cosine overflow/underflow, cancelling extreme dot products, and large L1/L2 inputs.
  • Replaced one-pass f32 normalization statistics with two-pass f64 host preparation, fixing tiny L2 vectors and catastrophic z-score cancellation.
  • Guarded dispatch counts and storage bindings against the selected device limits before submitting work, preventing wgpu validation panics on oversized vectors and matrices.
  • Made gpu: :auto use CPU when no adapter is available even when the forced-GPU fallback policy is :error, and normalized runtime failures to stable atoms.
  • Added direct GPU NIF paths for little-endian f32 binaries, structural binary dimension checks, GPU-backed CI with lavapipe, Vector/Compute doctests, and an explicit Rust 1.91 MSRV check.
  • Aligned transient CPU and GPU top-k overflow semantics with Flat search: only the unrepresentable row is skipped, while valid candidates are retained.
  • Added explicit per-score validity in resident shaders so overflow cannot be mistaken for a zero-valued candidate, including at the finite f32 boundary.
  • Made hardware-dependent parity tests and benchmark preflights aware of f32 reduction-order ties. Scores and unambiguous ranks remain checked, while ids may permute inside a numerically tied boundary group.
  • Made the resident GPU benchmark parse metrics through a closed lookup table, fixing its CI preflight in a fresh BEAM where the requested metric atom did not already exist.
  • Added strict resident-GPU parity coverage over committed and freshly inferred 384-dimensional BAAI/bge-small-en-v1.5 document/query embeddings, including semantic retrieval and resident-cache reuse assertions.
  • Rebuilt resident buffers after every effective mutation and cached deterministic build failures by index generation, preventing repeated full snapshots for an unchanged unsupported matrix.

Performance

  • GPU devices and compiled pipelines are initialized lazily and reused. CPU calls skip GPU detection entirely, and GPU mean pooling uploads only selected rows rather than the complete model matrix.
  • Flat snapshot sorting, device upload, dispatch, and readback now happen outside the index read lock; writers are blocked only while the immutable host snapshot is copied.
  • Replaced the single-thread-per-chunk resident top-k pass with a 16-lane local reduction followed by the compact final merge.
  • Parallelized GPU mean pooling across 256 lanes per output column and scaled each selected column before accumulation, reducing drift and avoiding representable means overflowing during intermediate f32 sums.
  • Cached failed GPU runtime initialization for ten seconds so hosts without an adapter do not enumerate and request a device on every fallback call.

[0.3.4] - 2026-08-23

Fixed

  • Updated the local Rust toolchain pin to the crate's Rust 1.91 MSRV.
  • Corrected ExDoc's landing page and source links for versioned releases.
  • Replaced panic-prone HNSW graph lookups with recoverable errors and made flat/HNSW searches skip individual rows whose score overflows.
  • Serialized ETS snapshots with writes so snapshots represent one consistent point in time.
  • Aligned collection metric aliases with the compatibility constructor and made empty-id reads and deletes return {:error, :invalid_id} consistently.

Changed

  • Changed the Vettore.new/1 default from score: :raw to score: :similarity, matching the compatibility API. This changes Result.score values for callers that omitted the option; pass score: :raw to preserve the previous scale. Existing snapshots retain the score mode stored in their configuration.
  • Collections and compatibility databases are now reclaimed automatically when the process that created them exits. Long-lived resources must be created by a long-lived owner rather than handed off from a short-lived task or request process.

Security and reliability

  • Capped implicit adaptive-search candidate counts at 1,000,000 and reject adaptive searches whose result limit exceeds that bound. Explicit candidate counts above the bound, previously accepted, now return {:error, :invalid_candidates}.
  • Added Hex and RustSec dependency audits to CI.

[0.3.3] - 2026-08-12

Fixed

  • Rejected non-UTF-8 ids before ETS writes and Rustler decoding, preventing a failed insert from leaving the canonical store and native index inconsistent.
  • Made cosine collection ranking compute true cosine even when normalization is explicitly disabled or uses a non-L2 transform.
  • Kept quantized Hamming and Jaccard candidate selection consistent with their non-zero truth semantics.
  • Serialized ETS-backed store/index mutations so concurrent puts and deletes of the same id cannot leave phantom native entries.
  • Corrected compatibility insert and batch return ids when an empty id falls back to value.

Changed

  • Centralized index lifecycle, mutation, and search boundaries to remove cyclic module dependencies and keep flat and HNSW behavior aligned.
  • Added reverse HNSW edges, diversified pruning, local reconnection after deletes, and fresh search bounds to improve recall and deletion cost.
  • MMR now runs in one native batch instead of one NIF transition per pair.
  • Hybrid search reuses one ETS snapshot across adaptive generators, multi-stage funnel search narrows candidates progressively, and close/1 clears native index memory immediately.

Tests and release engineering

  • Raised enforced Elixir line coverage to 99%; the full suite reaches 99.36% with 175 passing checks.
  • Added a committed embedding fixture generated by the real ex_fastembed backend, plus deterministic offline integration tests and an opt-in fixture regeneration script.
  • Updated Elixir and Rust dependency locks, including wide 1.6.1.

[0.3.2] - 2026-07-21

Fixed

  • Fixed HNSW reciprocal-link pruning that left almost every newly inserted node unreachable and caused severe recall loss.
  • Hydrated HNSW and flat results from canonical ETS records so value and metadata are preserved, while stale native ids are ignored safely.
  • Normalized representative vectors derived from multi-vector records before cosine indexing.
  • Corrected :negative_inner_product score conversion and MMR similarity semantics, including malformed or missing MMR ids.
  • Replaced raising input paths with tagged errors for collection options, vectors, adaptive search, multi-vector scoring, and MUVERA configuration.
  • Validated custom-store records before adaptive NIF calls so malformed ids, duplicate rows, dimensions, and out-of-f32 values return tagged errors rather than raising during Rustler decoding.
  • Made snapshot index overrides persistent when a loaded collection is snapshotted again; added schema, record, checksum, and corruption validation.
  • Loaded legacy public-table snapshots under protected ownership instead of preserving unsafe table permissions.
  • Prevented collection-table leaks when index construction, snapshot restore, duplicate compatibility creation, or database deletion fails.
  • Made compatibility-database shutdown atomic with concurrent collection creation and removed the unsafe timeout on large owner-mediated batches.
  • Deleted drained ETS tables before acknowledging database shutdown so callers consistently observe {:error, :closed} immediately after close/1.
  • Added overflow-safe L2, cosine, z-score, and min-max normalization for extreme finite f32 values.
  • Recovered valid large L2 and cancelling dot-product results with f64 fallback, while rejecting genuinely unrepresentable squared distances and MaxSim sums.
  • Propagated metric failures through MMR and late-interaction reranking instead of silently substituting misleading zero scores.
  • Bounded MUVERA seed decoding and rejected non-finite encoding accumulation instead of returning corrupted vectors.
  • Kept Rust panics unwindable in release NIFs so Rustler can contain them instead of aborting the BEAM VM.

Changed

  • ETS tables are now owned by supervised temporary workers instead of the process that creates a collection. Tables survive caller exit and are protected against out-of-band writes.
  • Added idempotent Vettore.close/1 for deterministic collection and compatibility-database cleanup.
  • Collection construction and search reject unknown, duplicated, or malformed options instead of silently ignoring them.
  • Snapshot files are written through a temporary file and include ETS object count and MD5 integrity metadata.
  • Local Rust builds are now explicitly enabled with VETTORE_BUILD=1; normal dependency builds use the published precompiled NIFs.

Performance

  • Protected ETS tables keep concurrent-read optimization enabled while avoiding unused concurrent-writer bookkeeping behind their single supervised owner.
  • Direct ETS reads no longer perform redundant owner/table liveness probes; closed-table races are handled on the actual operation instead.
  • Default cosine helper calls now use one overflow-safe native kernel instead of two normalization calls followed by a third metric call.
  • Exact flat search computes each metric once and retains top-k results with a bounded heap instead of sorting every record.
  • HNSW batches inserts under one native write lock.
  • Funnel, quantized, hybrid, and multi-vector paths batch candidate scoring into dirty CPU NIF calls, avoiding one NIF transition per record or vector pair.

Tests and release engineering

  • Added 50 Rust unit tests covering every metric, scalar/SIMD differential checks, all top-k limits, HNSW graph invariants and recall, packed-bit word boundaries, multi-vector scoring, and MUVERA safety. Algorithm modules exceed 99% Rust line coverage.
  • Expanded the Elixir suite to 161 passing checks, including 60 doctests, fault-injected failure paths, concurrent readers and writers, and 98%+ line coverage (excluding unmeasurable NIF fallback stubs).
  • Added real BAAI/bge-small-en-v1.5 exact/HNSW/hybrid integration coverage.
  • Added deterministic latency and overlap benchmarks for every search mode, direct MaxSim, MUVERA encodings, and the ETS read/write ownership boundary.
  • Added pull-request CI for enforced Elixir and Rust algorithm coverage, Credo, Dialyzer, docs, Hex package contents, Rust formatting, tests, and Clippy.
  • Added explicit Cargo feature forwarding and CI checks for Rustler NIF 2.15 and 2.16 precompiled artifact builds.
  • Updated Rustler to 0.38, RustlerPrecompiled to 0.9, and wide to 1.5. Local native builds now require Rust 1.91 or newer.
  • Isolated the real ex_fastembed integration dependency from published Hex metadata so its older Rustler constraint cannot block application updates.
  • Made the complete precompiled-NIF matrix manually runnable from a release branch without creating or publishing a GitHub Release.
  • The tag release workflow now validates version/tag parity and publishes a generated Rustler checksum file with the native archives.

[0.3.1]

  • Previous release.