Skip to content

v0.7.0

Choose a tag to compare

@tvanreenen tvanreenen released this 24 Aug 15:58
· 11 commits to main since this release
5fec98e

Summary

Version 0.7.0 closes the remaining public contract gaps found during the 1.0 readiness audit. It rejects two forms of lossy NumPy coercion, makes a bound archive path stable for the lifetime of its store, and publishes the API and compatibility policy intended for 1.x. It also adds release checks that enforce package and artifact versions before publication.

Valid, documented 0.6 usage continues to work. This release does not add a new feature family, remove documented API, change search ranking, add a runtime dependency, or change archive format version 1.

Public API and 1.x compatibility policy

The supported package-level imports are now explicit:

from numpy_vector_store import VectorHit, VectorStore, __version__
  • The new public API and compatibility policy names the supported VectorStore methods and properties, VectorHit fields, return types, ownership behavior, exception classes, and persistence guarantees.
  • The policy distinguishes supported top-level imports from private helpers, submodule layout, subclass hooks, exact error wording, allocation details, and internal algorithms.
  • The proposed 1.x rules cover semantic versioning, deprecation and removal, Python and NumPy support, and archive compatibility before those become long-term commitments in 1.0.
  • VectorHit remains an immutable record whose equality and hashability follow its values. Opaque metadata retains its own comparison and hashing behavior, so a hit containing a dictionary remains unhashable.

The runtime API remains centered on VectorStore, VectorHit, three explicit metric methods, typed opaque metadata, and the create/open/save/reload persistence lifecycle.

Lossless numeric inputs

  • Python row-selector sequences containing a Python or NumPy Boolean are rejected before NumPy can coerce the Boolean to row zero or one. This includes mixed values such as [0, True].
  • Native NumPy integer selectors retain vectorized validation and the existing shape, uniqueness, and bounds rules.
  • Complex vector batches passed to add() and complex queries passed to any metric are rejected before conversion to float32 can discard imaginary components. Complex dtypes are rejected even when their current values have a zero imaginary part.
  • Complex-query validation runs before empty-store and empty-filter shortcuts, so the accepted query contract does not depend on current store state.

Calls that deliberately used Boolean row indexes or complex vectors now raise TypeError. Real-valued integer and floating-point inputs keep their existing behavior.

Stable archive bindings

  • A relative path is anchored to the current working directory when save(path) or VectorStore.open(path) binds it.
  • file_path returns the anchored absolute path, and later save() and reload() calls remain pointed at the same archive if the process changes working directory.
  • Extensionless .npz handling and lexical path behavior remain unchanged. Anchoring does not resolve .. components or dereference symlinks.
  • Save As remains transactional: a new binding becomes visible only after the new archive is written successfully.

Format version 1 is unchanged, and no archive conversion is required. Code that compares file_path with a relative path should compare against its anchored absolute form. Code that changed directories to redirect a later pathless save should pass the new destination explicitly to save(path).

Packaging and release safeguards

  • Distribution metadata now uses the SPDX MIT license expression and includes LICENSE in both the wheel and source distribution.
  • The existing py.typed marker is declared through Typing :: Typed, and the package is classified as Beta for the 0.7 adoption cycle.
  • Publication verifies that source __version__, the GitHub release tag, wheel metadata, and source-distribution metadata agree. It also requires exactly one wheel and one source distribution so stale build output cannot be uploaded accidentally.
  • Remote GitHub Actions are pinned to immutable commits with readable release comments beside each pin.
  • The full suite now runs on Windows with Python 3.13 in addition to Python 3.11 through 3.14 on Linux and the Python 3.11 minimum NumPy check.
  • Archive regression coverage now includes unexpected fields, nonpositive dimensions, malformed array shapes, and platform-specific filesystem behavior.

The release verifier and benchmark tools remain outside the runtime wheel and add no package dependency.

Compatibility and upgrade guidance

  • Python 3.11 through 3.14
  • NumPy 1.23.2 or newer
  • Archive format version 1

Most applications can upgrade from 0.6 without changes. Review code that used Boolean row selectors, supplied complex vectors or queries, compared file_path with a relative path, or relied on changing the process working directory to redirect a bound store. Persistence remains a trusted-file feature because opaque metadata uses pickle-backed NumPy object arrays.

See the repository changelog for the complete release record and the migration guide for applications upgrading from the older 0.3 persistence API.

Full comparison: v0.6.0...v0.7.0