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
fix(studio): discover On Device GGUFs from disk before Hub (#12460)
Lee Jacksone4e875bdb31a
diff --git a/studio/backend/hub/services/models/account_access.py b/studio/backend/hub/services/models/account_access.pyindex a537f55d1df..8e1f19ebe9c 100644--- a/studio/backend/hub/services/models/account_access.py+++ b/studio/backend/hub/services/models/account_access.py@@ -552,7 +552,12 @@ def _source_speaks_for_the_cache() -> bool:return active_source() != MODELSCOPE-def repo_is_public(repo_id: str, repo_type: str = "model") -> bool:+def repo_is_public(+ repo_id: str,+ repo_type: str = "model",+ *,+ offline: bool = False,+) -> bool:"""Only an anonymous Hub answer proves a shared-cache repo public."""if not _source_speaks_for_the_cache():return False@@ -562,6 +567,8 @@ def repo_is_public(repo_id: str, repo_type: str = "model") -> bool:cached = _public_repos.get(key)if cached is not None and cached[0] > time.monotonic():return cached[1]+ if offline:+ return name in _load_public_verdicts()flight = _public_flights.get(key)leading = flight is Noneif leading:@@ -730,13 +737,18 @@ def repo_visible(repo_type: str = "model",*,grants: set[str] | None = None,+ offline: bool = False,) -> bool:if not managed_account():return Trueif not repo_id:return Falsegranted = model_grants() if grants is None else grants- return _grant_key(repo_id, repo_type) in granted or repo_is_public(repo_id, repo_type)+ return _grant_key(repo_id, repo_type) in granted or (+ repo_is_public(repo_id, repo_type, offline = True)+ if offline+ else repo_is_public(repo_id, repo_type)+ )def _cached_repo(path: Path) -> tuple[str, str] | None:@@ -754,6 +766,7 @@ def model_visible(*,grants: set[str] | None = None,repo_type: str = "model",+ offline: bool = False,) -> bool:"""Grants cover repo ids and cache snapshot/file spellings; other local paths stay private."""if not managed_account():@@ -761,6 +774,7 @@ def model_visible(if not isinstance(reference, str) or not reference:return Falsereference = reference.strip()+ access_options = {"offline": True} if offline else {}path = Path(reference).expanduser()if path.is_absolute() or reference.startswith(("./", "../", "~")) or path.exists():try:@@ -776,7 +790,9 @@ def model_visible(if cached is not None:# Snapshots point at their own repo's blobs; cross-repo links are refused.actual = _cached_repo(resolved)- return actual == cached and repo_visible(cached[0], cached[1], grants = grants)+ return actual == cached and repo_visible(+ cached[0], cached[1], grants = grants, **access_options+ )except (OSError, RuntimeError, ValueError):return Falsereturn False@@ -785,11 +801,17 @@ def model_visible(if not all(parts[:2]):return Falserepo_id = "/".join(parts[:2])- return repo_visible(repo_id, repo_type, grants = grants)+ return repo_visible(repo_id, repo_type, grants = grants, **access_options)-def require_model_access(reference: str, repo_type: str = "model") -> None:- if not model_visible(reference, repo_type = repo_type):+def require_model_access(+ reference: str,+ repo_type: str = "model",+ *,+ offline: bool = False,+) -> None:+ access_options = {"offline": True} if offline else {}+ if not model_visible(reference, repo_type = repo_type, **access_options):raise HTTPException(status_code = 404, detail = "Model not found")diff --git a/studio/backend/hub/services/models/gguf_variants.py b/studio/backend/hub/services/models/gguf_variants.pyindex ad05a4cf3da..560670a5bb0 100644--- a/studio/backend/hub/services/models/gguf_variants.py+++ b/studio/backend/hub/services/models/gguf_variants.py@@ -28,6 +28,7 @@ from hub.utils.hf_errors import hf_error_status, modelscope_missingfrom hub.utils.hf_tokens import cached_read_refused as hub_cached_read_refusedfrom hub.utils.hf_tokens import call_with_anonymous_retryfrom hub.utils.hf_cache_state import (+ cached_repo_ref_for_path,incomplete_blob_hash,iter_destructive_repo_cache_dirs,repo_cache_dir_name,@@ -1143,9 +1144,12 @@ async def get_gguf_variants_answer(with file sizes, whether the model supports vision, and the recommendeddefault variant."""+ access_options = {"offline": True} if offline else {}if local_path:if account_access.managed_account():- await asyncio.to_thread(account_access.require_model_access, local_path)+ await asyncio.to_thread(+ account_access.require_model_access, local_path, **access_options+ )hf_token = account_access.account_hf_token(hf_token)if not local_path:audio_cpp_answer = await _audio_cpp_variants_answer(repo_id, hf_token, offline)@@ -1153,11 +1157,11 @@ async def get_gguf_variants_answer(return audio_cpp_answerif account_access.managed_account():try:- await asyncio.to_thread(account_access.require_model_access, repo_id)+ await asyncio.to_thread(account_access.require_model_access, repo_id, **access_options)except HTTPException:# No grant exists before the first download, so for a private repo the caller's own- # token proves Hub access instead. A cache-only request without a token needs the grant.- if not isinstance(hf_token, str) or not hf_token.strip():+ # token proves Hub access instead. Offline requests need an existing grant or public proof.+ if offline or not isinstance(hf_token, str) or not hf_token.strip():raiseif is_local_path(repo_id) or not _is_valid_repo_id(repo_id):raise@@ -1596,6 +1600,16 @@ async def get_gguf_variants_answer()return _locally_resolved(response, snapshot) if offline else responseif local_path and is_local_path(local_path):+ # A named Hub snapshot remains a cache read, even on the filesystem fallback.+ cached_ref = cached_repo_ref_for_path(local_path)+ if cached_ref is not None and hub_cached_read_refused(+ hf_token,+ repo_id = cached_ref[0],+ repo_type = cached_ref[1],+ is_cached = lambda: True,+ offline = bool(offline),+ ):+ raise HTTPException(status_code = 404, detail = "Model not found")variants, has_vision = list_local_gguf_variants(local_path)if variants or has_vision:answered_from[0] = local_pathdiff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.pyindex 58af39bf059..63067fa81ee 100644--- a/studio/backend/routes/models.py+++ b/studio/backend/routes/models.py@@ -4562,7 +4562,9 @@ async def get_gguf_variants(repo_id = resolve_host_path_reference(repo_id) or repo_idlocal_path = resolve_host_path_reference(local_path) or local_pathif account_access.managed_account():- await asyncio.to_thread(account_access.require_model_access, repo_id)+ await asyncio.to_thread(+ account_access.require_model_access, repo_id, **({"offline": True} if offline else {})+ )try:hf_token = _resolve_hub_token(hf_token_header, hf_token)from hub.services.models import gguf_variants as hub_gguf_variantsdiff --git a/studio/backend/tests/test_on_device_gguf_discovery.py b/studio/backend/tests/test_on_device_gguf_discovery.pynew file mode 100644index 00000000000..489e4fe4058--- /dev/null+++ b/studio/backend/tests/test_on_device_gguf_discovery.py@@ -0,0 +1,227 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""The disk-only requests used by On Device retain authorization and completeness checks."""++import asyncio+from collections import OrderedDict+import struct+import time+from types import SimpleNamespace++from fastapi import FastAPI, HTTPException+from fastapi.testclient import TestClient+import pytest++from auth.authentication import authenticated_via_api_key, get_current_subject+from hub.dependencies import get_request_hf_token+from hub.routes import inventory+from hub.services.models import gguf_variants as GV+from hub.utils import download_manifest, hf_tokens, inventory_scan+from routes import models+from utils import hf_cache_settings++REPO = "Org/OnDevice-GGUF"+QUANT = "Q4_K_M"+MAIN = f"model-{QUANT}.gguf"+TOKEN = "hf_on_device_test_owner"+++def cached_model(monkeypatch, tmp_path):+ cache = tmp_path / "hub"+ monkeypatch.setitem(hf_cache_settings._EXPLICIT_CACHE_ENV, "HF_HUB_CACHE", str(cache))+ monkeypatch.setenv("HF_HUB_CACHE", str(cache))+ monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [cache])+ monkeypatch.setattr("huggingface_hub.constants.HF_HUB_CACHE", str(cache))+ monkeypatch.setattr(GV, "_VARIANT_REQUIREMENT_LAST_KNOWN", OrderedDict())+ monkeypatch.setattr(GV, "_VARIANT_REQUIREMENT_FORGOTTEN", False)+ hf_tokens.reset_repo_access_cache()+ monkeypatch.setattr(hf_tokens, "_hub_offline", lambda: False)+ monkeypatch.setattr(hf_tokens, "_host_hf_credentials", lambda: (True, [TOKEN]))+ monkeypatch.setattr(hf_tokens, "_no_other_credential_ever_held", lambda _: True)+ monkeypatch.setattr(hf_tokens, "_recorded_request_token_repos", lambda: {})+ monkeypatch.setattr(hf_tokens, "_provenance_record_is_missing", lambda *_: False)+ calls = []++ def unreachable(*args, **kwargs):+ calls.append(args)+ raise ConnectionError("Hugging Face unavailable")++ monkeypatch.setattr(+ "huggingface_hub.utils.get_session", lambda: SimpleNamespace(get = unreachable)+ )+ monkeypatch.setattr("huggingface_hub.HfApi.model_info", unreachable)+ monkeypatch.setattr("huggingface_hub.model_info", unreachable)+ monkeypatch.setattr(GV, "_gguf_all_variant_requirements", unreachable)+ monkeypatch.setattr(GV, "list_gguf_variants", unreachable)+ repo = cache / "models--Org--OnDevice-GGUF"+ snapshot = repo / "snapshots" / ("a" * 40)+ snapshot.mkdir(parents = True)+ (repo / "refs").mkdir()+ (repo / "refs/main").write_text(snapshot.name)+ (snapshot / MAIN).write_bytes(b"GGUF" + struct.pack("<IQQ", 3, 0, 0) + b"\0" * 232)++ def plan(*files):+ assert download_manifest.write_manifest(+ "model",+ REPO,+ QUANT,+ [download_manifest.ExpectedFile(name, size) for name, size in files],+ hub_cache = cache,+ )+ inventory_scan.invalidate_hf_cache_scans()++ plan((MAIN, 256))+ yield SimpleNamespace(repo = repo, snapshot = snapshot, plan = plan, calls = calls)+ hf_tokens.reset_repo_access_cache()+ inventory_scan.invalidate_hf_cache_scans()+++def query(+ model,+ prefix,+ *,+ token = TOKEN,+ local_path = True,+ offline = True,+):+ app = FastAPI()+ app.include_router(inventory.router if prefix == "/api/hub" else models.router, prefix = prefix)+ app.dependency_overrides[get_current_subject] = lambda: "test-owner"+ app.dependency_overrides[authenticated_via_api_key] = lambda: False+ app.dependency_overrides[get_request_hf_token] = lambda: token+ params = {+ "repo_id": REPO,+ "prefer_local_cache": str(offline).lower(),+ "offline": str(offline).lower(),+ "include_cache_locations": "true",+ }+ if local_path:+ params["local_path"] = str(model.snapshot)+ with TestClient(app) as client:+ return client.get(f"{prefix}/gguf-variants", params = params)++[email protected]("prefix", ["/api/hub", "/api/models"])+def test_cached_quant_resolves_without_hub_even_when_host_reports_online(cached_model, prefix):+ response = query(cached_model, prefix)+ assert response.status_code == 200, response.text+ data = response.json()+ assert data["dependencies_resolved"] is True+ assert [v["quant"] for v in data["variants"] if v["downloaded"]] == [QUANT]+ assert cached_model.calls == []++[email protected]("missing", ["shard", "companion"])[email protected]("prefix", ["/api/hub", "/api/models"])+def test_local_discovery_keeps_incomplete_quants_non_loadable(cached_model, prefix, missing):+ if missing == "companion":+ cached_model.plan((MAIN, 256), ("mmproj-F16.gguf", 128))+ else:+ shard = "model-Q4_K_M-00001-of-00002.gguf"+ (cached_model.snapshot / MAIN).rename(cached_model.snapshot / shard)+ cached_model.plan((shard, 256), ("model-Q4_K_M-00002-of-00002.gguf", 256))+ response = query(cached_model, prefix)+ assert response.status_code == 200, response.text+ data = response.json()+ assert data["dependencies_resolved"] is False+ assert all(not v["downloaded"] or v["partial"] for v in data["variants"])+ assert cached_model.calls == []++[email protected]("token", ["hf_another_credential", False])[email protected]("local_path", [False, True])+def test_local_discovery_withholds_private_cache_from_another_identity(+ cached_model, token, local_path+):+ (cached_model.snapshot / "Q8_0").mkdir()+ response = query(cached_model, "/api/hub", token = token, local_path = local_path)+ assert response.status_code == 404 or (+ response.status_code == 200 and response.json()["variants"] == []+ )+ assert cached_model.calls == []+++def test_offline_managed_account_cannot_probe_for_a_missing_grant(cached_model, monkeypatch):+ access = GV.account_access+ monkeypatch.setattr(access, "managed_account", lambda: True)+ monkeypatch.setattr(access, "account_hf_token", lambda token: token)++ def denied(*args, **kwargs):+ raise HTTPException(403, "Model is not granted to this account")++ def authorize(*args):+ cached_model.calls.append("authorize_download")+ denied()++ monkeypatch.setattr(access, "require_model_access", denied)+ monkeypatch.setattr(access, "authorize_download", authorize)+ with pytest.raises(HTTPException) as error:+ asyncio.run(+ GV.get_gguf_variants_response(+ REPO, hf_token = TOKEN, offline = True, prefer_local_cache = True+ )+ )+ assert error.value.status_code == 403+ assert cached_model.calls == []++[email protected]("prefix", ["/api/hub", "/api/models"])[email protected]("access", ["grant", "public-proof", "none"])+def test_managed_account_authorizes_from_disk_without_public_repo_probe(+ cached_model, monkeypatch, access, prefix+):+ policy = GV.account_access+ monkeypatch.setattr(policy, "managed_account", lambda: True)+ monkeypatch.setattr(+ policy, "model_grants", lambda: {f"model:{REPO.lower()}"} if access == "grant" else set()+ )+ monkeypatch.setattr(policy, "_public_repos", {})+ key = policy._public_key(REPO, "model")+ name = f"{key[0]}|model:{REPO.lower()}"+ monkeypatch.setattr(+ policy,+ "_load_public_verdicts",+ lambda: {name: time.time()} if access == "public-proof" else {},+ )++ def no_probe(*args, **kwargs):+ cached_model.calls.append("public_repo_probe")+ raise ConnectionError("offline")++ monkeypatch.setattr(policy, "_hub_public_answer", no_probe)+ response = query(cached_model, prefix)+ assert response.status_code == (404 if access == "none" else 200), response.text+ if response.status_code == 200:+ assert response.json()["dependencies_resolved"] is True+ assert cached_model.calls == []+++def test_an_explicit_non_hub_folder_keeps_its_local_listing(cached_model, tmp_path):+ local = tmp_path / "local-model"+ local.mkdir()+ (local / MAIN).write_bytes((cached_model.snapshot / MAIN).read_bytes())+ response = asyncio.run(+ GV.get_gguf_variants_response(REPO, local_path = str(local), offline = True, hf_token = False)+ )+ assert [v.quant for v in response.variants if v.downloaded] == [QUANT]+ assert cached_model.calls == []++[email protected]("prefix", ["/api/hub", "/api/models"])+def test_online_remote_discovery_still_lists_published_quants(cached_model, monkeypatch, prefix):+ from hub.utils.gguf import GgufVariantInfo++ listed = []++ def remote(repo_id, **kwargs):+ listed.append(repo_id)+ return [GgufVariantInfo(filename = MAIN, quant = QUANT, size_bytes = 256)], False, []++ monkeypatch.setattr(GV, "list_gguf_variants", remote)+ monkeypatch.setattr(GV, "_gguf_all_variant_requirements", lambda *_a, **_kw: {})+ response = query(cached_model, prefix, local_path = False, offline = False)+ assert response.status_code == 200, response.text+ assert listed == [REPO]+ assert response.json()["variants"]diff --git a/studio/frontend/src/features/chat/api/gguf-variants-request.ts b/studio/frontend/src/features/chat/api/gguf-variants-request.tsindex cbf3f207bb9..4e42fdce4c2 100644--- a/studio/frontend/src/features/chat/api/gguf-variants-request.ts+++ b/studio/frontend/src/features/chat/api/gguf-variants-request.ts@@ -16,6 +16,8 @@ import {export const GGUF_VARIANTS_TIMEOUT_MS = 30_000;export interface GgufVariantsRequestOptions {+ /** Answer from disk without Hub discovery or authorization probes. */+ localOnly?: boolean;preferLocalCache?: boolean;includeCacheLocations?: boolean;localPath?: string | null;@@ -29,19 +31,20 @@ export function ggufVariantsQuery(options: GgufVariantsRequestOptions | undefined,offline: boolean,): URLSearchParams {+ const localOnly = options?.localOnly === true || offline;const params = new URLSearchParams({ repo_id: repoId });// Chat resolves logical quants across remembered folders. Media callers opt out.if (options?.includeCacheLocations !== false) {params.set("include_cache_locations", "true");}- if (options?.preferLocalCache || offline) {+ if (options?.preferLocalCache || localOnly) {params.set("prefer_local_cache", "true");}const localPath = options?.localPath?.trim();if (localPath) {params.set("local_path", localPath);}- if (offline) {+ if (localOnly) {params.set("offline", "true");}return params;diff --git a/studio/frontend/src/features/chat/index.ts b/studio/frontend/src/features/chat/index.tsindex f2999221ae0..7a3da666e8f 100644--- a/studio/frontend/src/features/chat/index.ts+++ b/studio/frontend/src/features/chat/index.ts@@ -42,6 +42,7 @@ export type {ApiMonitorEntry,BackendModelDetails,GgufVariantDetail,+ GgufVariantsResponse,InferenceStatusResponse,} from "./types/api";export {diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.tsindex 320fd7e319d..a6491e5844e 100644--- a/studio/frontend/src/features/chat/types/api.ts+++ b/studio/frontend/src/features/chat/types/api.ts@@ -204,7 +204,7 @@ export interface GgufVariantsResponse {variants: GgufVariantDetail[];has_vision: boolean;default_variant: string | null;- /** True only when Hub metadata resolved every required companion. */+ /** True when Hub metadata or a complete cached download plan proves companion readiness. */dependencies_resolved?: boolean;/** Native max context from GGUF metadata; present once a variant is downloaded. */context_length?: number | null;diff --git a/studio/frontend/src/features/hub/index.ts b/studio/frontend/src/features/hub/index.tsindex 51216e64cb2..84f39f53ec1 100644--- a/studio/frontend/src/features/hub/index.ts+++ b/studio/frontend/src/features/hub/index.ts@@ -30,6 +30,7 @@ export { useHubInfiniteScroll } from "./hooks/use-hub-infinite-scroll";export type { CapabilityKey } from "./lib/model-capabilities";export { useLatestRef } from "./hooks/use-latest-ref";export { useHubAvailability, useOnlineStatus } from "./hooks/use-online-status";+export { isHuggingFaceOffline } from "./lib/network";export { HubFailureHint } from "./catalog/catalog-states";export {INVENTORY_HINT_KIND,diff --git a/studio/frontend/src/features/hub/inventory/api.ts b/studio/frontend/src/features/hub/inventory/api.tsindex df615a7218d..d71b6fbcbc5 100644--- a/studio/frontend/src/features/hub/inventory/api.ts+++ b/studio/frontend/src/features/hub/inventory/api.ts@@ -222,7 +222,7 @@ export interface GgufVariantsResponse {variants: GgufVariantDetail[];has_vision: boolean;default_variant: string | null;- /** True only when Hub metadata resolved every required companion. */+ /** True when Hub metadata or a complete cached download plan proves companion readiness. */dependencies_resolved?: boolean;}@@ -499,18 +499,19 @@ export async function listGgufVariants(repoId: string,hfToken?: string,options?: {+ localOnly?: boolean;preferLocalCache?: boolean;includeCacheLocations?: boolean;localPath?: string | null;signal?: AbortSignal;},): Promise<GgufVariantsResponse> {- const offline = isHuggingFaceOffline();+ const offline = options?.localOnly === true || isHuggingFaceOffline();const localPath = options?.localPath?.trim() || null;const preferLocalCache = !!options?.preferLocalCache || offline;const signal = options?.signal;const key = `${repoId}::${fingerprintToken(hfToken)}::${- preferLocalCache ? "local" : "remote"+ offline ? "offline" : preferLocalCache ? "local" : "remote"}::${localPathCacheKey(localPath)}::${!!options?.includeCacheLocations}`;const now = Date.now();const hit = ggufVariantsCache.get(key);diff --git a/studio/frontend/src/features/model-picker/components/model-selector/gguf-discovery.ts b/studio/frontend/src/features/model-picker/components/model-selector/gguf-discovery.tsnew file mode 100644index 00000000000..8987a2bee04--- /dev/null+++ b/studio/frontend/src/features/model-picker/components/model-selector/gguf-discovery.ts@@ -0,0 +1,116 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import type { GgufVariantDetail, GgufVariantsResponse } from "@/features/chat";++/** Hub-only state the disk answer cannot know: a newer revision or a companion the Hub added. */+function withHubState<V extends GgufVariantDetail>(+ local: V,+ published: V | undefined,+): V {+ const drafter = local.pending_drafter_filename ? local : published;+ return {+ ...published,+ ...local,+ update_available: published?.update_available ?? local.update_available,+ pending_drafter_filename: drafter?.pending_drafter_filename,+ pending_drafter_size_bytes: drafter?.pending_drafter_size_bytes,+ // The Hub's sizes count companions (mmproj, drafter) and an update's new revision.+ ...(published+ ? {+ size_bytes: published.size_bytes,+ download_size_bytes: published.download_size_bytes,+ }+ : {}),+ };+}++export async function loadPickerGgufVariants<T extends GgufVariantsResponse>(+ list: (localOnly: boolean) => Promise<T>,+ options: {+ onDevice: boolean;+ canDiscoverRemote: () => boolean;+ signal?: AbortSignal;+ },+ onCached: (response: T) => void,+): Promise<T> {+ if (!options.onDevice) return list(false);++ let cached: T;+ try {+ cached = await list(true);+ } catch (error) {+ // A disk answer the Hub can still give (moved cache, token-only access) falls back to it.+ if (options.signal?.aborted || !options.canDiscoverRemote()) throw error;+ return list(false);+ }+ onCached(cached);+ // Remote discovery still runs with All quantizations off: update badges come only from the Hub.+ if (options.signal?.aborted || !options.canDiscoverRemote()) {+ return cached;+ }++ try {+ const remote = await list(false);+ const variants = new Map(+ remote.variants.map((v) => [v.quant.toLowerCase(), v]),+ );+ for (const local of cached.variants) {+ const key = local.quant.toLowerCase();+ variants.set(key, withHubState(local, variants.get(key)));+ }+ return {+ ...cached,+ variants: [...variants.values()],+ has_vision: cached.has_vision || remote.has_vision,+ default_variant: remote.default_variant ?? cached.default_variant,+ };+ } catch {+ // A remote timeout or connection error must not replace the usable disk answer.+ return cached;+ }+}++/** Whether a reachable Hub reports an update or a missing companion for a cached quant: only the+ * expander carries those actions, so the collapsed row must give way. */+export async function hubWithdrawsSoleQuant<T extends GgufVariantsResponse>(+ listRemote: () => Promise<T>,+ quant: string,+): Promise<boolean> {+ let remote: T;+ try {+ remote = await listRemote();+ } catch {+ return false;+ }+ const published = remote.variants.find(+ (v) => v.quant.toLowerCase() === quant.toLowerCase(),+ );+ return Boolean(+ published?.update_available || published?.pending_drafter_filename,+ );+}++export function createTaskLimiter(limit: number) {+ let active = 0;+ const queue: (() => void)[] = [];+ const next = () => {+ if (active >= limit) return;+ const start = queue.shift();+ if (start) start();+ };+ return function run<R>(task: () => Promise<R>): Promise<R> {+ return new Promise<R>((resolve, reject) => {+ queue.push(() => {+ active += 1;+ task()+ .then(resolve, reject)+ .finally(() => {+ active -= 1;+ next();+ });+ });+ next();+ });+ };+}diff --git a/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx b/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsxindex d101cad5eed..5a0cdedadb0 100644--- a/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx+++ b/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx@@ -1,7 +1,15 @@// SPDX-License-Identifier: AGPL-3.0-only// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0-import { isChatGgufTask, reconcileGgufPinsAfterDelete } from "./reconcile-gguf-pins";+import {+ isChatGgufTask,+ reconcileGgufPinsAfterDelete,+} from "./reconcile-gguf-pins";+import {+ createTaskLimiter,+ hubWithdrawsSoleQuant,+ loadPickerGgufVariants,+} from "./gguf-discovery";import { ModelMemoryBar } from "@/components/model-memory-bar";import { shouldRefreshPickerInventoryOnMount } from "@/components/resource-picker/picker-tab-policy";@@ -56,11 +64,9 @@ import {listGgufVariants as listGgufVariantsCached,useGgufVariantsCacheVersions,useHubInfiniteScroll,+ isHuggingFaceOffline,} from "@/features/hub";-import {- type HfModelResult,- useHubModelSearch,-} from "@/features/hub";+import { type HfModelResult, useHubModelSearch } from "@/features/hub";import {classifyUnslothSupport,downloadManager,@@ -1646,8 +1652,7 @@ function normalizeGgufVariantsResponse(// The backend's own verdict, which resolves existence-first: a marker-less relative name that// exists on disk is a local model. A server predating the field leaves the prefix test.resolvedLocally: res?.resolved_locally === true,- // Missing/false means the server used local or offline fallback metadata. That cannot prove- // whether a cached main GGUF still needs a managed drafter companion.+ // The server proves dependencies from Hub metadata or a complete local download plan.dependenciesResolved: res?.dependencies_resolved === true,};}@@ -1668,13 +1673,14 @@ interface SoleDownloadedQuant {hasVision: boolean | undefined;}-/** The repo's one complete quant, or null when Hub metadata cannot verify its dependencies. */+/** The repo's one complete cached quant, or null when its dependencies cannot be verified. */async function readSoleQuant(target: SoleQuantTarget,hfToken?: string,): Promise<SoleDownloadedQuant | null> {try {const res = await listGgufVariantsCached(target.repoId, hfToken, {+ localOnly: true,localPath: target.localSource,includeCacheLocations: target.includeCacheLocations,});@@ -1690,6 +1696,22 @@ async function readSoleQuant(}}+function soleQuantNeedsExpander(+ target: SoleQuantTarget,+ quant: string,+ hfToken?: string,+): Promise<boolean> {+ if (isHuggingFaceOffline()) return Promise.resolve(false);+ return hubWithdrawsSoleQuant(+ () =>+ listGgufVariantsCached(target.repoId, hfToken, {+ localPath: target.localSource,+ includeCacheLocations: target.includeCacheLocations,+ }),+ quant,+ );+}+const EMPTY_SOLE_QUANT_ENTRIES: ReadonlyMap<string,SoleQuantEntry<SoleDownloadedQuant>@@ -1757,6 +1779,7 @@ function useSoleDownloadedQuants(};}, []);+ const hubProbeLimitRef = useRef(createTaskLimiter(SOLE_QUANT_WORKERS));const readerRef = useRef<ReturnType<typeof createSoleQuantReader<SoleDownloadedQuant>> | null>(null);@@ -1771,6 +1794,23 @@ function useSoleDownloadedQuants(next.set(target.repoId, { key: target.key, quant });return next;});+ if (!quant) return;+ // The disk verdict shows at once; a later Hub answer may still send the row back to its expander.+ void hubProbeLimitRef.current(() =>+ soleQuantNeedsExpander(+ target,+ quant.variant.quant,+ hfTokenRef.current,+ ),+ ).then((withdraw) => {+ if (!withdraw || !mountedRef.current) return;+ setEntries((prev) => {+ if (prev.get(target.repoId)?.key !== target.key) return prev;+ const next = new Map(prev);+ next.set(target.repoId, { key: target.key, quant: null });+ return next;+ });+ });},});}@@ -1883,6 +1923,9 @@ function GgufVariantExpander({// which a downloaded hub model also carries.const [resolvedLocally, setResolvedLocally] = useState(false);const localSource = loadId || cachePath || null;+ const showAllQuantizations = useChatRuntimeStore(+ (s) => s.showAllQuantizations,+ );useEffect(() => {let canceled = false;@@ -1898,23 +1941,45 @@ function GgufVariantExpander({setResolvedLocally(false);});- // Chat rows name the repository; media and explicit local rows retain their folder scope.- listGgufVariants(repoId, hfToken, {- ...(localSource ? { localPath: localSource } : {}),- includeCacheLocations: !mediaPageForTask(pipelineTag),- signal: controller.signal,- })+ let cachedResponse:+ | Awaited<ReturnType<typeof listGgufVariants>>+ | undefined;+ const applyResponse = (+ res: Awaited<ReturnType<typeof listGgufVariants>>,+ ) => {+ if (canceled) return;+ const normalized = normalizeGgufVariantsResponse(res);+ setVariants(normalized.variants);+ setDefaultVariant(normalized.defaultVariant);+ setHasVision(normalized.hasVision);+ if (normalized.hasVision !== undefined) {+ onHasVision?.(normalized.hasVision);+ }+ setNativeContext(normalized.contextLength);+ setResolvedLocally(normalized.resolvedLocally);+ };++ loadPickerGgufVariants(+ (localOnly) =>+ listGgufVariants(repoId, hfToken, {+ ...(localSource ? { localPath: localSource } : {}),+ localOnly,+ includeCacheLocations: !mediaPageForTask(pipelineTag),+ signal: controller.signal,+ }),+ {+ onDevice,+ canDiscoverRemote: () => !isHuggingFaceOffline(),+ signal: controller.signal,+ },+ (res) => {+ cachedResponse = res;+ applyResponse(res);+ if (!canceled) setLoading(false);+ },+ ).then((res) => {- if (canceled) return;- const normalized = normalizeGgufVariantsResponse(res);- setVariants(normalized.variants);- setDefaultVariant(normalized.defaultVariant);- setHasVision(normalized.hasVision);- if (normalized.hasVision !== undefined) {- onHasVision?.(normalized.hasVision);- }- setNativeContext(normalized.contextLength);- setResolvedLocally(normalized.resolvedLocally);+ if (res !== cachedResponse) applyResponse(res);}).catch((err) => {if (canceled) return;@@ -1928,7 +1993,7 @@ function GgufVariantExpander({canceled = true;controller.abort();};- }, [repoId, localSource, refreshKey, hfToken, pipelineTag]);+ }, [repoId, localSource, refreshKey, hfToken, pipelineTag, onDevice]);// Covers Unix absolute, Windows drive, UNC, relative and tilde paths.const isLocalPath = /^(\/|\.{1,2}[\\/]|~[\\/]|[A-Za-z]:[\\/]|\\\\)/.test(@@ -2100,9 +2165,6 @@ function GgufVariantExpander({}, [variants, variantGroups, effectiveRecommendedByGroup, getVariantFit]);// On Device only: with All quantizations off, list quants already on disk, torn ones included.- const showAllQuantizations = useChatRuntimeStore(- (s) => s.showAllQuantizations,- );const displayVariants = useMemo(() => {if (!sortedVariants) return sortedVariants;return visibleGgufVariants(sortedVariants, {diff --git a/studio/frontend/tests/gguf-local-discovery.test.ts b/studio/frontend/tests/gguf-local-discovery.test.tsnew file mode 100644index 00000000000..d08025c6360--- /dev/null+++ b/studio/frontend/tests/gguf-local-discovery.test.ts@@ -0,0 +1,98 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import assert from "node:assert/strict";+import test from "node:test";+import { registerStoreStubResolver } from "./helpers/kit.ts";++registerStoreStubResolver();+const { setAuthFetchHandler } = await import("./helpers/store-stubs/auth.ts");+const { listGgufVariants } = await import(+ "../src/features/hub/inventory/api.ts"+);+const { ggufVariantsQuery } = await import(+ "../src/features/chat/api/gguf-variants-request.ts"+);++const cached = {+ repo_id: "Org/Cached",+ variants: [+ {+ quant: "Q4_K_M",+ filename: "model-Q4_K_M.gguf",+ size_bytes: 256,+ downloaded: true,+ },+ ],+ has_vision: false,+ default_variant: "Q4_K_M",+ dependencies_resolved: true,+};++test("chat local-only discovery skips remote work even when connectivity is reported online", () => {+ const params = ggufVariantsQuery(+ "Org/Cached",+ { localOnly: true, localPath: "/models/cached" },+ false,+ );+ assert.equal(params.get("offline"), "true");+ assert.equal(params.get("prefer_local_cache"), "true");+ assert.equal(params.get("local_path"), "/models/cached");+});++test("the cached single-quant client sends local-only discovery while navigator reports online", async () => {+ const original = Object.getOwnPropertyDescriptor(globalThis, "navigator");+ Object.defineProperty(globalThis, "navigator", {+ value: { onLine: true },+ configurable: true,+ });+ const calls: URL[] = [];+ setAuthFetchHandler(async (url) => {+ calls.push(new URL(String(url), "http://localhost"));+ return new Response(JSON.stringify(cached));+ });+ try {+ const result = await listGgufVariants("Org/OnlineWebview", undefined, {+ localOnly: true,+ });+ assert.equal(result.dependencies_resolved, true);+ assert.equal(calls.length, 1);+ assert.equal(calls[0].searchParams.get("offline"), "true");+ assert.equal(calls[0].searchParams.get("prefer_local_cache"), "true");+ } finally {+ if (original) Object.defineProperty(globalThis, "navigator", original);+ else delete (globalThis as Record<string, unknown>).navigator;+ }+});++test("a cache-preferred answer cannot replace a dependency-proven local-only answer", async () => {+ const calls: URL[] = [];+ setAuthFetchHandler(async (url) => {+ const request = new URL(String(url), "http://localhost");+ calls.push(request);+ return new Response(+ JSON.stringify({+ ...cached,+ dependencies_resolved: request.searchParams.get("offline") === "true",+ }),+ );+ });+ const preferred = await listGgufVariants("Org/ModeSwitch", undefined, {+ preferLocalCache: true,+ });+ assert.equal(preferred.dependencies_resolved, false);+ const local = await listGgufVariants("Org/ModeSwitch", undefined, {+ localOnly: true,+ });+ assert.equal(local.dependencies_resolved, true);+ assert.equal(calls.length, 2);+ const again = await listGgufVariants("Org/ModeSwitch", undefined, {+ localOnly: true,+ });+ assert.equal(again.dependencies_resolved, true);+ assert.equal(+ calls.length,+ 2,+ "local-only answers still share their own cache",+ );+});diff --git a/studio/frontend/tests/picker-gguf-discovery.test.ts b/studio/frontend/tests/picker-gguf-discovery.test.tsnew file mode 100644index 00000000000..0e7eb21979b--- /dev/null+++ b/studio/frontend/tests/picker-gguf-discovery.test.ts@@ -0,0 +1,316 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import assert from "node:assert/strict";+import test from "node:test";+import type { GgufVariantsResponse } from "../src/features/chat/types/api.ts";+import {+ loadPickerGgufVariants,+ createTaskLimiter,+ hubWithdrawsSoleQuant,+} from "../src/features/model-picker/components/model-selector/gguf-discovery.ts";++const local: GgufVariantsResponse = {+ repo_id: "Org/Cached",+ variants: [+ {+ quant: "Q4_K_M",+ filename: "old-Q4_K_M.gguf",+ size_bytes: 256,+ downloaded: true,+ cache_path: "/cache/old",+ },+ ],+ has_vision: false,+ default_variant: "Q4_K_M",+ context_length: 4096,+ dependencies_resolved: true,+};+const options = {+ onDevice: true,+ canDiscoverRemote: () => true,+};++test("On Device answers from disk alone once the Hub is known unreachable", async () => {+ const calls: boolean[] = [];+ const shown: (typeof local)[] = [];+ const result = await loadPickerGgufVariants(+ async (localOnly) => {+ calls.push(localOnly);+ return local;+ },+ { ...options, canDiscoverRemote: () => false },+ (response) => shown.push(response),+ );+ assert.deepEqual(calls, [true]);+ assert.deepEqual(shown, [local]);+ assert.equal(result, local);+});++test("On Device publishes cached quants before a stalled remote request finishes", async () => {+ const calls: boolean[] = [];+ let displayed: GgufVariantsResponse | null = null;+ let rejectRemote!: (error: Error) => void;+ const remote = new Promise<typeof local>((_resolve, reject) => {+ rejectRemote = reject;+ });+ const pending = loadPickerGgufVariants(+ async (localOnly) => {+ calls.push(localOnly);+ return localOnly ? local : remote;+ },+ options,+ (response) => {+ displayed = response;+ },+ );+ await new Promise((resolve) => setTimeout(resolve, 0));+ assert.equal(+ displayed,+ local,+ "cached quant must be usable while remote discovery is pending",+ );+ assert.deepEqual(calls, [true, false]);+ rejectRemote(new Error("Hugging Face unreachable"));+ assert.equal(await pending, local);+});++test("online discovery adds published quants without changing a cached quant's load path or readiness", async () => {+ const remote = {+ ...local,+ context_length: 8192,+ variants: [+ {+ ...local.variants[0],+ filename: "new-Q4_K_M.gguf",+ downloaded: false,+ cache_path: "/cache/new",+ update_available: true,+ },+ {+ quant: "Q8_0",+ filename: "model-Q8_0.gguf",+ size_bytes: 512,+ downloaded: false,+ cache_path: null,+ },+ ],+ };+ const result = await loadPickerGgufVariants(+ async (localOnly) => (localOnly ? local : remote),+ options,+ () => {},+ );+ assert.equal(result.variants.length, 2);+ const cached = result.variants.find((v) => v.quant === "Q4_K_M");+ assert.equal(cached?.filename, "old-Q4_K_M.gguf");+ assert.equal(cached?.cache_path, "/cache/old");+ assert.equal(cached?.downloaded, true);+ assert.equal(cached?.update_available, true);+ assert.equal(result.context_length, 4096);+ assert.equal(+ result.variants.find((v) => v.quant === "Q8_0")?.downloaded,+ false,+ );+});++test("a remote answer cannot promote a locally incomplete quant", async () => {+ const incomplete = {+ ...local,+ variants: [{ ...local.variants[0], downloaded: false, partial: true }],+ dependencies_resolved: false,+ };+ const result = await loadPickerGgufVariants(+ async (localOnly) => (localOnly ? incomplete : local),+ options,+ () => {},+ );+ assert.equal(result.variants[0].downloaded, false);+ assert.equal(result.variants[0].partial, true);+ assert.equal(result.dependencies_resolved, false);+});++test("known Hub backoff keeps On Device local", async () => {+ const calls: boolean[] = [];+ await loadPickerGgufVariants(+ async (localOnly) => {+ calls.push(localOnly);+ return local;+ },+ { ...options, canDiscoverRemote: () => false },+ () => {},+ );+ assert.deepEqual(calls, [true]);+});++test("collapsing the row after its cached answer prevents remote work", async () => {+ const controller = new AbortController();+ const calls: boolean[] = [];+ await loadPickerGgufVariants(+ async (localOnly) => {+ calls.push(localOnly);+ return local;+ },+ { ...options, signal: controller.signal },+ () => controller.abort(),+ );+ assert.deepEqual(calls, [true]);+});++test("catalog rows retain remote discovery", async () => {+ const calls: boolean[] = [];+ await loadPickerGgufVariants(+ async (localOnly) => {+ calls.push(localOnly);+ return local;+ },+ { ...options, onDevice: false },+ () => assert.fail("catalog rows must not publish a cached phase"),+ );+ assert.deepEqual(calls, [false]);+});++test("a Hub update or missing drafter reaches a cached quant's row", async () => {+ const remote = {+ ...local,+ variants: [+ {+ ...local.variants[0],+ update_available: true,+ pending_drafter_filename: "mtp-drafter.gguf",+ pending_drafter_size_bytes: 64,+ },+ ],+ };+ const result = await loadPickerGgufVariants(+ async (localOnly) => (localOnly ? local : remote),+ options,+ () => {},+ );+ assert.equal(result.variants[0].update_available, true);+ assert.equal(result.variants[0].pending_drafter_filename, "mtp-drafter.gguf");+ assert.equal(result.variants[0].pending_drafter_size_bytes, 64);+ assert.equal(result.variants[0].filename, "old-Q4_K_M.gguf");+});++test("an update downloads the published revision's size and the Hub default wins", async () => {+ const remote: GgufVariantsResponse = {+ ...local,+ default_variant: "Q8_0",+ variants: [+ {+ ...local.variants[0],+ size_bytes: 300,+ download_size_bytes: 300,+ update_available: true,+ },+ { quant: "Q8_0", filename: "model-Q8_0.gguf", size_bytes: 512 },+ ],+ };+ const result = await loadPickerGgufVariants(+ async (localOnly) =>+ localOnly+ ? {+ ...local,+ variants: [{ ...local.variants[0], download_size_bytes: 0 }],+ }+ : remote,+ options,+ () => {},+ );+ const cached = result.variants.find((v) => v.quant === "Q4_K_M");+ assert.equal(cached?.download_size_bytes, 300);+ assert.equal(cached?.size_bytes, 300);+ assert.equal(cached?.cache_path, "/cache/old");+ assert.equal(result.default_variant, "Q8_0");+ const current = await loadPickerGgufVariants(+ async (localOnly) =>+ localOnly ? local : { ...remote, variants: [local.variants[0]] },+ options,+ () => {},+ );+ assert.equal(current.variants[0].size_bytes, 256);+});++test("a Hub update or missing drafter withdraws a collapsed sole quant", async () => {+ for (const extra of [+ { update_available: true },+ { pending_drafter_filename: "mtp-drafter.gguf" },+ ]) {+ const remote = { ...local, variants: [{ ...local.variants[0], ...extra }] };+ assert.equal(+ await hubWithdrawsSoleQuant(async () => remote, "q4_k_m"),+ true,+ );+ }+ assert.equal(await hubWithdrawsSoleQuant(async () => local, "Q4_K_M"), false);+ assert.equal(+ await hubWithdrawsSoleQuant(async () => {+ throw new Error("Hugging Face unreachable");+ }, "Q4_K_M"),+ false,+ );+});++test("follow-up Hub probes never exceed the limiter's concurrency", async () => {+ const run = createTaskLimiter(2);+ let active = 0;+ let peak = 0;+ const done = await Promise.all(+ Array.from({ length: 7 }, (_, i) =>+ run(async () => {+ active += 1;+ peak = Math.max(peak, active);+ await new Promise((resolve) => setTimeout(resolve, 5));+ active -= 1;+ if (i === 3) throw new Error("probe failed");+ return i;+ }).catch(() => -1),+ ),+ );+ assert.equal(peak, 2);+ assert.deepEqual(done, [0, 1, 2, -1, 4, 5, 6]);+});++test("a failed disk phase falls back to the Hub only when it is reachable", async () => {+ const calls: boolean[] = [];+ const list = async (localOnly: boolean) => {+ calls.push(localOnly);+ if (localOnly) throw new Error("Model not found");+ return local;+ };+ const shown: GgufVariantsResponse[] = [];+ assert.equal(+ await loadPickerGgufVariants(list, options, (r) => shown.push(r)),+ local,+ );+ assert.deepEqual(shown, []);+ await assert.rejects(+ loadPickerGgufVariants(+ list,+ { ...options, canDiscoverRemote: () => false },+ () => {},+ ),+ /Model not found/,+ );+ assert.deepEqual(calls, [true, false, true]);+});++test("an up-to-date cached quant keeps the Hub's companion-inclusive size", async () => {+ const result = await loadPickerGgufVariants(+ async (localOnly) =>+ localOnly+ ? {+ ...local,+ variants: [{ ...local.variants[0], download_size_bytes: 256 }],+ }+ : {+ ...local,+ variants: [{ ...local.variants[0], download_size_bytes: 900 }],+ },+ options,+ () => {},+ );+ assert.equal(result.variants[0].download_size_bytes, 900);+ assert.equal(result.variants[0].cache_path, "/cache/old");+});diff --git a/tests/studio/test_model_picker_contracts.py b/tests/studio/test_model_picker_contracts.pyindex 4c769b3180c..4b7ba97b8ed 100644--- a/tests/studio/test_model_picker_contracts.py+++ b/tests/studio/test_model_picker_contracts.py@@ -769,15 +769,17 @@ def test_a_pinned_cached_row_loads_from_the_id_the_backend_pinned():# The variant click withholds it: a quant outside the pinned snapshot lands in a different one.block = re.search(r"onSelect\(repoId, \{.*?\n\s*\}", picker, re.S)assert block and "loadId: downloaded === true ? loadId : undefined," in block.group(0)- # localPath alone: preferLocalCache would answer from disk and drop the undownloaded quants.- # #7767 added the expander's abort signal to this call, so the options are an object- # literal now rather than the bare localSource ternary.call = re.search(r"listGgufVariants\(repoId, hfToken, \{.*?\n\s*\}\)", picker, re.S)assert call, "the expander must still list variants for the row's own repo"assert "...(localSource ? { localPath: localSource } : {})" in call.group(0), "the expander drops the row's own cache directory"assert "preferLocalCache" not in call.group(0)+ assert "localOnly," in call.group(0)+ assert "loadPickerGgufVariants(" in picker+ sole = re.search(r"async function readSoleQuant\(.*?\n}", picker, re.S)+ assert sole and "localOnly: true," in sole.group(0)+ assert "soleQuantNeedsExpander(" in picker and "hubWithdrawsSoleQuant(" in pickerassert "cachePath={c.cache_path}" in picker# A reload rebuilds its target from the checkpoint id, so the resident model remembers the pin.