Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Tests for the latest-transformers support check and the consented sidecar install."""
import ast
import json
import os
import textwrap
import time
import pytest
from pathlib import Path
import sys
def _shared_setup_1(monkeypatch):
monkeypatch.setattr(
tl,
"latest_transformers_supports",
lambda _t: {"pypi_version": "5.15.0", "supported_in_pypi": True, "supported_in_main": True},
)
def _shared_setup_2(monkeypatch):
monkeypatch.setattr(tl, "_disabled", lambda: False)
monkeypatch.setattr(tl, "_env_offline", lambda: False)
monkeypatch.setattr(tl, "_config_model_types", lambda tier: {"llama"})
monkeypatch.setattr(tl, "_hardcoded_model_types", lambda: frozenset())
def _shared_setup_3(monkeypatch):
cfg = {
"model_type": "zz_new_wrapper",
"text_config": {"model_type": "zz_new_llm"},
}
monkeypatch.setattr(tl, "_load_config_json", lambda *a, **k: cfg)
def _shared_setup_4(monkeypatch):
monkeypatch.setattr(
tv,
"_ensure_venv_dir",
lambda *a: (_ for _ in ()).throw(AssertionError("must not install")),
)
def _shared_setup_5(monkeypatch, tmp_path):
venv_dir = tmp_path / ".venv_t5_latest"
venv_dir.mkdir()
(venv_dir / tv._LATEST_PIN_MARKER).write_text("5.13.0")
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(venv_dir))
return venv_dir
_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
if _BACKEND_DIR not in sys.path:
sys.path.insert(0, _BACKEND_DIR)
import types as _types
_loggers_stub = _types.ModuleType("loggers")
_loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
sys.modules.setdefault("loggers", _loggers_stub)
import utils.transformers_latest as tl
import utils.transformers_version as tv
from utils.transformers_latest import (
check_upgrade_for_model,
install_latest_transformers,
latest_transformers_supports,
_fetch_remote_model_types,
_model_types_from_config,
)
from utils.transformers_version import (
_config_mapping_cache,
_config_json_cache,
_higher_tier,
_is_valid_version_string,
_model_types_from_source,
_tier_from_config_mapping,
_venv_t5_latest_packages,
activate_transformers_for_subprocess,
ensure_latest_transformers_venv,
get_transformers_tier,
latest_venv_pinned_version,
)
# A CONFIG_MAPPING_NAMES source exercising every construct the AST extractor supports.
_MAPPING_SOURCE = """
from collections import OrderedDict
CONFIG_MAPPING_NAMES = OrderedDict(
[
("llama", "LlamaConfig"),
("gemma4", "Gemma4Config"),
],
**{"qwen3_moe": "Qwen3MoeConfig"},
)
CONFIG_MAPPING_NAMES.update({"brandnew_arch": "BrandNewConfig"})
"""
_MAIN_ONLY_SOURCE = """
CONFIG_MAPPING_NAMES = {
"llama": "LlamaConfig",
"gemma4": "Gemma4Config",
"qwen3_moe": "Qwen3MoeConfig",
"brandnew_arch": "BrandNewConfig",
"dev_only_arch": "DevOnlyConfig",
}
"""
class _FakeResponse:
def __init__(self, body: bytes):
self._body = body
def read(self):
return self._body
def __enter__(self):
return self
def __exit__(self, *args):
return False
def _fake_urlopen_factory(counter: dict):
"""urlopen stub serving the PyPI JSON and both refs' mapping sources."""
def _fake_urlopen(req, timeout = None):
url = req.full_url if hasattr(req, "full_url") else str(req)
counter[url] = counter.get(url, 0) + 1
counter["__total__"] = counter.get("__total__", 0) + 1
if url == tl._PYPI_JSON_URL:
return _FakeResponse(json.dumps({"info": {"version": "5.13.0"}}).encode())
if "/v5.13.0/" in url and url.endswith("auto_mappings.py"):
return _FakeResponse(_MAPPING_SOURCE.encode())
if "/v5.13.0/" in url and url.endswith("configuration_auto.py"):
return _FakeResponse(b"CONFIG_MAPPING_NAMES = {}\n")
if "/main/" in url and url.endswith("auto_mappings.py"):
return _FakeResponse(_MAIN_ONLY_SOURCE.encode())
if "/main/" in url and url.endswith("configuration_auto.py"):
return _FakeResponse(b"CONFIG_MAPPING_NAMES = {}\n")
if url == f"{tl._MAIN_RAW}/src/transformers/__init__.py":
return _FakeResponse(b'__version__ = "5.14.0.dev0"\n')
raise AssertionError(f"unexpected URL fetched: {url}")
return _fake_urlopen
@pytest.fixture(autouse = True)
def _isolated_caches(tmp_path: Path, monkeypatch):
"""Fresh in-memory + on-disk caches per test; no accidental real studio_root writes."""
tl.clear_caches()
monkeypatch.setattr(tl, "_cache_file", lambda: tmp_path / "transformers_latest_check.json")
# The swap reservation writes a lock next to the venv dir; keep it in tmp.
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(tmp_path / "venv_t5_latest"))
monkeypatch.delenv("UNSLOTH_STUDIO_NO_LATEST_TRANSFORMERS", raising = False)
monkeypatch.delenv("HF_HUB_OFFLINE", raising = False)
monkeypatch.delenv("TRANSFORMERS_OFFLINE", raising = False)
yield
tl.clear_caches()
def _no_network(monkeypatch, exc = None):
"""Fail every urlopen and count calls; check_upgrade_for_model swallows exceptions, so a raising
stub alone cannot prove that no fetch happened."""
calls = {"n": 0}
def _raise(*args, **kwargs):
calls["n"] += 1
raise (exc or OSError("network fetch attempted"))
monkeypatch.setattr("urllib.request.urlopen", _raise)
return calls
class TestModelTypesFromSource:
def test_ordereddict_update_and_unpacking(self):
keys = _model_types_from_source(_MAPPING_SOURCE)
assert keys == {"llama", "gemma4", "qwen3_moe", "brandnew_arch"}
def test_plain_dict_literal(self):
keys = _model_types_from_source(_MAIN_ONLY_SOURCE)
assert "dev_only_arch" in keys and "llama" in keys
def test_syntax_error_raises_for_caller_to_handle(self):
with pytest.raises(SyntaxError):
_model_types_from_source("def broken(:\n")
class TestFetchRemoteModelTypes:
def test_merges_both_auto_files(self, monkeypatch):
counter = {}
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory(counter))
keys = _fetch_remote_model_types("v5.13.0")
assert keys is not None and "brandnew_arch" in keys
def test_all_fetches_failing_returns_none(self, monkeypatch):
_no_network(monkeypatch, exc = OSError("no route"))
assert _fetch_remote_model_types("main") is None
def test_empty_mapping_treated_as_failure(self, monkeypatch):
monkeypatch.setattr(
"urllib.request.urlopen",
lambda req, timeout = None: _FakeResponse(b"CONFIG_MAPPING_NAMES = {}\n"),
)
assert _fetch_remote_model_types("main") is None
def test_transient_failure_of_one_file_fails_whole_lookup(self, monkeypatch):
# One file times out: the partial map must not be returned and cached.
def _fake(req, timeout = None):
url = req.full_url if hasattr(req, "full_url") else str(req)
if url.endswith("configuration_auto.py"):
return _FakeResponse(_MAPPING_SOURCE.encode())
raise OSError("timed out")
monkeypatch.setattr("urllib.request.urlopen", _fake)
assert _fetch_remote_model_types("main") is None
def test_missing_auto_mappings_404_still_succeeds(self, monkeypatch):
# Pre-5.10 tags have no auto_mappings.py; a 404 must not fail the lookup.
import urllib.error
def _fake(req, timeout = None):
url = req.full_url if hasattr(req, "full_url") else str(req)
if url.endswith("configuration_auto.py"):
return _FakeResponse(_MAPPING_SOURCE.encode())
raise urllib.error.HTTPError(url, 404, "Not Found", None, None)
monkeypatch.setattr("urllib.request.urlopen", _fake)
keys = _fetch_remote_model_types("v5.9.0")
assert keys is not None and "brandnew_arch" in keys
def test_unparseable_file_fails_whole_lookup(self, monkeypatch):
def _fake(req, timeout = None):
url = req.full_url if hasattr(req, "full_url") else str(req)
if url.endswith("configuration_auto.py"):
return _FakeResponse(_MAPPING_SOURCE.encode())
return _FakeResponse(b"def broken(:\n")
monkeypatch.setattr("urllib.request.urlopen", _fake)
assert _fetch_remote_model_types("main") is None
class TestLatestTransformersSupports:
def test_supported_in_pypi(self, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
result = latest_transformers_supports("brandnew_arch")
assert result == {
"pypi_version": "5.13.0",
"supported_in_pypi": True,
"supported_in_main": True,
"main_version": "5.14.0.dev0",
}
def test_dev_only_arch_reported_main_only(self, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
result = latest_transformers_supports("dev_only_arch")
assert result["supported_in_pypi"] is False
assert result["supported_in_main"] is True
assert result["main_version"] == "5.14.0.dev0"
def test_unknown_everywhere(self, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
result = latest_transformers_supports("no_such_arch")
assert result["supported_in_pypi"] is False and result["supported_in_main"] is False
def test_network_failure_returns_none(self, monkeypatch):
_no_network(monkeypatch, exc = OSError("down"))
assert latest_transformers_supports("brandnew_arch") is None
def test_offline_returns_none_without_fetch(self, monkeypatch):
monkeypatch.setenv("HF_HUB_OFFLINE", "1")
calls = _no_network(monkeypatch)
assert latest_transformers_supports("brandnew_arch") is None
assert calls["n"] == 0
def test_kill_switch_returns_none_without_fetch(self, monkeypatch):
monkeypatch.setenv("UNSLOTH_STUDIO_NO_LATEST_TRANSFORMERS", "1")
calls = _no_network(monkeypatch)
assert latest_transformers_supports("brandnew_arch") is None
assert calls["n"] == 0
def test_memory_cache_hit_avoids_refetch(self, monkeypatch):
counter = {}
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory(counter))
latest_transformers_supports("brandnew_arch")
first_total = counter["__total__"]
latest_transformers_supports("some_other_arch")
assert counter["__total__"] == first_total
def test_disk_cache_survives_restart(self, monkeypatch):
counter = {}
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory(counter))
latest_transformers_supports("brandnew_arch")
# Simulate a restart: memory gone, disk snapshot stays, network unavailable.
tl.clear_caches()
_no_network(monkeypatch)
result = latest_transformers_supports("brandnew_arch")
assert result is not None and result["supported_in_pypi"] is True
def test_expired_snapshot_refetches(self, monkeypatch):
counter = {}
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory(counter))
latest_transformers_supports("brandnew_arch")
stale = dict(tl._memory_snapshot, fetched_at = time.time() - tl._CACHE_TTL_SECONDS - 1)
tl.clear_caches()
tl._save_snapshot_file(stale)
first_total = counter["__total__"]
latest_transformers_supports("brandnew_arch")
assert counter["__total__"] > first_total
def test_pre_main_version_snapshot_refetches(self, monkeypatch):
# A snapshot written before main_version existed must not hide the main install.
counter = {}
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory(counter))
latest_transformers_supports("brandnew_arch")
old = dict(tl._memory_snapshot, schema = 1)
old.pop("main_version")
tl.clear_caches()
tl._save_snapshot_file(old)
result = latest_transformers_supports("dev_only_arch")
assert result["main_version"] == "5.14.0.dev0"
def test_failed_main_version_lookup_retries_after_backoff(self):
snapshot = {"main_checked": True, "main_version": None, "fetched_at": time.time()}
assert tl._snapshot_is_fresh(snapshot)
snapshot["fetched_at"] -= tl._FAILURE_BACKOFF_SECONDS + 1
assert not tl._snapshot_is_fresh(snapshot)
snapshot["main_version"] = "5.14.0.dev0"
assert tl._snapshot_is_fresh(snapshot)
# A failed main mapping fetch is retried after the same backoff.
snapshot["main_checked"] = False
assert not tl._snapshot_is_fresh(snapshot)
def test_corrupt_disk_cache_ignored(self, monkeypatch, tmp_path: Path):
counter = {}
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory(counter))
tl._cache_file().write_text("{not json", encoding = "utf-8")
result = latest_transformers_supports("brandnew_arch")
assert result is not None and counter["__total__"] > 0
def test_failure_backoff_skips_immediate_retry(self, monkeypatch):
calls = {"n": 0}
def _fail(*args, **kwargs):
calls["n"] += 1
raise OSError("down")
monkeypatch.setattr("urllib.request.urlopen", _fail)
assert latest_transformers_supports("brandnew_arch") is None
first = calls["n"]
assert latest_transformers_supports("brandnew_arch") is None
assert calls["n"] == first
def _local_model(tmp_path: Path, model_type: str) -> str:
d = tmp_path / f"model_{model_type}"
d.mkdir()
(d / "config.json").write_text(json.dumps({"model_type": model_type}))
return str(d)
_FAKE_OVERLAYS = {
"default": frozenset({"llama", "bert", "gpt2"}),
"530": frozenset({"qwen3_moe", "qwen3_next"}),
"550": frozenset({"gemma4"}),
"510": frozenset({"gemma4_unified"}),
"latest": frozenset(),
}
def _fake_overlays(monkeypatch, overlays = None):
overlays = overlays or _FAKE_OVERLAYS
fake = lambda tier: overlays.get(tier, frozenset())
monkeypatch.setattr(tv, "_config_model_types", fake)
monkeypatch.setattr(tl, "_config_model_types", fake)
class TestCheckUpgradeForModel:
def test_unknown_type_supported_in_pypi_signals(self, tmp_path: Path, monkeypatch):
_fake_overlays(monkeypatch)
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
result = check_upgrade_for_model(_local_model(tmp_path, "brandnew_arch"))
assert result == {
"model_type": "brandnew_arch",
"pypi_version": "5.13.0",
"supported_in_pypi": True,
"supported_in_main": True,
"main_version": "5.14.0.dev0",
}
def test_dev_only_type_signals_main_only(self, tmp_path: Path, monkeypatch):
_fake_overlays(monkeypatch)
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
result = check_upgrade_for_model(_local_model(tmp_path, "dev_only_arch"))
assert result["supported_in_pypi"] is False and result["supported_in_main"] is True
def test_unknown_everywhere_falls_through(self, tmp_path: Path, monkeypatch):
_fake_overlays(monkeypatch)
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
assert check_upgrade_for_model(_local_model(tmp_path, "no_such_arch")) is None
def test_offline_falls_through_without_fetch(self, tmp_path: Path, monkeypatch):
_fake_overlays(monkeypatch)
monkeypatch.setenv("TRANSFORMERS_OFFLINE", "1")
calls = _no_network(monkeypatch)
assert check_upgrade_for_model(_local_model(tmp_path, "brandnew_arch")) is None
assert calls["n"] == 0
def test_network_failure_falls_through(self, tmp_path: Path, monkeypatch):
_fake_overlays(monkeypatch)
_no_network(monkeypatch, exc = OSError("down"))
assert check_upgrade_for_model(_local_model(tmp_path, "brandnew_arch")) is None
def test_known_default_type_never_fetches(self, tmp_path: Path, monkeypatch):
_fake_overlays(monkeypatch)
calls = _no_network(monkeypatch)
assert check_upgrade_for_model(_local_model(tmp_path, "llama")) is None
assert calls["n"] == 0
def test_known_sidecar_type_never_fetches(self, tmp_path: Path, monkeypatch):
_fake_overlays(monkeypatch)
calls = _no_network(monkeypatch)
assert check_upgrade_for_model(_local_model(tmp_path, "gemma4_unified")) is None
assert calls["n"] == 0
def test_hardcoded_tier_type_never_fetches_even_without_overlays(
self, tmp_path: Path, monkeypatch
):
_fake_overlays(
monkeypatch,
{"default": frozenset({"llama"})},
)
calls = _no_network(monkeypatch)
assert check_upgrade_for_model(_local_model(tmp_path, "qwen3_5_moe")) is None
assert calls["n"] == 0
def test_unreadable_default_overlay_bails_out(self, tmp_path: Path, monkeypatch):
_fake_overlays(monkeypatch, {"default": frozenset()})
calls = _no_network(monkeypatch)
assert check_upgrade_for_model(_local_model(tmp_path, "brandnew_arch")) is None
assert calls["n"] == 0
def test_no_model_type_falls_through(self, tmp_path: Path, monkeypatch):
_fake_overlays(monkeypatch)
_no_network(monkeypatch)
d = tmp_path / "no_type"
d.mkdir()
(d / "config.json").write_text(json.dumps({"architectures": ["Whatever"]}))
assert check_upgrade_for_model(str(d)) is None
def test_nested_model_type_is_used(self, tmp_path: Path, monkeypatch):
_fake_overlays(monkeypatch)
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
d = tmp_path / "nested"
d.mkdir()
(d / "config.json").write_text(json.dumps({"text_config": {"model_type": "brandnew_arch"}}))
result = check_upgrade_for_model(str(d))
assert result is not None and result["model_type"] == "brandnew_arch"
def test_never_raises_on_internal_error(self, monkeypatch):
monkeypatch.setattr(
tl, "_load_config_json", lambda *a, **k: (_ for _ in ()).throw(RuntimeError("boom"))
)
assert check_upgrade_for_model("some/model") is None
class TestNestedModelTypeExtraction:
def test_top_level_wins(self):
assert _model_types_from_config(
{"model_type": "a", "text_config": {"model_type": "b"}}
) == ["a", "b"]
def test_nested_fallback(self):
assert _model_types_from_config({"llm_config": {"model_type": "b"}}) == ["b"]
def test_missing_returns_none(self):
assert _model_types_from_config({}) == []
class TestRoutingParity:
def test_all_overlay_types_route_identically_and_never_check(self, tmp_path: Path, monkeypatch):
_fake_overlays(monkeypatch)
calls = _no_network(monkeypatch)
expected_tier = {
"llama": "default",
"bert": "default",
"gpt2": "default",
"qwen3_moe": "530",
"qwen3_next": "530",
"gemma4": "550",
"gemma4_unified": "510",
}
for model_type, tier in expected_tier.items():
cfg = {"model_type": model_type}
assert _tier_from_config_mapping(cfg) == tier, model_type
assert check_upgrade_for_model(_local_model(tmp_path, model_type)) is None
assert calls["n"] == 0
def test_real_installed_mappings_route_without_checker(self, monkeypatch, tmp_path: Path):
"""Shipped model_types resolve statically on the real overlays, so the remote checker never
fires and routing stays byte-identical with the feature enabled."""
_no_network(monkeypatch)
seen = 0
for tier in ("default", "530", "550", "510"):
types = tv._config_model_types(tier)
if not types:
continue
for model_type in types:
assert _tier_from_config_mapping({"model_type": model_type}) is not None
seen += 1
if seen == 0:
pytest.skip("no transformers overlay available in this environment")
def test_get_tier_unchanged_by_kill_switch(self, tmp_path: Path, monkeypatch):
_fake_overlays(monkeypatch)
_no_network(monkeypatch)
path = _local_model(tmp_path, "no_such_arch")
_config_json_cache.clear()
tier_default = get_transformers_tier(path, probe = False)
monkeypatch.setenv("UNSLOTH_STUDIO_NO_LATEST_TRANSFORMERS", "1")
_config_json_cache.clear()
assert get_transformers_tier(path, probe = False) == tier_default == "default"
class TestLatestVenvProvisioning:
def test_version_string_validation(self):
assert _is_valid_version_string("5.13.0")
assert _is_valid_version_string("5.14.0rc1")
assert not _is_valid_version_string("5.13.0; rm -rf /")
assert not _is_valid_version_string("git+https://evil")
assert not _is_valid_version_string("")
def test_packages_pin_exact_version(self):
pkgs = _venv_t5_latest_packages("5.13.0")
assert pkgs[0] == "transformers==5.13.0"
assert any(p.startswith("huggingface_hub==") for p in pkgs)
def test_ensure_latest_writes_pin_and_invalidates_cache(self, tmp_path: Path, monkeypatch):
venv_dir = tmp_path / ".venv_t5_latest"
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(venv_dir))
recorded = {}
def _fake_ensure(dir_, packages, label):
recorded["dir"] = dir_
recorded["packages"] = packages
Path(dir_).mkdir(parents = True, exist_ok = True)
return True
monkeypatch.setattr(tv, "_ensure_venv_dir", _fake_ensure)
_config_mapping_cache["latest"] = frozenset({"stale"})
assert ensure_latest_transformers_venv("5.13.0") is True
# Stage-and-swap: pip installs into staging, the live dir is the swap result.
assert recorded["dir"] == str(venv_dir) + ".staging"
assert "transformers==5.13.0" in recorded["packages"]
assert venv_dir.is_dir()
assert not Path(str(venv_dir) + ".staging").exists()
assert latest_venv_pinned_version() == "5.13.0"
assert "latest" not in _config_mapping_cache
def test_ensure_latest_upgrade_failure_keeps_old_sidecar(self, tmp_path: Path, monkeypatch):
venv_dir = tmp_path / ".venv_t5_latest"
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(venv_dir))
venv_dir.mkdir(parents = True)
(venv_dir / tv._LATEST_PIN_MARKER).write_text(
json.dumps({"version": "5.12.0", "packages": ["transformers==5.12.0"]})
)
(venv_dir / "transformers").mkdir()
monkeypatch.setattr(tv, "_venv_dir_is_valid", lambda *a, **k: True)
# Install fails mid-flight: the previous sidecar and pin survive.
monkeypatch.setattr(tv, "_ensure_venv_dir", lambda *a, **k: False)
assert ensure_latest_transformers_venv("5.13.0") is False
assert latest_venv_pinned_version() == "5.12.0"
assert (venv_dir / "transformers").is_dir()
assert not Path(str(venv_dir) + ".staging").exists()
def test_ensure_latest_rejects_bad_version(self, tmp_path: Path, monkeypatch):
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(tmp_path / ".venv_t5_latest"))
_shared_setup_4(monkeypatch)
assert ensure_latest_transformers_venv("5.13.0 && curl evil") is False
def test_ensure_latest_offline_refuses(self, tmp_path: Path, monkeypatch):
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(tmp_path / ".venv_t5_latest"))
monkeypatch.setenv("HF_HUB_OFFLINE", "1")
_shared_setup_4(monkeypatch)
assert ensure_latest_transformers_venv("5.13.0") is False
def test_unpinned_sidecar_never_installs(self, tmp_path: Path, monkeypatch):
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(tmp_path / ".venv_t5_latest"))
_shared_setup_4(monkeypatch)
assert tv._ensure_venv_t5_latest_exists() is False
def test_pinned_sidecar_repairs_with_same_version(self, tmp_path: Path, monkeypatch):
venv_dir = _shared_setup_5(monkeypatch, tmp_path)
monkeypatch.setattr(tv, "_venv_dir_is_valid", lambda *a: False)
recorded = {}
def _fake_ensure(dir_, packages, label):
recorded["dir"] = dir_
recorded["packages"] = packages
Path(dir_).mkdir(parents = True, exist_ok = True)
return True
monkeypatch.setattr(tv, "_ensure_venv_dir", _fake_ensure)
assert tv._ensure_venv_t5_latest_exists() is True
assert recorded["dir"] == str(venv_dir) + ".staging"
assert "transformers==5.13.0" in recorded["packages"]
assert latest_venv_pinned_version() == "5.13.0"
class TestLatestTierRouting:
def test_latest_outranks_510(self):
assert _higher_tier("latest", "510") == "latest"
assert _higher_tier("510", "latest") == "latest"
def test_tier_from_mapping_prefers_lowest_but_reaches_latest(self, monkeypatch):
overlays = dict(_FAKE_OVERLAYS)
overlays["latest"] = frozenset({"brandnew_arch"})
_fake_overlays(monkeypatch, overlays)
assert _tier_from_config_mapping({"model_type": "brandnew_arch"}) == "latest"
assert _tier_from_config_mapping({"model_type": "qwen3_moe"}) == "530"
def test_overlay_dir_for_latest(self, tmp_path: Path, monkeypatch):
venv_dir = tmp_path / ".venv_t5_latest"
(venv_dir / "transformers").mkdir(parents = True)
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(venv_dir))
assert tv._overlay_transformers_dir("latest") is None
(venv_dir / tv._LATEST_PIN_MARKER).write_text("5.13.0")
assert tv._overlay_transformers_dir("latest") == str(venv_dir / "transformers")
def test_probe_order_excludes_unprovisioned_latest(self, tmp_path: Path, monkeypatch):
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(tmp_path / ".venv_t5_latest"))
assert tv._probe_tier_order() == tv._PROBE_TIER_ORDER
def test_probe_order_includes_provisioned_latest(self, tmp_path: Path, monkeypatch):
venv_dir = _shared_setup_5(monkeypatch, tmp_path)
assert tv._probe_tier_order() == tv._PROBE_TIER_ORDER + ("latest",)
def test_activation_prepends_latest_dir(self, tmp_path: Path, monkeypatch):
venv_dir = _shared_setup_5(monkeypatch, tmp_path)
monkeypatch.setattr(tv, "get_transformers_tier", lambda *a, **k: "latest")
monkeypatch.setattr(tv, "_ensure_venv_t5_latest_exists", lambda: True)
old_sys_path = list(sys.path)
old_pp = os.environ.get("PYTHONPATH")
try:
activate_transformers_for_subprocess("some/brand-new-model")
assert sys.path[0] == str(venv_dir)
assert os.environ["PYTHONPATH"].split(os.pathsep)[0] == str(venv_dir)
finally:
sys.path[:] = old_sys_path
if old_pp is None:
os.environ.pop("PYTHONPATH", None)
else:
os.environ["PYTHONPATH"] = old_pp
def test_activation_raises_when_latest_missing(self, tmp_path: Path, monkeypatch):
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(tmp_path / ".venv_t5_latest"))
monkeypatch.setattr(tv, "get_transformers_tier", lambda *a, **k: "latest")
with pytest.raises(RuntimeError, match = "venv_t5_latest"):
activate_transformers_for_subprocess("some/brand-new-model")
class TestInstallLatestTransformers:
def test_success_path(self, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
monkeypatch.setattr(tl, "compat_plan", lambda v: ((), []))
recorded = {}
def _fake_ensure(
version,
extra_packages = (),
before_swap = None,
):
recorded["args"] = (version, extra_packages)
return True
monkeypatch.setattr(tl, "ensure_latest_transformers_venv", _fake_ensure)
monkeypatch.setattr(tl, "latest_venv_pinned_version", lambda: "5.13.0")
result = install_latest_transformers("5.13.0")
assert result["success"] is True and result["version"] == "5.13.0"
assert recorded["args"] == ("5.13.0", ())
def test_version_mismatch_rejected(self, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
monkeypatch.setattr(
tl,
"ensure_latest_transformers_venv",
lambda v, extra_packages = (): (_ for _ in ()).throw(AssertionError("must not install")),
)
result = install_latest_transformers("4.99.0")
assert result["success"] is False and "not the latest" in result["message"]
def test_offline_rejected(self, monkeypatch):
monkeypatch.setenv("HF_HUB_OFFLINE", "1")
_no_network(monkeypatch)
result = install_latest_transformers("5.13.0")
assert result["success"] is False and "offline" in result["message"].lower()
def test_kill_switch_rejected(self, monkeypatch):
monkeypatch.setenv("UNSLOTH_STUDIO_NO_LATEST_TRANSFORMERS", "1")
_no_network(monkeypatch)
result = install_latest_transformers("5.13.0")
assert result["success"] is False
def test_install_failure_reported(self, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
monkeypatch.setattr(tl, "compat_plan", lambda v: ((), []))
monkeypatch.setattr(
tl,
"ensure_latest_transformers_venv",
lambda v, extra_packages = (), before_swap = None: False,
)
result = install_latest_transformers("5.13.0")
assert result["success"] is False and "failed" in result["message"]
def test_blocked_by_incompatible_deps(self, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
monkeypatch.setattr(tl, "compat_plan", lambda v: ((), ["numpy>=99.0"]))
monkeypatch.setattr(
tl,
"ensure_latest_transformers_venv",
lambda v, extra_packages = (): (_ for _ in ()).throw(AssertionError("must not install")),
)
result = install_latest_transformers("5.13.0")
assert result["success"] is False and "numpy>=99.0" in result["message"]
def test_compat_shadows_passed_to_installer(self, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
monkeypatch.setattr(tl, "compat_plan", lambda v: (("tokenizers==0.23.0",), []))
recorded = {}
def _fake_ensure(
version,
extra_packages = (),
before_swap = None,
):
recorded["extras"] = extra_packages
return True
monkeypatch.setattr(tl, "ensure_latest_transformers_venv", _fake_ensure)
monkeypatch.setattr(tl, "latest_venv_pinned_version", lambda: "5.13.0")
result = install_latest_transformers("5.13.0")
assert result["success"] is True
assert recorded["extras"] == ("tokenizers==0.23.0",)
def test_main_version_installs_after_consent(self, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
monkeypatch.setattr(tl, "compat_plan", lambda v: ((), []))
recorded = {}
def _fake_ensure(
version,
extra_packages = (),
before_swap = None,
):
recorded["version"] = version
recorded["source"] = tv._install_source(f"transformers=={version}")
return True
monkeypatch.setattr(tl, "_resolve_main_commit", lambda: "a" * 40)
monkeypatch.setattr(tl, "_fetch_main_version", lambda ref = "main": "5.14.0.dev0")
monkeypatch.setattr(tl, "ensure_latest_transformers_venv", _fake_ensure)
monkeypatch.setattr(tl, "latest_venv_pinned_version", lambda: "5.14.0.dev0")
result = install_latest_transformers("5.14.0.dev0")
assert result["success"] is True and "(main)" in result["message"]
assert recorded["version"] == "5.14.0.dev0"
# The archive is the commit whose version was checked, not the moving branch.
assert recorded["source"].endswith(f"/archive/{'a' * 40}.zip")
assert tv._install_source("transformers==5.14.0.dev0").endswith("refs/heads/main.zip")
def test_main_moved_since_check_rejected(self, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
seen = iter(["5.14.0.dev0", "5.15.0.dev0"])
monkeypatch.setattr(tl, "_fetch_main_version", lambda ref = "main": next(seen))
monkeypatch.setattr(tl, "_resolve_main_commit", lambda: "b" * 40)
monkeypatch.setattr(
tl,
"ensure_latest_transformers_venv",
lambda v, extra_packages = (), before_swap = None: (_ for _ in ()).throw(
AssertionError("must not install")
),
)
result = install_latest_transformers("5.14.0.dev0")
assert result["success"] is False and "no longer" in result["message"]
assert result["latest_main_version"] == "5.15.0.dev0"
def test_unresolvable_main_commit_rejected(self, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
monkeypatch.setattr(tl, "_resolve_main_commit", lambda: None)
monkeypatch.setattr(
tl,
"ensure_latest_transformers_venv",
lambda v, extra_packages = (), before_swap = None: (_ for _ in ()).throw(
AssertionError("must not install")
),
)
result = install_latest_transformers("5.14.0.dev0")
assert result["success"] is False and "Could not check" in result["message"]
def test_stale_main_version_rejected(self, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
monkeypatch.setattr(
tl,
"ensure_latest_transformers_venv",
lambda v, extra_packages = (), before_swap = None: (_ for _ in ()).throw(
AssertionError("must not install")
),
)
result = install_latest_transformers("5.12.0.dev0")
assert result["success"] is False
# Retry needs the current main, else it re-sends the stale dev version forever.
assert result["latest_main_version"] == "5.14.0.dev0"
class TestCompatPlan:
def _patch_env(self, monkeypatch, requires, installed):
monkeypatch.setattr(tl, "_fetch_requires_dist", lambda v: requires)
def _ver(name):
from importlib.metadata import PackageNotFoundError
key = name.lower().replace("_", "-")
if key not in installed:
raise PackageNotFoundError(name)
return installed[key]
monkeypatch.setattr("importlib.metadata.version", _ver)
def test_satisfied_env_needs_nothing(self, monkeypatch):
self._patch_env(
monkeypatch,
["tokenizers<=0.23.0,>=0.22.0", "safetensors>=0.8.0", "numpy>=1.17"],
{"tokenizers": "0.22.2", "safetensors": "0.8.0", "numpy": "2.4.4"},
)
extras, blockers = tl.compat_plan("5.13.0")
assert extras == () and blockers == []
def test_unsatisfied_shadowable_dep_pinned(self, monkeypatch):
self._patch_env(
monkeypatch,
["tokenizers>=0.24.0"],
{"tokenizers": "0.22.2"},
)
monkeypatch.setattr(tl, "_resolve_exact_version", lambda name, spec: "0.24.1")
extras, blockers = tl.compat_plan("5.99.0")
assert extras == ("tokenizers==0.24.1",) and blockers == []
def test_unsatisfied_non_shadowable_dep_blocks(self, monkeypatch):
self._patch_env(monkeypatch, ["numpy>=99.0"], {"numpy": "2.4.4"})
extras, blockers = tl.compat_plan("5.99.0")
assert extras == () and blockers == ["numpy>=99.0"]
def test_cli_only_dep_ignored(self, monkeypatch):
self._patch_env(monkeypatch, ["typer"], {})
extras, blockers = tl.compat_plan("5.13.0")
assert extras == () and blockers == []
def test_sidecar_provided_hub_checked_against_recipe_pin(self, monkeypatch):
self._patch_env(monkeypatch, ["huggingface-hub<2.0,>=1.5.0"], {"huggingface-hub": "0.36.2"})
extras, blockers = tl.compat_plan("5.13.0")
assert extras == () and blockers == []
def test_sidecar_provided_hub_out_of_range_blocks(self, monkeypatch):
self._patch_env(monkeypatch, ["huggingface-hub>=2.1"], {"huggingface-hub": "0.36.2"})
extras, blockers = tl.compat_plan("5.99.0")
assert blockers == ["huggingface-hub>=2.1"]
def test_sidecar_hub_shadowed_by_base_env_pins(self, monkeypatch):
self._patch_env(
monkeypatch,
["huggingface-hub<2.0,>=1.31.0"],
{"huggingface-hub": "1.32.0", "hf-xet": "1.5.2"},
)
extras, blockers = tl.compat_plan("5.18.0")
assert blockers == []
assert extras == ("huggingface-hub==1.32.0", "hf-xet==1.5.2")
def test_dev_version_reads_main_setup_py(self, monkeypatch):
monkeypatch.setattr(
tl,
"_fetch_requires_dist",
lambda v: (_ for _ in ()).throw(AssertionError("dev builds are not on PyPI")),
)
monkeypatch.setattr(tl, "_fetch_main_requires", lambda: ["numpy>=99.0"])
extras, blockers = tl.compat_plan("5.14.0.dev0")
assert blockers == ["numpy>=99.0"]
def test_unfetchable_requires_dist_blocks_install(self, monkeypatch):
# Proceeding unverified could pin a sidecar whose imports crash workers.
monkeypatch.setattr(tl, "_fetch_requires_dist", lambda v: None)
extras, blockers = tl.compat_plan("5.13.0")
assert extras == () and len(blockers) == 1 and "retry" in blockers[0]
def test_extra_marker_requirements_skipped(self, monkeypatch):
self._patch_env(
monkeypatch,
['torch>=99.0; extra == "torch"', 'pytest; python_version < "3.0"'],
{},
)
extras, blockers = tl.compat_plan("5.13.0")
assert extras == () and blockers == []
def test_get_snapshot_waits_for_inflight_fetch(monkeypatch):
"""A caller arriving during a fetch must wait for it, not read a None as no upgrade needed."""
import threading as _threading
tl.clear_caches()
monkeypatch.setattr(tl, "_load_snapshot_file", lambda: None)
monkeypatch.setattr(tl, "_save_snapshot_file", lambda snapshot: None)
fetch_started = _threading.Event()
release = _threading.Event()
calls = {"n": 0}
def slow_refresh():
calls["n"] += 1
fetch_started.set()
release.wait(10)
return {
"schema": tl._SNAPSHOT_SCHEMA,
"fetched_at": time.time(),
"pypi_version": "5.99.0",
"pypi_model_types": ["brandnew"],
"main_model_types": ["brandnew"],
"main_checked": True,
}
monkeypatch.setattr(tl, "_refresh_snapshot", slow_refresh)
answers: dict[str, dict | None] = {}
winner = _threading.Thread(target = lambda: answers.__setitem__("winner", tl._get_snapshot()))
winner.start()
assert fetch_started.wait(10)
loser = _threading.Thread(target = lambda: answers.__setitem__("loser", tl._get_snapshot()))
loser.start()
# The loser is parked on the in-flight fetch; nothing can land until it is released.
loser.join(0.5)
assert loser.is_alive()
release.set()
winner.join(10)
loser.join(10)
assert calls["n"] == 1
assert answers["winner"] is not None and answers["winner"]["pypi_version"] == "5.99.0"
assert answers["loser"] is not None and answers["loser"]["pypi_version"] == "5.99.0"
tl.clear_caches()
def test_inflight_wait_covers_a_whole_refresh():
"""The in-flight wait must cover a whole refresh's worst case, or the loser returns a false None."""
urls = 1 + 2 * len(tl._AUTO_FILES)
assert tl._REFRESH_URL_COUNT == urls
worst_case = urls * (1 + tl._FETCH_RETRIES) * tl._FETCH_TIMEOUT_SECONDS
assert tl._INFLIGHT_WAIT_SECONDS >= worst_case
def test_get_snapshot_dedupes_concurrent_fetch(monkeypatch):
"""A caller that finds a fetch in flight never starts a second one."""
with tl._lock:
tl._is_fetching = True
calls = {"n": 0}
def boom():
calls["n"] += 1
raise AssertionError("must not fetch while another fetch is in flight")
monkeypatch.setattr(tl, "_refresh_snapshot", boom)
assert tl._get_snapshot() is None
assert calls["n"] == 0
tl.clear_caches()
def test_install_serialized():
"""A second install call while one is in progress gets a structured refusal."""
from utils.transformers_version import try_begin_sidecar_swap
assert try_begin_sidecar_swap() is True
out = tl.install_latest_transformers("5.13.0")
assert out["success"] is False
assert "already in progress" in out["message"]
tl.clear_caches()
def test_install_in_progress_reflects_reservation():
"""is_install_in_progress mirrors the swap reservation; a lazy repair blocks worker starts."""
from utils.transformers_version import end_sidecar_swap, try_begin_sidecar_swap
assert tl.is_install_in_progress() is False
assert try_begin_sidecar_swap() is True
try:
assert tl.is_install_in_progress() is True
finally:
end_sidecar_swap()
assert tl.is_install_in_progress() is False
def test_upgrade_check_sees_nested_model_types(monkeypatch):
"""A supported wrapper with a brand-new nested backbone must still signal."""
cfg = {
"model_type": "llava",
"text_config": {"model_type": "zz_brand_new_llm"},
}
monkeypatch.setattr(tl, "_load_config_json", lambda *a, **k: cfg)
monkeypatch.setattr(
tl,
"latest_transformers_supports",
lambda mt: {
"pypi_version": "5.13.0",
"supported_in_pypi": mt == "zz_brand_new_llm",
"supported_in_main": mt == "zz_brand_new_llm",
},
)
out = tl.check_upgrade_for_model("some-org/wrapped-new-backbone")
assert out is not None
assert out["model_type"] == "zz_brand_new_llm"
def test_upgrade_check_ignores_nested_known_types(monkeypatch):
"""All nested types known to installed overlays -> no signal, no remote call."""
cfg = {
"model_type": "llava",
"text_config": {"model_type": "llama"},
"vision_config": {"model_type": "clip_vision_model"},
}
monkeypatch.setattr(tl, "_load_config_json", lambda *a, **k: cfg)
calls = []
monkeypatch.setattr(tl, "latest_transformers_supports", lambda mt: calls.append(mt) or None)
assert tl.check_upgrade_for_model("some-org/normal-vlm") is None
assert calls == []
def test_upgrade_check_requires_primary_supported(monkeypatch):
"""A nested-only type in latest must not prompt: routing still cannot load the primary."""
_shared_setup_3(monkeypatch)
monkeypatch.setattr(
tl,
"latest_transformers_supports",
lambda mt: {
"pypi_version": "5.13.0",
"supported_in_pypi": mt == "zz_new_llm",
"supported_in_main": mt == "zz_new_llm",
},
)
assert tl.check_upgrade_for_model("some-org/half-supported") is None
def test_upgrade_check_requires_every_missing_type(monkeypatch):
"""A missing nested backbone suppresses the prompt, since CONFIG_MAPPING would still fail on the
sub-config; all supported gives a signal carrying the primary type."""
_shared_setup_3(monkeypatch)
monkeypatch.setattr(
tl,
"latest_transformers_supports",
lambda mt: {
"pypi_version": "5.13.0",
"supported_in_pypi": mt == "zz_new_wrapper",
"supported_in_main": mt == "zz_new_wrapper",
},
)
assert tl.check_upgrade_for_model("some-org/half-supported") is None
monkeypatch.setattr(
tl,
"latest_transformers_supports",
lambda mt: {
"pypi_version": "5.13.0",
"supported_in_pypi": True,
"supported_in_main": True,
},
)
out = tl.check_upgrade_for_model("some-org/fully-supported")
assert out is not None and out["model_type"] == "zz_new_wrapper"
def test_upgrade_check_ignores_inert_nested_types(monkeypatch):
"""Cosmos3-Edge's projector_config model_type is never registered nor built (a plain dict), so
it must not veto the offer the way an unknown backbone does."""
_shared_setup_2(monkeypatch)
cfg = {
"model_type": "cosmos3_edge",
"projector_config": {"model_type": "cosmos3_edge_projector"},
"text_config": {"model_type": "cosmos3_edge_text"},
"vision_config": {"model_type": "cosmos3_edge_vision"},
}
monkeypatch.setattr(tl, "_load_config_json", lambda *a, **k: cfg)
asked = []
unregistered = ("cosmos3_edge_projector", "zz_unknown_projector")
def supports(mt):
asked.append(mt)
return {
"pypi_version": "5.20.2",
"supported_in_pypi": mt not in unregistered,
"supported_in_main": mt not in unregistered,
}
monkeypatch.setattr(tl, "latest_transformers_supports", supports)
out = tl.check_upgrade_for_model("nvidia/Cosmos3-Edge")
assert out is not None and out["model_type"] == "cosmos3_edge"
assert out["supported_in_pypi"] is True
assert "cosmos3_edge_projector" not in asked
cfg["projector_config"] = {"model_type": "zz_unknown_projector"}
assert tl.check_upgrade_for_model("nvidia/Cosmos3-Edge") is None
def test_install_success_invalidates_capability_caches(monkeypatch):
"""Install success drops tier probes, latest mapping, vision-detection cache; no restart."""
from utils.models import model_config as mc
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
monkeypatch.setattr(tl, "compat_plan", lambda v: ((), []))
monkeypatch.setattr(
tl, "ensure_latest_transformers_venv", lambda v, extra_packages = (), before_swap = None: True
)
monkeypatch.setattr(tl, "latest_venv_pinned_version", lambda: "5.13.0")
tv._probe_tier_cache["stale/model"] = "default"
tv._config_mapping_cache["latest"] = frozenset({"stale_type"})
tv._config_mapping_cache["default"] = frozenset({"llama"})
mc._vision_detection_cache[("stale/model", None, False)] = False
result = install_latest_transformers("5.13.0")
assert result["success"] is True
assert tv._probe_tier_cache == {}
assert "latest" not in tv._config_mapping_cache
assert tv._config_mapping_cache.get("default") == frozenset({"llama"})
assert mc._vision_detection_cache == {}
tv._probe_tier_cache.clear()
tv._config_mapping_cache.clear()
tl.clear_caches()
def test_vision_subprocess_unions_sidecar_registry():
"""Vision-check script unions the active sidecar registry so sidecar-only archs classify."""
from utils.models import model_config as mc
script = mc._VISION_CHECK_SCRIPT
ast.parse(script)
stub_registry = {
"MODEL_FOR_IMAGE_TEXT_TO_TEXT_MAPPING_NAMES": {
"zz_sidecar_vlm": "ZzSidecarForConditionalGeneration"
},
}
ns = {}
# Exec only the registry-union block against a stubbed sidecar registry.
body = script.split("from transformers import AutoConfig", 1)[1]
body = body.split("kwargs = {", 1)[0]
helpers = script.split("sys.path.insert(0, backend_dir)", 1)[1]
helpers = helpers.split("try:", 1)[0]
exec(helpers, ns)
class _FakeMa:
MODEL_FOR_IMAGE_TEXT_TO_TEXT_MAPPING_NAMES = stub_registry[
"MODEL_FOR_IMAGE_TEXT_TO_TEXT_MAPPING_NAMES"
]
import sys as _sys
import types as _types
fake_pkg = _types.ModuleType("transformers.models.auto")
fake_pkg.modeling_auto = _FakeMa
saved = {
k: _sys.modules.get(k)
for k in ("transformers.models.auto", "transformers.models.auto.modeling_auto")
}
_sys.modules["transformers.models.auto"] = fake_pkg
_sys.modules["transformers.models.auto.modeling_auto"] = _FakeMa
try:
exec(textwrap.dedent(body), ns)
finally:
for k, v in saved.items():
if v is None:
_sys.modules.pop(k, None)
else:
_sys.modules[k] = v
assert "zz_sidecar_vlm" in ns["_VLM_MODEL_TYPES"]
assert "ZzSidecarForConditionalGeneration" in ns["_VLM_CLASS_NAMES"]
class _Cfg:
architectures = ["ZzSidecarForConditionalGeneration"]
model_type = "zz_sidecar_vlm"
assert ns["_is_vlm"](_Cfg()) is True
def test_upgrade_check_mixed_pypi_main_reports_dev_only(monkeypatch):
"""Primary type in PyPI but nested type only on main: no install may be offered (CONFIG_MAPPING
fails on the nested sub-config), so the aggregate reads main-only."""
_shared_setup_3(monkeypatch)
monkeypatch.setattr(
tl,
"latest_transformers_supports",
lambda mt: {
"pypi_version": "5.13.0",
"supported_in_pypi": mt == "zz_new_wrapper",
"supported_in_main": True,
},
)
out = tl.check_upgrade_for_model("some-org/mixed-support")
assert out is not None
assert out["model_type"] == "zz_new_wrapper"
assert out["supported_in_pypi"] is False
assert out["supported_in_main"] is True
def test_install_endpoint_not_mounted_on_v1():
"""Admin pip-install endpoint belongs on studio_router, not OpenAI-compatible /v1 mount."""
from routes import inference as ri
path = "/install-latest-transformers"
assert path in [r.path for r in ri.studio_router.routes]
assert path not in [r.path for r in ri.router.routes]
def test_kill_switch_removes_provisioned_latest_from_routing(tmp_path, monkeypatch):
"""UNSLOTH_STUDIO_NO_LATEST_TRANSFORMERS must roll back a provisioned latest
sidecar: no overlay mapping, no probe participation, no file deletion needed."""
venv_dir = tmp_path / ".venv_t5_latest"
(venv_dir / "transformers").mkdir(parents = True)
(venv_dir / tv._LATEST_PIN_MARKER).write_text("5.13.0")
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(venv_dir))
assert tv._overlay_transformers_dir("latest") == str(venv_dir / "transformers")
assert tv._probe_tier_order() == tv._PROBE_TIER_ORDER + ("latest",)
monkeypatch.setenv("UNSLOTH_STUDIO_NO_LATEST_TRANSFORMERS", "1")
tv._config_mapping_cache.pop("latest", None)
assert tv._overlay_transformers_dir("latest") is None
assert tv._probe_tier_order() == tv._PROBE_TIER_ORDER
tv._config_mapping_cache.pop("latest", None)
def test_repair_failure_preserves_pin_and_live_dir(tmp_path, monkeypatch):
"""A failed lazy repair keeps the pinned live sidecar so a later attempt can retry it."""
venv_dir = tmp_path / ".venv_t5_latest"
venv_dir.mkdir()
(venv_dir / tv._LATEST_PIN_MARKER).write_text("5.13.0")
(venv_dir / "partial_file").write_text("x")
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(venv_dir))
monkeypatch.setattr(tv, "_venv_dir_is_valid", lambda *a: False)
monkeypatch.setattr(tv, "_ensure_venv_dir", lambda *a, **k: False)
from utils.transformers_version import latest_venv_pinned_version
assert tv._ensure_venv_t5_latest_exists() is False
assert venv_dir.is_dir()
assert (venv_dir / "partial_file").exists()
assert latest_venv_pinned_version() == "5.13.0"
assert not (tmp_path / ".venv_t5_latest.staging").exists()
def test_failed_staging_install_removes_staging_dir(tmp_path, monkeypatch):
"""A pip failure inside _ensure_venv_dir returns False without raising, so
the except cleanup never runs; the partial staging dir must still go."""
venv_dir = tmp_path / ".venv_t5_latest"
monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(venv_dir))
def _fake_ensure(dir_, packages, label):
Path(dir_).mkdir(parents = True, exist_ok = True)
(Path(dir_) / "partial").write_text("x")
return False
monkeypatch.setattr(tv, "_ensure_venv_dir", _fake_ensure)
assert ensure_latest_transformers_venv("5.13.0") is False
assert not Path(str(venv_dir) + ".staging").exists()
def _slow_drip_server(chunks: int, gap: float):
"""Localhost server that sends a body one chunk per gap, so only a wall-clock budget stops it."""
import socket as _socket
import threading as _threading
sock = _socket.socket()
sock.setsockopt(_socket.SOL_SOCKET, _socket.SO_REUSEADDR, 1)
sock.bind(("127.0.0.1", 0))
sock.listen(1)
def serve():
try:
conn, _ = sock.accept()
conn.recv(65536)
piece = b"x" * 8
conn.sendall(
b"HTTP/1.1 200 OK\r\nContent-Length: %d\r\nConnection: close\r\n\r\n"
% (len(piece) * chunks)
)
for _ in range(chunks):
time.sleep(gap)
conn.sendall(piece)
conn.close()
except Exception:
pass
_threading.Thread(target = serve, daemon = True).start()
return f"http://127.0.0.1:{sock.getsockname()[1]}/"
def test_fetch_text_bounds_the_whole_transfer_not_just_socket_operations(monkeypatch):
"""A dribbling body must hit the transfer budget; urlopen's timeout bounds only each read."""
monkeypatch.setattr(tl, "_FETCH_RETRIES", 0)
monkeypatch.setattr(tl, "_FETCH_TIMEOUT_SECONDS", 1.0)
monkeypatch.setattr(tl, "_FETCH_DEADLINE_SECONDS", 0.4)
url = _slow_drip_server(chunks = 30, gap = 0.05)
started = time.monotonic()
body = tl._fetch_text(url)
elapsed = time.monotonic() - started
assert body is None, "a transfer past its budget must not be accepted as an answer"
assert elapsed < 1.2, f"fetch ran {elapsed:.2f}s, past its own budget"
def test_fetch_attempt_bound_covers_the_budget_and_one_blocking_read():
"""The attempt bound is the budget plus one straddling read, so the in-flight wait is a ceiling."""
assert tl._FETCH_ATTEMPT_SECONDS == tl._FETCH_DEADLINE_SECONDS + tl._FETCH_TIMEOUT_SECONDS
urls = 1 + 2 * len(tl._AUTO_FILES)
worst_case = urls * (1 + tl._FETCH_RETRIES) * tl._FETCH_ATTEMPT_SECONDS
assert tl._INFLIGHT_WAIT_SECONDS >= worst_case
def test_waiter_never_answers_no_upgrade_while_the_refresh_is_still_running(monkeypatch):
"""A waiter must not answer no-upgrade while the refresh still runs, or the model can't load."""
import threading as _threading
tl.clear_caches()
monkeypatch.setattr(tl, "_load_snapshot_file", lambda: None)
monkeypatch.setattr(tl, "_save_snapshot_file", lambda snapshot: None)
# In-flight wait expires before a slow refresh ends: a mirror within its socket timeout.
monkeypatch.setattr(tl, "_INFLIGHT_WAIT_SECONDS", 0.05)
fetch_started = _threading.Event()
def slow_refresh():
fetch_started.set()
time.sleep(0.6)
return {
"schema": tl._SNAPSHOT_SCHEMA,
"fetched_at": time.time(),
"pypi_version": "5.99.0",
"pypi_model_types": ["brandnew"],
"main_model_types": ["brandnew"],
"main_checked": True,
}
monkeypatch.setattr(tl, "_refresh_snapshot", slow_refresh)
answers: dict[str, dict | None] = {}
winner = _threading.Thread(target = lambda: answers.__setitem__("winner", tl._get_snapshot()))
winner.start()
assert fetch_started.wait(10)
loser = _threading.Thread(target = lambda: answers.__setitem__("loser", tl._get_snapshot()))
loser.start()
winner.join(10)
loser.join(10)
assert answers["winner"] is not None
assert answers["loser"] is not None, "the loser answered 'no upgrade' mid-refresh"
assert answers["loser"]["pypi_version"] == "5.99.0"
tl.clear_caches()
# Budget must not reject ordinary responses either, or /validate never finds an upgrade.
class _BodyServer:
"""Serves one body, either in full or split across chunks."""
def __init__(
self,
body: bytes,
chunked = False,
status = 200,
):
import http.server
import threading
outer = self
self.body, self.chunked, self.status = body, chunked, status
class Handler(http.server.BaseHTTPRequestHandler):
protocol_version = "HTTP/1.1"
def do_GET(self): # noqa: N802
self.send_response(outer.status)
if outer.chunked:
self.send_header("Transfer-Encoding", "chunked")
self.end_headers()
step = max(1, len(outer.body) // 7)
for i in range(0, len(outer.body), step):
piece = outer.body[i : i + step]
self.wfile.write(f"{len(piece):x}\r\n".encode() + piece + b"\r\n")
self.wfile.write(b"0\r\n\r\n")
else:
self.send_header("Content-Length", str(len(outer.body)))
self.end_headers()
self.wfile.write(outer.body)
self.wfile.flush()
def log_message(self, *args):
pass
self.httpd = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler)
self.url = f"http://127.0.0.1:{self.httpd.server_port}/x"
self.thread = threading.Thread(target = self.httpd.serve_forever, daemon = True)
def __enter__(self):
self.thread.start()
return self
def __exit__(self, *exc):
self.httpd.shutdown()
self.httpd.server_close()
_AUTO_SOURCE = textwrap.dedent(
"""
CONFIG_MAPPING_NAMES = OrderedDict[str, str](
[
("albert", "AlbertConfig"),
("llama", "LlamaConfig"),
]
)
"""
)
@pytest.mark.parametrize("chunked", [False, True])
def test_an_ordinary_response_comes_back_whole(chunked):
with _BodyServer(_AUTO_SOURCE.encode(), chunked = chunked) as server:
body = tl._fetch_text(server.url)
assert body is not None and body.strip() == _AUTO_SOURCE.strip()
def test_a_multi_chunk_body_is_not_truncated_by_the_budget():
# configuration_auto.py is ~200 KB against a 64 KB read, so several chunks is normal.
payload = (_AUTO_SOURCE + "# padding\n" * 40_000).encode()
with _BodyServer(payload) as server:
body = tl._fetch_text(server.url)
assert body is not None and len(body) == len(payload.decode())
def test_an_empty_body_is_not_a_failure():
with _BodyServer(b"") as server:
assert tl._fetch_text(server.url) == ""
def test_a_missing_file_stays_distinguishable_from_a_failure():
# Pre-5.10 tags have no auto_mappings.py, so a 404 is its own answer.
with _BodyServer(b"nope", status = 404) as server:
assert tl._fetch_text(server.url) == tl._FETCH_MISSING
def test_a_truncated_source_fails_the_lookup_instead_of_shrinking_the_map(monkeypatch):
# A truncated mapping cached for the TTL would offer upgrades to every missing model.
truncated = _AUTO_SOURCE[: len(_AUTO_SOURCE) // 2].encode()
with _BodyServer(truncated) as server:
monkeypatch.setattr(tl, "_RAW_URL", server.url + "?{ref}{name}")
assert tl._fetch_remote_model_types("v5.15.0") is None
def _hardware_module(device):
"""Stand in for utils.hardware, whose import needs real hardware."""
import enum
module = _types.ModuleType("utils.hardware")
class DeviceType(str, enum.Enum):
CUDA = "cuda"
XPU = "xpu"
MLX = "mlx"
CPU = "cpu"
module.DeviceType = DeviceType
module.get_device = lambda: DeviceType(device)
return module
@pytest.fixture(autouse = True)
def _transformers_backend_host(monkeypatch):
"""Pin device to cuda so tests ignore the host; on MLX the upgrade check short-circuits."""
monkeypatch.setitem(sys.modules, "utils.hardware", _hardware_module("cuda"))
@pytest.mark.parametrize("device", ["cuda", "cpu", "xpu"])
def test_transformers_backends_still_get_the_upgrade_offer(device, monkeypatch):
monkeypatch.setitem(sys.modules, "utils.hardware", _hardware_module(device))
_shared_setup_2(monkeypatch)
monkeypatch.setattr(tl, "_load_config_json", lambda *a, **k: {"model_type": "brandnew_arch"})
_shared_setup_1(monkeypatch)
offered = tl.check_upgrade_for_model("org/brandnew")
assert offered is not None and offered["model_type"] == "brandnew_arch"
def test_mlx_host_is_never_offered_a_transformers_upgrade(monkeypatch):
"""MLX chooses its backend from hardware and never falls back to transformers, so no install can
make an architecture loadable there."""
_shared_setup_2(monkeypatch)
monkeypatch.setattr(tl, "_load_config_json", lambda *a, **k: {"model_type": "muse_glimmer"})
_shared_setup_1(monkeypatch)
monkeypatch.setitem(sys.modules, "utils.hardware", _hardware_module("cuda"))
assert tl.check_upgrade_for_model("mlx-community/Muse-Glimmer-30B-4bit") is not None
monkeypatch.setitem(sys.modules, "utils.hardware", _hardware_module("mlx"))
assert tl.check_upgrade_for_model("mlx-community/Muse-Glimmer-30B-4bit") is None
def _bnb(model_type):
return {
"model_type": model_type,
"quantization_config": {"quant_method": "bitsandbytes", "load_in_4bit": True},
}
def test_mlx_still_offers_the_upgrade_for_a_bitsandbytes_repo(monkeypatch):
"""MLX dequantizes bnb weights via transformers, which raises on a new type, so the offer stays."""
_shared_setup_2(monkeypatch)
_shared_setup_1(monkeypatch)
monkeypatch.setitem(sys.modules, "utils.hardware", _hardware_module("mlx"))
# Control: the same architecture unquantized is MLX's own to load, and is skipped.
monkeypatch.setattr(tl, "_load_config_json", lambda *a, **k: {"model_type": "muse_glimmer"})
assert tl.check_upgrade_for_model("mlx-community/Muse-Glimmer-30B-4bit") is None
# A third-party bnb build of it goes through transformers, so the offer is real.
monkeypatch.setattr(tl, "_load_config_json", lambda *a, **k: _bnb("muse_glimmer"))
offered = tl.check_upgrade_for_model("someorg/Muse-Glimmer-30B-bnb-4bit")
assert offered is not None and offered["model_type"] == "muse_glimmer"
def test_mlx_skips_the_unsloth_bnb_repo_it_swaps_for_a_base(monkeypatch):
"""unsloth/*-bnb-4bit ids remap to a full-precision base on MLX, so they keep skipping the offer."""
_shared_setup_2(monkeypatch)
monkeypatch.setattr(tl, "_load_config_json", lambda *a, **k: _bnb("muse_glimmer"))
_shared_setup_1(monkeypatch)
monkeypatch.setitem(sys.modules, "utils.hardware", _hardware_module("mlx"))
for remapped in (
"unsloth/Muse-Glimmer-30B-unsloth-bnb-4bit",
"unsloth/Muse-Glimmer-30B-bnb-4bit",
):
assert tl.check_upgrade_for_model(remapped) is None
# Same suffix, different owner: not remapped, so it still goes to transformers.
assert tl.check_upgrade_for_model("someorg/Muse-Glimmer-30B-bnb-4bit") is not None
def test_upgrade_offer_survives_a_broken_hardware_import(monkeypatch):
"""Detection is best effort: failing it must not silence a real offer."""
broken = _types.ModuleType("utils.hardware")
def _raise():
raise RuntimeError("no hardware")
broken.get_device = _raise
broken.DeviceType = object()
monkeypatch.setitem(sys.modules, "utils.hardware", broken)
assert tl._architecture_cannot_come_from_transformers() is False
def test_fetch_main_requires_parses_setup_py(monkeypatch):
setup_py = textwrap.dedent(
"""
_deps = [
"huggingface-hub>=1.31.0,<2.0",
"numpy>=1.17",
"pytest>=7.2.0",
"tokenizers>=0.22.0,<=0.23.0",
]
install_requires = [
deps["huggingface-hub"],
deps["numpy"],
deps["tokenizers"],
]
"""
)
monkeypatch.setattr(tl, "_fetch_text", lambda url: setup_py)
assert tl._fetch_main_requires() == [
"huggingface-hub>=1.31.0,<2.0",
"numpy>=1.17",
"tokenizers>=0.22.0,<=0.23.0",
]
def test_fetch_main_requires_reads_the_pinned_commit(monkeypatch):
seen = []
monkeypatch.setattr(tl, "_fetch_text", lambda url: seen.append(url))
tl._fetch_main_requires()
with tv.transformers_main_at("e" * 40):
tl._fetch_main_requires()
assert seen[0].endswith("/main/setup.py") and seen[1].endswith(f"/{'e' * 40}/setup.py")
def test_fetch_main_version_requires_dev_string(monkeypatch):
monkeypatch.setattr(tl, "_fetch_text", lambda url: '__version__ = "5.18.0"\n')
assert tl._fetch_main_version() is None
monkeypatch.setattr(tl, "_fetch_text", lambda url: '__version__ = "5.19.0.dev0"\n')
assert tl._fetch_main_version() == "5.19.0.dev0"
def _custom_code_model(tmp_path: Path, saved_by: str) -> str:
"""LFM3-shaped checkpoint: model_type no transformers ships, config class in repo code."""
d = tmp_path / f"custom_{saved_by}"
d.mkdir()
cfg = {
"model_type": "lfm3_omni",
"architectures": ["Lfm3OmniForConditionalGeneration"],
"auto_map": {"AutoConfig": "configuration_lfm3_omni.Lfm3OmniConfig"},
"transformers_version": saved_by,
}
(d / "config.json").write_text(json.dumps(cfg))
return str(d)
class TestCustomCodeRouting:
"""The probe parses with trust_remote_code=False, so custom code fell to 5.3.0 (#16054)."""
@pytest.fixture(autouse = True)
def _no_probe(self, monkeypatch):
_fake_overlays(monkeypatch)
monkeypatch.setattr(tv, "_probe_tier", lambda *a, floor = "530", **k: floor)
monkeypatch.setattr(tv, "latest_venv_pinned_version", lambda: None)
monkeypatch.setattr(tv, "TRANSFORMERS_DEFAULT_VERSION", "5.5.0")
def test_newer_than_every_tier_routes_to_newest_fixed_tier(self, tmp_path: Path):
assert get_transformers_tier(_custom_code_model(tmp_path, "5.19.0.dev0")) == "510"
def test_routes_to_pinned_latest_when_new_enough(self, tmp_path: Path, monkeypatch):
monkeypatch.setattr(tv, "latest_venv_pinned_version", lambda: "5.22.0")
assert get_transformers_tier(_custom_code_model(tmp_path, "5.19.0.dev0")) == "latest"
def test_oldest_sidecar_at_or_above_saving_version(self, tmp_path: Path):
assert get_transformers_tier(_custom_code_model(tmp_path, "5.8.0")) == "510"
def test_default_kept_when_new_enough(self, tmp_path: Path):
assert get_transformers_tier(_custom_code_model(tmp_path, "5.3.0")) == "default"
def test_patch_release_fits_its_minor(self, tmp_path: Path):
assert get_transformers_tier(_custom_code_model(tmp_path, "5.5.4")) == "default"
def test_v5_tokenizer_saved_at_530_keeps_530(self, tmp_path: Path):
d = Path(_custom_code_model(tmp_path, "5.3.0"))
(d / "tokenizer_config.json").write_text(
json.dumps({"tokenizer_class": "TokenizersBackend"})
)
assert get_transformers_tier(str(d)) == "530"
def test_upgrade_offered_when_pypi_is_new_enough(self, tmp_path: Path, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
result = check_upgrade_for_model(_custom_code_model(tmp_path, "5.12.0.dev0"))
assert result is not None
assert result["model_type"] == "lfm3_omni" and result["pypi_version"] == "5.13.0"
assert result["supported_in_pypi"] is True
def test_no_offer_when_pypi_too_old(self, tmp_path: Path, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
assert check_upgrade_for_model(_custom_code_model(tmp_path, "5.19.0.dev0")) is None
def test_no_offer_when_installed_tier_fits(self, tmp_path: Path, monkeypatch):
calls = _no_network(monkeypatch)
assert check_upgrade_for_model(_custom_code_model(tmp_path, "5.8.0")) is None
assert calls["n"] == 0
def test_native_tier_is_raised_to_saving_version(self, tmp_path: Path):
d = tmp_path / "custom_native"
d.mkdir()
cfg = {
"model_type": "qwen3_moe",
"architectures": ["Qwen3MoeForCausalLM"],
"auto_map": {"AutoConfig": "configuration_x.XConfig"},
"transformers_version": "5.8.0",
}
(d / "config.json").write_text(json.dumps(cfg))
assert get_transformers_tier(str(d)) == "510"
def test_main_offered_when_pypi_is_behind(self, tmp_path: Path, monkeypatch):
monkeypatch.setattr("urllib.request.urlopen", _fake_urlopen_factory({}))
result = check_upgrade_for_model(_custom_code_model(tmp_path, "5.14.0.dev0"))
assert result is not None
assert result["supported_in_pypi"] is False and result["supported_in_main"] is True
assert result["main_version"] == "5.14.0.dev0"
def test_nested_saving_version_routes_when_top_level_has_none(
self, tmp_path: Path, monkeypatch
):
monkeypatch.setattr(tv, "latest_venv_pinned_version", lambda: "5.22.0")
d = Path(_custom_code_model(tmp_path, "unused"))
cfg = json.loads((d / "config.json").read_text())
del cfg["transformers_version"]
cfg["lfm"] = {"model_type": "lfm3", "transformers_version": "5.19.0.dev0"}
cfg["depthformer"] = {"model_type": "lfm3", "transformers_version": "5.8.0"}
(d / "config.json").write_text(json.dumps(cfg))
assert get_transformers_tier(str(d)) == "latest"
def test_no_saving_version_anywhere_is_not_routed(self, tmp_path: Path):
d = Path(_custom_code_model(tmp_path, "unused"))
cfg = json.loads((d / "config.json").read_text())
del cfg["transformers_version"]
cfg["encoder"] = {"hidden_size": 8}
(d / "config.json").write_text(json.dumps(cfg))
assert tv._remote_code_min_version(cfg) is None
def test_hub_name_match_is_raised_to_saving_version(self, monkeypatch):
cfg = {
"model_type": "qwen3_5",
"auto_map": {"AutoConfig": "configuration_x.XConfig"},
"transformers_version": "5.8.0",
}
monkeypatch.setattr(tv, "_load_config_json", lambda name, token = None: cfg)
assert get_transformers_tier("someorg/Qwen3.5-Custom") == "510"