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
Studio: load a downloaded GGUF from disk when the Hub cannot be read or refuses it (#12161)
Daniel Han866b5bcff5e0
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.pyindex 2e814690646..9ba1453e73d 100644--- a/studio/backend/core/inference/llama_cpp.py+++ b/studio/backend/core/inference/llama_cpp.py@@ -3209,8 +3209,12 @@ def _cached_variant_candidates(hf_variant: str,*,require_mmproj: bool = False,+ strict: bool = False,) -> Generator[tuple[str, str, list[str], Path], None, None]:- """Yield complete cached variant copies in snapshot preference order."""+ """Yield complete cached variant copies in snapshot preference order.++ A copy whose recorded download is unfinished or cancelled comes last, and ``strict``+ drops it: only a copy that can run without the Hub qualifies then."""try:from hub.utils.gguf_sources import (cached_gguf_manifest_complete,@@ -3249,7 +3253,8 @@ def _cached_variant_candidates(continueyield candidate# Keep existing reuse semantics when no completed duplicate is available.- yield from pending_downloads+ if not strict:+ yield from pending_downloadsexcept Exception as e:logger.debug(f"Cache lookup for variant failed: {e}")@@ -3354,8 +3359,10 @@ def cached_gguf_for_load(require_mmproj: bool = False,verify_sizes: bool = False,hf_token: Optional[str] = None,+ strict: bool = False,) -> Optional[str]:- """Return a cached GGUF that can be loaded without downloading."""+ """Return a cached GGUF that can be loaded without downloading (``strict``: and whose+ recorded download is complete, see _cached_variant_candidates)."""if not hf_variant:return Nonehf_repo = _resolve_repo_id_casing(hf_repo)@@ -3363,6 +3370,7 @@ def cached_gguf_for_load(hf_repo,hf_variant,require_mmproj = require_mmproj,+ strict = strict,):if verify_sizes and not _cached_candidate_matches_revision_size(hf_repo, candidate, hf_token@@ -7206,6 +7214,8 @@ class LlamaCppBackend:self._last_load_warning: Optional[str] = None# Same, for a quant fallback: the download fills the pair, the launch publishes it.self._variant_fallback_warning: Optional[str] = None+ # The route's Hub notice for the running model, so /status matches the load response.+ self.hub_access_warning: Optional[str] = Noneself._pending_variant_fallback: Optional[tuple[str, str]] = None# Set per launch by _record_carveout_advice; None on nearly every load.self._last_carveout_advice: Optional[dict] = None@@ -14687,6 +14697,7 @@ class LlamaCppBackend:reverse -- the placement everything was priced against is the one that justdied."""self._last_load_warning = None+ self.hub_access_warning = None# Same lifetime, same reason: the advice describes the placement the dying# child was priced against and must not be reported against its replacement.self._last_carveout_advice = Nonediff --git a/studio/backend/hub/services/models/gguf_variants.py b/studio/backend/hub/services/models/gguf_variants.pyindex 8464fcf5e67..0dc6dc5fcbd 100644--- a/studio/backend/hub/services/models/gguf_variants.py+++ b/studio/backend/hub/services/models/gguf_variants.py@@ -177,14 +177,41 @@ def _variant_requirement_cache_get(key: tuple[str, str, str]) -> Optional[_GgufVdef _variant_requirement_cache_set_many(repo_id: str, hf_token: Optional[str], requirements: dict[str, _GgufVariantRequirement]) -> None:+ global _VARIANT_REQUIREMENT_FORGOTTENwith _VARIANT_HASH_LOCK:now = time.monotonic()for quant, requirement in requirements.items():key = _variant_hash_cache_key(repo_id, quant, hf_token)_VARIANT_REQUIREMENT_CACHE[key] = (requirement, now)_VARIANT_REQUIREMENT_CACHE.move_to_end(key)+ known = key[:2]+ _VARIANT_REQUIREMENT_LAST_KNOWN[known] = requirement+ _VARIANT_REQUIREMENT_LAST_KNOWN.move_to_end(known)while len(_VARIANT_REQUIREMENT_CACHE) > _VARIANT_HASH_MAX:_VARIANT_REQUIREMENT_CACHE.popitem(last = False)+ while len(_VARIANT_REQUIREMENT_LAST_KNOWN) > _VARIANT_REQUIREMENT_LAST_KNOWN_MAX:+ _VARIANT_REQUIREMENT_LAST_KNOWN.popitem(last = False)+ _VARIANT_REQUIREMENT_FORGOTTEN = True+++# Newest requirement per (repo, variant), kept past the TTL so an expired entry never reads as+# "nothing required". Not keyed by credential: it describes the repo's files.+_VARIANT_REQUIREMENT_LAST_KNOWN: "OrderedDict[tuple[str, str], _GgufVariantRequirement]" = (+ OrderedDict()+)+# After any eviction an absent entry may be a forgotten companion.+_VARIANT_REQUIREMENT_LAST_KNOWN_MAX = 65536+_VARIANT_REQUIREMENT_FORGOTTEN = False+++def _variant_requirement_last_known(key: tuple[str, ...]) -> Optional[_GgufVariantRequirement]:+ with _VARIANT_HASH_LOCK:+ return _VARIANT_REQUIREMENT_LAST_KNOWN.get(key[:2])+++def _variant_requirement_may_be_forgotten() -> bool:+ with _VARIANT_HASH_LOCK:+ return _VARIANT_REQUIREMENT_FORGOTTENdef _build_gguf_variant_requirements(siblings: list) -> dict[str, _GgufVariantRequirement]:@@ -1073,6 +1100,8 @@ async def get_gguf_variants_answer(cache_authorized = [True]variant_context_sources: dict[str, str] = {}hub_listing = None+ # The downloaded rows a Hub-less answer proved complete from disk, see _locally_resolved.+ locally_proven: list[Optional[frozenset]] = [None]def _compute(local_path: Optional[str] = local_path) -> GgufVariantsResponse:nonlocal hub_listing@@ -1401,6 +1430,57 @@ async def get_gguf_variants_answer(hf_token, repo_id = repo_id, is_cached = lambda: True, offline = bool(offline))+ def _locally_resolved(+ response: GgufVariantsResponse, snapshot: Optional[Path]+ ) -> GgufVariantsResponse:+ """*response* marked ``dependencies_resolved`` when the disk alone proves every+ downloaded row loadable. Only for answers given because the Hub could not be read+ (offline, or the listing failed): with the Hub up, a companion the current revision+ added is only visible in its listing, which is why a local-first answer never+ carries this. The proof, per downloaded quant: its main file is in *snapshot*, the+ snapshot's own manifest, cancel marker and blobs do not make it partial, the+ download's recorded plan (main shards and companions) is all on disk, and so is+ every companion a Hub answer earlier in this process named. A drafter that is still+ missing only turns speculative decoding off at load, so a quant downloaded before+ manifests existed is judged on its shards alone."""+ if snapshot is None or response.dependencies_resolved:+ return response+ from hub.utils.gguf_sources import (+ cached_gguf_manifest_complete,+ cached_gguf_source_partial,+ )++ downloaded = [v for v in response.variants if v.downloaded]+ if not downloaded or any(v.partial for v in downloaded):+ return response+ proven = set()+ for v in downloaded:+ if not v.quant or not v.filename:+ return response+ try:+ if not (snapshot / v.filename).is_file():+ return response+ if cached_gguf_source_partial(response.repo_id, v.quant, snapshot):+ return response+ if not cached_gguf_manifest_complete(response.repo_id, v.quant, snapshot):+ return response+ requirement = _variant_requirement_last_known(+ _variant_hash_cache_key(response.repo_id, v.quant, hf_token)+ )+ if requirement is None and _variant_requirement_may_be_forgotten():+ return response+ for expected in requirement.expected_files if requirement is not None else ():+ target = snapshot / expected.path+ if not target.is_file() or (+ expected.size and target.stat().st_size != expected.size+ ):+ return response+ except (OSError, RuntimeError, ValueError):+ return response+ proven.add((v.quant.lower(), v.filename))+ locally_proven[0] = frozenset(proven)+ return response.model_copy(update = {"dependencies_resolved": True})+def _scoped_local_response():"""The pinned snapshot's own answer, or None when it holds nothing."""if snapshot_scope is None or not cache_reads_authorized:@@ -1420,7 +1500,11 @@ async def get_gguf_variants_answer(if local_only:scoped_response = _scoped_local_response()if scoped_response is not None:- return scoped_response+ return (+ _locally_resolved(scoped_response, snapshot_scope)+ if offline+ else scoped_response+ )cached = (select_gguf_cache_snapshot(repo_id, root = hub_cache)if cache_reads_authorized@@ -1434,10 +1518,11 @@ async def get_gguf_variants_answer(# repo-dir walk a sibling revision's.answered_from[0] = str(snapshot)# The lister leaves torn quants in: they stay listed for management, but not ready.- return _with_state_partials(+ response = _with_state_partials(_local_response(repo_id, variants, has_vision, complete),snapshot,)+ return _locally_resolved(response, snapshot) if offline else responseif local_path and is_local_path(local_path):variants, has_vision = list_local_gguf_variants(local_path)if variants or has_vision:@@ -1475,7 +1560,7 @@ async def get_gguf_variants_answer(return Nonescoped_response = _scoped_local_response()if scoped_response is not None:- return scoped_response+ return _locally_resolved(scoped_response, snapshot_scope)cached = select_gguf_cache_snapshot(repo_id, root = hub_cache)if cached is not None:variants, has_vision, complete, snapshot = _merge_when_the_repo_id_loads(@@ -1484,8 +1569,11 @@ async def get_gguf_variants_answer(answered_from[0] = str(snapshot)# Same reason as the local_only branch above: an unreachable Hub is exactly when a resume has# nowhere else to surface, so state partials are included.- return _with_state_partials(- _local_response(repo_id, variants, has_vision, complete),+ return _locally_resolved(+ _with_state_partials(+ _local_response(repo_id, variants, has_vision, complete),+ snapshot,+ ),snapshot,)partial = _quants_from_state(repo_id, hub_cache)@@ -1934,9 +2022,11 @@ async def get_gguf_variants_answer(if cached is None:original_source = answered_from[0]original_local = answered_locally[0]+ original_proven = locally_proven[0]try:scoped = _compute(str(snapshot))finally:+ locally_proven[0] = original_provenanswered_from[0] = original_source# Restored too: this is a nested lookup, not the outer answer, and# leaving it set would suppress the merge that reads it.@@ -2077,6 +2167,16 @@ async def get_gguf_variants_answer(ready = [v for v in response.variants if v.downloaded and not v.partial]best = pick_best_gguf(_default_variant_candidates(ready or response.variants))response.default_variant = gguf_variant_key(best) if best else None+ if response.dependencies_resolved and locally_proven[0] is not None:+ rows = frozenset(+ (v.quant.lower(), v.filename)+ for v in response.variants+ if v.downloaded and v.quant and v.filename+ )+ if rows != locally_proven[0] or any(+ v.partial for v in response.variants if v.downloaded+ ):+ response = response.model_copy(update = {"dependencies_resolved": False})if skip or answered_locally[0]:return responsereturn _mark_empty_dir_cleanables(diff --git a/studio/backend/hub/utils/hf_tokens.py b/studio/backend/hub/utils/hf_tokens.pyindex 9abc5f9d570..dcd36467e84 100644--- a/studio/backend/hub/utils/hf_tokens.py+++ b/studio/backend/hub/utils/hf_tokens.py@@ -1042,6 +1042,15 @@ HUB_TOKEN_REJECTED_WARNING = ("model was read without it. Update or clear the token in Settings to keep access to ""gated and private models.")+++def hub_refused_cached_copy_warning(repo_id: str) -> str:+ return (+ f"Hugging Face refused {repo_id}, so Studio is running the copy already downloaded on "+ "this machine. It will not receive updates until access is restored."+ )++HUB_TOKEN_REJECTED_ERROR = ("Hugging Face rejected the saved token (HTTP 401); it may be expired or revoked. ""Update or clear it in Settings, then try again."@@ -1051,9 +1060,11 @@ HUB_TOKEN_REJECTED_ERROR = (class HubTokenRejections:"""What one request learned about its credential. Shared by the threads it hands off to."""- __slots__ = ("recovered", "refused", "_rejected", "_recovered")+ __slots__ = ("recovered", "refused", "served_from_cache", "_rejected", "_recovered")def __init__(self) -> None:+ # Repos the Hub refused that this request loaded from their downloaded copy instead.+ self.served_from_cache: "list[str]" = []self.recovered = Falseself.refused = False# Digests, never tokens: a traceback or debugger can print this.diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.pyindex f6a6ed12180..2113471124e 100644--- a/studio/backend/routes/inference.py+++ b/studio/backend/routes/inference.py@@ -88,6 +88,7 @@ from hub.utils.hf_tokens import (HfTokenArg,call_hub_with_anonymous_retry,collecting_hub_token_rejections,+ hub_refused_cached_copy_warning,)from hub.services.models.ollama import (acquire_ollama_model_ref,@@ -16147,15 +16148,56 @@ def _cancel_scoped_load_attempt(return attempt, is_running+def _hub_access_warnings(token_rejections) -> list[str]:+ """What this request's Hub reads tell the user: a refused token, a refused repo's copy."""+ warnings = [HUB_TOKEN_REJECTED_WARNING] if token_rejections.recovered else []+ warnings += [+ hub_refused_cached_copy_warning(repo)+ for repo in dict.fromkeys(token_rejections.served_from_cache)+ ]+ return warnings++def _with_token_rejected_warning(response, token_rejections):- """Tell the user the model loaded without their token, which Hugging Face refused."""- if not token_rejections.recovered or not isinstance(response, LoadResponse):+ """Tell the user the model loaded without their token, or from a copy the Hub now refuses."""+ warnings = _hub_access_warnings(token_rejections)+ if not warnings or not isinstance(response, LoadResponse):return responseexisting = response.memory_warning- warning = f"{existing} {HUB_TOKEN_REJECTED_WARNING}" if existing else HUB_TOKEN_REJECTED_WARNING+ warning = " ".join(([existing] if existing else []) + warnings)return response.model_copy(update = {"memory_warning": warning})+def _remember_hub_access_warning(response, token_rejections) -> None:+ """Keep a GGUF load's Hub notice for /status, whose warning the client re-shows after a load."""+ if isinstance(response, LoadResponse) and response.is_gguf:+ warnings = _hub_access_warnings(token_rejections)+ get_llama_cpp_backend().hub_access_warning = " ".join(warnings) or None+++def _status_load_warning(llama_backend) -> Optional[str]:+ """The running GGUF's load warning as its load response carried it."""+ notices = (llama_backend.last_load_warning, getattr(llama_backend, "hub_access_warning", None))+ return " ".join(notice for notice in notices if notice) or None+++# True only in the user's /load, the one that shows the warning; background loads stay refused.+_load_warnings_reach_user: contextvars.ContextVar[bool] = contextvars.ContextVar(+ "load_warnings_reach_user", default = False+)+++def _owner_session(fastapi_request) -> bool:+ """The machine owner's own UI session: not a managed account and no API key of any kind.++ _request_has_api_key, not _request_used_api_key: the latter excludes Unsloth's internal+ workflow keys for API monitoring, and a data-recipe subprocess holds one of those.+ """+ if fastapi_request is None or account_access.managed_account():+ return False+ return not _request_has_api_key(fastapi_request)++async def _run_tracked_load_model_impl(request: LoadRequest,fastapi_request: Request,@@ -16174,16 +16216,22 @@ async def _run_tracked_load_model_impl(try:if attempt.cancel_event.is_set():raise HTTPException(status_code = 409, detail = "Model load cancelled")- with collecting_hub_token_rejections() as token_rejections:- response = await _load_model_impl(- request,- fastapi_request,- current_subject,- current_request_counted = current_request_counted,- on_reload_confirmed = on_reload_confirmed,- load_cancel_event = attempt.cancel_event,- )- return _with_token_rejected_warning(response, token_rejections)+ warnings_token = _load_warnings_reach_user.set(True)+ try:+ with collecting_hub_token_rejections() as token_rejections:+ response = await _load_model_impl(+ request,+ fastapi_request,+ current_subject,+ current_request_counted = current_request_counted,+ on_reload_confirmed = on_reload_confirmed,+ load_cancel_event = attempt.cancel_event,+ )+ finally:+ _load_warnings_reach_user.reset(warnings_token)+ response = _with_token_rejected_warning(response, token_rejections)+ _remember_hub_access_warning(response, token_rejections)+ return responsefinally:if attempt.cancel_event.is_set() and not attempt.cancel_complete.is_set():if not await asyncio.to_thread(@@ -16907,17 +16955,21 @@ async def _load_model_impl(chat_template = _chat_template,)+ _caller_is_owner = _owner_session(fastapi_request) and _load_warnings_reach_user.get()+# is_lora auto-detected from adapter_config.json on disk/HF.# Probe wrap so offline loads skip 30-60s of soft-failed network checks before# the worker starts. Off-loop: the guard can spend seconds on DNS plus a HEAD and# its TCP fallback, and this handler is awaited directly by the route, so running# it inline would stall every unrelated request. Same shape as /validate.+def _resolve_config():with _hf_offline_if_unreachable_for(model_identifier):return ModelConfig.from_identifier(model_id = model_identifier,hf_token = request.hf_token,gguf_variant = request.gguf_variant,+ owner_session = _caller_is_owner,# A native grant covers one directory, and this is the first# pass that touches a drafter candidate, so the boundary has# to travel with it rather than being applied afterwards.@@ -17108,16 +17160,20 @@ async def _load_model_impl(# Mark the load and refuse one the download manager already owns BEFORE the eviction below: this 409 leaves nothing# loaded. It runs after argument inheritance, since a carried --no-mmproj changes the companion requirement.- if config.is_gguf and config.gguf_hf_repo:+ # A refused repo's downloaded copy loads as a file, from that repo's cache all the same.+ interlock_repo = config.is_gguf and (+ config.gguf_hf_repo or getattr(config, "gguf_cache_repo", None)+ )+ if interlock_repo:from core.inference.llama_cpp import gguf_load_in_flight- gguf_load_stack.enter_context(gguf_load_in_flight(config.gguf_hf_repo))+ gguf_load_stack.enter_context(gguf_load_in_flight(interlock_repo))from core.inference.llama_cpp import _hub_download_blocks_gguf_loadif await asyncio.to_thread(_hub_download_blocks_gguf_load,- config.gguf_hf_repo,+ interlock_repo,config.gguf_variant,# Same predicate as the marker's own check, and as the loader's# download gate: the projector is fetched whenever the repo ships one@@ -17999,12 +18055,15 @@ async def validate_model(# /load; otherwise the stall just moves here and /load is never reached.# Off-loop twice over: the guard is a network round trip, and the first# from_identifier builds the detection registry (transformers, or the warm's lock).+ _caller_is_owner = _owner_session(fastapi_request)+def _resolve_config():with _hf_offline_if_unreachable_for(model_identifier):return ModelConfig.from_identifier(model_id = model_identifier,hf_token = request.hf_token,gguf_variant = request.gguf_variant,+ owner_session = _caller_is_owner,# A native grant covers one directory, and this is the first# pass that touches a drafter candidate, so the boundary has# to travel with it rather than being applied afterwards.@@ -18320,10 +18379,8 @@ async def validate_model(return restore_inventory_handles(ValidateModelResponse(valid = True,- message = (- f"Model identifier is valid. {HUB_TOKEN_REJECTED_WARNING}"- if token_rejections.recovered- else "Model identifier is valid."+ message = " ".join(+ ["Model identifier is valid."] + _hub_access_warnings(token_rejections)),identifier = model_log_label if native_grant_backed else config.identifier,resident = await asyncio.to_thread(@@ -20129,7 +20186,7 @@ async def get_status(current_subject: str):llama_backend, _native_grant_backed, _model_id),gguf_variant = llama_backend.hf_variant,- memory_warning = llama_backend.last_load_warning,+ memory_warning = _status_load_warning(llama_backend),loading = _loading,# Plus anything the Unsloth registry still holds: the GGUF load# only unloaded the ACTIVE one, so a model cached behind it isdiff --git a/studio/backend/tests/test_gguf_hub_unreadable.py b/studio/backend/tests/test_gguf_hub_unreadable.pyindex 4574b888783..64c1098db71 100644--- a/studio/backend/tests/test_gguf_hub_unreadable.py+++ b/studio/backend/tests/test_gguf_hub_unreadable.py@@ -104,13 +104,28 @@ def test_hub_401_on_gguf_repo_raises_clear_error(monkeypatch):assert isinstance(exc_info.value, ValueError)-def test_hub_401_is_not_served_from_a_stale_cache(monkeypatch, _isolated):+ "hf_token",+ [None, False, "hf_" + "k" * 34],+ ids = ["no_token", "anonymous", "explicit_token"],+)+def test_hub_401_is_not_served_from_a_stale_cache(monkeypatch, _isolated, hf_token):+ # Not the owner's own session (an API key or another account): the cached copy stays+ # refused. The owner's session case lives in test_gguf_refused_cached_load.py._cache(_isolated, REPO, GGUF)monkeypatch.setattr(huggingface_hub, "model_info", _hub(RepositoryNotFoundError("401 Client Error")))+ monkeypatch.setattr(+ llama_cpp, "cached_gguf_for_load", lambda repo, variant, **kwargs: str(_isolated / GGUF)+ )+ monkeypatch.setattr(+ hf_tokens,+ "_explicit_token_reaches_repo",+ lambda repo, token, repo_type, offline = False: False,+ )with pytest.raises(GgufRepoUnreadableError):- ModelConfig.from_identifier(REPO)+ ModelConfig.from_identifier(REPO, hf_token = hf_token)def test_repeated_timeouts_on_uncached_gguf_repo_raise_clear_error(monkeypatch):diff --git a/studio/backend/tests/test_gguf_refused_cached_load.py b/studio/backend/tests/test_gguf_refused_cached_load.pynew file mode 100644index 00000000000..f6a1ea3759a--- /dev/null+++ b/studio/backend/tests/test_gguf_refused_cached_load.py@@ -0,0 +1,575 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""A GGUF the owner already downloaded still runs when the Hub refuses its repo.++A repo that was deleted, made private or gated after the download answers 401/403/404 to every+listing, and #12117 made that a clear error instead of a Transformers misroute. The machine+owner's own session may still run the complete copy on its disk, with a warning; anyone the+cache rules would refuse (anonymous, an API key without a token, another account, a token the+Hub says cannot reach the repo) is refused exactly as before.+"""++from pathlib import Path+from types import SimpleNamespace++import huggingface_hub+import pytest++import core.inference.llama_cpp as llama_cpp+import hub.utils.hf_tokens as hf_tokens+import utils.hf_cache_settings as hf_cache_settings+import utils.models.model_config as mc+from hub.utils.hf_tokens import (+ AmbientAuthorizedToken,+ collecting_hub_token_rejections,+ hub_refused_cached_copy_warning,+)+from utils.models.model_config import GgufRepoUnreadableError, ModelConfig++REPO = "unsloth/Qwen3-0.6B-GGUF"+VARIANT = "UD-Q4_K_XL"+GGUF = f"Qwen3-0.6B-{VARIANT}.gguf"+REV = "a" * 40+++class RepositoryNotFoundError(Exception):+ """Matched by type name, as detect_gguf_model_remote does."""++ def __init__(+ self,+ message,+ status_code = 401,+ ):+ super().__init__(message)+ self.response = SimpleNamespace(status_code = status_code, headers = {})+++class GatedRepoError(RepositoryNotFoundError):+ pass++[email protected](autouse = True)+def _isolated(tmp_path, monkeypatch):+ monkeypatch.delenv("HF_HUB_OFFLINE", raising = False)+ monkeypatch.delenv("TRANSFORMERS_OFFLINE", raising = False)+ monkeypatch.setattr(+ hf_cache_settings, "get_hf_cache_paths", lambda: SimpleNamespace(hub_cache = tmp_path)+ )+ monkeypatch.setattr(mc.time, "sleep", lambda *_: None)+ monkeypatch.setattr(hf_tokens, "_ambient_hf_token", lambda: (True, None))+ monkeypatch.setattr(+ llama_cpp.LlamaCppBackend,+ "_find_llama_server_binary",+ staticmethod(lambda *, include_denied = False: "/fake/llama-server"),+ )+ monkeypatch.setattr(mc, "is_vision_model", lambda *a, **k: False)+ monkeypatch.setattr(mc, "detect_audio_type", lambda *a, **k: None)+ monkeypatch.setattr(mc, "is_model_cached", lambda *a, **k: False)+ # Only this test's cache: no copies remembered from caches the host used before.+ import hub.utils.gguf_sources as gguf_sources++ monkeypatch.setattr(gguf_sources, "gguf_cache_snapshots", lambda repo: [])+ from collections import OrderedDict++ from hub.services.models import gguf_variants++ monkeypatch.setattr(gguf_variants, "_VARIANT_REQUIREMENT_LAST_KNOWN", OrderedDict())+ monkeypatch.setattr(gguf_variants, "_VARIANT_REQUIREMENT_FORGOTTEN", False)+ return tmp_path+++def _snapshot(root: Path) -> Path:+ snapshot = root / f"models--{REPO.replace('/', '--')}" / "snapshots" / REV+ snapshot.mkdir(parents = True, exist_ok = True)+ refs = snapshot.parent.parent / "refs"+ refs.mkdir(exist_ok = True)+ (refs / "main").write_text(REV)+ return snapshot+++def _download(root: Path, *names: str) -> Path:+ snapshot = _snapshot(root)+ for name in names:+ path = snapshot / name+ path.parent.mkdir(parents = True, exist_ok = True)+ path.write_bytes(b"GGUF" + b"\0" * 64)+ return snapshot+++def _hub(behaviour):+ def model_info(repo_id, **kwargs):+ if isinstance(behaviour, BaseException):+ raise behaviour+ return SimpleNamespace(siblings = [SimpleNamespace(rfilename = f) for f in behaviour])++ return model_info+++def _refuse(monkeypatch, error = None):+ monkeypatch.setattr(+ huggingface_hub,+ "model_info",+ _hub(error if error is not None else RepositoryNotFoundError("401 Client Error")),+ )+++def _load(**kwargs):+ with collecting_hub_token_rejections() as rejections:+ config = ModelConfig.from_identifier(REPO, **kwargs)+ return config, rejections+++ "error",+ [+ RepositoryNotFoundError("401 Client Error"),+ RepositoryNotFoundError("404 Client Error", status_code = 404),+ GatedRepoError("403 Client Error", status_code = 403),+ ],+ ids = ["401", "404", "gated"],+)[email protected]("variant", [VARIANT, None], ids = ["variant", "auto"])+def test_owner_runs_the_downloaded_copy_when_the_hub_refuses(+ monkeypatch, _isolated, error, variant+):+ snapshot = _download(_isolated, GGUF)+ _refuse(monkeypatch, error)+ config, rejections = _load(gguf_variant = variant, owner_session = True)+ assert config.is_gguf+ assert config.gguf_hf_repo is None, "must not go back to the Hub for the weights"+ assert Path(config.gguf_file) == snapshot / GGUF+ assert config.identifier == REPO+ assert config.gguf_variant == VARIANT+ assert rejections.served_from_cache == [REPO]+++ "token",+ [None, AmbientAuthorizedToken("hf_" + "u" * 34)],+ ids = ["ambient", "ui_saved_token"],+)+def test_the_owner_session_is_authorized_with_or_without_a_saved_token(+ monkeypatch, _isolated, token+):+ _download(_isolated, GGUF)+ _refuse(monkeypatch)+ config, _ = _load(hf_token = token, gguf_variant = VARIANT, owner_session = True)+ assert config.is_gguf and config.gguf_file+++def test_the_warning_names_the_repo():+ warning = hub_refused_cached_copy_warning(REPO)+ assert REPO in warning and "downloaded" in warning and "updates" in warning+++def test_a_split_copy_missing_a_shard_is_refused(monkeypatch, _isolated):+ _download(_isolated, f"{VARIANT}/Qwen3-0.6B-{VARIANT}-00001-of-00002.gguf")+ _refuse(monkeypatch)+ with pytest.raises(GgufRepoUnreadableError):+ _load(gguf_variant = VARIANT, owner_session = True)+++def test_a_copy_its_manifest_calls_incomplete_is_refused(monkeypatch, _isolated):+ # The download recorded a projector the variant needs, and it never arrived.+ _download(_isolated, GGUF)+ import hub.utils.gguf_sources as gguf_sources++ monkeypatch.setattr(+ gguf_sources, "cached_gguf_manifest_complete", lambda repo, quant, snapshot: False+ )+ _refuse(monkeypatch)+ with pytest.raises(GgufRepoUnreadableError):+ _load(gguf_variant = VARIANT, owner_session = True)+++def test_only_a_projector_on_disk_is_refused(monkeypatch, _isolated):+ _download(_isolated, "mmproj-F16.gguf")+ _refuse(monkeypatch)+ with pytest.raises(GgufRepoUnreadableError):+ _load(owner_session = True)+++ "token",+ [False, None, "hf_" + "k" * 34],+ ids = ["anonymous", "api_key_without_token", "api_key_with_token"],+)+def test_callers_the_cache_rules_refuse_stay_refused(monkeypatch, _isolated, token):+ # owner_session=False: an sk-unsloth API key or a managed account. No token there is+ # anonymous, not the installation's; an explicit token must reach the repo, which the+ # Hub just refused.+ _download(_isolated, GGUF)+ _refuse(monkeypatch)+ monkeypatch.setattr(+ hf_tokens,+ "_explicit_token_reaches_repo",+ lambda repo, token, repo_type, offline = False: False,+ )+ with pytest.raises(GgufRepoUnreadableError):+ _load(hf_token = token, gguf_variant = VARIANT)+++ "verdict", [True, None], ids = ["cached_auth_check_yes", "probe_cannot_answer"]+)+def test_a_token_the_hub_just_refused_is_not_outranked_by_the_cache_rule(+ monkeypatch, _isolated, verdict+):+ # The listing refused this very token. A /auth-check "yes" still in its cache, or a probe+ # that times out on a host whose only credential downloaded the repo, must not let an API+ # key or another account read the downloaded copy.+ _download(_isolated, GGUF)+ _refuse(monkeypatch, GatedRepoError("403 Client Error", status_code = 403))+ monkeypatch.setattr(+ hf_tokens,+ "_explicit_token_reaches_repo",+ lambda repo, token, repo_type, offline = False: verdict,+ )+ # This token downloaded the copy, so an unanswerable probe would otherwise be settled by it.+ monkeypatch.setattr(hf_tokens, "_caller_populated_the_cache", lambda *a, **k: True)+ monkeypatch.setattr(hf_tokens, "_repo_present_on_disk", lambda *a, **k: True)+ for _ in range(2):+ with pytest.raises(GgufRepoUnreadableError):+ _load(hf_token = "hf_" + "k" * 34, gguf_variant = VARIANT, owner_session = False)+++def test_a_revoked_grant_is_refused_even_for_a_managed_accounts_token(monkeypatch, _isolated):+ # A managed account's own token whose access the Hub has withdrawn: the cache is another+ # person's download, and /auth-check says this token no longer reaches the repo.+ _download(_isolated, GGUF)+ _refuse(monkeypatch)+ monkeypatch.setattr(+ hf_tokens,+ "_explicit_token_reaches_repo",+ lambda repo, token, repo_type, offline = False: False,+ )+ with pytest.raises(GgufRepoUnreadableError):+ _load(hf_token = "hf_" + "m" * 34, gguf_variant = VARIANT, owner_session = False)+++def test_timeouts_keep_todays_cache_route(monkeypatch, _isolated):+ _download(_isolated, GGUF)+ monkeypatch.setattr(huggingface_hub, "model_info", _hub(TimeoutError("read timed out")))+ monkeypatch.setattr(+ mc,+ "list_gguf_variants",+ lambda identifier, hf_token = None: (+ [mc.GgufVariantInfo(filename = GGUF, quant = VARIANT, size_bytes = 1)],+ False,+ ),+ )+ config, rejections = _load(gguf_variant = VARIANT, owner_session = True)+ assert config.is_gguf and config.gguf_hf_repo == REPO+ assert rejections.served_from_cache == []+++def test_a_healthy_hub_is_unchanged(monkeypatch, _isolated):+ _download(_isolated, GGUF)+ monkeypatch.setattr(huggingface_hub, "model_info", _hub([GGUF, "README.md"]))+ monkeypatch.setattr(+ mc,+ "list_gguf_variants",+ lambda identifier, hf_token = None: (+ [mc.GgufVariantInfo(filename = GGUF, quant = VARIANT, size_bytes = 1)],+ False,+ ),+ )+ config, rejections = _load(gguf_variant = VARIANT, owner_session = True)+ assert config.is_gguf and config.gguf_hf_repo == REPO+ assert rejections.served_from_cache == []+++def test_an_uncached_refused_repo_still_raises_the_clear_error(monkeypatch, _isolated):+ _refuse(monkeypatch)+ with pytest.raises(GgufRepoUnreadableError, match = "HTTP 401"):+ _load(gguf_variant = VARIANT, owner_session = True)+++def test_the_load_response_carries_the_cached_copy_warning():+ from models.inference import LoadResponse+ from routes.inference import _with_token_rejected_warning++ response = LoadResponse(status = "loaded", model = REPO, display_name = REPO, inference = {})+ with collecting_hub_token_rejections() as rejections:+ assert _with_token_rejected_warning(response, rejections) is response+ rejections.served_from_cache += [REPO, REPO]+ warned = _with_token_rejected_warning(response, rejections)+ assert warned.memory_warning == hub_refused_cached_copy_warning(REPO)+++ "managed,api_key,expected",+ [(False, False, True), (False, True, False), (True, False, False)],+ ids = ["owner_ui", "api_key", "managed_account"],+)+def test_only_the_owners_own_session_counts_as_the_owner(monkeypatch, managed, api_key, expected):+ import routes.inference as inference++ monkeypatch.setattr(inference.account_access, "managed_account", lambda: managed)+ monkeypatch.setattr(inference, "_request_has_api_key", lambda request: api_key)+ assert inference._owner_session(object()) is expected+ assert inference._owner_session(None) is False+++def test_an_internal_workflow_key_is_not_the_owner(monkeypatch):+ # A data-recipe subprocess holds an internal sk-unsloth key: never the owner's session.+ import routes.inference as inference++ monkeypatch.setattr(inference.account_access, "managed_account", lambda: False)+ monkeypatch.setattr(inference, "_request_api_key_token", lambda request: "sk-unsloth-internal")+ monkeypatch.setattr(inference.auth_storage, "is_internal_api_key", lambda token: True)+ assert inference._request_used_api_key(object()) is False+ assert inference._owner_session(object()) is False+++def test_a_cancelled_download_is_not_run_when_the_hub_refuses(monkeypatch, _isolated):+ # Its main file is on disk, but the download was cancelled: not a complete copy.+ _download(_isolated, GGUF)+ import hub.utils.gguf_sources as gguf_sources++ monkeypatch.setattr(+ gguf_sources, "cached_gguf_source_partial", lambda repo, quant, snapshot: True+ )+ _refuse(monkeypatch)+ with pytest.raises(GgufRepoUnreadableError):+ _load(gguf_variant = VARIANT, owner_session = True)+++def test_auto_selection_falls_back_to_the_next_complete_variant(monkeypatch, _isolated):+ # The preferred UD-Q4_K_XL was interrupted after its first shard; Q8_0 is complete.+ snapshot = _download(+ _isolated,+ f"{VARIANT}/Qwen3-0.6B-{VARIANT}-00001-of-00002.gguf",+ "Qwen3-0.6B-Q8_0.gguf",+ )+ _refuse(monkeypatch)+ config, rejections = _load(owner_session = True)+ assert Path(config.gguf_file) == snapshot / "Qwen3-0.6B-Q8_0.gguf"+ assert config.gguf_variant == "Q8_0"+ assert rejections.served_from_cache == [REPO]+++def test_the_refusal_fallback_passes_the_snapshot_root_as_the_companion_root(+ monkeypatch, _isolated+):+ # A main file in a non-quant subdirectory still finds a repo-root projector or drafter.+ monkeypatch.setattr(+ hf_cache_settings,+ "get_hf_cache_paths",+ lambda: SimpleNamespace(hub_cache = _isolated, source = "environment"),+ )+ snapshot = _download(_isolated, f"distilled/Qwen3-0.6B-{VARIANT}.gguf")+ _refuse(monkeypatch)+ seen = []+ real = ModelConfig.from_identifier.__func__++ def spy(cls, model_id, *args, **kwargs):+ if model_id != REPO:+ seen.append(kwargs.get("gguf_companion_roots"))+ return real(cls, model_id, *args, **kwargs)++ monkeypatch.setattr(ModelConfig, "from_identifier", classmethod(spy))+ config, _ = _load(owner_session = True)+ assert config.is_gguf+ assert seen == [(str(snapshot),)]+++def test_a_repo_not_named_gguf_still_runs_its_downloaded_gguf(monkeypatch, _isolated):+ # _looks_like_gguf_repo says no for this name, yet a healthy Hub would have found the GGUF.+ monkeypatch.setattr(mc, "_looks_like_gguf_repo", lambda *a, **k: False)+ snapshot = _download(_isolated, GGUF)+ _refuse(monkeypatch)+ config, rejections = _load(gguf_variant = VARIANT, owner_session = True)+ assert Path(config.gguf_file) == snapshot / GGUF+ assert rejections.served_from_cache == [REPO]+++def test_auto_selection_finds_a_complete_variant_in_an_older_snapshot(monkeypatch, _isolated):+ # The newest snapshot holds only an interrupted UD-Q4_K_XL; an older one a complete Q8_0.+ import os++ older = _download(_isolated, "Qwen3-0.6B-Q8_0.gguf")+ newer = older.parent / ("b" * 40)+ (newer / VARIANT).mkdir(parents = True)+ (newer / VARIANT / f"Qwen3-0.6B-{VARIANT}-00001-of-00002.gguf").write_bytes(+ b"GGUF" + b"\0" * 64+ )+ (older.parent.parent / "refs" / "main").write_text("b" * 40)+ os.utime(older, (1_000_000_000, 1_000_000_000))+ _refuse(monkeypatch)+ config, rejections = _load(owner_session = True)+ assert Path(config.gguf_file) == older / "Qwen3-0.6B-Q8_0.gguf"+ assert config.gguf_variant == "Q8_0"+ assert rejections.served_from_cache == [REPO]+++def test_the_downloaded_copy_keeps_its_repo_for_the_download_interlock(monkeypatch, _isolated):+ # Not gguf_hf_repo (that would fetch from the Hub), but /load's marker and 409 need the repo.+ _download(_isolated, GGUF)+ _refuse(monkeypatch)+ config, _ = _load(gguf_variant = VARIANT, owner_session = True)+ assert config.gguf_hf_repo is None+ assert config.gguf_cache_repo == REPO+++def test_a_missing_llama_server_fails_before_the_cached_copy_is_returned(monkeypatch, _isolated):+ # /load must not unload the resident model for a launch that cannot start.+ _download(_isolated, GGUF)+ _refuse(monkeypatch)+ monkeypatch.setattr(+ llama_cpp.LlamaCppBackend,+ "_find_llama_server_binary",+ staticmethod(lambda *, include_denied = False: None),+ )+ with pytest.raises(llama_cpp.LlamaServerNotFoundError):+ _load(gguf_variant = VARIANT, owner_session = True)++[email protected]("listed", ["root_first", "subdir_first"])+def test_auto_selection_prefers_the_root_checkpoint_whatever_the_listing_order(+ monkeypatch, _isolated, listed+):+ # As the healthy-Hub pick: the bare repo id is the root checkpoint, not distilled/.+ root, sub = "Qwen3-0.6B-Q6_K.gguf", "distilled/Qwen3-0.6B-Q6_K.gguf"+ snapshot = _download(_isolated, root, sub)+ order = [root, sub] if listed == "root_first" else [sub, root]+ monkeypatch.setattr(mc, "_hf_cache_main_gguf_files", lambda repo, **k: list(order))+ _refuse(monkeypatch)+ config, _ = _load(owner_session = True)+ assert Path(config.gguf_file) == snapshot / root+++def test_auto_selection_finds_a_copy_in_a_remembered_cache(+ monkeypatch, _isolated, tmp_path_factory+):+ # The active cache was switched to an empty one; the explicit-variant lookup still finds the+ # remembered copy, so automatic selection must too.+ import hub.utils.gguf_sources as gguf_sources++ remembered = _download(tmp_path_factory.mktemp("previous_cache"), GGUF)+ monkeypatch.setattr(+ gguf_sources,+ "gguf_cache_snapshots",+ lambda repo: [remembered] if repo == REPO else [],+ )+ _refuse(monkeypatch)+ config, _ = _load(owner_session = True)+ assert Path(config.gguf_file) == remembered / GGUF+ assert config.gguf_variant == VARIANT+++def test_the_downloaded_copy_is_reported_as_a_hub_model(monkeypatch, _isolated):+ # Not the user's own file: /load reports is_local_model from this, and the chat settings+ # then give Hub recovery guidance rather than "put the drafter beside your file".+ _download(_isolated, GGUF)+ _refuse(monkeypatch)+ config, _ = _load(gguf_variant = VARIANT, owner_session = True)+ assert config.is_local is False++[email protected]("projector_on_disk", [False, True])+def test_a_companion_an_earlier_listing_named_must_be_on_disk(+ monkeypatch, _isolated, projector_on_disk+):+ # No manifest, so the shards alone look complete; the live listing said it needs a projector.+ from hub.services.models import gguf_variants+ from hub.utils import download_manifest++ snapshot = _download(_isolated, GGUF)+ if projector_on_disk:+ (snapshot / "mmproj-F16.gguf").write_bytes(b"GGUF" + b"\0" * 60)+ requirement = SimpleNamespace(+ expected_files = (+ download_manifest.ExpectedFile(GGUF, (snapshot / GGUF).stat().st_size),+ download_manifest.ExpectedFile("mmproj-F16.gguf", 64),+ )+ )+ gguf_variants._variant_requirement_cache_set_many(REPO, None, {VARIANT: requirement})+ _refuse(monkeypatch)+ for variant in (VARIANT, None):+ if projector_on_disk:+ config, _ = _load(gguf_variant = variant, owner_session = True)+ assert Path(config.gguf_file) == snapshot / GGUF+ else:+ with pytest.raises(GgufRepoUnreadableError):+ _load(gguf_variant = variant, owner_session = True)+++def test_only_the_load_that_shows_the_warning_may_use_the_cached_copy(monkeypatch):+ # Auto-switch, idle restore and preview call the impl directly and drop its response, so+ # the warning would never be seen; only the /load wrapper turns the fallback on.+ import asyncio++ import routes.inference as inference++ seen = []++ async def impl(*args, **kwargs):+ seen.append(inference._load_warnings_reach_user.get())+ return None++ monkeypatch.setattr(inference, "_load_model_impl", impl)+ from models.inference import LoadRequest++ request = LoadRequest(model_path = REPO)+ asyncio.run(inference._run_tracked_load_model_impl(request, object(), "subject"))+ assert seen == [True]+ assert inference._load_warnings_reach_user.get() is False++[email protected]("status", [403, 404])+def test_a_refusal_known_only_by_its_status_takes_the_refused_repo_policy(+ monkeypatch, _isolated, status+):+ # DisabledRepoError or a bare HTTP 403: not retried into the ordinary cache route, where an+ # API key would get the copy with no warning.+ class DisabledRepoError(Exception):+ def __init__(self):+ super().__init__(f"{status} Client Error")+ self.response = SimpleNamespace(status_code = status, headers = {})++ _download(_isolated, GGUF)+ _refuse(monkeypatch, DisabledRepoError())+ config, rejections = _load(gguf_variant = VARIANT, owner_session = True)+ assert rejections.served_from_cache == [REPO]+ with pytest.raises(GgufRepoUnreadableError):+ _load(hf_token = "hf_" + "k" * 34, gguf_variant = VARIANT, owner_session = False)+++def test_status_keeps_the_cached_copy_warning_the_load_carried(monkeypatch):+ # The client re-applies /status after a load and shows its memory_warning, so a warning only+ # on the load response is dismissed as soon as it appears.+ import routes.inference as inference_routes+ from models.inference import LoadResponse++ backend = SimpleNamespace(last_load_warning = "Runs partly from disk.", hub_access_warning = None)+ monkeypatch.setattr(inference_routes, "get_llama_cpp_backend", lambda: backend)+ response = LoadResponse(+ status = "loaded",+ model = REPO,+ display_name = REPO,+ inference = {},+ is_gguf = True,+ memory_warning = backend.last_load_warning,+ )+ with collecting_hub_token_rejections() as rejections:+ rejections.served_from_cache.append(REPO)+ warned = inference_routes._with_token_rejected_warning(response, rejections)+ inference_routes._remember_hub_access_warning(warned, rejections)+ assert inference_routes._status_load_warning(backend) == warned.memory_warning+ assert hub_refused_cached_copy_warning(REPO) in warned.memory_warning++ # The next GGUF load that the Hub answers drops it.+ with collecting_hub_token_rejections() as rejections:+ inference_routes._remember_hub_access_warning(response, rejections)+ assert inference_routes._status_load_warning(backend) == "Runs partly from disk."+++def test_a_new_load_forgets_the_previous_hub_warning():+ backend = llama_cpp.LlamaCppBackend.__new__(llama_cpp.LlamaCppBackend)+ backend._last_load_warning = None+ backend._variant_fallback_warning = None+ backend.hub_access_warning = "Hugging Face refused it."+ backend._begin_load_warnings()+ assert backend.hub_access_warning is Nonediff --git a/studio/backend/tests/test_gguf_variants_local_dependencies.py b/studio/backend/tests/test_gguf_variants_local_dependencies.pynew file mode 100644index 00000000000..9e23579775e--- /dev/null+++ b/studio/backend/tests/test_gguf_variants_local_dependencies.py@@ -0,0 +1,267 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""A downloaded GGUF must stay a one-click On Device row when the Hub cannot be read.++The picker collapses a repo holding one complete quant only when the variants answer says its+dependencies are resolved. Only a live Hub listing used to say so, so with the Hub offline,+unreachable or refusing the saved token, every downloaded sole-quant repo fell back to the+expander. A Hub-less answer now proves it from disk: the quant's shards, its snapshot's own+partial state, the download's recorded plan and any companion a Hub answer named earlier.+With the Hub up a local-first answer still never claims it, since a companion the current+revision added is only visible in the listing (#10243).+"""++from __future__ import annotations++import asyncio+from types import SimpleNamespace++from collections import OrderedDict++import pytest++from hub.services.models import gguf_variants+from hub.utils import download_manifest, inventory_scan+from utils import hf_cache_settings++REPO = "org/Sole-GGUF"+REV = "0123456789abcdef0123456789abcdef01234567"+QUANT = "Q4_K_M"+MAIN = f"Sole-{QUANT}.gguf"+++def _snapshot():+ hub_cache = hf_cache_settings.get_hf_cache_paths().hub_cache+ repo = hub_cache / "models--org--Sole-GGUF"+ snapshot = repo / "snapshots" / REV+ snapshot.mkdir(parents = True, exist_ok = True)+ (repo / "refs").mkdir(exist_ok = True)+ (repo / "refs" / "main").write_text(REV)+ return repo, snapshot+++def _write(path, size: int = 256):+ path.parent.mkdir(parents = True, exist_ok = True)+ path.write_bytes(b"GGUF" + b"\0" * (size - 4))+ return path+++def _record_plan(repo, files):+ assert download_manifest.write_manifest(+ "model",+ REPO,+ QUANT,+ [download_manifest.ExpectedFile(name, size) for name, size in files],+ hub_cache = repo.parent,+ )+++def hub_calls(monkeypatch, tmp_path):+ # A cache of this test's own: the suite-wide empty cache is shared across tests.+ hub_cache = str(tmp_path / "hub")+ monkeypatch.setitem(hf_cache_settings._EXPLICIT_CACHE_ENV, "HF_HUB_CACHE", hub_cache)+ monkeypatch.setenv("HF_HUB_CACHE", hub_cache)+ monkeypatch.setattr("huggingface_hub.constants.HF_HUB_CACHE", hub_cache)+ calls = []++ def refused(*args, **kwargs):+ calls.append(args)+ raise ConnectionError("hub unreachable")++ monkeypatch.setattr(gguf_variants, "list_gguf_variants", refused)+ monkeypatch.setattr(gguf_variants, "_gguf_all_variant_requirements", refused)+ monkeypatch.setattr("huggingface_hub.model_info", refused)+ monkeypatch.setattr("huggingface_hub.list_repo_files", refused)+ inventory_scan.invalidate_hf_cache_scans()+ monkeypatch.setattr(+ gguf_variants, "_VARIANT_REQUIREMENT_LAST_KNOWN", OrderedDict(), raising = False+ )+ monkeypatch.setattr(gguf_variants, "_VARIANT_REQUIREMENT_FORGOTTEN", False, raising = False)+ return calls+++def _answer(**kwargs):+ inventory_scan.invalidate_hf_cache_scans()+ return asyncio.run(gguf_variants.get_gguf_variants_response(REPO, **kwargs))+++# What the picker sends when it believes the Hub is offline, and a Hub that fails a request.+HUBLESS = [+ pytest.param({"prefer_local_cache": True, "offline": True}, id = "offline"),+ pytest.param({}, id = "hub_failed"),+]++[email protected]("request_kwargs", HUBLESS)+def test_a_complete_download_is_resolved_without_the_hub(hub_calls, request_kwargs):+ repo, snapshot = _snapshot()+ _write(snapshot / MAIN)+ _record_plan(repo, [(MAIN, 256)])++ response = _answer(**request_kwargs)++ assert [v.quant for v in response.variants] == [QUANT]+ assert response.variants[0].downloaded is True+ assert response.dependencies_resolved is True+ if request_kwargs.get("offline"):+ assert hub_calls == [], "an offline answer must not reach the Hub"++[email protected]("request_kwargs", HUBLESS)+def test_a_download_from_before_manifests_is_judged_on_its_shards(hub_calls, request_kwargs):+ _repo, snapshot = _snapshot()+ _write(snapshot / MAIN)++ assert _answer(**request_kwargs).dependencies_resolved is True+++def test_a_local_first_answer_with_the_hub_up_still_defers_to_the_listing(hub_calls):+ """#10243: a companion the current revision added only shows in the Hub listing."""+ repo, snapshot = _snapshot()+ _write(snapshot / MAIN)+ _record_plan(repo, [(MAIN, 256)])++ response = _answer(prefer_local_cache = True)++ assert response.variants[0].downloaded is True+ assert response.dependencies_resolved is False++[email protected]("request_kwargs", HUBLESS)+ "companion",+ ["mmproj-F16.gguf", f"mtp-Sole-{QUANT}.gguf"],+ ids = ["mmproj", "mtp_drafter"],+)+def test_a_planned_companion_that_is_missing_leaves_it_unresolved(+ hub_calls, request_kwargs, companion+):+ repo, snapshot = _snapshot()+ _write(snapshot / MAIN)+ _record_plan(repo, [(MAIN, 256), (companion, 128)])++ assert _answer(**request_kwargs).dependencies_resolved is False++[email protected]("request_kwargs", HUBLESS)+def test_a_truncated_planned_file_leaves_it_unresolved(hub_calls, request_kwargs):+ repo, snapshot = _snapshot()+ _write(snapshot / MAIN, 200)+ _record_plan(repo, [(MAIN, 256)])++ assert _answer(**request_kwargs).dependencies_resolved is False++[email protected]("request_kwargs", HUBLESS)+def test_a_split_quant_short_a_shard_leaves_it_unresolved(hub_calls, request_kwargs):+ _repo, snapshot = _snapshot()+ _write(snapshot / QUANT / f"Sole-{QUANT}-00001-of-00002.gguf")++ response = _answer(**request_kwargs)++ assert all(not v.downloaded for v in response.variants)+ assert response.dependencies_resolved is False++[email protected]("request_kwargs", HUBLESS)+def test_a_cancelled_download_leaves_it_unresolved(hub_calls, request_kwargs):+ repo, snapshot = _snapshot()+ _write(snapshot / MAIN)+ _record_plan(repo, [(MAIN, 256)])+ download_manifest.write_cancel_marker("model", REPO, QUANT, hub_cache = repo.parent)++ assert _answer(**request_kwargs).dependencies_resolved is False++[email protected]("request_kwargs", HUBLESS)[email protected]("drafter_on_disk", [False, True], ids = ["missing", "present"])+def test_a_companion_the_hub_named_earlier_must_be_on_disk(+ hub_calls, monkeypatch, request_kwargs, drafter_on_disk+):+ _repo, snapshot = _snapshot()+ _write(snapshot / MAIN)+ drafter = f"mtp-Sole-{QUANT}.gguf"+ if drafter_on_disk:+ _write(snapshot / drafter, 128)+ requirement = SimpleNamespace(+ expected_files = (+ download_manifest.ExpectedFile(MAIN, 256),+ download_manifest.ExpectedFile(drafter, 128),+ )+ )+ monkeypatch.setattr(gguf_variants, "_variant_requirement_last_known", lambda key: requirement)++ assert _answer(**request_kwargs).dependencies_resolved is drafter_on_disk++[email protected]("request_kwargs", HUBLESS)+def test_a_requirement_past_its_refresh_ttl_still_counts_without_the_hub(hub_calls, request_kwargs):+ _repo, snapshot = _snapshot()+ _write(snapshot / MAIN)+ drafter = f"mtp-Sole-{QUANT}.gguf"+ requirement = SimpleNamespace(+ expected_files = (+ download_manifest.ExpectedFile(MAIN, 256),+ download_manifest.ExpectedFile(drafter, 128),+ )+ )+ gguf_variants._variant_requirement_cache_set_many("org/Sole-GGUF", None, {QUANT: requirement})+ # The live listing's entry expires; what it said the variant needs does not.+ gguf_variants._VARIANT_REQUIREMENT_CACHE.clear()+ assert _answer(**request_kwargs).dependencies_resolved is False+++def test_a_live_listing_still_resolves_dependencies(hub_calls, monkeypatch):+ _repo, snapshot = _snapshot()+ _write(snapshot / MAIN)+ info = SimpleNamespace(filename = MAIN, quant = QUANT, display_label = None, size_bytes = 256)+ sibling = SimpleNamespace(rfilename = MAIN, size = 256, blob_id = "b", lfs = None)+ monkeypatch.setattr(+ gguf_variants, "list_gguf_variants", lambda *a, **k: ([info], False, [sibling])+ )+ monkeypatch.setattr(gguf_variants, "_gguf_all_variant_requirements", lambda *a, **k: {})++ assert _answer().dependencies_resolved is True++[email protected]("request_kwargs", HUBLESS)+def test_a_requirement_learned_under_another_token_still_counts(hub_calls, request_kwargs):+ # The listing that named the drafter ran with the old token; the owner has since replaced+ # or cleared it. The drafter is still missing, so the copy is still not resolved.+ _repo, snapshot = _snapshot()+ _write(snapshot / MAIN)+ requirement = SimpleNamespace(+ expected_files = (+ download_manifest.ExpectedFile(MAIN, 256),+ download_manifest.ExpectedFile(f"mtp-Sole-{QUANT}.gguf", 128),+ )+ )+ gguf_variants._variant_requirement_cache_set_many(REPO, "hf_" + "a" * 34, {QUANT: requirement})+ gguf_variants._VARIANT_REQUIREMENT_CACHE.clear()+ assert _answer(**request_kwargs).dependencies_resolved is False++[email protected]("request_kwargs", HUBLESS)+def test_an_evicted_requirement_is_not_read_as_nothing_required(+ hub_calls, monkeypatch, request_kwargs+):+ # A long session listed enough variants to push this one's requirement out. Its drafter may+ # still be missing, so the copy stays unresolved rather than being called complete.+ _repo, snapshot = _snapshot()+ _write(snapshot / MAIN)+ requirement = SimpleNamespace(+ expected_files = (+ download_manifest.ExpectedFile(MAIN, 256),+ download_manifest.ExpectedFile(f"mtp-Sole-{QUANT}.gguf", 128),+ )+ )+ for cap in ("_VARIANT_HASH_MAX", "_VARIANT_REQUIREMENT_LAST_KNOWN_MAX"):+ monkeypatch.setattr(gguf_variants, cap, 2, raising = False)+ gguf_variants._variant_requirement_cache_set_many(REPO, None, {QUANT: requirement})+ gguf_variants._variant_requirement_cache_set_many(+ "org/Other-GGUF", None, {"Q8_0": requirement, "Q6_K": requirement}+ )+ gguf_variants._VARIANT_REQUIREMENT_CACHE.clear()+ assert _answer(**request_kwargs).dependencies_resolved is Falsediff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.pyindex c993e64531f..23b4842aa2c 100644--- a/studio/backend/utils/models/model_config.py+++ b/studio/backend/utils/models/model_config.py@@ -3,7 +3,7 @@"""Model and LoRA configuration handling."""-from dataclasses import dataclass+from dataclasses import dataclass, replace as _dataclass_replacefrom typing import Optional, Dict, Anyfrom utils.paths.storage_roots import own_entry, within_accountfrom utils.paths import (@@ -30,6 +30,7 @@ from hub.utils.hf_tokens import (call_with_anonymous_retry,collecting_hub_token_rejections,HUB_TOKEN_REJECTED_ERROR,+ hf_token_arg,is_rejected_credential_error,is_anonymous,normalize_token,@@ -3300,7 +3301,21 @@ def _detect_gguf_from_hf_cache(repo_id: str) -> Optional[str]:Excludes mmproj (vision projector) files so a partial cache holding onlythe projector cannot route it as the main model."""- for snap in _iter_hf_cache_snapshots(repo_id):+ rel_files = _hf_cache_main_gguf_files(repo_id)+ return _pick_best_gguf(rel_files) if rel_files else None+++def _hf_cache_main_gguf_files(repo_id: str, *, every_snapshot: bool = False) -> list[str]:+ """Main GGUF paths of the first cached snapshot of *repo_id* that holds any, or with+ *every_snapshot* of all of them (newest first, each path once), remembered caches included+ as the strict load lookup includes them."""+ found: list[str] = []+ if every_snapshot:+ from core.inference.llama_cpp import _cached_gguf_snapshots+ snapshots = _cached_gguf_snapshots(repo_id)+ else:+ snapshots = _iter_hf_cache_snapshots(repo_id)+ for snap in snapshots:rel_files = []for f in _iter_gguf_files(snap, recursive = True):rel = f.relative_to(snap).as_posix()@@ -3313,9 +3328,10 @@ def _detect_gguf_from_hf_cache(repo_id: str) -> Optional[str]:):continuerel_files.append(rel)- if rel_files:- return _pick_best_gguf(rel_files)- return None+ if rel_files and not every_snapshot:+ return rel_files+ found += [rel for rel in rel_files if rel not in found]+ return foundclass GgufRepoUnreadableError(ValueError):@@ -3383,6 +3399,100 @@ def _gguf_repo_unreadable_message()+def _is_hub_refusal(error: Exception) -> bool:+ """The Hub answered no (401/403/404, gated), as opposed to not answering at all."""+ from hub.utils.hf_tokens import _is_probe_timeout++ if _is_probe_timeout(error):+ return False+ if type(error).__name__ in ("RepositoryNotFoundError", "GatedRepoError"):+ return True+ status = getattr(getattr(error, "response", None), "status_code", None)+ return status in (401, 403, 404)+++def _refused_repo_cache_token(hf_token: HfTokenArg, owner_session: bool) -> HfTokenArg:+ """The credential class ``cache_reads_authorized`` judges a refused repo's cache read by.++ The machine owner's UI session reads its own downloads (``AmbientAuthorizedToken`` or+ ambient); anyone else is judged as they would be for any cache read, with "no token"+ meaning anonymous rather than borrowing the installation's."""+ if is_anonymous(hf_token):+ return False+ token = hf_token.strip() if isinstance(hf_token, str) else ""+ return hf_token_arg(token, allow_ambient_token = owner_session)+++def _remembered_companions_present(repo_id: str, variant: str, local_file: str) -> bool:+ """Whether every file an earlier live listing said *variant* needs is beside *local_file*.+ A manifest-less download is otherwise judged by its shards alone."""+ from core.inference.llama_cpp import _snapshot_dir_of+ from hub.services.models import gguf_variants++ requirement = gguf_variants._variant_requirement_last_known((repo_id.lower(), variant.lower()))+ if requirement is None:+ return not gguf_variants._variant_requirement_may_be_forgotten()+ snapshot = _snapshot_dir_of(local_file)+ if snapshot is None:+ return False+ try:+ for expected in requirement.expected_files:+ target = Path(snapshot) / expected.path+ if not target.is_file() or (expected.size and target.stat().st_size != expected.size):+ return False+ except OSError:+ return False+ return True+++def _refused_repo_cached_gguf(+ repo_id: str, gguf_variant: Optional[str], hf_token: HfTokenArg, *, owner_session: bool+) -> Optional[tuple[str, str]]:+ """``(main file, variant)`` of a complete downloaded copy this caller may run while the Hub+ refuses the repo, or None.++ Complete means every shard present and, when the download recorded a manifest, every file+ it names (a projector or drafter the variant needs included). Only the owner's session,+ which may read its own downloads: anyone else sent the token the Hub just refused for this+ repo, and neither an earlier ``/auth-check`` verdict nor a probe that cannot answer outranks+ that refusal."""+ if not owner_session:+ return None+ if not cache_reads_authorized(+ _refused_repo_cache_token(hf_token, owner_session), repo_id = repo_id+ ):+ return None+ from core.inference.llama_cpp import cached_gguf_for_load++ if gguf_variant:+ local_file = cached_gguf_for_load(repo_id, gguf_variant, strict = True)+ if local_file and _remembered_companions_present(repo_id, gguf_variant, local_file):+ return local_file, gguf_variant+ return None+ # Auto: preferred variant first, falling through incomplete ones, across every snapshot.+ remaining = sorted(_hf_cache_main_gguf_files(repo_id, every_snapshot = True))+ while remaining:+ # Repo-root checkpoint first, as the healthy-Hub pick does.+ root_rows = [+ f for f in remaining if "/" not in _qualified_variant_name(f, _extract_quant_label(f))+ ]+ best = _pick_best_gguf(root_rows or remaining)+ if not best:+ return None+ label = _extract_quant_label(best)+ variant = _qualified_variant_name(best, label) if label else None+ local_file = cached_gguf_for_load(repo_id, variant, strict = True) if variant else None+ if local_file and _remembered_companions_present(repo_id, variant, local_file):+ return local_file, variant+ remaining = [+ f+ for f in remaining+ if f != best+ and not (label and _qualified_variant_name(f, _extract_quant_label(f)) == variant)+ ]+ return None++def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Optional[str]:"""Return the best GGUF filename in a HF repo, or None.@@ -3417,12 +3527,13 @@ def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Oplast_err = e# 404 / RepoNotFound is permanent -- don't retryerr_name = type(e).__name__+ # Status-only refusals too (DisabledRepoError, bare 403), or the refused-repo policy is skipped.if err_name in ("RepositoryNotFoundError","GatedRepoError","RevisionNotFoundError","EntryNotFoundError",- ):+ ) or _is_hub_refusal(e):logger.debug(f"Could not check GGUF files for '{repo_id}': {e}")_note_gguf_remote_detect_failure(e)return None@@ -4078,6 +4189,8 @@ class ModelConfig:gguf_hf_repo: Optional[str] = (None # HF repo ID for -hf mode (e.g. "unsloth/gemma-3-4b-it-GGUF"))+ # Repo a refused-Hub cached GGUF came from, for the download interlock.+ gguf_cache_repo: Optional[str] = Nonegguf_variant: Optional[str] = None # Quantization variant (e.g. "Q4_K_M")base_model: Optional[str] = None # Base model (for LoRAs)@@ -4140,6 +4253,7 @@ class ModelConfig:drafter_accept: Optional[Callable[[str, str, str, str], bool]] = None,gguf_companion_roots: Optional[Tuple[str, ...]] = None,mmproj_accept: Optional[Callable[[str, str], bool]] = None,+ owner_session: bool = False,) -> Optional["ModelConfig"]:"""Create ModelConfig from a clean model identifier (HF repo or localpath), for FastAPI routes that send sanitized paths.@@ -4165,6 +4279,8 @@ class ModelConfig:compatible mmproj without changing the selected main weights.mmproj_accept: ``(candidate, gguf_file) -> bool`` admission ruleapplied before reading projector metadata for native loads.+ owner_session: the caller is the machine owner's own UI session, which may+ run a GGUF it already downloaded when the Hub refuses the repo.Returns:ModelConfig or None if it cannot be created.@@ -4328,7 +4444,50 @@ class ModelConfig:gguf_filename = detect_gguf_model_remote(identifier, hf_token = hf_token)finally:_gguf_remote_detect_failure.reset(failure_token)- # A failed listing is not "no GGUF"; a refused repo is never served from cache (#11551).+ # A failed listing is not "no GGUF" (#11551): a refused repo's downloaded copy goes+ # only to a caller who may read that cache, with a warning.+ if not gguf_filename and detect_failures and _is_hub_refusal(detect_failures[-1]):+ cached = _refused_repo_cached_gguf(+ identifier, gguf_variant, hf_token, owner_session = owner_session+ )+ if cached is not None:+ local_file, cached_variant = cached+ logger.warning(+ "Hugging Face refused '%s' (%s); loading the downloaded copy.",+ identifier,+ type(detect_failures[-1]).__name__,+ )+ from core.inference.llama_cpp import _snapshot_dir_of++ # Snapshot root, so a repo-root mmproj or drafter is found.+ snapshot = _snapshot_dir_of(local_file)+ local_config = cls.from_identifier(+ model_id = local_file,+ hf_token = hf_token,+ gguf_variant = cached_variant,+ drafter_accept = drafter_accept,+ gguf_companion_roots = gguf_companion_roots+ or ((str(snapshot),) if snapshot is not None else None),+ mmproj_accept = mmproj_accept,+ )+ if local_config is not None and local_config.is_gguf:+ # Preflight, so /load never unloads the resident model for nothing.+ from core.inference.llama_cpp import (+ LLAMA_SERVER_NOT_FOUND_DETAIL,+ LlamaCppBackend,+ LlamaServerNotFoundError,+ )++ if not LlamaCppBackend._find_llama_server_binary(include_denied = True):+ raise LlamaServerNotFoundError(LLAMA_SERVER_NOT_FOUND_DETAIL)+ token_rejections.served_from_cache.append(identifier)+ return _dataclass_replace(+ local_config,+ identifier = identifier,+ display_name = f"{identifier.split('/')[-1]} ({cached_variant})",+ gguf_cache_repo = identifier,+ is_local = False,+ )if not gguf_filename and _looks_like_gguf_repo(identifier, gguf_variant):if detect_failures:raise GgufRepoUnreadableError(