Add structure demotion option to KVzipPress / RestoreKVPress 🤖🤖🤖

[JeetuSK0808]

PR description

What. A default-off option on KVzipPress (inherited by RestoreKVPress): before eviction, scale the
reconstruction scores of structural tokens — punctuation/whitespace/symbol tokens that repeat ≥
structure_min_repeats times in the context and are not glued inside an identifier — by structure_demotion.
Letters and digits are never touched.

Why. On RULER-4096 at compression ratio 0.9375 (256 KV pairs per head kept), RestoreKV_plus spends about half
of its budget on the scaffolding of the context: list separators, newlines, quotes (diagnostic on cwe: ~60% of the
context is list structure; words are kept at 10%, numbers at 3.8%, whitespace at 8.7%). Reconstruction-based
scoring rates those tokens highly because they are trivially predictable from each other, not because the
answer needs them. Demoting them hands the budget to content.

Measured (Qwen3-8B, ratio 0.9375, paired 100-row screens on the same rows as the baseline, MPS+sdpa):
cwe 90.6 vs 77.2 (+13.4, 95% CI [+10.8, +16.0]); niah_multikey_1 94.0 vs 90.0 (+4.0, CI [+1.0, +8.0]);
niah_multivalue 85.5 vs 80.8 (+4.75, CI [+1.5, +7.75]); fwe 90.0 vs 82.3 (+7.67, CI [+4.67, +10.67]).

Full 13-task run (500 rows each, RULER 4096, Qwen3-8B, ratio 0.9375, MPS + sdpa, bf16): mean string_match 89.64 vs 86.38
for RestoreKV_plus on the leaderboard — cwe 90.96 (78.88), fwe 90.0 (83.67), niah_multikey_1 92.2 (85.8), niah_multikey_2
99.2 (99.6), niah_multikey_3 96.8 (97.0), niah_multiquery 98.2 (96.8), niah_multivalue 88.15 (82.75), niah_single_1 100 (100),
niah_single_2 96.0 (90.8), niah_single_3 95.8 (93.0), qa_1 67.6 (65.4), qa_2 50.4 (49.2), vt 100 (100). Results PR to the
leaderboard Space: nvidia/kvpress-leaderboard (opened right after this PR). I don't have a CUDA box; happy to see a CUDA re-run replace the row.

Safety by construction. The rule keys on repetition and token class; a needle is a number or a word and is
never demoted. Punctuation glued inside an identifier — a whitespace-free token between a letter/digit and a
letter/digit, such as the dashes of a UUID, 3.14, 10:30, 1,000 — is a joiner and is never demoted either
(without this, RULER's niah_multikey_3, whose keys and values are UUIDs, lost a third of its answers). Prefix and
sink positions are excluded; positions beyond the context (RestoreKV's restore tokens) are untouched.
structure_demotion=0 (default) leaves every existing press bit-identical.

Tests. tests/presses/test_kvzip_structure_demotion.py (16 CPU tests). Style: black/isort/flake8/mypy clean.

Assisted by an automated agent (Claude Code); reviewed and submitted by the author. 🤖🤖🤖

Checklist

Before submitting a PR, please make sure:

• Tests are working (make test) — the new tests/presses/test_kvzip_structure_demotion.py (16 CPU tests) plus upstream's KVzip-related test files (tests/presses/test_presses.py, tests/test_pipeline.py: 278 passed, 3 skipped, CPU) were run locally; the option is default-off so existing presses are bit-identical
• Code is formatted correctly (make style, on errors try fix with make format) — black / isort / flake8 clean, mypy --check-untyped-defs clean on the touched file
• Copyright header is included
• All commits are signed-off using git commit -s

Not a new press file — this PR adds two default-off options to the existing KVzipPress (inherited by RestoreKVPress) and two registry entries, so the "(new press)" items do not apply:

• (new press) mypress_press.py is in the presses directory — n/a
• (new press) MyPress is in __init__.py — n/a
• (new press) README.md is updated with a 1 liner about the new press in the Available presses section — one sub-bullet under KVzipPress
• (new press) New press is in the default_presses list in tests/default_presses.py — n/a (option on an existing press)
• (new press) A docstring is provided that follows the same structure as the existing ones

🤖 Generated with Claude Code 🤖🤖🤖

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[JeetuSK0808]

Results PR on the leaderboard Space (RULER 4096, Qwen3-8B, ratio 0.94: 89.64): https://huggingface.co/spaces/nvidia/kvpress-leaderboard/discussions/24 🤖🤖🤖

[SimJeg]

Thanks for the contribution and for sharing the benchmark results. We're maintaining kvpress with limited review capacity, so we're currently prioritizing bug fixes and methods backed by an associated paper. Could you link a paper that describes and evaluates the method proposed here? If there isn't a paper for this method, we'll close the PR for now.

[JeetuSK0808]

Thanks for taking a look! There's no paper yet. Structure demotion is new, and the benchmark run linked above is the main evaluation so far. I'm writing it up as a short preprint now. Would an arXiv link be enough? If so I'll post it here once it's up. Otherwise feel free to close this for now and I'll reopen it with the paper. 🤖🤖🤖

[JeetuSK0808]

Here's the paper: https://github.com/JeetuSK0808/kvpress/blob/structure-demotion-paper/structure_demotion.pdf (LaTeX source is in the same branch). It describes and evaluates the method, with the full per-task results and paired confidence intervals against the leaderboard predictions. I'm setting up an arXiv posting and will add that link here once it's live. Also rebased this PR onto current main, so the merge conflict in kvzip_press.py is resolved. 🤖🤖🤖