hyperglyph-codec 0.1.0__py3-none-any.whl

hyperglyph_codec-0.1.0.dist-info/METADATA

@@ -0,0 +1,627 @@
+Metadata-Version: 2.4
+Name: hyperglyph-codec
+Version: 0.1.0
+Summary: Hyperdimensional symbolic residual compression for neural network weights
+Author: Robert McMenemy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: compression,hyperdimensional-computing,machine-learning,model-compression,neural-networks,pytorch,quantization,research
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Provides-Extra: torch
+Requires-Dist: torch; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# Hyper Glyph
+
+<p align="center">
+  Hyperdimensional symbolic residual compression for neural network weights.
+</p>
+
+<p align="center">
+  <img width="256" height="256" alt="Hyper Glyph Logo" src="https://github.com/Arkay92/Hyper-Glyph/raw/main/hyperglyph.png" />
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/hyperglyph-codec/"><img alt="PyPI" src="https://img.shields.io/pypi/v/hyperglyph-codec.svg" /></a>
+  <img alt="Python" src="https://img.shields.io/pypi/pyversions/hyperglyph-codec.svg" />
+  <img alt="License" src="https://img.shields.io/pypi/l/hyperglyph-codec.svg" />
+  <img alt="Status" src="https://img.shields.io/badge/status-alpha-orange.svg" />
+</p>
+
+> **Package name:** `hyperglyph-codec`  
+> **Project name:** Hyper Glyph  
+> **Install:** `pip install hyperglyph-codec`  
+> **Import:** `from hyperglyph import HyperGlyphCodec`
+
+**Hyper Glyph** combines:
+
+- **Block-level tensor compression** for NumPy arrays and neural network weights.
+- **Symbolic prototype assignment** to represent repeated weight patterns compactly.
+- **Sparse residual repair** to preserve reconstruction fidelity after prototype decoding.
+- **Configurable compression controls** for block size, prototype count, residual size, and tensor filtering.
+- **State dict compression** for model-like parameter dictionaries.
+- **Optional PyTorch support** for loading, compressing, restoring, and benchmarking `.pt` state dicts.
+- **`.hwz` serialization** for saving compressed models as portable archives.
+- **Compression reports** with size ratio, tensor counts, and reconstruction error metrics.
+- **A small CLI** for compressing, decompressing, inspecting, and benchmarking model archives.
+- **Typed Python API** designed for research, experimentation, and extension.
+
+---
+
+## Before / After
+
+```python
+import numpy as np
+
+from hyperglyph import HyperGlyphCodec, HyperGlyphConfig
+
+state_dict = {
+    "layer.weight": np.arange(1024, dtype=np.float32).reshape(32, 32),
+}
+
+config = HyperGlyphConfig(
+    block_size=16,
+    n_prototypes=32,
+    residual_k=4,
+)
+
+codec = HyperGlyphCodec(config)
+compressed = codec.compress_state_dict(state_dict)
+restored = codec.decompress_state_dict(compressed)
+report = codec.report(compressed, state_dict, restored)
+
+print(report)
+```
+
+Example output:
+
+```text
+CompressionReport(
+    original_bytes=4096,
+    compressed_bytes=...,
+    compression_ratio=...,
+    tensors_compressed=1,
+    tensors_skipped=0,
+    total_mse=...,
+    total_mae=...,
+    max_abs_error=...
+)
+```
+
+That is the core job: encode large weight tensors as reusable symbolic
+prototypes plus a small residual correction, then report the size and
+reconstruction tradeoff.
+
+Hyper Glyph v0.1.0 is an experimental research codec. It is intended for
+testing ideas around hyperdimensional and symbolic weight compression rather
+than guaranteed production compression.
+
+---
+
+## Why Hyperdimensional Weight Compression?
+
+Neural network weights often contain repeated local structure, approximate
+patterns, and redundancy that can be represented more compactly than raw
+floating-point tensors:
+
+```text
+Weight tensors
+  -> Split into fixed-size blocks
+  -> Learn reusable prototype blocks
+  -> Assign each block to a prototype
+  -> Store per-block scales
+  -> Store sparse top-k residual corrections
+
+  -> Save compressed archive
+  -> Restore approximate tensors
+  -> Report compression and reconstruction metrics
+```
+
+`Hyper Glyph` is designed for experiments where you want to inspect that
+tradeoff directly:
+
+- **Large weight matrices** that can be split into repeated local blocks.
+- **Prototype-based compression** where blocks share learned representatives.
+- **Sparse residual repair** where only the largest reconstruction corrections are stored.
+- **Approximate reconstruction** with measurable MSE, MAE, and max absolute error.
+- **State dict workflows** that match common PyTorch model storage patterns.
+- **Portable archive output** for saving and inspecting compressed runs.
+
+---
+
+## Why Not Just Quantization?
+
+Quantization changes the numeric precision of individual weights. Hyper Glyph
+uses a different representation: each tensor block is mapped to a learned
+prototype, scaled, and repaired with a sparse residual.
+
+That makes Hyper Glyph useful for experimenting with symbolic and
+hyperdimensional compression ideas, not as a drop-in replacement for mature
+quantization, pruning, or production model compression toolchains.
+
+---
+
+## Architecture
+
+```text
+Input weights
+  - NumPy arrays
+  - PyTorch state_dict values
+    |
+    v
+Compression
+  - tensor filtering
+  - block splitting
+  - prototype learning
+  - prototype assignment
+  - scale calculation
+  - sparse residual encoding
+    |
+    v
+CompressedModel
+  - compressed tensors
+  - shapes
+  - prototype ids
+  - scales
+  - residuals
+  - prototype matrices
+  - codec metadata
+    |
+    v
+Decompression and report
+  - reconstructed tensors
+  - original/compressed byte estimates
+  - compression ratio
+  - MSE / MAE / max error
+```
+
+---
+
+## Install
+
+```bash
+pip install hyperglyph-codec
+```
+
+For PyTorch state dict support:
+
+```bash
+pip install "hyperglyph-codec[torch]"
+```
+
+For documentation dependencies:
+
+```bash
+pip install "hyperglyph-codec[docs]"
+```
+
+For development:
+
+```bash
+pip install -e ".[dev,torch,docs]"
+pytest
+python -m build
+```
+
+---
+
+## Quick Start
+
+### Compress a NumPy State Dict
+
+```python
+import numpy as np
+
+from hyperglyph import HyperGlyphCodec, HyperGlyphConfig
+
+state_dict = {
+    "weight": np.arange(256, dtype=np.float32).reshape(16, 16),
+}
+
+config = HyperGlyphConfig(
+    block_size=8,
+    n_prototypes=8,
+    residual_k=2,
+)
+
+codec = HyperGlyphCodec(config)
+compressed = codec.compress_state_dict(state_dict)
+restored = codec.decompress_state_dict(compressed)
+
+print(restored["weight"].shape)
+```
+
+### Compress a PyTorch Model
+
+```python
+import torch
+
+from hyperglyph import HyperGlyphCodec, HyperGlyphConfig
+
+model = torch.nn.Sequential(
+    torch.nn.Linear(32, 32),
+    torch.nn.ReLU(),
+    torch.nn.Linear(32, 8),
+)
+
+config = HyperGlyphConfig(
+    block_size=16,
+    n_prototypes=16,
+    residual_k=4,
+)
+
+codec = HyperGlyphCodec(config)
+compressed = codec.compress_state_dict(model.state_dict())
+restored = codec.decompress_state_dict(compressed)
+
+print(f"Compressed tensors: {len(compressed.tensors)}")
+print(f"Restored keys: {sorted(restored)}")
+```
+
+### Save and Load `.hwz` Archives
+
+```python
+from hyperglyph import load_compressed, save_compressed
+
+save_compressed(compressed, "model.hwz")
+loaded = load_compressed("model.hwz")
+restored = codec.decompress_state_dict(loaded)
+```
+
+### Generate a Report
+
+```python
+report = codec.report(
+    compressed_model=compressed,
+    original_state_dict=state_dict,
+    restored_state_dict=restored,
+)
+
+print(report.compression_ratio)
+print(report.total_mse)
+print(report.max_abs_error)
+```
+
+---
+
+## CLI
+
+Compress a PyTorch state dict into a `.hwz` archive:
+
+```bash
+hyperglyph compress model.pt model.hwz
+```
+
+Tune compression settings:
+
+```bash
+hyperglyph compress model.pt model.hwz \
+  --block-size 16 \
+  --hdc-dim 4096 \
+  --n-buckets 16 \
+  --n-prototypes 128 \
+  --residual-k 8 \
+  --min-tensor-size 256
+```
+
+Restore a compressed archive back to a PyTorch state dict:
+
+```bash
+hyperglyph decompress model.hwz restored.pt
+```
+
+Inspect archive metadata:
+
+```bash
+hyperglyph inspect model.hwz
+```
+
+Benchmark compression and reconstruction:
+
+```bash
+hyperglyph benchmark model.pt
+```
+
+---
+
+## Benchmark Example
+
+A small practical benchmark is enough to see the current codec behavior:
+
+```bash
+hyperglyph benchmark model.pt
+```
+
+Example report fields:
+
+```text
+original_bytes
+compressed_bytes
+compression_ratio
+tensors_compressed
+tensors_skipped
+total_mse
+total_mae
+max_abs_error
+```
+
+The current package focuses on transparent compression experiments rather than
+claiming universal size reductions. Compare the restored model against your own
+accuracy, latency, and reconstruction thresholds.
+
+---
+
+## Main Features
+
+### 1. **Configurable Codec**
+
+Tune the compression shape with one dataclass:
+
+```python
+from hyperglyph import HyperGlyphConfig
+
+config = HyperGlyphConfig(
+    hdc_dim=4096,
+    block_size=16,
+    n_buckets=16,
+    n_prototypes=128,
+    residual_k=8,
+    seed=42,
+    min_tensor_size=256,
+    compress_bias=False,
+)
+```
+
+### 2. **Array Compression**
+
+Compress and reconstruct a single NumPy array:
+
+```python
+import numpy as np
+
+from hyperglyph import HyperGlyphCodec
+
+codec = HyperGlyphCodec()
+array = np.random.randn(64, 64).astype("float32")
+
+compressed = codec.compress_array("layer.weight", array)
+restored = codec.decompress_array(compressed)
+```
+
+### 3. **State Dict Compression**
+
+Compress dictionary-style model weights:
+
+```python
+compressed = codec.compress_state_dict(state_dict)
+restored = codec.decompress_state_dict(compressed)
+```
+
+By default, small tensors and bias tensors are skipped. Set `min_tensor_size`
+and `compress_bias` in `HyperGlyphConfig` to change that behavior.
+
+### 4. **Sparse Residual Repair**
+
+Each block is reconstructed from a prototype and scale, then corrected with a
+top-k sparse residual:
+
+```text
+block ~= prototype[prototype_id] * scale + sparse_residual
+```
+
+Increase `residual_k` for better reconstruction fidelity, or reduce it for a
+smaller compressed representation.
+
+### 5. **Serialization**
+
+Save compressed models as `.hwz` zip archives:
+
+```python
+from hyperglyph import load_compressed, save_compressed
+
+save_compressed(compressed, "model.hwz")
+loaded = load_compressed("model.hwz")
+```
+
+### 6. **PyTorch Adapter**
+
+Install the `torch` extra to convert PyTorch tensors into compressed Hyper Glyph
+models:
+
+```python
+from hyperglyph import compress_state_dict, decompress_state_dict
+
+compressed = compress_state_dict(model.state_dict())
+restored = decompress_state_dict(compressed, reference_state_dict=model.state_dict())
+```
+
+### 7. **Compression Metrics**
+
+Measure the compression and reconstruction tradeoff:
+
+```python
+report = codec.report(compressed, state_dict, restored)
+
+print(report.original_bytes)
+print(report.compressed_bytes)
+print(report.compression_ratio)
+print(report.total_mse)
+print(report.total_mae)
+print(report.max_abs_error)
+```
+
+---
+
+## Configuration
+
+```python
+from hyperglyph import HyperGlyphConfig
+
+config = HyperGlyphConfig(
+    hdc_dim=4096,
+    block_size=16,
+    n_buckets=16,
+    n_prototypes=128,
+    residual_k=8,
+    seed=42,
+    min_tensor_size=256,
+    compress_bias=False,
+    dtype="float32",
+    device="cpu",
+)
+```
+
+Key settings:
+
+- **`block_size`** controls how many flattened weights are grouped together.
+- **`n_prototypes`** controls how many reusable block representatives are learned.
+- **`residual_k`** controls how many residual correction values are stored per block.
+- **`min_tensor_size`** skips tensors too small to benefit from compression.
+- **`compress_bias`** enables compression for bias tensors, which are skipped by default.
+- **`seed`** makes prototype selection deterministic.
+
+---
+
+## Examples
+
+```python
+import numpy as np
+
+from hyperglyph import HyperGlyphCodec, HyperGlyphConfig
+
+state_dict = {
+    "encoder.weight": np.random.randn(128, 128).astype("float32"),
+    "decoder.weight": np.random.randn(128, 64).astype("float32"),
+}
+
+codec = HyperGlyphCodec(
+    HyperGlyphConfig(
+        block_size=16,
+        n_prototypes=64,
+        residual_k=8,
+    )
+)
+
+compressed = codec.compress_state_dict(state_dict)
+restored = codec.decompress_state_dict(compressed)
+report = codec.report(compressed, state_dict, restored)
+
+print(report)
+```
+
+```bash
+hyperglyph compress model.pt model.hwz
+hyperglyph inspect model.hwz
+hyperglyph benchmark model.pt
+```
+
+---
+
+## Project Structure
+
+```text
+src/hyperglyph/
+  __init__.py             # Public API
+  blocks.py               # Tensor flattening, block splitting, shape restore
+  cli.py                  # Command-line interface
+  codec.py                # HyperGlyphCodec and compressed dataclasses
+  config.py               # HyperGlyphConfig
+  exceptions.py           # Package exceptions
+  hdc.py                  # Hyperdimensional vector helpers
+  metrics.py              # Size and reconstruction metrics
+  prototypes.py           # Prototype learning and assignment
+  residual.py             # Sparse residual encoding and repair
+  serialization.py        # .hwz save/load helpers
+  torch_adapter.py        # Optional PyTorch integration
+  py.typed                # Typing marker
+tests/
+  test_*.py               # Unit tests
+docs/
+  algorithm.md            # Algorithm overview
+  api.md                  # API notes
+  cli.md                  # CLI examples
+  index.md                # Documentation home
+  roadmap.md              # Planned work
+examples/
+  compress_mlp.py         # PyTorch MLP compression example
+  compress_state_dict.py  # NumPy state dict compression example
+  mnist_demo.py           # MNIST-oriented demo
+hyperglyph.png            # Project logo
+pyproject.toml            # Package metadata and dependencies
+CHANGELOG.md              # Release history
+CONTRIBUTING.md           # Contribution guide
+LICENSE                   # MIT license
+```
+
+---
+
+## Development
+
+```bash
+# Install with dev, PyTorch, and docs extras
+pip install -e ".[dev,torch,docs]"
+
+# Run tests
+pytest
+
+# Run linting
+ruff check .
+
+# Type-check package code
+mypy
+
+# Build package
+python -m build
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+## Contributing
+
+Contributions are welcome. Open an issue or pull request with the model shape,
+codec configuration, expected compression behavior, reconstruction metrics, and
+any accuracy checks you used.
+
+---
+
+## Citation
+
+If you use Hyper Glyph in research, please cite:
+
+```bibtex
+@software{HyperGlyph2026,
+  title={Hyper Glyph: Hyperdimensional Symbolic Residual Compression for Neural Network Weights},
+  author={Robert McMenemy},
+  year={2026},
+  version={0.1.0},
+}
+```
+

hyperglyph_codec-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+hyperglyph/__init__.py,sha256=y4mLyDGcQqsBygUGK-uYH3JQ11OETKBoR9aOHkrHdPg,542
+hyperglyph/blocks.py,sha256=KIOrQMUYQKzXok5FPULpQNIZ7zEeR-r8TS5d9lxk1k0,1833
+hyperglyph/cli.py,sha256=YRll872p2L0Z_7stIXpTPLi8O9gl78O-yShmVjh3PYU,4220
+hyperglyph/codec.py,sha256=AEkhheZ4Po_B4zIArG74o34I5Y9xXLA2ucDyvMBtC70,7832
+hyperglyph/config.py,sha256=o_NlcObZXsxbfLHVTjnCp3GTRdtk0NEATH16YeZVL_E,1218
+hyperglyph/exceptions.py,sha256=bEybexbnni-qUX53nY9Md-7HQ5hEEjiUHdmpjRf5HcY,231
+hyperglyph/hdc.py,sha256=C4cxsh3t4803mOzmuk3NSRKOYpe0Q-ppPgFBbLDPNbk,2189
+hyperglyph/metrics.py,sha256=-qfu7Q6mCl9lJQwzAqdoT2sbZcq5TiLfErmsOb2ENqI,2141
+hyperglyph/prototypes.py,sha256=aSg8Z0loK8lp36WOu4kEd7tOf0v27GbVPOspqpr-aCo,2479
+hyperglyph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hyperglyph/residual.py,sha256=Cr93tx0T-7pC4DVNlECxdSeGHrZtgi_XiTUpaqvHelQ,1580
+hyperglyph/serialization.py,sha256=Uy0ny5ezO8BxpZXx2BYmMEogRMZQFX_UXr_BXmz-4Es,2978
+hyperglyph/torch_adapter.py,sha256=2wnTznlDoEr-8ewgDRNPAM_v_cCd8mqauJjKWOf03qc,2299
+hyperglyph_codec-0.1.0.dist-info/METADATA,sha256=952AN_OTENZ-Wax4BwaSVU41oWkOLqH3aGtwORs1l5s,15233
+hyperglyph_codec-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+hyperglyph_codec-0.1.0.dist-info/entry_points.txt,sha256=yoRAHIDr2Qm2RaIW17eVOGbZx3IqOP7bfuJiVEzJbWs,51
+hyperglyph_codec-0.1.0.dist-info/licenses/LICENSE,sha256=lyYmqzkoDh1IH05AKxjL_wfMtVWqpqpjrQgjITQR01M,1117
+hyperglyph_codec-0.1.0.dist-info/RECORD,,

hyperglyph_codec-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

hyperglyph_codec-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hyperglyph = hyperglyph.cli:main

hyperglyph_codec-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert McMenemy
+
+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, ACTION OF
+CONTRACT, NEGLIGENCE OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.