ruvector-cluster 0.1.0__tar.gz

ruvector_cluster-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.py[cod]
+dist/
+.pytest_cache/

ruvector_cluster-0.1.0/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.

ruvector_cluster-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: ruvector-cluster
+Version: 0.1.0
+Summary: Embedding clustering for Python using RuVector native Rust libraries
+Project-URL: Homepage, https://github.com/ruvnet/RuVector
+Project-URL: Documentation, https://github.com/ruvnet/RuVector/tree/main/python/portfolio/ruvector-cluster
+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: cluster,embeddings,rag,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.2
+Description-Content-Type: text/markdown
+
+# ruvector-cluster: Embedding clustering in Python
+
+![Embedding clustering: Python API to PyO3 to Rust](https://raw.githubusercontent.com/ruvnet/RuVector/main/docs/python-portfolio/cluster.svg)
+
+## What is ruvector-cluster?
+
+ruvector-cluster provides embedding clustering through `ruvector-cluster-rag` in the RuVector Rust library family. It adds a focused Python API over the existing `ruvector` PyO3 runtime. It does not ship a separate native engine or reduce the shared runtime's installation size.
+
+## Install
+
+```bash
+pip install ruvector-cluster==0.1.0
+```
+
+Release candidate: this command works only after publication. From a checkout, install `ruvector==0.1.2` and then `pip install ./python/portfolio/ruvector-cluster`. Python 3.10 or newer; native platform support follows the shared runtime wheels.
+
+## Quick start
+
+```python
+from ruvector_cluster import cluster
+result = cluster([[1, 0], [1.1, 0], [10, 10], [10.1, 10]], 2)
+assert result.labels[0] == result.labels[1]
+assert result.labels[2] == result.labels[3]
+assert result.labels[0] != result.labels[2]
+assert result.sizes.sum() == 4
+```
+
+## API and limitations
+
+Public exports: `ClusterResult, cluster`. Lloyd clustering for numeric embeddings. No embedding model download or network service. Quality and latency depend on your data; no universal speedup or recall claim.
+
+Input conversion can copy arrays. Reuse contiguous float32 arrays for repeated operations. No service, telemetry or credentials are added by this package. Apply application memory and request limits for untrusted data.
+
+## How does it relate to RuVector?
+
+The algorithm executes through the existing Rust PyO3 binding, pinned to `ruvector==0.1.2`. Python implements convenience conversion and result formatting. For vector search use `pip install ruvector`; for other capabilities see the [Python portfolio](https://github.com/ruvnet/RuVector/tree/main/python/portfolio).
+
+## Verification and security
+
+CI tests built wheels against a native runtime compiled from this repository, checks sdists and README rendering, audits resolved dependencies and publishes through PyPI Trusted Publishing. Native vulnerability scanning is a separate required gate. See [security scope](https://github.com/ruvnet/RuVector/blob/main/python/portfolio/SECURITY.md).

ruvector_cluster-0.1.0/README.md

@@ -0,0 +1,40 @@
+# ruvector-cluster: Embedding clustering in Python
+
+![Embedding clustering: Python API to PyO3 to Rust](https://raw.githubusercontent.com/ruvnet/RuVector/main/docs/python-portfolio/cluster.svg)
+
+## What is ruvector-cluster?
+
+ruvector-cluster provides embedding clustering through `ruvector-cluster-rag` in the RuVector Rust library family. It adds a focused Python API over the existing `ruvector` PyO3 runtime. It does not ship a separate native engine or reduce the shared runtime's installation size.
+
+## Install
+
+```bash
+pip install ruvector-cluster==0.1.0
+```
+
+Release candidate: this command works only after publication. From a checkout, install `ruvector==0.1.2` and then `pip install ./python/portfolio/ruvector-cluster`. Python 3.10 or newer; native platform support follows the shared runtime wheels.
+
+## Quick start
+
+```python
+from ruvector_cluster import cluster
+result = cluster([[1, 0], [1.1, 0], [10, 10], [10.1, 10]], 2)
+assert result.labels[0] == result.labels[1]
+assert result.labels[2] == result.labels[3]
+assert result.labels[0] != result.labels[2]
+assert result.sizes.sum() == 4
+```
+
+## API and limitations
+
+Public exports: `ClusterResult, cluster`. Lloyd clustering for numeric embeddings. No embedding model download or network service. Quality and latency depend on your data; no universal speedup or recall claim.
+
+Input conversion can copy arrays. Reuse contiguous float32 arrays for repeated operations. No service, telemetry or credentials are added by this package. Apply application memory and request limits for untrusted data.
+
+## How does it relate to RuVector?
+
+The algorithm executes through the existing Rust PyO3 binding, pinned to `ruvector==0.1.2`. Python implements convenience conversion and result formatting. For vector search use `pip install ruvector`; for other capabilities see the [Python portfolio](https://github.com/ruvnet/RuVector/tree/main/python/portfolio).
+
+## Verification and security
+
+CI tests built wheels against a native runtime compiled from this repository, checks sdists and README rendering, audits resolved dependencies and publishes through PyPI Trusted Publishing. Native vulnerability scanning is a separate required gate. See [security scope](https://github.com/ruvnet/RuVector/blob/main/python/portfolio/SECURITY.md).

ruvector_cluster-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ruvector-cluster"
+version = "0.1.0"
+description = "Embedding clustering for Python using RuVector native Rust libraries"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "RuVector Team"}]
+dependencies = ["ruvector==0.1.2", "numpy>=1.21"]
+keywords = ["ruvector", "rust", "cluster", "embeddings", "rag"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Rust",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/ruvnet/RuVector"
+Documentation = "https://github.com/ruvnet/RuVector/tree/main/python/portfolio/ruvector-cluster"
+Repository = "https://github.com/ruvnet/RuVector"
+Issues = "https://github.com/ruvnet/RuVector/issues"
+Changelog = "https://github.com/ruvnet/RuVector/blob/main/python/portfolio/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ruvector_cluster"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE", "pyproject.toml"]

ruvector_cluster-0.1.0/src/ruvector_cluster/__init__.py

@@ -0,0 +1,31 @@
+"""Embedding clustering backed by RuVector Rust bindings."""
+from dataclasses import dataclass
+import numpy as np
+from numpy.typing import NDArray
+from ruvector import kmeans
+
+__all__ = ["ClusterResult", "cluster"]
+
+@dataclass(frozen=True)
+class ClusterResult:
+    labels: NDArray[np.int64]
+    centroids: NDArray[np.float32]
+    cohesion: NDArray[np.float32]
+    sizes: NDArray[np.int64]
+
+def cluster(vectors, k: int, *, iterations: int = 20) -> ClusterResult:
+    """Cluster embeddings with the native Rust Lloyd implementation.
+
+    Converts numeric array inputs to contiguous float32. Cohesion is cosine
+    similarity, not Euclidean inertia. Labels are not stable identifiers.
+    """
+    if isinstance(k, bool) or not isinstance(k, int) or k < 1:
+        raise ValueError("k must be a positive integer")
+    if isinstance(iterations, bool) or not isinstance(iterations, int) or not 1 <= iterations <= 10000:
+        raise ValueError("iterations must be between 1 and 10000")
+    data = np.ascontiguousarray(vectors, dtype=np.float32)
+    if data.ndim != 2 or not all(data.shape) or k > data.shape[0]:
+        raise ValueError("vectors must be nonempty rows by dimensions and k <= rows")
+    if not np.isfinite(data).all():
+        raise ValueError("vectors must be finite")
+    return ClusterResult(*kmeans(data, k, iters=iterations))