spectral-kv-benchmark

SpectralKV: Fourier-Wavelet Hybrid Methods for KV Cache Compression

Author: C. Keasey | Affiliation: CKZ Data Labs Ltd
Paper: paper.md — Full research paper with analysis
Code: All compressors (PyTorch + MLX), evaluation suite, and raw results

Key Results (Qwen2.5-0.5B, 4K-token document, budget=512)

Cache Compression

All spectral pruning methods: 50.3 → 7.1 MB (7.1× compression, 86% saved)
TurboQuant-4bit: 1.0× (no savings in simulated-dequant mode)

Attention Output Perturbation (AOP — lower is better)

Perplexity (ND-PPL — lower is better)

Multi-Turn Cache Drift (5 turns — lower drift is better)

Generation Throughput

Key Findings

1. WaveletKV achieves lowest attention perturbation — 18% lower than TurboQuant, validating multi-resolution localization
2. WaveletTriAttention achieves best perplexity among pruning methods — trig prior captures positional distance preferences
3. All spectral methods deliver 86% memory savings at throughput parity (~33 tok/s)
4. WaveletFourierKV uniquely self-corrects over multi-turn — cascaded DWT→FFT captures complementary temporal structure
5. No single method dominates all metrics — choose by deployment scenario

Architecture

spectral_kv/
├── __init__.py
├── compressors.py           # PyTorch/CUDA (FourierKV, WaveletKV, WaveletFourierKV, etc.)
├── compressors_mlx.py       # MLX for Apple Silicon
├── metrics.py               # AOP, spectral fidelity, reconstruction metrics
├── benchmark.py             # Synthetic + real model benchmark
├── eval_comprehensive.py    # Full 4-phase evaluation suite
results/
├── eval_v3.json             # Raw results from comprehensive evaluation
├── benchmark_results.json   # Synthetic benchmark results
paper.md                     # Full research paper

Quick Start

pip install torch transformers accelerate PyWavelets scipy tabulate

# Run comprehensive evaluation
python -m spectral_kv.eval_comprehensive

# Run synthetic benchmark
python -m spectral_kv.benchmark

Improvements (v2→v3)

1. Tukey window — smooth cosine roll-off in frequency mask (eliminates Gibbs ringing)
2. Cascaded DWT→FFT — per-band FFT within wavelet scales for joint time-frequency scoring
3. Adaptive alpha — non-stationarity measurement drives wavelet/Fourier blend ratio
4. Recency + norm bias — 20% recency + 20% key-norm in all spectral scorers

References

• TriAttention (Mao et al., 2026)
• TreeKV (He et al., 2025)
• FreqKV (2025)
• Ada-KV (Feng et al., 2024)
• SCBench (Yue et al., 2024)

License

Apache 2.0