Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(kompress): pin ModernBERT tokenizer and encoder revisions (#3808)
Tejas Chopra2de582875b7d
diff --git a/headroom/onnx_runtime.py b/headroom/onnx_runtime.pyindex 8157c2202..445d85b4f 100644--- a/headroom/onnx_runtime.py+++ b/headroom/onnx_runtime.py@@ -71,6 +71,10 @@ def onnx_thread_spinning_enabled() -> bool:_PINNED_REVISIONS: dict[str, str] = {# chopratejas/kompress-v2-base @ 2026-06-10"chopratejas/kompress-v2-base": "b1563631b35bfdcee37587ad530147497d820d4c",+ # Kompress tokenizer + torch-path encoder base. The ONNX artifacts were+ # exported against this snapshot; a silently updated tokenizer would shift+ # token ids under the shipped weights.+ "answerdotai/ModernBERT-base": "8949b909ec900327062f0ebf497f51aef5e6f0c8","chopratejas/technique-router-onnx": "27b0b4bfa510a1cff66d888072c0b807082721a8","chopratejas/siglip-image-encoder-onnx": "d0a9fbd66d4bd8c761bff592d44831f7c2ae184e",# Third-party repo — pinning matters most here.diff --git a/headroom/transforms/kompress_compressor.py b/headroom/transforms/kompress_compressor.pyindex 5b679b658..0fab296f2 100644--- a/headroom/transforms/kompress_compressor.py+++ b/headroom/transforms/kompress_compressor.py@@ -30,6 +30,7 @@ from typing import Any, Literalfrom ..config import TransformResultfrom ..onnx_runtime import (ONNX_CPU_ARENA_ENV,+ _resolve_revision,create_cpu_session_options,hf_entry_known_absent,hf_hub_download_local_first,@@ -600,9 +601,22 @@ def _get_model_class() -> type:class HeadroomCompressorModel(nn.Module):"""Dual-head ModernBERT: token classification + span importance CNN."""- def __init__(self, model_name: str = "answerdotai/ModernBERT-base"):+ def __init__(+ self,+ model_name: str = "answerdotai/ModernBERT-base",+ *,+ revision: str | None = None,+ allow_download: bool = True,+ ):super().__init__()- self.encoder = AutoModel.from_pretrained(model_name, attn_implementation="eager")+ # Same pin as the tokenizer: the fine-tuned heads were trained on+ # this encoder snapshot. Unknown repos resolve to None (floating).+ self.encoder = AutoModel.from_pretrained(+ model_name,+ attn_implementation="eager",+ revision=_resolve_revision(model_name, revision),+ local_files_only=not allow_download,+ )hidden_size = self.encoder.config.hidden_size # 768# Head 1: Token keep/discard@@ -831,6 +845,9 @@ def _load_kompress_onnx(return model, tokenizer, backend+_MODERNBERT_TOKENIZER_REPO = "answerdotai/ModernBERT-base"++def _load_modernbert_tokenizer(auto_tokenizer: Any, *, allow_download: bool) -> Any:"""Load the ModernBERT tokenizer, cache-only when ``allow_download`` is False.@@ -845,14 +862,25 @@ def _load_modernbert_tokenizer(auto_tokenizer: Any, *, allow_download: bool) ->changes whether the Hub is consulted to confirm what is already on disk.Mirrors ``onnx_runtime.hf_hub_download_local_first``, which the ONNX half ofthis loader already uses.++ The load is pinned to the same immutable revision as the model artifacts+ (``onnx_runtime._PINNED_REVISIONS``): the ONNX export was produced against+ that tokenizer snapshot, so a floating ``main`` could shift token ids under+ the shipped weights without any code change. ``HEADROOM_HF_PIN=off`` floats+ it, exactly as for the weights."""+ revision = _resolve_revision(_MODERNBERT_TOKENIZER_REPO, None)try:- return auto_tokenizer.from_pretrained("answerdotai/ModernBERT-base", local_files_only=True)+ return auto_tokenizer.from_pretrained(+ _MODERNBERT_TOKENIZER_REPO, revision=revision, local_files_only=True+ )except _NOT_CACHED_ERRORS as exc:if not allow_download:- raise KompressModelNotCached("answerdotai/ModernBERT-base") from exc- # Genuine cache miss and downloading is permitted: fetch it.- return auto_tokenizer.from_pretrained("answerdotai/ModernBERT-base", local_files_only=False)+ raise KompressModelNotCached(_MODERNBERT_TOKENIZER_REPO) from exc+ # Genuine cache miss and downloading is permitted: fetch it at the pin.+ return auto_tokenizer.from_pretrained(+ _MODERNBERT_TOKENIZER_REPO, revision=revision, local_files_only=False+ )# Sub-state-dict keys inside a merged v2-style checkpoint (see@@ -971,7 +999,12 @@ def _load_kompress_pytorch(logger.info("Downloading Kompress PyTorch model from %s ...", model_id)HeadroomCompressorModel = _get_model_class()- model = HeadroomCompressorModel()+ try:+ model = HeadroomCompressorModel(allow_download=allow_download)+ except _NOT_CACHED_ERRORS as exc:+ if allow_download:+ raise+ raise KompressModelNotCached(_MODERNBERT_TOKENIZER_REPO) from exc_load_pytorch_weights(model, model_id, allow_download=allow_download)diff --git a/scripts/export_kompress_v2_onnx.py b/scripts/export_kompress_v2_onnx.pyindex 383f473db..97ed8c62f 100644--- a/scripts/export_kompress_v2_onnx.py+++ b/scripts/export_kompress_v2_onnx.py@@ -31,12 +31,22 @@ Usage# Convert, verify, and upload back to the HF repo (needs `huggingface-cli login`):python scripts/export_kompress_v2_onnx.py --model-id chopratejas/kompress-v2-base --upload++Reproducibility+---------------+Every Hub load is pinned to an immutable commit: the checkpoint to+``--revision`` and the ModernBERT encoder + tokenizer to ``--base-revision``.+Both default to the production pins in ``headroom.onnx_runtime._PINNED_REVISIONS``+(``HEADROOM_HF_PIN`` does not apply here), so the exported artifact is built+from exactly what production loads. Upgrading a model is a reviewed pin bump+plus a regenerated artifact, never ambient Hub state."""from __future__ import annotationsimport argparseimport logging+import reimport sysfrom pathlib import Path@@ -47,8 +57,24 @@ logger = logging.getLogger("export_kompress_v2_onnx")BASE_MODEL = "answerdotai/ModernBERT-base"DEFAULT_MODEL_ID = "chopratejas/kompress-v2-base"+_COMMIT_SHA = re.compile(r"[0-9a-f]{40}")+++def _pinned_revision(repo_id: str, revision: str | None) -> str:+ """Return an immutable commit for ``repo_id``: ``revision`` if given, else+ the production pin. Branches, tags and unpinned repos are rejected."""+ from headroom.onnx_runtime import _PINNED_REVISIONS++ revision = revision or _PINNED_REVISIONS.get(repo_id)+ if revision is None or not _COMMIT_SHA.fullmatch(revision):+ raise SystemExit(+ f"{repo_id}: need a 40-hex commit SHA (got {revision!r}). "+ "Pass one explicitly or pin the repo in headroom.onnx_runtime._PINNED_REVISIONS."+ )+ return revision+-def _build_core(model_id: str):+def _build_core(model_id: str, revision: str, base_revision: str):"""Instantiate HeadroomCompressorModel and load the merged v2 weights.The v2 repo's ``model.safetensors`` is the *unmerged* PEFT structure@@ -67,7 +93,7 @@ def _build_core(model_id: str):from headroom.transforms.kompress_compressor import _get_model_class- ckpt_path = hf_hub_download(model_id, "merged.pt")+ ckpt_path = hf_hub_download(model_id, "merged.pt", revision=revision)ckpt = torch.load(ckpt_path, map_location="cpu")for key in ("encoder_state_dict", "token_head_state_dict", "span_conv_state_dict"):if key not in ckpt:@@ -76,7 +102,7 @@ def _build_core(model_id: str):"This script targets the v2 'merged' checkpoint format.")- core = _get_model_class()(model_name=BASE_MODEL)+ core = _get_model_class()(model_name=BASE_MODEL, revision=base_revision)def _strict_load(module, sd, label: str) -> None:missing, unexpected = module.load_state_dict(sd, strict=False)@@ -115,11 +141,18 @@ def _export_wrapper(core):return ExportWrapper(core).eval()-def export(model_id: str, out_path: Path, opset: int, precision: str) -> None:+def export(+ model_id: str,+ out_path: Path,+ opset: int,+ precision: str,+ revision: str,+ base_revision: str,+) -> None:import numpy as npimport torch- core = _build_core(model_id)+ core = _build_core(model_id, revision, base_revision)wrapper = _export_wrapper(core)out_path.parent.mkdir(parents=True, exist_ok=True)@@ -167,15 +200,15 @@ def export(model_id: str, out_path: Path, opset: int, precision: str) -> None:)trace_target.unlink(missing_ok=True)- _verify(model_id, core, out_path, np, torch)+ _verify(core, out_path, base_revision, np, torch)-def _verify(model_id: str, core, out_path: Path, np, torch) -> None:+def _verify(core, out_path: Path, base_revision: str, np, torch) -> None:"""Compare ONNX scores against PyTorch get_scores on a real tokenized sample."""import onnxruntime as ortfrom transformers import AutoTokenizer- tok = AutoTokenizer.from_pretrained(BASE_MODEL)+ tok = AutoTokenizer.from_pretrained(BASE_MODEL, revision=base_revision)sample = ("The proxy compresses tool outputs before they reach the model. ""Errors and stack traces should survive; boilerplate should not. "@@ -236,6 +269,16 @@ def upload(model_id: str, out_path: Path) -> None:def main() -> int:ap = argparse.ArgumentParser(description=__doc__)ap.add_argument("--model-id", default=DEFAULT_MODEL_ID)+ ap.add_argument(+ "--revision",+ default=None,+ help="Checkpoint commit SHA. Defaults to the production pin for --model-id.",+ )+ ap.add_argument(+ "--base-revision",+ default=None,+ help=f"{BASE_MODEL} commit SHA (encoder + tokenizer). Defaults to the production pin.",+ )ap.add_argument("--precision",choices=["fp32", "int8"],@@ -256,8 +299,12 @@ def main() -> int:)args = ap.parse_args()+ revision = _pinned_revision(args.model_id, args.revision)+ base_revision = _pinned_revision(BASE_MODEL, args.base_revision)+ logger.info("Pins: %s@%s, %s@%s", args.model_id, revision, BASE_MODEL, base_revision)+out_path = args.out or Path(f"onnx/kompress-{args.precision}.onnx")- export(args.model_id, out_path, args.opset, args.precision)+ export(args.model_id, out_path, args.opset, args.precision, revision, base_revision)if args.upload:upload(args.model_id, out_path)return 0diff --git a/tests/test_hf_revision_pinning.py b/tests/test_hf_revision_pinning.pyindex c9974b6ba..474e71508 100644--- a/tests/test_hf_revision_pinning.py+++ b/tests/test_hf_revision_pinning.py@@ -51,3 +51,99 @@ def test_pin_can_be_disabled_via_env(monkeypatch, value):def test_pin_disabled_still_respects_explicit_revision(monkeypatch):monkeypatch.setenv("HEADROOM_HF_PIN", "off")assert _resolve_revision("chopratejas/kompress-v2-base", "abc123") == "abc123"+++def test_modernbert_tokenizer_base_is_pinned():+ # The Kompress tokenizer (and torch-path encoder) load from this repo; the+ # ONNX export was produced against the pinned snapshot, so it must not float.+ assert "answerdotai/ModernBERT-base" in _PINNED_REVISIONS+++def test_tokenizer_loader_passes_pinned_revision(monkeypatch):+ monkeypatch.delenv("HEADROOM_HF_PIN", raising=False)+ from headroom.transforms import kompress_compressor as kc++ calls: list[dict] = []++ class _Tok:+ @staticmethod+ def from_pretrained(repo, **kwargs):+ calls.append({"repo": repo, **kwargs})+ return object()++ kc._load_modernbert_tokenizer(_Tok, allow_download=True)+ assert calls == [+ {+ "repo": "answerdotai/ModernBERT-base",+ "revision": _PINNED_REVISIONS["answerdotai/ModernBERT-base"],+ "local_files_only": True,+ }+ ]+++def test_tokenizer_loader_downloads_at_pin_on_cache_miss(monkeypatch):+ monkeypatch.delenv("HEADROOM_HF_PIN", raising=False)+ from headroom.transforms import kompress_compressor as kc++ calls: list[dict] = []++ class _Tok:+ @staticmethod+ def from_pretrained(repo, **kwargs):+ calls.append({"repo": repo, **kwargs})+ if kwargs.get("local_files_only"):+ raise OSError("not cached")+ return object()++ kc._load_modernbert_tokenizer(_Tok, allow_download=True)+ assert [c["local_files_only"] for c in calls] == [True, False]+ assert {c["revision"] for c in calls} == {_PINNED_REVISIONS["answerdotai/ModernBERT-base"]}+++def test_tokenizer_loader_floats_when_pin_disabled(monkeypatch):+ monkeypatch.setenv("HEADROOM_HF_PIN", "off")+ from headroom.transforms import kompress_compressor as kc++ calls: list[dict] = []++ class _Tok:+ @staticmethod+ def from_pretrained(repo, **kwargs):+ calls.append(kwargs)+ return object()++ kc._load_modernbert_tokenizer(_Tok, allow_download=True)+ assert calls[0]["revision"] is None+++def test_cache_only_pytorch_load_does_not_fetch_encoder(monkeypatch):+ # A cache-only load must not download the pinned encoder on the request+ # path; a missing snapshot defers the load like any other cache miss.+ import sys+ import types++ from headroom.transforms import kompress_compressor as kc++ calls: list[dict] = []++ class _AutoModel:+ @staticmethod+ def from_pretrained(repo, **kwargs):+ calls.append(kwargs)+ if kwargs.get("local_files_only"):+ raise OSError("pinned encoder snapshot not cached")+ raise AssertionError("cache-only load reached the network")++ nn = types.SimpleNamespace(Module=object)+ monkeypatch.setitem(sys.modules, "torch", types.SimpleNamespace(nn=nn))+ monkeypatch.setitem(sys.modules, "torch.nn", nn)+ monkeypatch.setitem(+ sys.modules,+ "transformers",+ types.SimpleNamespace(AutoModel=_AutoModel, AutoTokenizer=object),+ )+ monkeypatch.setattr(kc, "_kompress_cache", {})++ with pytest.raises(kc.KompressModelNotCached):+ kc._load_kompress_pytorch("chopratejas/kompress-v2-base", allow_download=False)+ assert [c["local_files_only"] for c in calls] == [True]diff --git a/tests/test_scripts/test_export_kompress_v2_onnx_pins.py b/tests/test_scripts/test_export_kompress_v2_onnx_pins.pynew file mode 100644index 000000000..a18d88514--- /dev/null+++ b/tests/test_scripts/test_export_kompress_v2_onnx_pins.py@@ -0,0 +1,124 @@+"""The Kompress ONNX export must build from the same immutable Hub snapshots+production loads, so an exported artifact can never mix floating inputs."""++from __future__ import annotations++import ast+import importlib.util+import re+import sys+import types+from pathlib import Path++import pytest++from headroom.onnx_runtime import _PINNED_REVISIONS++SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "export_kompress_v2_onnx.py"+SHA = re.compile(r"[0-9a-f]{40}")+BASE = "answerdotai/ModernBERT-base"+CKPT = "chopratejas/kompress-v2-base"+++def _load_script():+ spec = importlib.util.spec_from_file_location("export_kompress_v2_onnx", SCRIPT)+ mod = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(mod)+ return mod+++def _call_name(call: ast.Call) -> str:+ func = call.func+ if isinstance(func, ast.Attribute):+ return func.attr+ if isinstance(func, ast.Name):+ return func.id+ if isinstance(func, ast.Call): # _get_model_class()(...)+ return _call_name(func) + "()"+ return ""+++def test_every_hub_load_in_export_script_passes_revision():+ loaders = {"from_pretrained", "hf_hub_download", "snapshot_download", "_get_model_class()"}+ calls = [+ node+ for node in ast.walk(ast.parse(SCRIPT.read_text()))+ if isinstance(node, ast.Call) and _call_name(node) in loaders+ ]+ assert {_call_name(c) for c in calls} >= {+ "from_pretrained",+ "hf_hub_download",+ "_get_model_class()",+ }+ unpinned = [+ f"line {c.lineno}: {_call_name(c)}"+ for c in calls+ if not any(kw.arg == "revision" for kw in c.keywords)+ ]+ assert unpinned == []+++def test_export_defaults_to_production_pins_even_with_pinning_disabled(monkeypatch):+ monkeypatch.setenv("HEADROOM_HF_PIN", "off")+ mod = _load_script()+ seen: dict = {}+ monkeypatch.setattr(mod, "export", lambda *a: seen.setdefault("args", a))+ monkeypatch.setattr(sys, "argv", ["export"])++ assert mod.main() == 0+ revision, base_revision = seen["args"][-2:]+ assert revision == _PINNED_REVISIONS[CKPT]+ assert base_revision == _PINNED_REVISIONS[BASE]+ assert SHA.fullmatch(revision) and SHA.fullmatch(base_revision)+++ "argv",+ [+ ["--revision", "main"],+ ["--base-revision", "v1.0"],+ ["--model-id", "someone/unpinned-model"],+ ],+)+def test_export_rejects_floating_or_missing_revisions(monkeypatch, argv):+ mod = _load_script()+ monkeypatch.setattr(mod, "export", lambda *a: pytest.fail("export ran unpinned"))+ monkeypatch.setattr(sys, "argv", ["export", *argv])+ with pytest.raises(SystemExit, match="40-hex commit SHA"):+ mod.main()+++def test_build_core_threads_both_revisions(monkeypatch):+ mod = _load_script()+ calls: list[tuple] = []++ def fake_download(repo, filename, **kwargs):+ calls.append(("download", repo, kwargs.get("revision")))+ return "merged.pt"++ keys = ("encoder_state_dict", "token_head_state_dict", "span_conv_state_dict")+ monkeypatch.setitem(+ sys.modules, "torch", types.SimpleNamespace(load=lambda *a, **k: {k: {} for k in keys})+ )+ monkeypatch.setitem(+ sys.modules, "huggingface_hub", types.SimpleNamespace(hf_hub_download=fake_download)+ )++ class _Part:+ def load_state_dict(self, sd, strict):+ return [], []++ class _Core:+ def __init__(self, model_name, **kwargs):+ calls.append(("encoder", model_name, kwargs.get("revision")))+ self.encoder = self.token_head = self.span_conv = _Part()++ def eval(self):+ return self++ from headroom.transforms import kompress_compressor as kc++ monkeypatch.setattr(kc, "_get_model_class", lambda: _Core)++ mod._build_core(CKPT, "a" * 40, "b" * 40)+ assert calls == [("download", CKPT, "a" * 40), ("encoder", BASE, "b" * 40)]