hyperglyph-codec 0.1.0__py3-none-any.whl

hyperglyph/__init__.py

@@ -0,0 +1,19 @@
+"""Hyper Glyph package."""
+
+from .codec import CompressedModel, CompressedTensor, CompressionReport, HyperGlyphCodec
+from .config import HyperGlyphConfig
+from .serialization import load_compressed, save_compressed
+from .torch_adapter import compress_state_dict, decompress_state_dict
+
+__all__ = [
+    "HyperGlyphCodec",
+    "HyperGlyphConfig",
+    "CompressionReport",
+    "CompressedModel",
+    "CompressedTensor",
+    "compress_state_dict",
+    "decompress_state_dict",
+    "save_compressed",
+    "load_compressed",
+]
+__version__ = "0.1.0"

hyperglyph/blocks.py

@@ -0,0 +1,49 @@
+"""Helpers for splitting arrays into blocks."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def pad_tensor_to_blocks(array: np.ndarray, block_size: int) -> tuple[np.ndarray, tuple[int, ...]]:
+    """Pad a flattened tensor so its size is divisible by block_size."""
+    if block_size <= 0:
+        raise ValueError("block_size must be positive")
+    flattened = array.reshape(-1)
+    remainder = flattened.size % block_size
+    if remainder == 0:
+        return flattened.copy(), tuple(array.shape)
+    padded_size = flattened.size + (block_size - remainder)
+    padded = np.pad(flattened, (0, padded_size - flattened.size), mode="constant")
+    return padded.astype(np.float32), tuple(array.shape)
+
+
+def split_array_blocks(array: np.ndarray, block_size: int) -> list[np.ndarray]:
+    """Split a flat or regular array into blocks of size block_size."""
+    padded, _ = pad_tensor_to_blocks(array, block_size)
+    flat_padded = padded.reshape(-1)
+    return [
+        flat_padded[index : index + block_size] for index in range(0, flat_padded.size, block_size)
+    ]
+
+
+def merge_array_blocks(
+    blocks: list[np.ndarray],
+    original_shape: tuple[int, ...],
+    padded_shape: tuple[int, ...],
+    block_size: int,
+) -> np.ndarray:
+    """Merge blocks back into their original shape."""
+    flat = np.concatenate(blocks, axis=0)
+    flat = flat[: int(np.prod(original_shape))]
+    return flat.reshape(original_shape)
+
+
+def flatten_tensor_for_blocks(array: np.ndarray) -> np.ndarray:
+    """Flatten tensors to 1D for block processing."""
+    return np.asarray(array, dtype=np.float32).reshape(-1)
+
+
+def restore_tensor_shape(array: np.ndarray, original_shape: tuple[int, ...]) -> np.ndarray:
+    """Restore a flattened vector to the original shape."""
+    return np.asarray(array, dtype=np.float32).reshape(original_shape)

hyperglyph/cli.py

@@ -0,0 +1,112 @@
+"""Command-line interface for Hyper Glyph."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Sequence
+
+try:
+    import torch  # type: ignore
+except ImportError:  # pragma: no cover - optional dependency path
+    torch = None
+
+from .codec import HyperGlyphCodec
+from .config import HyperGlyphConfig
+from .serialization import load_compressed, save_compressed
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser."""
+    parser = argparse.ArgumentParser(prog="hyperglyph", description="Hyper Glyph compression CLI")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    compress_parser = subparsers.add_parser("compress")
+    compress_parser.add_argument("input", help="Input torch state dict file (.pt)")
+    compress_parser.add_argument("output", help="Output .hwz file")
+    compress_parser.add_argument("--block-size", type=int, default=16)
+    compress_parser.add_argument("--hdc-dim", type=int, default=4096)
+    compress_parser.add_argument("--n-buckets", type=int, default=16)
+    compress_parser.add_argument("--n-prototypes", type=int, default=128)
+    compress_parser.add_argument("--residual-k", type=int, default=8)
+    compress_parser.add_argument("--seed", type=int, default=42)
+    compress_parser.add_argument("--compress-bias", action="store_true")
+    compress_parser.add_argument("--min-tensor-size", type=int, default=256)
+
+    decompress_parser = subparsers.add_parser("decompress")
+    decompress_parser.add_argument("input", help="Input .hwz file")
+    decompress_parser.add_argument("output", help="Output torch state dict file (.pt)")
+
+    inspect_parser = subparsers.add_parser("inspect")
+    inspect_parser.add_argument("input", help="Input .hwz file")
+
+    benchmark_parser = subparsers.add_parser("benchmark")
+    benchmark_parser.add_argument("input", help="Input torch state dict file (.pt)")
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI."""
+    parser = build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+
+    if args.command == "compress":
+        if torch is None:
+            raise SystemExit("PyTorch is required for the compress/decompress CLI commands")
+        state_dict = torch.load(args.input, map_location="cpu")
+        config = HyperGlyphConfig(
+            hdc_dim=args.hdc_dim,
+            block_size=args.block_size,
+            n_buckets=args.n_buckets,
+            n_prototypes=args.n_prototypes,
+            residual_k=args.residual_k,
+            seed=args.seed,
+            compress_bias=args.compress_bias,
+            min_tensor_size=args.min_tensor_size,
+        )
+        codec = HyperGlyphCodec(config)
+        compressed = codec.compress_state_dict(state_dict)
+        save_compressed(compressed, args.output)
+        print(f"Saved compressed model to {args.output}")
+        return 0
+
+    if args.command == "decompress":
+        if torch is None:
+            raise SystemExit("PyTorch is required for the compress/decompress CLI commands")
+        compressed = load_compressed(args.input)
+        restored = HyperGlyphCodec().decompress_state_dict(compressed)
+        torch.save(restored, args.output)
+        print(f"Restored state dict to {args.output}")
+        return 0
+
+    if args.command == "inspect":
+        compressed = load_compressed(args.input)
+        print(
+            json.dumps(
+                {
+                    "format_version": compressed.format_version,
+                    "tensor_count": len(compressed.tensors),
+                },
+                indent=2,
+            )
+        )
+        return 0
+
+    if args.command == "benchmark":
+        if torch is None:
+            raise SystemExit("PyTorch is required for benchmark CLI commands")
+        state_dict = torch.load(args.input, map_location="cpu")
+        codec = HyperGlyphCodec()
+        compressed = codec.compress_state_dict(state_dict)
+        restored = codec.decompress_state_dict(compressed)
+        report = codec.report(compressed, state_dict, restored)
+        print(report)
+        return 0
+
+    parser.error("unknown command")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hyperglyph/codec.py

@@ -0,0 +1,200 @@
+"""Main compression codec."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+import numpy as np
+
+from .blocks import restore_tensor_shape, split_array_blocks
+from .config import HyperGlyphConfig
+from .metrics import (
+    compressed_size_bytes,
+    compression_ratio,
+    mae,
+    max_abs_error,
+    mse,
+    original_size_bytes,
+)
+from .prototypes import assign_prototypes, learn_prototypes, reconstruct_from_prototypes
+from .residual import apply_residual, compute_topk_residual, serialize_residual
+
+
+@dataclass(slots=True)
+class CompressedTensor:
+    """Compressed representation for a single tensor."""
+
+    name: str
+    shape: tuple[int, ...]
+    block_size: int
+    prototype_ids: list[int]
+    scales: list[float]
+    residuals: list[dict[str, Any]]
+    prototype_matrix: np.ndarray
+    seed: int
+    codec_config: dict[str, Any]
+
+
+@dataclass(slots=True)
+class CompressedModel:
+    """Compressed representation of a model state_dict."""
+
+    tensors: dict[str, CompressedTensor]
+    payload: bytes = field(default_factory=bytes)
+    format_version: str = "0.1"
+
+
+@dataclass(slots=True)
+class CompressionReport:
+    """Report about a compression run."""
+
+    original_bytes: int
+    compressed_bytes: int
+    compression_ratio: float
+    tensors_compressed: int
+    tensors_skipped: int
+    total_mse: float
+    total_mae: float
+    max_abs_error: float
+
+
+class HyperGlyphCodec:
+    """A simple experimental compression codec for weight tensors."""
+
+    def __init__(self, config: HyperGlyphConfig | None = None) -> None:
+        self.config = config or HyperGlyphConfig()
+
+    def compress_array(self, name: str, array: np.ndarray) -> CompressedTensor:
+        """Compress a single NumPy array."""
+        array = np.asarray(array, dtype=np.float32)
+        if array.size < self.config.min_tensor_size:
+            raise ValueError("tensor too small to compress")
+
+        blocks = split_array_blocks(array, self.config.block_size)
+        if not blocks:
+            raise ValueError("no blocks available")
+
+        block_matrix = np.stack([np.asarray(block, dtype=np.float32) for block in blocks], axis=0)
+        prototypes = learn_prototypes(block_matrix, self.config.n_prototypes, self.config.seed)
+        assignments = assign_prototypes(block_matrix, prototypes)
+        reconstructed_prototypes = reconstruct_from_prototypes(assignments, prototypes)
+
+        prototype_ids: list[int] = [int(idx) for idx in assignments]
+        scales: list[float] = []
+        residuals: list[dict[str, Any]] = []
+        for idx, block in enumerate(blocks):
+            proto = reconstructed_prototypes[idx]
+            block_norm = float(np.linalg.norm(block))
+            proto_norm = max(float(np.linalg.norm(proto)), 1e-6)
+            scale = block_norm / proto_norm
+            scales.append(scale)
+            proto_scaled = proto * scale
+            residual = compute_topk_residual(block, proto_scaled, self.config.residual_k)
+            residuals.append(serialize_residual(residual))
+
+        return CompressedTensor(
+            name=name,
+            shape=tuple(array.shape),
+            block_size=self.config.block_size,
+            prototype_ids=prototype_ids,
+            scales=scales,
+            residuals=residuals,
+            prototype_matrix=prototypes,
+            seed=self.config.seed,
+            codec_config={
+                "hdc_dim": self.config.hdc_dim,
+                "block_size": self.config.block_size,
+                "n_buckets": self.config.n_buckets,
+                "n_prototypes": self.config.n_prototypes,
+                "residual_k": self.config.residual_k,
+                "seed": self.config.seed,
+                "dtype": self.config.dtype,
+                "device": self.config.device,
+            },
+        )
+
+    def decompress_array(self, compressed: CompressedTensor) -> np.ndarray:
+        """Decompress a single tensor."""
+        if not compressed.prototype_matrix.size:
+            return np.zeros(compressed.shape, dtype=np.float32)
+
+        prototype_vectors: np.ndarray = compressed.prototype_matrix.astype(np.float32)
+        reconstructed_blocks: list[np.ndarray] = []
+        for idx, prototype_id in enumerate(compressed.prototype_ids):
+            prototype = prototype_vectors[prototype_id]
+            scale = compressed.scales[idx]
+            block = prototype * scale
+            block = apply_residual(block, compressed.residuals[idx])
+            reconstructed_blocks.append(block)
+
+        flat = np.concatenate(reconstructed_blocks, axis=0)
+        return restore_tensor_shape(flat[: int(np.prod(compressed.shape))], compressed.shape)
+
+    def compress_state_dict(self, state_dict: Mapping[str, Any]) -> CompressedModel:
+        """Compress an entire state_dict."""
+        compressed_tensors: dict[str, CompressedTensor] = {}
+        for name, tensor in state_dict.items():
+            if not self._should_compress(name, tensor):
+                continue
+            compressed_tensors[name] = self.compress_array(
+                name, np.asarray(tensor, dtype=np.float32)
+            )
+        payload = json.dumps({"tensors": list(compressed_tensors)}).encode("utf-8")
+        return CompressedModel(tensors=compressed_tensors, payload=payload)
+
+    def decompress_state_dict(self, compressed_model: CompressedModel) -> dict[str, np.ndarray]:
+        """Reconstruct a state_dict from compressed data."""
+        restored: dict[str, np.ndarray] = {}
+        for name, compressed in compressed_model.tensors.items():
+            restored[name] = self.decompress_array(compressed)
+        return restored
+
+    def report(
+        self,
+        compressed_model: CompressedModel,
+        original_state_dict: Mapping[str, Any] | None = None,
+        restored_state_dict: Mapping[str, Any] | None = None,
+    ) -> CompressionReport:
+        """Create a report summarizing compression quality and size."""
+        original_bytes = original_size_bytes(original_state_dict or {})
+        compressed_bytes = compressed_size_bytes(compressed_model)
+        ratio = compression_ratio(original_bytes, compressed_bytes)
+        tensors_compressed = len(compressed_model.tensors)
+        tensors_skipped = 0
+        if original_state_dict is not None:
+            tensors_skipped = sum(
+                1 for name in original_state_dict if name not in compressed_model.tensors
+            )
+
+        total_mse = 0.0
+        total_mae = 0.0
+        max_error = 0.0
+        if original_state_dict is not None and restored_state_dict is not None:
+            for name in compressed_model.tensors:
+                if name in original_state_dict and name in restored_state_dict:
+                    original = np.asarray(original_state_dict[name], dtype=np.float32)
+                    restored = np.asarray(restored_state_dict[name], dtype=np.float32)
+                    total_mse += mse(original, restored)
+                    total_mae += mae(original, restored)
+                    max_error = max(max_error, max_abs_error(original, restored))
+        return CompressionReport(
+            original_bytes=original_bytes,
+            compressed_bytes=compressed_bytes,
+            compression_ratio=ratio,
+            tensors_compressed=tensors_compressed,
+            tensors_skipped=tensors_skipped,
+            total_mse=total_mse,
+            total_mae=total_mae,
+            max_abs_error=max_error,
+        )
+
+    def _should_compress(self, name: str, tensor: Any) -> bool:
+        if not hasattr(tensor, "shape"):
+            return False
+        if self.config.compress_bias:
+            return int(np.prod(tensor.shape)) >= self.config.min_tensor_size
+        return (
+            "bias" not in name.lower() and int(np.prod(tensor.shape)) >= self.config.min_tensor_size
+        )

hyperglyph/config.py

@@ -0,0 +1,37 @@
+"""Configuration dataclasses for Hyper Glyph."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class HyperGlyphConfig:
+    """Configuration for the Hyper Glyph compression codec."""
+
+    hdc_dim: int = 4096
+    block_size: int = 16
+    n_buckets: int = 16
+    n_prototypes: int = 128
+    residual_k: int = 8
+    seed: int = 42
+    min_tensor_size: int = 256
+    compress_bias: bool = False
+    dtype: str = "float32"
+    device: str = "cpu"
+
+    def __post_init__(self) -> None:
+        if self.hdc_dim <= 0:
+            raise ValueError("hdc_dim must be positive")
+        if self.block_size <= 0:
+            raise ValueError("block_size must be positive")
+        if self.n_buckets <= 0:
+            raise ValueError("n_buckets must be positive")
+        if self.n_prototypes <= 0:
+            raise ValueError("n_prototypes must be positive")
+        if self.residual_k < 0:
+            raise ValueError("residual_k must be non-negative")
+        if self.min_tensor_size <= 0:
+            raise ValueError("min_tensor_size must be positive")
+        if self.dtype not in {"float32", "float64"}:
+            raise ValueError("dtype must be 'float32' or 'float64'")

hyperglyph/exceptions.py

@@ -0,0 +1,9 @@
+"""Exceptions for the Hyper Glyph package."""
+
+
+class HyperGlyphError(Exception):
+    """Base exception for Hyper Glyph."""
+
+
+class OptionalDependencyError(HyperGlyphError):
+    """Raised when optional dependencies are missing."""

hyperglyph/hdc.py

@@ -0,0 +1,69 @@
+"""Simple deterministic hyperdimensional computing helpers."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Iterable
+
+import numpy as np
+
+
+def _hash_seed(name: str, index: int, seed: int) -> int:
+    payload = f"{name}:{index}:{seed}".encode("utf-8")
+    return int(hashlib.sha256(payload).hexdigest()[:8], 16)
+
+
+def make_role_vector(name: str, index: int, dim: int, seed: int) -> np.ndarray:
+    """Create a deterministic bipolar role vector."""
+    rng = np.random.default_rng(_hash_seed(name, index, seed))
+    vector = rng.choice([-1.0, 1.0], size=dim)
+    return vector.astype(np.float32)
+
+
+def bind(a: np.ndarray, b: np.ndarray) -> np.ndarray:
+    """Bind two bipolar vectors via elementwise multiplication."""
+    return a * b
+
+
+def bind_many(vectors: Iterable[np.ndarray]) -> np.ndarray:
+    """Bind a sequence of vectors together."""
+    vectors = list(vectors)
+    if not vectors:
+        raise ValueError("at least one vector is required")
+    result = np.ones_like(vectors[0], dtype=np.float32)
+    for vector in vectors:
+        result = result * vector
+    return result
+
+
+def bundle(vectors: Iterable[np.ndarray]) -> np.ndarray:
+    """Bundle vectors by elementwise summation and sign."""
+    vectors = list(vectors)
+    if not vectors:
+        raise ValueError("at least one vector is required")
+    result = np.zeros_like(vectors[0], dtype=np.float32)
+    for vector in vectors:
+        result = result + vector
+    return np.sign(result)
+
+
+def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
+    """Compute cosine similarity between two vectors."""
+    a = np.asarray(a, dtype=np.float32).ravel()
+    b = np.asarray(b, dtype=np.float32).ravel()
+    denom = np.linalg.norm(a) * np.linalg.norm(b)
+    if denom == 0:
+        return 0.0
+    return float(np.dot(a, b) / denom)
+
+
+def hamming_distance(a: np.ndarray, b: np.ndarray) -> int:
+    """Compute Hamming distance between two bipolar vectors."""
+    a = np.asarray(a)
+    b = np.asarray(b)
+    return int(np.count_nonzero(a != b))
+
+
+def binarize(v: np.ndarray) -> np.ndarray:
+    """Binarize a vector to {-1, 1}."""
+    return np.sign(np.asarray(v, dtype=np.float32)).astype(np.int8)

hyperglyph/metrics.py

@@ -0,0 +1,60 @@
+"""Metrics for compression quality."""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+import numpy as np
+
+
+def original_size_bytes(state_dict: Mapping[str, np.ndarray]) -> int:
+    """Estimate the byte size of a state_dict."""
+    total = 0
+    for tensor in state_dict.values():
+        total += np.asarray(tensor).nbytes
+    return total
+
+
+def compressed_size_bytes(compressed_model: object) -> int:
+    """Estimate the compressed size in bytes."""
+    if isinstance(compressed_model, Mapping):
+        return len(compressed_model.get("payload", b""))
+    return 0
+
+
+def compression_ratio(original_bytes: int, compressed_bytes: int) -> float:
+    """Compute compression ratio as original / compressed."""
+    if compressed_bytes <= 0:
+        return float("inf")
+    return original_bytes / compressed_bytes
+
+
+def mse(original: np.ndarray, reconstructed: np.ndarray) -> float:
+    """Compute mean squared error."""
+    original = np.asarray(original, dtype=np.float32)
+    reconstructed = np.asarray(reconstructed, dtype=np.float32)
+    return float(np.mean((original - reconstructed) ** 2))
+
+
+def mae(original: np.ndarray, reconstructed: np.ndarray) -> float:
+    """Compute mean absolute error."""
+    original = np.asarray(original, dtype=np.float32)
+    reconstructed = np.asarray(reconstructed, dtype=np.float32)
+    return float(np.mean(np.abs(original - reconstructed)))
+
+
+def max_abs_error(original: np.ndarray, reconstructed: np.ndarray) -> float:
+    """Compute maximum absolute error."""
+    original = np.asarray(original, dtype=np.float32)
+    reconstructed = np.asarray(reconstructed, dtype=np.float32)
+    return float(np.max(np.abs(original - reconstructed)))
+
+
+def cosine_weight_similarity(original: np.ndarray, reconstructed: np.ndarray) -> float:
+    """Compute cosine similarity between two arrays."""
+    original = np.asarray(original, dtype=np.float32).ravel()
+    reconstructed = np.asarray(reconstructed, dtype=np.float32).ravel()
+    denom = np.linalg.norm(original) * np.linalg.norm(reconstructed)
+    if denom == 0:
+        return 0.0
+    return float(np.dot(original, reconstructed) / denom)

hyperglyph/prototypes.py

@@ -0,0 +1,60 @@
+"""Prototype learning and reconstruction helpers."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def _init_prototypes(blocks: np.ndarray, n_prototypes: int, seed: int) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    indices = rng.choice(len(blocks), size=min(n_prototypes, len(blocks)), replace=False)
+    return blocks[indices].astype(np.float32).copy()
+
+
+def learn_prototypes(blocks: np.ndarray, n_prototypes: int, seed: int) -> np.ndarray:
+    """Learn deterministic prototypes from a set of blocks using mini k-means."""
+    blocks = np.asarray(blocks, dtype=np.float32)
+    if blocks.size == 0:
+        return np.empty((0, blocks.shape[-1]), dtype=np.float32)
+    if n_prototypes <= 0:
+        raise ValueError("n_prototypes must be positive")
+
+    prototypes = _init_prototypes(blocks, n_prototypes, seed)
+    for _ in range(5):
+        distances = np.linalg.norm(blocks[:, None, :] - prototypes[None, :, :], axis=2)
+        assignments = np.argmin(distances, axis=1)
+        new_prototypes = np.empty_like(prototypes)
+        for idx in range(len(prototypes)):
+            members = blocks[assignments == idx]
+            if len(members) == 0:
+                new_prototypes[idx] = prototypes[idx]
+            else:
+                new_prototypes[idx] = members.mean(axis=0)
+        if np.allclose(new_prototypes, prototypes):
+            break
+        prototypes = new_prototypes
+    return prototypes
+
+
+def assign_prototypes(blocks: np.ndarray, prototypes: np.ndarray) -> np.ndarray:
+    """Assign each block to its nearest prototype."""
+    blocks = np.asarray(blocks, dtype=np.float32)
+    prototypes = np.asarray(prototypes, dtype=np.float32)
+    if len(prototypes) == 0:
+        return np.zeros(len(blocks), dtype=np.int32)
+    distances = np.linalg.norm(blocks[:, None, :] - prototypes[None, :, :], axis=2)
+    return np.argmin(distances, axis=1).astype(np.int32)
+
+
+def reconstruct_from_prototypes(
+    assignments: np.ndarray, prototypes: np.ndarray, scales: np.ndarray | None = None
+) -> np.ndarray:
+    """Reconstruct blocks from prototype assignments."""
+    assignments = np.asarray(assignments, dtype=np.int32)
+    prototypes = np.asarray(prototypes, dtype=np.float32)
+    if len(prototypes) == 0:
+        return np.empty((len(assignments), 0), dtype=np.float32)
+    reconstructed = prototypes[assignments]
+    if scales is not None:
+        return reconstructed * np.asarray(scales, dtype=np.float32)[:, None]
+    return reconstructed

hyperglyph/residual.py

@@ -0,0 +1,49 @@
+"""Sparse residual helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+
+def compute_topk_residual(
+    original_block: np.ndarray, reconstructed_block: np.ndarray, k: int
+) -> dict[str, Any]:
+    """Return the indices and values of the top-k residual entries."""
+    if k < 0:
+        raise ValueError("k must be non-negative")
+    if original_block.shape != reconstructed_block.shape:
+        raise ValueError("blocks must have the same shape")
+
+    diff = np.asarray(original_block, dtype=np.float32) - np.asarray(
+        reconstructed_block, dtype=np.float32
+    )
+    if k == 0:
+        return {"indices": [], "values": []}
+
+    if diff.size == 0:
+        return {"indices": [], "values": []}
+
+    flat = diff.reshape(-1)
+    topk_idx = np.argsort(np.abs(flat))[-k:][::-1]
+    return {
+        "indices": [int(index) for index in topk_idx],
+        "values": [float(flat[index]) for index in topk_idx],
+    }
+
+
+def apply_residual(block: np.ndarray, residual: dict[str, Any]) -> np.ndarray:
+    """Apply sparse residual values to a block."""
+    result = np.asarray(block, dtype=np.float32).reshape(-1).copy()
+    for index, value in zip(residual.get("indices", []), residual.get("values", [])):
+        result[int(index)] += float(value)
+    return result.reshape(block.shape)
+
+
+def serialize_residual(residual: dict[str, Any]) -> dict[str, Any]:
+    """Serialize residual metadata for JSON compatibility."""
+    return {
+        "indices": list(residual.get("indices", [])),
+        "values": list(residual.get("values", [])),
+    }