hyperretro 0.3.0__py3-none-any.whl

hyperretro-0.3.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: hyperretro
+Version: 0.3.0
+Summary: Geometric LLM compression: factor+int4 with verifiable quality certificates
+Author-email: "William Ken Ohara Stewart (NagusameCS)" <nagusamecs@proton.me>
+License: MIT License
+        
+        Copyright (c) 2026 William "Nagusame" Ken Ohara Stewart
+        
+        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.
+        
+Project-URL: Repository, https://github.com/NagusameCS/HyperTensor
+Project-URL: Documentation, https://github.com/NagusameCS/HyperTensor/tree/main/hyperretro
+Project-URL: Issues, https://github.com/NagusameCS/HyperTensor/issues
+Project-URL: Changelog, https://github.com/NagusameCS/HyperTensor/blob/main/CHANGELOG.md
+Keywords: llm,compression,quantization,speculative-decoding,pytorch,huggingface,vllm,gguf,safetensors,low-rank,svd,grc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: safetensors>=0.4
+Provides-Extra: hf
+Requires-Dist: transformers>=4.40; extra == "hf"
+Requires-Dist: torch>=2.1; extra == "hf"
+Requires-Dist: huggingface_hub>=0.20; extra == "hf"
+Provides-Extra: vllm
+Requires-Dist: vllm>=0.5; extra == "vllm"
+Provides-Extra: bench
+Requires-Dist: torch>=2.1; extra == "bench"
+Requires-Dist: transformers>=4.40; extra == "bench"
+Requires-Dist: datasets>=2.18; extra == "bench"
+Requires-Dist: tqdm; extra == "bench"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# HyperRetro
+
+**HyperTensor, retrofitted into the PyTorch / HuggingFace / vLLM ecosystem.**
+
+HyperTensor proper is a standalone runtime. HyperRetro is the *integrated*
+sibling project: it takes the same geometric primitives (UGT shared basis,
+GRC / sink-aware projection, geodesic speculative draft, fused dual-Q8
+GEMV) and exposes them as drop-in pieces of the standard inference stack.
+
+```
+hyperretro/
+├── kernels/        # PyTorch C++ extension (gemv_dual_q8_0, ...)
+├── hf/             # offline HuggingFace compression -> .safetensors
+├── vllm/           # speculative-decoding draft adapter
+└── bench/          # 3-way benchmark harness (baseline | retro | HyperTensor)
+```
+
+## Three retrofits
+
+### 1. Fused kernels as a PyTorch extension
+
+The CUDA kernel `kernel_gemv_dual_q8_0` from
+[`runtime/nn/cuda_kernels.cu`](../runtime/nn/cuda_kernels.cu) is wrapped as a
+JIT-built `torch.utils.cpp_extension` so users can call it from regular
+PyTorch:
+
+```python
+import hyperretro
+import torch
+
+x = torch.randn(4096)
+# Wa, Wb may be float matrices or pre-quantized (scale, codes) tuples
+out_a, out_b = hyperretro.gemv_dual_q8_0(x, Wa, Wb)
+```
+
+Backend resolution: `cext` (JIT-compiled C extension) → `torch` (pure
+torch reference) → `numpy` (always works). Force the fallback with
+`HYPERRETRO_FORCE_FALLBACK=1`.
+
+### 2. Offline HuggingFace compression
+
+A single CLI takes a vanilla HF model, runs the GRC projection / sink-aware
+GRC pipeline ([Paper E](../ARXIV_SUBMISSIONS/paper-V)), and writes the
+result back out as standard `.safetensors` shards that load with stock
+`AutoModelForCausalLM.from_pretrained`:
+
+```bash
+pip install -e hyperretro[hf]
+hyperretro-compress \
+    --model Qwen/Qwen2.5-0.5B-Instruct \
+    --out ./qwen-grc-1024/ \
+    --rank 1024 \
+    --sink 4
+```
+
+The output directory is 100 % HuggingFace-native — no HyperTensor runtime
+needed at inference time. A `hyperretro_report.json` is written alongside
+recording the per-layer Frobenius rel-err.
+
+### 3. Geodesic speculative draft for vLLM
+
+`hyperretro.vllm.GeodesicDraft` replaces the random / smaller-model draft
+proposer in vLLM-style speculative decoding with the geodesic-step
+draft from [Paper C](../docs/papers/03-speculative-decoding.html). The
+adapter is framework-agnostic (`propose(h_curr, h_prev) -> (token_ids,
+confidences)`) and includes a `register_with_vllm()` hook for live
+deployments.
+
+## Benchmarks
+
+```bash
+hyperretro-bench kernel  --rows 4096 --in-dim 4096
+hyperretro-bench spec    --d-model 512 --k 64 --vocab 2048 --steps 64
+hyperretro-bench compress --model Qwen/Qwen2.5-0.5B --out /tmp/qwen-retro \
+                         --rank 256 --eval-text "The quick brown fox..."
+```
+
+Each subcommand emits a JSON report comparing **standard baseline**,
+**HyperRetro**, and (where applicable) **standalone HyperTensor**.
+
+## License
+
+MIT for code, CC-BY-4.0 for the accompanying documentation/papers — same
+as the parent HyperTensor project.

hyperretro-0.3.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+hyperretro-0.3.0.dist-info/licenses/LICENSE,sha256=Y6hoyise223tZL3FphgIR7K87fvF9jfXeMYtNrnTKkg,1114
+hyperretro-0.3.0.dist-info/METADATA,sha256=0F-pcqQd8HZicRRq2QqRYqH0F5IvXlJzy0l9lZdHfv8,6196
+hyperretro-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hyperretro-0.3.0.dist-info/entry_points.txt,sha256=AWAmTID1J8IzsoVqHpzRRMASBcB1R7LnRO0CZf4Hceg,261
+hyperretro-0.3.0.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+hyperretro-0.3.0.dist-info/RECORD,,

hyperretro-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hyperretro-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+hyperretro = hyperretro.cli:main
+hyperretro-bench = hyperretro.bench.run:_cli_main
+hyperretro-compress = hyperretro.hf.compress:_cli_main
+hyperretro-distill = hyperretro.hf.distill:_cli_main
+hyperretro-vllm = hyperretro.vllm_adapter:_cli_main

hyperretro-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William "Nagusame" Ken Ohara Stewart
+
+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.

hyperretro-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+