ruvector-ruvllm 0.2.0__py3-none-any.whl

ruvector_ruvllm/__init__.py

@@ -0,0 +1,68 @@
+"""Bounded full precision token caches backed by native ruvllm Rust code."""
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from ruvector import KVCache
+
+__all__ = ["KVCache", "TokenCache"]
+
+
+class TokenCache:
+    """Row-shaped interface to the native KVCache.
+
+    append accepts (tokens, dimensions) arrays. Attention is a single
+    flattened head, not a model inference or text generation API.
+    """
+
+    def __init__(self, dimensions: int, max_tokens: int = 4096) -> None:
+        if isinstance(dimensions, bool) or isinstance(max_tokens, bool):
+            raise ValueError("dimensions and max_tokens must be integers, not booleans")
+        self._cache = KVCache(dimensions, max_tokens)
+
+    @property
+    def dimensions(self) -> int:
+        return self._cache.dimensions
+
+    @property
+    def max_tokens(self) -> int:
+        return self._cache.max_tokens
+
+    def __len__(self) -> int:
+        return len(self._cache)
+
+    def append(self, keys: ArrayLike, values: ArrayLike) -> None:
+        """Append matching token matrices, without eviction or quantization.
+
+        Finite values must have magnitude at most 1e10. Conversion to
+        float32 may copy input arrays. Invalid input never changes the cache.
+        """
+        k = np.asarray(keys)
+        v = np.asarray(values)
+        if k.ndim != 2 or v.shape != k.shape or k.shape[1] != self.dimensions:
+            raise ValueError("keys and values must share shape (tokens, dimensions)")
+        if k.shape[0] == 0 or k.shape[0] > self.max_tokens - len(self):
+            raise ValueError("empty batch or cache capacity exceeded")
+        for data in (k, v):
+            if data.dtype.kind not in "iuf" or not np.isfinite(data).all() or (np.abs(data.astype(np.float64)) > 1e10).any():
+                raise ValueError("coordinates must be finite real numbers with magnitude <= 1e10")
+        self._cache.append(k.astype(np.float32).ravel().tolist(), v.astype(np.float32).ravel().tolist())
+
+    def attend(self, query: ArrayLike, scale: float | None = None) -> NDArray[np.float32]:
+        """Return softmax attention output; default scale = 1/sqrt(dimensions)."""
+        q = np.asarray(query)
+        if q.shape != (self.dimensions,) or q.dtype.kind not in "iuf":
+            raise ValueError("query must be a real vector with shape (dimensions,)")
+        if not np.isfinite(q).all() or (np.abs(q.astype(np.float64)) > 1e10).any():
+            raise ValueError("query must be finite with magnitude <= 1e10")
+        return np.asarray(self._cache.attend(q.astype(np.float32).tolist(), scale), dtype=np.float32)
+
+    def get_all(self) -> tuple[NDArray[np.float32], NDArray[np.float32]]:
+        """Return copied (keys, values) matrices in insertion order."""
+        keys, values = self._cache.get_all()
+        return (np.asarray(keys, dtype=np.float32).reshape(-1, self.dimensions),
+                np.asarray(values, dtype=np.float32).reshape(-1, self.dimensions))
+
+    def clear(self) -> None:
+        """Discard all cached tokens."""
+        self._cache.clear()

ruvector_ruvllm-0.2.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: ruvector-ruvllm
+Version: 0.2.0
+Summary: Bounded native Rust key value cache and attention primitives for Python LLM pipelines
+Project-URL: Homepage, https://github.com/ruvnet/RuVector
+Project-URL: Documentation, https://github.com/ruvnet/RuVector/tree/main/python/portfolio/ruvector-ruvllm
+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: attention,kv-cache,llm,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-ruvllm: Native Rust KV cache for Python
+
+![Animated ruvllm token cache and attention overview](https://raw.githubusercontent.com/ruvnet/RuVector/main/docs/python-portfolio/ruvllm.svg)
+
+## What is ruvector-ruvllm?
+
+A bounded CPU key/value cache and attention primitive for Python LLM pipelines, backed by the actual `ruvllm` Rust crate. Store key/value token vectors and query them with scaled dot product attention. This focused Python package exposes cache operations, **not text generation or full npm ruvllm feature parity**. No model weights or hosted services are required.
+
+## Getting started
+
+Requires Python 3.10 or newer and a platform supported by `ruvector==0.1.3` native wheels.
+
+```bash
+pip install ruvector-ruvllm==0.2.0
+```
+
+This version requires publication of both the package and its pinned native runtime before that command works. In a source checkout, build/install the native SDK first, then install `./python/portfolio/ruvector-ruvllm`.
+
+```python
+from ruvector_ruvllm import TokenCache
+
+cache = TokenCache(dimensions=2, max_tokens=128)
+cache.append(keys=[[1.0, 0.0], [0.0, 1.0]],
+             values=[[2.0, 4.0], [8.0, 10.0]])
+answer = cache.attend([1.0, 0.0])
+assert answer.shape == (2,)
+assert len(cache) == 2
+keys, values = cache.get_all()
+assert keys.shape == values.shape == (2, 2)
+cache.clear()
+assert len(cache) == 0
+```
+
+## Architecture
+
+```mermaid
+flowchart TD
+    A[Python token matrices] --> B[Shape and finite value validation]
+    B --> C[PyO3 KVCache]
+    C --> D[ruvllm full precision cache]
+    D --> E[Scaled softmax attention output]
+```
+
+The shared runtime keeps computation in Rust. The row-shaped Python interface converts inputs to float32. For flat inputs, `from ruvector_ruvllm import KVCache` exposes the native class directly.
+
+## API and limits
+
+| Operation | Behavior |
+| --- | --- |
+| `TokenCache(dimensions, max_tokens=4096)` | Create an empty bounded cache |
+| `append(keys, values)` | Add matching matrices shaped `(tokens, dimensions)` |
+| `attend(query, scale=None)` | Return float32 vector; default scale is `1/sqrt(dimensions)` |
+| `get_all()` | Copy all keys and values into matrices |
+| `clear()` | Remove all tokens |
+| `len(cache)` | Number of stored tokens |
+
+Attention treats each token as one vector, not independent attention heads. The implementation retains full float32 precision, with no quantization, sliding window or automatic eviction. Capacity errors leave the cache unchanged. Empty-cache attention returns zeros.
+
+Dimensions are limited to 4096, tokens to 65536, and their product to 8388608. Raw keys and values therefore occupy at most 64 MiB, excluding objects, conversion buffers and returned copies. Coordinates must be finite and have absolute value at most `1e10`. Isolate untrusted workloads with process memory limits because Python conversion can allocate before native validation.
+
+## Relationship to npm and Rust
+
+Inspired by the popular npm `ruvllm` package, using the repository's real Rust cache implementation. This release does not expose model loading, tokenization, GPU inference, serving, learning or text generation. It ships a focused wrapper over the shared `ruvector` native runtime rather than a separate binary engine.
+
+Source: [RuVector](https://github.com/ruvnet/RuVector). [Security policy](https://github.com/ruvnet/RuVector/blob/main/python/portfolio/SECURITY.md). License: MIT.

ruvector_ruvllm-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+ruvector_ruvllm/__init__.py,sha256=yw3LdI7yOzzghDAlOKm7IVpvQLE_FwSpf3k_2hKCIR8,3092
+ruvector_ruvllm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ruvector_ruvllm-0.2.0.dist-info/METADATA,sha256=RDwBAq_jzyt1esDPiqlaG67caht1IYCnhib34UpSZDA,4382
+ruvector_ruvllm-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ruvector_ruvllm-0.2.0.dist-info/licenses/LICENSE,sha256=UP77k1YK9EITacmck8whTNg1sxgat_FjI_nm8t7YcOM,1060
+ruvector_ruvllm-0.2.0.dist-info/RECORD,,

ruvector_ruvllm-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_ruvllm-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.