Repository navigation
v0.6.0
Summary
Version 0.6.0 makes the existing API's input and failure contracts predictable before 1.0. It closes cases where the same invalid call could behave differently on an empty and populated store, where Python booleans could act as row indexes or counts, and where loosely coerced configuration could change meaning after persistence. It also turns the project's performance claims and format-version-1 compatibility promise into reproducible regression evidence.
Valid, documented 0.5 usage continues to work unchanged. This release does not add a new feature family, archive format, runtime dependency, or public exception hierarchy.
Predictable scalar inputs
dimensions,top_k, andget(index)accept Python integers, NumPy integer scalars, and other integer-index values, then convert them to a Pythonint.- Python and NumPy booleans are rejected where integer semantics are required.
top_k=Trueno longer means one, andget(True)no longer invokes NumPy boolean indexing. normalizeaccepts Python and NumPy booleans and retains a canonical Pythonboolin memory and persistence.min_valueandmax_valueaccept finite Python and NumPy integer or floating-point scalars. Booleans, strings, complex values, arrays, and non-finite thresholds are rejected before search.
An inappropriate scalar type now raises TypeError, while a supported type with an invalid value raises ValueError. Row selector bounds use IndexError. Exact error wording remains explanatory rather than a compatibility guarantee.
Search checks independent of store state
within_rowsis validated before an empty result can be returned. It must be a one-dimensional sequence of unique integer row indexes, without booleans, and every index must exist in the current store.- Duplicate filtered indexes are rejected instead of returning the same stored row more than once.
- Zero-query rules now apply before empty-store shortcuts. Cosine search always requires a non-zero query. Dot-product and Euclidean searches require one when the store normalizes vectors, while raw stores continue accepting zero queries for those two metrics.
- Native NumPy integer selectors retain vectorized validation, and Python sequence validation no longer changes process-global warning filters.
These changes affect preconditions, not ranking. Valid 0.5 searches retain the same metric calculations, thresholds, deterministic tie handling, filtered-row semantics, and VectorHit results.
Persistence inputs and compatibility
open()andsave(path)accept strings and string-returning path-like objects. Explicitly empty paths raiseValueError, while inappropriate path types, including bytes paths, raiseTypeError.save()with no argument remains distinct fromsave(""): omission means save to the current binding; an empty string is invalid.- Extension resolution is unchanged. A path without
.npzresolves to the same archive for saving, opening, and reloading. - Persistence failures keep their owning exception types. Filesystem failures use the relevant
OSErrorsubclass, malformed schemas useValueError, and NumPy, pickle, or application metadata-loading exceptions are not hidden inside a package wrapper.
Archive format version 1 is unchanged. The compatibility suite now opens a fixture created by the published 0.4.0 package on Python 3.11 with NumPy 1.23.2 and verifies its configuration, vectors, and metadata. This protects forward reading of the self-describing format; it does not restore support for unversioned two-array archives or promise that an older package can read arbitrary future formats.
No archive conversion is required when upgrading from 0.5. Persistence remains a trusted-file feature because opaque metadata uses NumPy's pickle-backed object arrays.
Reproducible performance evidence
- New repository commands benchmark public exact search and ingestion and emit workload details, seeded input digests, complete timing samples, medians, Git state, Python and NumPy versions, timer information, thread-related environment variables, and NumPy build configuration as JSON.
- Structural tests protect geometric capacity reuse, partial top-k selection, and unfiltered access to the stored vector matrix without a preliminary full-matrix copy.
- Shared CI intentionally avoids wall-clock limits, which would make results depend on runner load rather than code structure.
The README reports an aligned cosine-search grid at 1,000, 10,000, and 100,000 rows for 384, 1,536, and 3,072 dimensions. Measurements on a 24 GB Apple M4 Mac mini range from about 0.032 ms per query at 1,000 rows × 384 dimensions to 20.509 ms at 100,000 rows × 3,072 dimensions. The largest matrix alone uses about 1.23 GB.
These are reference measurements, not latency guarantees. NumPy Vector Store is intended for small-to-medium, in-process exact search; 100,000 rows is an upper reference rather than a target for indefinite scaling. Workloads that routinely reach millions of vectors generally need an indexed or service-backed system.
Compatibility and upgrade guidance
- Python 3.11 through 3.14
- NumPy 1.23.2 or newer
- Archive format version 1
Applications using documented 0.5 input types should not need code changes. Review call sites that pass booleans where integers are expected, fractional result counts, string or boolean thresholds, duplicate or malformed within_rows values, zero queries that were only attempted against empty stores, or explicitly empty persistence paths. Those accidentally accepted or state-dependent cases now fail consistently at the public boundary.
See the repository changelog for the complete release record and the persistence migration guide for applications upgrading from the older 0.3 persistence API.
Full comparison: v0.5.0...v0.6.0