Skip to content

v0.2.0

Choose a tag to compare

@tvanreenen tvanreenen released this 14 May 16:59
· 41 commits to main since this release

This release introduces the new stable pre-1.0 API direction for numpy-vector-store: a small, typed, exact cosine vector store built on NumPy, with explicit composable filtering and no framework-specific metadata query layer.

Highlights

  • Added VectorStore[TMetadata] for typed metadata payloads.
  • Added VectorHit(index, value, metadata) as the typed search result object.
  • Added VectorStore.add(vectors, metadata) as the preferred insertion API.
  • Added VectorStore.cosine_search(...) as the preferred explicit cosine similarity search API.
  • Added within_rows for efficient prefiltered search using row indexes from Python, NumPy, pandas, SQL, or any external filtering system.
  • Added __len__ support.
  • Simplified persistence around trusted local .npz files containing only vectors and metadata.

Compatibility

The older 0.1 methods are still available but now deprecated:

  • add_vectors(...) still works and delegates to add(...).
  • search(...) still works and returns the same tuple shape as before.
  • Both methods now emit DeprecationWarning.

metadata_schema has been removed. The supported model is now: store metadata as an opaque row payload, perform filtering externally, and pass matching row indexes to within_rows.

Breaking Changes

  • Python support now requires Python >=3.10.
  • metadata_schema is no longer supported.
  • The documented search result shape has moved from tuples to VectorHit.
  • The preferred search method is now cosine_search, with min_value instead of the legacy score_cutoff.

Why This Release Matters

0.2.0 defines the project’s intended API shape before broader adoption: explicit cosine search, typed metadata, simple local persistence, and composable filtering without taking on a metadata query language or embedding framework responsibilities.