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).
