ruvector-core 0.2.0__py3-none-any.whl

ruvector_core/__init__.py

@@ -0,0 +1,55 @@
+"""Validated Python convenience APIs backed by RuVector Rust."""
+import numpy as np
+
+_MAX_DIM = 65536
+
+def _integer(value, name, upper=_MAX_DIM):
+    if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= upper:
+        raise ValueError(f"{name} must be an integer in [1, {upper}]")
+    return value
+
+def _array(value, ndim, name, metric):
+    data = np.ascontiguousarray(value, dtype=np.float64)
+    if data.ndim != ndim or not data.size or data.shape[-1] > _MAX_DIM:
+        raise ValueError(f"{name} has an invalid or empty shape")
+    if not np.isfinite(data).all():
+        raise ValueError(f"{name} must be finite")
+    if np.any(np.abs(data) > 1e10):
+        raise ValueError("vector magnitude must not exceed 1e10 for stable native metrics")
+    if metric == "cosine":
+        scale = np.max(np.abs(data), axis=-1, keepdims=True)
+        if np.any(scale == 0):
+            raise ValueError("cosine vectors must have nonzero norm")
+        data = data / scale
+        data = data / np.linalg.norm(data, axis=-1, keepdims=True)
+    return np.ascontiguousarray(data, dtype=np.float32)
+
+from ruvector import Collection, HnswIndex, RabitqIndex, SearchHit
+__all__ = ["VectorStore", "Collection", "HnswIndex", "RabitqIndex", "SearchHit"]
+
+class VectorStore:
+    """Validated batch ingestion and search over the native HNSW Collection."""
+    def __init__(self, dimensions: int, *, metric: str = "cosine"):
+        self.dimensions = _integer(dimensions, "dimensions")
+        if metric not in {"cosine", "euclidean", "dot", "manhattan"}:
+            raise ValueError("unsupported metric")
+        self.metric = metric
+        self.collection = Collection.create(dimensions, metric=metric)
+
+    def add(self, vectors, *, metadata=None):
+        data = _array(vectors, 2, "vectors", self.metric)
+        if data.shape[1] != self.dimensions:
+            raise ValueError("vector dimension mismatch")
+        if metadata is not None and (len(metadata) != len(data) or any(m is not None and not isinstance(m, dict) for m in metadata)):
+            raise ValueError("metadata must contain one dict or None per vector")
+        return self.collection.insert_batch(data, metadatas=metadata)
+
+    def search(self, query, *, k: int = 10, filter=None):
+        q = _array(query, 1, "query", self.metric)
+        if len(q) != self.dimensions:
+            raise ValueError("query dimension mismatch")
+        _integer(k, "k", 100000)
+        return self.collection.search(q, k, filter=filter)
+
+    def __len__(self):
+        return len(self.collection)

ruvector_core-0.2.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: ruvector-core
+Version: 0.2.0
+Summary: Native vector search with ergonomic batch ingestion.
+Project-URL: Homepage, https://github.com/ruvnet/RuVector
+Project-URL: Documentation, https://github.com/ruvnet/RuVector/tree/main/python/portfolio/ruvector-core
+Project-URL: Repository, https://github.com/ruvnet/RuVector
+Project-URL: Issues, https://github.com/ruvnet/RuVector/issues
+Project-URL: Changelog, https://github.com/ruvnet/RuVector/blob/main/python/portfolio/CHANGELOG.md
+Author: RuVector Team
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,core,embeddings,rust,ruvector
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.21
+Requires-Dist: ruvector==0.1.3
+Description-Content-Type: text/markdown
+
+# ruvector-core
+
+![RuVector core animated overview](https://raw.githubusercontent.com/ruvnet/RuVector/main/docs/python-portfolio/core.svg)
+
+Native vector search with ergonomic batch ingestion.
+
+## Getting started
+
+Requires Python 3.10 or later and a platform supported by the `ruvector==0.1.3` native wheel.
+
+```sh
+python -m pip install ruvector-core==0.2.0
+```
+
+```python
+from ruvector_core import VectorStore
+store = VectorStore(2)
+store.add([[1, 0], [0, 1]])
+assert store.search([1, 0], k=1)[0].id == 0
+```
+
+## How it works
+
+Python sequences → finite contiguous float32 validation → shared RuVector native Rust runtime → typed Python or NumPy results. No Node.js process is used.
+
+## Scope and limits
+
+HNSW is approximate. Metadata filters are applied after ANN retrieval, with Collection overfetch retries. No embedding model is included.
+
+This is a Python convenience API backed by the shared native runtime, not complete npm API parity. Invalid dimensions and nonfinite inputs are rejected.
+
+## Documentation
+
+[Portfolio and architecture](https://github.com/ruvnet/RuVector/tree/main/python/portfolio) · [Source](https://github.com/ruvnet/RuVector/tree/main/python/portfolio/ruvector-core) · [Issues](https://github.com/ruvnet/RuVector/issues)
+
+Coordinates are limited to absolute values of `1e10` and dimensions to 65,536, preventing overflow in native float32 distance accumulation. Rescale larger vectors before ingestion or querying.
+
+Cosine vectors are normalized in float64 before float32 conversion to preserve tiny nonzero directions. Zero vectors are rejected for cosine; other metrics retain their original magnitudes.

ruvector_core-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+ruvector_core/__init__.py,sha256=PYMdB1d1Sh7x4KaS6qrxDuDlUpa_f2SH4V4bU--T828,2563
+ruvector_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ruvector_core-0.2.0.dist-info/METADATA,sha256=jlH8i7Ap4Lu98LxLz7hnChFtowku_2TL9etOHKJ2iaA,2584
+ruvector_core-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ruvector_core-0.2.0.dist-info/licenses/LICENSE,sha256=UP77k1YK9EITacmck8whTNg1sxgat_FjI_nm8t7YcOM,1060
+ruvector_core-0.2.0.dist-info/RECORD,,

ruvector_core-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ruvector_core-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rUv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.