ruvector-router 0.2.0__py3-none-any.whl

ruvector_router/__init__.py

@@ -0,0 +1,72 @@
+"""Embedding based routing over native RuVector HNSW, without network calls."""
+from dataclasses import dataclass
+import math
+import numpy as np
+from ruvector import HnswIndex
+
+__all__ = ['SemanticRouter', 'RouteMatch']
+
+@dataclass(frozen=True)
+class RouteMatch:
+    name: str
+    score: float
+
+class SemanticRouter:
+    """One representative embedding per route; cosine similarity threshold.
+
+    This is a Python routing policy over native core HNSW, not a binding to
+    the separate neural router crate. Embeddings must be supplied by callers.
+    """
+    def __init__(self, dimensions: int, *, threshold: float = 0.7):
+        if isinstance(dimensions, bool) or not isinstance(dimensions, int) or not 1 <= dimensions <= 65536:
+            raise ValueError('dimensions must be an integer in [1, 65536]')
+        if isinstance(threshold, bool) or not isinstance(threshold, (int, float)) or not math.isfinite(threshold) or not -1 <= threshold <= 1:
+            raise ValueError('threshold must be finite in [-1, 1]')
+        self.dimensions, self.threshold = dimensions, float(threshold)
+        self._vectors = {}
+        self._index = HnswIndex.create(dimensions)
+
+    def _vector(self, vector):
+        data = np.ascontiguousarray(vector, dtype=np.float32)
+        if data.ndim != 1 or len(data) != self.dimensions or not np.isfinite(data).all():
+            raise ValueError('embedding must be a finite vector matching dimensions')
+        # Reject zero norm; normalize in float64 to avoid float32 overflow.
+        norm = np.linalg.norm(data.astype(np.float64))
+        if not norm > 0:
+            raise ValueError('cosine routing requires nonzero embeddings')
+        return np.ascontiguousarray(data.astype(np.float64) / norm, dtype=np.float32)
+
+    def _replace(self, vectors):
+        # Build first, then commit. Replacement/deletion cannot retain stale HNSW
+        # graph nodes and invalid inserts leave the prior router intact.
+        index = HnswIndex.create(self.dimensions)
+        for name, vector in sorted(vectors.items()):
+            index.insert(name, vector)
+        self._index, self._vectors = index, vectors
+
+    def add(self, name: str, embedding):
+        if not isinstance(name, str) or not name.strip() or len(name) > 1024:
+            raise ValueError('name must be a nonempty string of at most 1024 characters')
+        vector = self._vector(embedding)
+        self._replace({**self._vectors, name: vector})
+
+    def remove(self, name: str) -> bool:
+        if name not in self._vectors:
+            return False
+        vectors = self._vectors.copy()
+        del vectors[name]
+        self._replace(vectors)
+        return True
+
+    def route(self, embedding, *, k: int = 1) -> list[RouteMatch]:
+        vector = self._vector(embedding)
+        if isinstance(k, bool) or not isinstance(k, int) or not 1 <= k <= 100000:
+            raise ValueError('k must be an integer in [1, 100000]')
+        if not self._vectors:
+            return []
+        results = self._index.search(vector, min(k, len(self._vectors)))
+        matches = [RouteMatch(name, max(-1., min(1., 1. - distance))) for name, distance, _ in results]
+        return sorted((m for m in matches if m.score >= self.threshold), key=lambda m: (-m.score, m.name))
+
+    def __len__(self):
+        return len(self._vectors)

ruvector_router-0.2.0.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: ruvector-router
+Version: 0.2.0
+Summary: Semantic embedding routing backed by native RuVector HNSW
+Project-URL: Homepage, https://github.com/ruvnet/RuVector
+Project-URL: Documentation, https://github.com/ruvnet/RuVector/tree/main/python/portfolio/ruvector-router
+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,embeddings,router,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-router
+
+![RuVector semantic routing](https://raw.githubusercontent.com/ruvnet/RuVector/main/docs/python-portfolio/router.svg)
+
+Route embedding vectors to named intents with native RuVector HNSW search and an explicit cosine similarity threshold. Supply your own embeddings; the router makes no network requests.
+
+## Getting started
+
+```sh
+python -m pip install ruvector-router==0.2.0
+```
+
+```python
+from ruvector_router import SemanticRouter
+router = SemanticRouter(2, threshold=0.8)
+router.add('support', [1, 0])
+router.add('sales', [0, 1])
+assert router.route([1, 0])[0].name == 'support'
+router.add('support', [-1, 0])  # Replace an existing route
+assert router.route([1, 0]) == []
+assert router.remove('support')
+assert not router.remove('support')
+```
+
+## Architecture and scope
+
+Caller embeddings → finite nonzero vector validation → normalization → native HNSW nearest routes → cosine threshold → typed `RouteMatch` values.
+
+One representative embedding per route. HNSW is approximate; thresholds are inclusive and do not guarantee intent classification quality. This is a Python semantic policy over the native core index, not a binding to the separate neural router or an embedding model. Mutation rebuilds the index before committing, ensuring replacements and deletions cannot leave stale routes, at a cost proportional to the number of routes. Designed for small intent catalogs rather than high frequency writes to large indexes. Ties among retrieved results sort by name.
+
+Python 3.10 or later; runtime `ruvector==0.1.3`. [Portfolio documentation](https://github.com/ruvnet/RuVector/tree/main/python/portfolio).

ruvector_router-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+ruvector_router/__init__.py,sha256=sjCH9cdLpgZJ2EsnuudTRzUhHKj_lQQtNdYit4Mshsk,3318
+ruvector_router/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ruvector_router-0.2.0.dist-info/METADATA,sha256=JzgGYQkt5JY2xehOUHkzaiBXh5oi5nZpwdrdDVBNVfc,2599
+ruvector_router-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ruvector_router-0.2.0.dist-info/licenses/LICENSE,sha256=UP77k1YK9EITacmck8whTNg1sxgat_FjI_nm8t7YcOM,1060
+ruvector_router-0.2.0.dist-info/RECORD,,

ruvector_router-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_router-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.