Skip to content

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.

fix: prevent HF tokenizer downloads in offline mode (#3783)

yi111d503c575eabd
diff --git a/headroom/tokenizers/huggingface.py b/headroom/tokenizers/huggingface.py
index 0afa93d0f..f6f546756 100644
--- a/headroom/tokenizers/huggingface.py
+++ b/headroom/tokenizers/huggingface.py
@@ -226,6 +226,12 @@ def _load_tokenizer(tokenizer_name: str):
# vetted, not a variant the caller chose.
tokenizer_name = repo
+ from headroom.offline import apply_offline_env, is_offline
+
+ offline = is_offline()
+ if offline:
+ apply_offline_env()
+
from transformers import AutoTokenizer
try:
@@ -242,6 +248,13 @@ def _load_tokenizer(tokenizer_name: str):
except Exception:
pass # Not in the local cache — try the network below, bounded.
+ if offline:
+ logger.warning(
+ f"Tokenizer {tokenizer_name} not in local HF cache and network "
+ f"loading is disabled (HEADROOM_OFFLINE); using estimation"
+ )
+ return None
+
timeout = _load_timeout_secs()
if timeout <= 0:
logger.warning(
diff --git a/tests/test_huggingface_tokenizer_timeout.py b/tests/test_huggingface_tokenizer_timeout.py
index a04ada7e4..7b0ca6e27 100644
--- a/tests/test_huggingface_tokenizer_timeout.py
+++ b/tests/test_huggingface_tokenizer_timeout.py
@@ -29,7 +29,10 @@ from headroom.tokenizers.huggingface import (
@pytest.fixture(autouse=True)
-def _fresh_cache():
+def _fresh_cache(monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.delenv("HEADROOM_OFFLINE", raising=False)
+ monkeypatch.delenv("HF_HUB_OFFLINE", raising=False)
+ monkeypatch.delenv("TRANSFORMERS_OFFLINE", raising=False)
_load_tokenizer.cache_clear()
yield
_load_tokenizer.cache_clear()
@@ -106,6 +109,41 @@ def test_timeout_zero_disables_network_loading(monkeypatch: pytest.MonkeyPatch)
assert _load_tokenizer("google/gemma-7b") is None
+def test_offline_mode_prevents_network_loading(monkeypatch: pytest.MonkeyPatch) -> None:
+ calls: list[dict[str, Any]] = []
+
+ def fake_from_pretrained(name: str, **kwargs: Any):
+ calls.append(kwargs)
+ if kwargs.get("local_files_only"):
+ raise OSError("not in cache")
+ raise AssertionError("network load attempted in offline mode")
+
+ _install_fake_transformers(monkeypatch, fake_from_pretrained)
+ monkeypatch.setenv("HEADROOM_OFFLINE", "1")
+ monkeypatch.setenv("HF_HUB_OFFLINE", "0")
+ monkeypatch.setenv("TRANSFORMERS_OFFLINE", "0")
+ monkeypatch.setenv("HEADROOM_HF_TOKENIZER_LOAD_TIMEOUT_SECS", "5")
+
+ assert _load_tokenizer("Qwen/Qwen2.5-7B") is None
+ assert len(calls) == 1
+ assert calls[0].get("local_files_only") is True
+
+
+def test_offline_mode_allows_cached_tokenizer(monkeypatch: pytest.MonkeyPatch) -> None:
+ calls: list[dict[str, Any]] = []
+
+ def fake_from_pretrained(name: str, **kwargs: Any):
+ calls.append(kwargs)
+ return "cached-tokenizer"
+
+ _install_fake_transformers(monkeypatch, fake_from_pretrained)
+ monkeypatch.setenv("HEADROOM_OFFLINE", "1")
+
+ assert _load_tokenizer("Qwen/Qwen2.5-7B") == "cached-tokenizer"
+ assert len(calls) == 1
+ assert calls[0].get("local_files_only") is True
+
+
def test_count_messages_fails_open_to_estimation(monkeypatch: pytest.MonkeyPatch) -> None:
def fake_from_pretrained(name: str, **kwargs: Any):
raise OSError("unavailable")