Bundled fixes & tests: V-norm accounting, OutlierTurboQuant.calibrate, rotation tests, ruff CI, HIP/AMD NaN docs

[brosequist]

Hi @TheTom — thanks for the friendly note on #61 back in April. I'd left the original six PRs (#61, #62, #63, #64, #65, #66) sitting open for a few weeks and decided to close them today and rebundle here as a single PR, hoping the smaller review surface helps you triage when you have time. All six commits still apply cleanly against main (zero rebase needed) and are preserved as separate commits in this branch so the individual rationale and git blame story stay intact.

Closing this PR if you'd rather see them re-opened individually is also fine — happy to follow whatever workflow works for you.

---

What's in this PR (6 commits, original PR refs in parens)

1. fix: V-norm in memory_stats, SeedSequence PRNG, streaming API, serialization (was #61)

• KVCacheCompressor.memory_stats() was omitting the 32-bit float norm stored per V vector, inflating the reported compression ratio. Adds v_bits_total += n_vectors * 32.
• Adds compressed_size_bits() to TurboQuantMSE (was missing; TurboQuant already had it).
• Replaces seed + 1000 offset with np.random.SeedSequence(seed).spawn(2) for true PRNG independence between the PolarQuant and QJL stages.
• Adds compress_token() / get_compressed_cache() streaming API to KVCacheCompressor for auto-regressive token-by-token inference.
• Adds CompressedVector.to_bytes() / from_bytes() for disk / network serialisation.

2. test: document QJL regression in test_turboquant_improves_over_polarquant (was #62)

• The existing test had no assertion — it only print()'d, silently allowing QJL to be worse than PolarQuant. Adds a regression-guard assertion documenting the empirical finding (TQ 2-bit avg ≈ 0.091 vs PQ 2-bit avg ≈ 0.041 inner-product distortion). If QJL is ever fixed to actually improve over PQ, the test will fail loudly and prompt re-evaluation of the production path.

3. test: add correctness and round-trip tests for fast rotation functions (was #63)

• Three property tests for fast_rotate / fast_unrotate (none of which existed previously):
  1. Round-trip invertibility — fast_unrotate(fast_rotate(x)) ≈ x
  2. Batch consistency — row-by-row equals all-at-once
  3. Energy distribution — roughly uniform per-coordinate variance after rotation

4. feat: add calibrate() to OutlierTurboQuant for data-driven channel split (was #64)

• OutlierTurboQuant.calibrate(calibration_vectors) computes per-channel RMS across a calibration set and marks channels whose RMS exceeds 3× the median as outlier channels, updating the compressor's split in place.
• Follows the dynamic-threshold approach from the LLM.int8() / SmoothQuant literature.

5. chore: add ruff linting to pyproject.toml and CI workflow (was #65)

• [tool.ruff] block in pyproject.toml (line-length=120, E/W/F, ignoring E501/E741).
• .github/workflows/lint.yml runs ruff check on push / PR.
• Pure tooling — zero behavioural changes.

6. docs: add HIP/AMD NaN warning for q8_0/turbo3 on large K-norm models (was #66)

• Prominent warning block in docs/turboquant-recommendations.md documenting observed NaN divergence when using q8_0 or turbo3 on models with large K-vector norms (e.g. Qwen2.5-7B) on AMD/ROCm (HIP) backends. Recommends turbo2 / turbo4 or pre-quantisation K-norm clipping.
• Likely related to the user-reported symptoms in [ROCm] Scale operation fails with "invalid device function" during Gemma 4 loading #86 ("[ROCm] Scale operation fails... during Gemma 4 loading") and [Bug] Numerical instability (NaN/Infinite Loop) with Qwen 2.5/3.5 models using turbo4 on RTX 4070Ti #60 ("Numerical instability with Qwen 2.5/3.5 models using turbo4").

---

Test plan

• pytest tests/test_kv_cache.py — covers V-norm accounting, streaming API, serialisation round-trip
• pytest tests/test_distortion.py::TestDistortionScaling::test_turboquant_improves_over_polarquant — QJL regression assertion
• pytest tests/test_rotation.py — fast-rotation property tests
• pytest tests/test_outlier.py — calibrate() plus all-inlier / all-outlier edge cases
• ruff check . — passes (and the new GH Actions workflow runs it on every push)
• Docs-only changes (Implement full TurboQuant (turboquant.py) — Algorithm 2 #6) — nothing to test

🤖 Generated with Claude Code

[TheTom]

hey @brosequist, first off, big apology for the delay on these. you opened the originals back in april, i sat on them way too long, and the rebundle made it much easier to review. really appreciate the patience and the diligence on the rebundle work.

i landed a curated subset in #91 with you as author on the cherry-picks. quick rundown:

merging from #90 (you authored, cherry-picked):

• ✅ V-norm fix in memory_stats + TurboQuantMSE.compressed_size_bits. split out of 0fd5de9 to keep just the fixes. real bug, accounting was off.
• ✅ SeedSequence PRNG cleanup. also split from 0fd5de9. cleaner than the magic offset.
• ✅ QJL regression-guard test. locks the production reality from docs/papers/turbo4-resurrection.md. good test.
• ✅ rotation property tests. pure additive, real coverage.
• ✅ ruff config (kept config, dropped the workflow per your follow-up).

deferred from #90:

• ⏸ streaming API (compress_token / get_compressed_cache) and binary/npz serialization (to_bytes / from_bytes / save / load). split out of 0fd5de9. solid code, but i don't have a production caller yet and want to design these for whatever ends up wiring them up. holding until that lands.
• ⏸ OutlierTurboQuant.calibrate(). the calibrate code itself is clean, but OutlierTurboQuant is a dead path on my end per docs/turboquant-plus-experiments.md (kurtosis stays high after channel removal, WHT rotation handles tails better, WUSH paper confirmed). holding for now.
• ⏸ HIP/AMD NaN docs. the root-cause story (large K norms causing NaN) actually contradicts what i'm seeing in docs/papers/asymmetric-kv-compression.md, which finds extreme K norms compress better because the post-normalization distribution becomes more Gaussian (boundary layers are ideal for Lloyd-Max). real cause is HIP-kernel-specific. happy to revisit after kernel triage.

also added a parallel K-norm accounting fix on top of yours in #91. compressed_size_bits for TurboQuant K was undercounting too (it stores two norms, not one), so #91 has both sides corrected. you flagged the V side, that pulled my attention to the K side.

thanks again for sticking with this. let me know if anything in the curation feels off, or if you'd like to take another swing at any of the deferred items with the production-caller / kernel context in mind.

[brosequist]

Thank you Tom, and no problem with these not being merged right away.

I saw that these weren't reflected on the last main fork and thought they were helpful enough fixes to re-bump, and make sure they weren't accidentally rejected/lost. I'll take a look at anything I missed the first go through that you've raised on the deferred items and see if there's anything else from there.