Repository navigation
v0.7.0
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
VectorStoremethods and properties,VectorHitfields, 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.
VectorHitremains 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 tofloat32can 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)orVectorStore.open(path)binds it. file_pathreturns the anchored absolute path, and latersave()andreload()calls remain pointed at the same archive if the process changes working directory.- Extensionless
.npzhandling 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
MITlicense expression and includesLICENSEin both the wheel and source distribution. - The existing
py.typedmarker is declared throughTyping :: 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