numpy-vector-store 0.3.1__tar.gz → 0.3.2__tar.gz

numpy_vector_store-0.3.2/.github/workflows/checks.yml

@@ -0,0 +1,115 @@
+name: Checks
+
+on:
+  workflow_call:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: checks-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Lint, format, and type-check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.32"
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install project dependencies
+        run: uv sync --locked --group dev
+
+      - name: Run Ruff lint checks
+        run: uv run --locked ruff check .
+
+      - name: Check Ruff formatting
+        run: uv run --locked ruff format --check .
+
+      - name: Run mypy
+        run: uv run --locked mypy src/
+
+  tests:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.32"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install project dependencies
+        run: uv sync --locked --group dev
+
+      - name: Run tests
+        run: uv run --locked pytest
+
+  minimum-numpy:
+    name: Test minimum NumPy on Python 3.10
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.32"
+          python-version: "3.10"
+          enable-cache: true
+
+      - name: Run tests with the minimum NumPy version
+        run: >-
+          uv run
+          --isolated
+          --no-project
+          --python 3.10
+          --with-editable .
+          --with numpy==1.21.3
+          --with pytest==8.4.2
+          python -m pytest

{numpy_vector_store-0.3.1 → numpy_vector_store-0.3.2}/.github/workflows/publish-pypi.yml

@@ -6,8 +6,13 @@ on:
       - published
 
 jobs:
+  validate:
+    name: Validate release
+    uses: ./.github/workflows/checks.yml
+
   publish-pypi:
     name: Publish to PyPI
+    needs: validate
     runs-on: ubuntu-latest
     permissions:
       contents: read

{numpy_vector_store-0.3.1 → numpy_vector_store-0.3.2}/.github/workflows/publish-testpypi.yml

@@ -4,8 +4,13 @@ on:
   workflow_dispatch:
 
 jobs:
+  validate:
+    name: Validate release candidate
+    uses: ./.github/workflows/checks.yml
+
   publish-testpypi:
     name: Publish to TestPyPI
+    needs: validate
     runs-on: ubuntu-latest
     permissions:
       contents: read

numpy_vector_store-0.3.2/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+This changelog records user-visible changes to NumPy Vector Store. Earlier
+release notes remain available on the
+[GitHub releases page](https://github.com/tvanreenen/numpy-vector-store/releases).
+
+## 0.3.2 - 2026-07-27
+
+This reliability and performance patch makes existing vector storage, search,
+metadata, and persistence behavior safer and more predictable. It does not
+intentionally break valid existing usage or change the `.npz` archive format.
+
+### Numerical reliability
+
+- Reject vectors, queries, and search thresholds that contain non-finite values
+  or cannot remain finite when represented as `float32`. Invalid input now
+  fails before it can corrupt stored state or ranking.
+- Calculate norms and raw metric intermediates with `float64` where `float32`
+  could overflow or underflow. Large and very small finite vectors can now be
+  normalized and compared reliably.
+- Allow zero vectors in stores created with `normalize=False`, where they are
+  valid for dot-product and Euclidean search.
+- Raise a clear error if a raw cosine search includes a zero vector, because
+  cosine similarity is undefined for that row.
+- Avoid duplicate full-size `float64` buffers when calculating raw Euclidean
+  distance.
+
+### Persistence
+
+- Resolve a path without an `.npz` suffix to the same archive for both saving
+  and loading. For example, `file_path="vectors"` consistently uses
+  `vectors.npz`.
+- Allow `load()` to be retried when the persistence file did not exist during
+  an earlier attempt.
+- Reset load state in `clear()` so a subsequent explicit `load()` can restore
+  the saved rows.
+- Keep repeated `load()` calls idempotent after a successful load.
+
+### Metadata
+
+- Preserve each item in the outer metadata sequence as one opaque row payload.
+  Tuples and lists are no longer mistaken for extra NumPy array dimensions.
+- Support dictionary, dataclass, tuple, list, string, integer, and other scalar
+  payloads consistently through insertion, search results, saving, and loading.
+- Continue rejecting explicitly multidimensional NumPy metadata arrays rather
+  than silently flattening ambiguous input.
+
+### Search memory use
+
+- Search the stored vector matrix directly when `within_rows` is omitted,
+  avoiding an unnecessary full-matrix copy on every unfiltered query.
+- Preserve original store indexes and metadata when `within_rows` selects a
+  filtered subset.
+- Document that filtered searches allocate a temporary matrix proportional to
+  the selected row count and vector dimensions.
+
+### Compatibility and validation
+
+- Test Python 3.10 through 3.14 in GitHub Actions.
+- Test the minimum supported NumPy version in a dedicated Python 3.10 job.
+- Raise the minimum NumPy requirement from 1.20 to 1.21.3 so it is compatible
+  with the oldest supported Python version.
+- Require linting, formatting, type checking, and the full Python test matrix
+  before publishing to PyPI.
+
+### Upgrade notes
+
+- No public method signatures or persisted field names changed.
+- Existing trusted `.npz` archives with `vectors` and `metadata` remain
+  readable.
+- Environments using NumPy 1.20 must upgrade to NumPy 1.21.3 or newer.
+- Inputs that previously produced `nan`, `inf`, or unreliable rankings now
+  raise `ValueError` instead.

{numpy_vector_store-0.3.1 → numpy_vector_store-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpy-vector-store
-Version: 0.3.1
+Version: 0.3.2
 Summary: A fast, lightweight, and zero-setup in-memory vector store powered by NumPy
 Project-URL: Homepage, https://github.com/tvanreenen/numpy-vector-store
 Project-URL: Repository, https://github.com/tvanreenen/numpy-vector-store
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
-Requires-Dist: numpy>=1.20.0
+Requires-Dist: numpy>=1.21.3
 Description-Content-Type: text/markdown
 
 # NumPy Vector Store
@@ -89,9 +89,10 @@ for hit in hits:
     print(f"{hit.metadata['title']}: {hit.value:.3f}")
 ```
 
-`metadata` is an opaque row payload returned with hits. It can be a dict,
-dataclass, string, integer row ID, or any other Python object that fits your
-application.
+`metadata` is an outer sequence with one opaque payload for each vector row.
+Each payload can be a dict, dataclass, tuple, list, string, integer row ID, or
+another Python object that fits your application. Tuple and list payloads remain
+single row values rather than being interpreted as additional array dimensions.
 
 ## Normalization
 
@@ -107,8 +108,23 @@ which is the common case for semantic embeddings. Use `normalize=False` when
 vector length matters, such as when magnitude encodes strength, confidence,
 counts, scale, or raw geometry.
 
-Zero vectors are rejected in both modes because cosine similarity is undefined
-for zero-norm vectors.
+Zero vectors are rejected when `normalize=True` because they cannot be scaled to
+unit length. Raw stores accept zero vectors for dot-product and Euclidean
+search. Because cosine similarity is undefined for zero vectors,
+`cosine_search` raises an error when its selected rows include one; use
+`within_rows` to exclude zero rows when needed.
+
+### Numerical inputs
+
+Stored vectors use `float32` to keep the store compact. Vectors and queries must
+remain finite when converted to `float32`, and search thresholds must also be
+finite. Invalid values are rejected before they can affect stored state or
+ranking.
+
+Norms and raw metric values use `float64` accumulation where `float32`
+intermediate calculations could overflow or underflow. This allows finite
+`float32` vectors across the representable magnitude range to be normalized and
+compared reliably.
 
 | Method | `normalize=True` default | `normalize=False` |
 |---|---|---|
@@ -160,6 +176,13 @@ rows = [
 hits = store.cosine_search(query, top_k=10, within_rows=rows)
 ```
 
+Searches without `within_rows` compute directly against the stored vector matrix
+and do not make a full copy of it. A filtered search gathers the selected rows
+into a temporary matrix, so its additional memory use scales with the number of
+selected rows and the vector dimensions. Omit `within_rows` when every row
+should be searched; passing every row explicitly would create an unnecessary
+full-size temporary matrix.
+
 For structured NumPy metadata, use NumPy to produce the row indexes:
 
 ```python
@@ -198,6 +221,9 @@ loaded = VectorStore[dict[str, str]](dimensions=1536, file_path="vectors.npz")
 loaded.load()
 ```
 
+The `.npz` suffix may be omitted. An extensionless path such as `"vectors"` is
+resolved to `"vectors.npz"` for both saving and loading.
+
 If you save with `normalize=False`, load with `normalize=False` too:
 
 ```python
@@ -227,16 +253,29 @@ with VectorStore[dict[str, str]](dimensions=1536, file_path="vectors.npz") as st
 Persistence uses a minimal NumPy `.npz` contract with `vectors` and `metadata`
 arrays. The `.npz` file does not encode the `normalize` setting; choose the same
 setting when loading that you used when saving. Loading validates shape,
-dimensions, row counts, and zero-norm vectors. It also uses `allow_pickle=True`
-for flexible Python metadata payloads, so only load files generated by your own
-application or another trusted local process. Loading untrusted `.npz` files is
-not a supported security model.
+dimensions, row counts, and zero-norm vectors. A `load()` call made before the
+file exists can be retried after the file is created. Repeated calls after a
+successful load do nothing unless `clear()` resets the in-memory store. Opaque
+metadata values remain individual row payloads across save/load round trips.
+Persistence uses `allow_pickle=True` for flexible Python metadata payloads, so
+only load files generated by your own application or another trusted local
+process. Loading untrusted `.npz` files is not a supported security model.
 
 ## Compatibility
 
 This project is still pre-1.0, so occasional breaking changes are expected while
-the API stabilizes. Breaking changes are documented in GitHub release notes.
-Deprecated APIs will keep warning for at least one point release before removal.
+the API stabilizes. Changes are documented in the [changelog](CHANGELOG.md) and
+GitHub release notes. Deprecated APIs will keep warning for at least one point
+release before removal.
+
+Supported Python versions are listed in the package classifiers and exercised
+in CI. The project generally retains stable CPython versions until their
+upstream end-of-life, adds new versions after its dependencies and CI support
+them, and drops versions only in minor releases.
+
+See the [changelog](CHANGELOG.md) for release history and the
+[project roadmap](ROADMAP.md) for the planned path to stable API and persistence
+contracts.
 
 ## Contributing
 

{numpy_vector_store-0.3.1 → numpy_vector_store-0.3.2}/README.md

@@ -65,9 +65,10 @@ for hit in hits:
     print(f"{hit.metadata['title']}: {hit.value:.3f}")
 ```
 
-`metadata` is an opaque row payload returned with hits. It can be a dict,
-dataclass, string, integer row ID, or any other Python object that fits your
-application.
+`metadata` is an outer sequence with one opaque payload for each vector row.
+Each payload can be a dict, dataclass, tuple, list, string, integer row ID, or
+another Python object that fits your application. Tuple and list payloads remain
+single row values rather than being interpreted as additional array dimensions.
 
 ## Normalization
 
@@ -83,8 +84,23 @@ which is the common case for semantic embeddings. Use `normalize=False` when
 vector length matters, such as when magnitude encodes strength, confidence,
 counts, scale, or raw geometry.
 
-Zero vectors are rejected in both modes because cosine similarity is undefined
-for zero-norm vectors.
+Zero vectors are rejected when `normalize=True` because they cannot be scaled to
+unit length. Raw stores accept zero vectors for dot-product and Euclidean
+search. Because cosine similarity is undefined for zero vectors,
+`cosine_search` raises an error when its selected rows include one; use
+`within_rows` to exclude zero rows when needed.
+
+### Numerical inputs
+
+Stored vectors use `float32` to keep the store compact. Vectors and queries must
+remain finite when converted to `float32`, and search thresholds must also be
+finite. Invalid values are rejected before they can affect stored state or
+ranking.
+
+Norms and raw metric values use `float64` accumulation where `float32`
+intermediate calculations could overflow or underflow. This allows finite
+`float32` vectors across the representable magnitude range to be normalized and
+compared reliably.
 
 | Method | `normalize=True` default | `normalize=False` |
 |---|---|---|
@@ -136,6 +152,13 @@ rows = [
 hits = store.cosine_search(query, top_k=10, within_rows=rows)
 ```
 
+Searches without `within_rows` compute directly against the stored vector matrix
+and do not make a full copy of it. A filtered search gathers the selected rows
+into a temporary matrix, so its additional memory use scales with the number of
+selected rows and the vector dimensions. Omit `within_rows` when every row
+should be searched; passing every row explicitly would create an unnecessary
+full-size temporary matrix.
+
 For structured NumPy metadata, use NumPy to produce the row indexes:
 
 ```python
@@ -174,6 +197,9 @@ loaded = VectorStore[dict[str, str]](dimensions=1536, file_path="vectors.npz")
 loaded.load()
 ```
 
+The `.npz` suffix may be omitted. An extensionless path such as `"vectors"` is
+resolved to `"vectors.npz"` for both saving and loading.
+
 If you save with `normalize=False`, load with `normalize=False` too:
 
 ```python
@@ -203,16 +229,29 @@ with VectorStore[dict[str, str]](dimensions=1536, file_path="vectors.npz") as st
 Persistence uses a minimal NumPy `.npz` contract with `vectors` and `metadata`
 arrays. The `.npz` file does not encode the `normalize` setting; choose the same
 setting when loading that you used when saving. Loading validates shape,
-dimensions, row counts, and zero-norm vectors. It also uses `allow_pickle=True`
-for flexible Python metadata payloads, so only load files generated by your own
-application or another trusted local process. Loading untrusted `.npz` files is
-not a supported security model.
+dimensions, row counts, and zero-norm vectors. A `load()` call made before the
+file exists can be retried after the file is created. Repeated calls after a
+successful load do nothing unless `clear()` resets the in-memory store. Opaque
+metadata values remain individual row payloads across save/load round trips.
+Persistence uses `allow_pickle=True` for flexible Python metadata payloads, so
+only load files generated by your own application or another trusted local
+process. Loading untrusted `.npz` files is not a supported security model.
 
 ## Compatibility
 
 This project is still pre-1.0, so occasional breaking changes are expected while
-the API stabilizes. Breaking changes are documented in GitHub release notes.
-Deprecated APIs will keep warning for at least one point release before removal.
+the API stabilizes. Changes are documented in the [changelog](CHANGELOG.md) and
+GitHub release notes. Deprecated APIs will keep warning for at least one point
+release before removal.
+
+Supported Python versions are listed in the package classifiers and exercised
+in CI. The project generally retains stable CPython versions until their
+upstream end-of-life, adds new versions after its dependencies and CI support
+them, and drops versions only in minor releases.
+
+See the [changelog](CHANGELOG.md) for release history and the
+[project roadmap](ROADMAP.md) for the planned path to stable API and persistence
+contracts.
 
 ## Contributing
 

numpy_vector_store-0.3.2/ROADMAP.md

@@ -0,0 +1,140 @@
+# Roadmap
+
+NumPy Vector Store is intentionally small: it provides exact in-memory vector
+search without adding a service, indexing system, or metadata query language.
+This roadmap explains how the project will make that focused core safer and
+more predictable on the way to a stable 1.0 release.
+
+The roadmap describes direction rather than delivery dates. Priorities may
+change as the library receives real-world feedback, and each release will have
+its final scope documented in its release notes.
+
+## Versioning approach
+
+The project follows semantic versioning while it is pre-1.0:
+
+- Patch releases such as 0.3.2 fix defects and improve existing documented
+  behavior without intentionally breaking valid usage.
+- Minor releases such as 0.4.0 may change behavior or file formats when that is
+  necessary to establish safer long-term contracts. Those changes will be
+  called out clearly and will preserve compatibility where practical.
+- The 1.0.0 release will mark a commitment to a stable public API and
+  persistence contract.
+
+Deprecated APIs will continue to warn for at least one point release before
+removal. Persisted data will receive an explicit compatibility and migration
+story before the project reaches 1.0.
+
+## Runtime support policy
+
+The Python versions listed in the package classifiers are part of the public
+compatibility contract and are exercised in CI. The project generally:
+
+- Supports stable CPython versions until their upstream end-of-life.
+- Adds a newly stable Python version after NumPy and the project's test suite
+  support it.
+- Drops a Python version only in a minor release and calls out the change in
+  release notes.
+
+The 0.3 series supports Python 3.10 through 3.14. Python 3.10 reaches upstream
+end-of-life in October 2026 and is expected to be removed in 0.4.0 rather than
+in a 0.3 patch release.
+
+Supported NumPy versions are also part of the runtime contract. The declared
+minimum should be installable on the oldest supported Python version and should
+have a dedicated minimum-dependency CI check. The regular Python matrix will
+continue to test the versions selected by the project's lockfile.
+
+## 0.3.2: Reliability and performance
+
+Status: complete
+
+This patch release focuses on cases where the current API can silently produce
+incorrect results, fail to reload data it saved, reject documented metadata
+payloads, or allocate much more memory than an exact search requires.
+
+Delivered changes:
+
+- Validate vectors and queries for finite numeric values.
+- Normalize large finite vectors without overflowing intermediate `float32`
+  calculations.
+- Accumulate raw metric values in `float64` when `float32` intermediates could
+  overflow.
+- Permit zero vectors in raw stores used for dot-product or Euclidean search,
+  while keeping cosine similarity's undefined zero-vector behavior explicit.
+- Make extensionless persistence paths save and load the same `.npz` file.
+- Allow loading to be retried when the persistence file was initially absent.
+- Preserve tuple, list, dataclass, scalar, and dictionary metadata as individual
+  opaque row payloads.
+- Avoid copying the complete vector matrix during an unfiltered search.
+- Add continuous validation across every supported Python version and require
+  equivalent checks before publishing.
+- Align the minimum NumPy requirement with Python 3.10 support and add a
+  minimum-dependency compatibility check.
+
+These changes are intended to preserve results and behavior for valid existing
+usage. Public state access, the persistence format, and context-manager
+semantics will not change in this patch release.
+
+## 0.4.0: Persistence and lifecycle
+
+The persistence format currently stores only vectors and metadata. That format
+is compact, but callers must separately remember dimensions and normalization
+mode. A safer format should be self-describing and able to reject incompatible
+configuration instead of silently changing vector semantics.
+
+Planned direction:
+
+- Introduce a versioned archive containing its dimensions and normalization
+  mode.
+- Continue reading the existing two-array archive format.
+- Write archives through a temporary file and replace the destination
+  atomically.
+- Define the difference between initial loading and explicit reloading.
+- Define whether context-manager exit saves after an exception.
+
+## 0.5.0: State safety and ingestion
+
+The current public NumPy arrays make inspection convenient, but they also let
+callers mutate normalized vectors and break internal search assumptions.
+Repeated small additions also copy all previously stored data.
+
+Planned direction:
+
+- Keep vector storage behind private state.
+- Expose read-only views or snapshots for inspection.
+- Make row retrieval safe from accidental mutation.
+- Improve ingestion for repeated additions without penalizing batch insertion.
+- Define deterministic ordering for equal search values.
+- Document thread-safety guarantees and limitations.
+
+## 0.6.0: API stabilization
+
+This release is intended to consolidate the earlier changes rather than add a
+new feature family.
+
+Planned direction:
+
+- Make validation and exception behavior consistent across methods.
+- Add performance regression coverage for representative store sizes.
+- Exercise persistence upgrades and backwards compatibility.
+- Resolve known high- and medium-priority defects.
+- Complete documentation of ordering, memory use, concurrency, and trusted-file
+  requirements.
+
+## 1.0.0: Stable contracts
+
+The project will be ready for 1.0 when:
+
+- The public API has completed at least one minor release cycle without
+  structural redesign.
+- Public access cannot silently invalidate vector-store invariants.
+- Persistence is self-describing and has a documented migration policy.
+- Supported numeric inputs behave reliably across supported Python and NumPy
+  versions.
+- Search and ingestion complexity are documented and covered by regression
+  tests.
+
+Reaching 1.0 does not require turning the project into a vector database. The
+library will continue to favor a small exact-search API over indexing services,
+framework integrations, or a built-in metadata query language.

{numpy_vector_store-0.3.1 → numpy_vector_store-0.3.2}/pyproject.toml

@@ -25,7 +25,7 @@ classifiers = [
     "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-    "numpy>=1.20.0",
+    "numpy>=1.21.3",
 ]
 
 
@@ -37,6 +37,9 @@ Issues = "https://github.com/tvanreenen/numpy-vector-store/issues"
 [tool.hatch.build.targets.wheel]
 packages = ["src/numpy_vector_store"]
 
+[tool.hatch.build.targets.sdist]
+exclude = ["/.codex"]
+
 [tool.hatch.version]
 path = "src/numpy_vector_store/__init__.py"
 

{numpy_vector_store-0.3.1 → numpy_vector_store-0.3.2}/src/numpy_vector_store/__init__.py

@@ -5,7 +5,7 @@ This package provides a lightweight vector store implementation for storing
 and searching vector embeddings using NumPy arrays.
 """
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 __author__ = "Tim VanReenen"
 
 from .vector_store import VectorHit, VectorStore