Skip to content

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.

Unsloth Studio: stop offering "Continue" on a base repo that only holds a GGUF's text encoder and VAE (#11644)

Leo Borcherding55866189c10a
diff --git a/studio/backend/hub/schemas/inventory.py b/studio/backend/hub/schemas/inventory.py
index b550534ccfb..c7db2572437 100644
--- a/studio/backend/hub/schemas/inventory.py
+++ b/studio/backend/hub/schemas/inventory.py
@@ -224,6 +224,14 @@ class LocalModelInfo(BaseModel):
False,
description = "Whether THIS partial can be continued byte for byte.",
)
+ # Mirrors CachedModelRepo.companion_prefetch: the Hub merges both listings.
+ companion_prefetch: bool = Field(
+ False,
+ description = (
+ "Pipeline repo holding only what a GGUF load borrowed (VAE, text encoder): partial "
+ "for loading, not an unfinished download."
+ ),
+ )
class LocalModelListResponse(BaseModel):
@@ -306,6 +314,7 @@ class CachedModelRepo(CachedRepoBase):
# An sd.cpp companion mirror is never a pick on any page, but still gets a row, because these run to
# tens of GB and the row is how they are seen and deleted.
companion: bool = False
+ companion_prefetch: bool = False
# An unrecognised pipeline carries no task and no root config for can_chat, so this flag is all
# that keeps it out of a chat picker. Declared because response_model drops undeclared keys, which
# left the CLI and the frontend disagreeing about the same row.
diff --git a/studio/backend/hub/services/models/cache_inventory.py b/studio/backend/hub/services/models/cache_inventory.py
index 2c93c5f4b2b..6879e4e936f 100644
--- a/studio/backend/hub/services/models/cache_inventory.py
+++ b/studio/backend/hub/services/models/cache_inventory.py
@@ -1178,6 +1178,8 @@ def _scan_cached_models(
"task": row_task,
"audio_type": audio_type,
"partial": snapshot_partial,
+ # Still partial so no picker loads it, but the Hub must not offer "Continue": that pulls the denoiser a GGUF replaces.
+ "companion_prefetch": companion_only and not download_partial,
"partial_transport": (
hf_cache_scan.partial_transport_for(
"model",
diff --git a/studio/backend/hub/services/models/local_inventory.py b/studio/backend/hub/services/models/local_inventory.py
index 0ca2e4a77ca..6f7a3f13546 100644
--- a/studio/backend/hub/services/models/local_inventory.py
+++ b/studio/backend/hub/services/models/local_inventory.py
@@ -438,6 +438,18 @@ def _scan_hf_cache(
snapshot_partial_transport = snapshot_partial_transport,
snapshot_partial_resumable = snapshot_partial_resumable,
)
+ # Denoiser-less pipeline (a GGUF's borrowed VAE / encoder): partial so no picker loads it, flagged so the Hub offers no Continue.
+ if not snapshot_partial and hf_cache_scan.snapshot_pipeline_missing_denoiser(
+ hf_cache_scan.latest_snapshot_dir(repo_dir)
+ ):
+ rows = [
+ row
+ if row.model_format == "gguf"
+ else row.model_copy(update = {"companion_prefetch": True})
+ for row in _apply_format_aware_partial(
+ rows, snapshot_partial = True, gguf_partial = gguf_partial
+ )
+ ]
found.extend(rows)
return found
diff --git a/studio/backend/hub/tests/test_model_services.py b/studio/backend/hub/tests/test_model_services.py
index 3531f35899b..984b9299d03 100644
--- a/studio/backend/hub/tests/test_model_services.py
+++ b/studio/backend/hub/tests/test_model_services.py
@@ -2274,6 +2274,7 @@ def test_cached_models_scan_marks_a_companion_only_pipeline_partial(monkeypatch,
)
assert row["partial"] is True
+ assert row["companion_prefetch"] is True
# A companion-only snapshot arrived intact, so it has no Resume / Redownload story.
assert row["partial_transport"] is None
@@ -2296,6 +2297,7 @@ def test_cached_models_scan_keeps_a_complete_pipeline_loadable(monkeypatch, tmp_
)
assert row["partial"] is False
+ assert row["companion_prefetch"] is False
assert row["single_file"] is False
@@ -3986,6 +3988,62 @@ def test_hf_cache_scan_fallback_row_uses_local_model_info_alias(monkeypatch, tmp
assert rows[0].model_format == "unknown"
+ "with_denoiser, download_partial, expected",
+ [(False, False, True), (True, False, False), (False, True, False)],
+ ids = ["companion-only", "complete-pipeline", "interrupted-download"],
+)
+def test_hf_cache_scan_flags_a_companion_only_pipeline(
+ monkeypatch, tmp_path, with_denoiser, download_partial, expected
+):
+ """The local listing must carry companion_prefetch like the cached one: the Hub merges both."""
+ cache_dir = tmp_path / "hub"
+ repo_dir = cache_dir / "models--Org--Pipeline"
+ snapshot = repo_dir / "snapshots" / _SNAPSHOT_SHA
+ for rel in ("vae/diffusion_pytorch_model.safetensors", "text_encoder/model.safetensors"):
+ (snapshot / rel).parent.mkdir(parents = True, exist_ok = True)
+ (snapshot / rel).write_bytes(b"weights")
+ (snapshot / "transformer").mkdir(parents = True, exist_ok = True)
+ (snapshot / "transformer" / "config.json").write_text("{}", encoding = "utf-8")
+ if with_denoiser:
+ (snapshot / "transformer" / "diffusion_pytorch_model.safetensors").write_bytes(b"weights")
+ (snapshot / "model_index.json").write_text(
+ json.dumps(
+ {
+ "_class_name": "QwenImagePipeline",
+ "transformer": ["diffusers", "QwenImageTransformer2DModel"],
+ "vae": ["diffusers", "AutoencoderKLQwenImage"],
+ "text_encoder": ["transformers", "Qwen2_5_VLForConditionalGeneration"],
+ }
+ ),
+ encoding = "utf-8",
+ )
+ (repo_dir / "refs").mkdir(parents = True, exist_ok = True)
+ (repo_dir / "refs" / "main").write_text(_SNAPSHOT_SHA)
+ (repo_dir / "blobs").mkdir(parents = True, exist_ok = True)
+ (repo_dir / "blobs" / "blob").write_bytes(b"content")
+ monkeypatch.setattr(
+ local_inventory.hf_cache_scan,
+ "is_snapshot_partial",
+ lambda *_args, **_kwargs: download_partial,
+ )
+ monkeypatch.setattr(
+ local_inventory.hf_cache_scan,
+ "is_gguf_repo_partial",
+ lambda *_args, **_kwargs: False,
+ )
+
+ rows = [
+ row for row in local_inventory._scan_hf_cache(cache_dir) if row.model_id == "Org/Pipeline"
+ ]
+
+ assert rows
+ assert all(row.companion_prefetch is expected for row in rows)
+ if expected:
+ # Still partial, so no picker loads a pipeline without its denoiser.
+ assert all(row.partial for row in rows)
+
+
def test_hf_cache_scan_uses_gguf_partial_row_for_variant_state(monkeypatch, tmp_path):
monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
cache_dir = tmp_path / "hub"
diff --git a/studio/frontend/src/features/hub/catalog/download-section.tsx b/studio/frontend/src/features/hub/catalog/download-section.tsx
index dee6adb1d44..ce1dd191ce3 100644
--- a/studio/frontend/src/features/hub/catalog/download-section.tsx
+++ b/studio/frontend/src/features/hub/catalog/download-section.tsx
@@ -13,6 +13,7 @@ export function DownloadSection({
isPartial = false,
partialTransport = null,
partialResumable = false,
+ companionPrefetch = false,
modelFormat,
isActive,
activeQuant,
@@ -37,6 +38,7 @@ export function DownloadSection({
isPartial?: boolean;
partialTransport?: string | null;
partialResumable?: boolean;
+ companionPrefetch?: boolean;
modelFormat?: ModelInventoryFormat | null;
isActive: boolean;
activeQuant: string | null;
@@ -86,6 +88,7 @@ export function DownloadSection({
isPartial={isPartial}
partialTransport={partialTransport}
partialResumable={partialResumable}
+ companionPrefetch={companionPrefetch}
modelFormat={modelFormat}
isActive={isActive}
isLoadingThisModel={isLoadingThisModel}
diff --git a/studio/frontend/src/features/hub/catalog/model-inspector.tsx b/studio/frontend/src/features/hub/catalog/model-inspector.tsx
index 5dddb7e3ee2..c9c5c41ffb5 100644
--- a/studio/frontend/src/features/hub/catalog/model-inspector.tsx
+++ b/studio/frontend/src/features/hub/catalog/model-inspector.tsx
@@ -708,6 +708,7 @@ export const ModelInspector = memo(function ModelInspector({
repoId={model.isLocal ? (model.hubRepoId ?? model.id) : model.id}
isGguf={model.isGguf}
{...downloadState}
+ companionPrefetch={model.companionPrefetch === true}
modelFormat={model.modelFormat}
isActive={isActive}
activeQuant={isActive ? (activeGgufVariant ?? null) : null}
diff --git a/studio/frontend/src/features/hub/catalog/models-catalog-rows.tsx b/studio/frontend/src/features/hub/catalog/models-catalog-rows.tsx
index 930c109e6b9..178291159a8 100644
--- a/studio/frontend/src/features/hub/catalog/models-catalog-rows.tsx
+++ b/studio/frontend/src/features/hub/catalog/models-catalog-rows.tsx
@@ -621,16 +621,17 @@ export const InventoryRow = memo(function InventoryRow({
? row.repoId
: null;
const canDelete = cacheDeletableRepoId !== null;
- const partialRepoId = row.partial
- ? row.kind === "cache"
- ? row.repoId
- : (row.repoId ?? row.loadId)
- : undefined;
+ const partialRepoId =
+ row.partial && !row.companionPrefetch
+ ? row.kind === "cache"
+ ? row.repoId
+ : (row.repoId ?? row.loadId)
+ : undefined;
const downloading = Boolean(partialRepoId && row.downloading);
const tooltip = buildRowStatusTooltip({
isGguf: showFormatDot && row.isGguf,
isAdapter: showFormatDot && row.modelFormat === "adapter",
- isAvailableOnDevice: !partialRepoId,
+ isAvailableOnDevice: !row.partial,
partialRepoId,
downloading,
unsupported,
@@ -686,7 +687,7 @@ export const InventoryRow = memo(function InventoryRow({
)}
{partialRepoId ? (
<PartialStatusDot downloading={downloading} />
- ) : (
+ ) : row.companionPrefetch ? null : (
<StatusDot tone="success" label="On device" />
)}
{unsupported && (
diff --git a/studio/frontend/src/features/hub/catalog/safetensors-download-card.tsx b/studio/frontend/src/features/hub/catalog/safetensors-download-card.tsx
index 6cb0ca2a629..2f4abe6ee69 100644
--- a/studio/frontend/src/features/hub/catalog/safetensors-download-card.tsx
+++ b/studio/frontend/src/features/hub/catalog/safetensors-download-card.tsx
@@ -51,6 +51,7 @@ export function SafetensorsDownloadCard({
isPartial = false,
partialTransport = null,
partialResumable = false,
+ companionPrefetch = false,
modelFormat,
isActive,
isLoadingThisModel,
@@ -65,6 +66,7 @@ export function SafetensorsDownloadCard({
isPartial?: boolean;
partialTransport?: string | null;
partialResumable?: boolean;
+ companionPrefetch?: boolean;
modelFormat?: ModelInventoryFormat | null;
isActive: boolean;
isLoadingThisModel: boolean;
@@ -165,8 +167,9 @@ export function SafetensorsDownloadCard({
!cancelling &&
!downloadAction.starting &&
!isLoadingThisModel;
+ const hasCachedFiles = isDownloaded || isPartial || companionPrefetch;
const canDelete =
- (isDownloaded || isPartial) &&
+ hasCachedFiles &&
!downloading &&
!repoPeerActive &&
!isActive &&
@@ -243,7 +246,8 @@ export function SafetensorsDownloadCard({
<div className="ml-auto flex items-center gap-0.5">
{/* Same 3-dots menu as GGUF, at repo level (no quant); pinning is
omitted here. Managed HF-cache repos only. */}
- {(isDownloaded || (isPartial && !downloading)) &&
+ {(isDownloaded ||
+ ((isPartial || companionPrefetch) && !downloading)) &&
!/^([/\\~.]|[A-Za-z]:)/.test(repoId) && (
<QuantOptionsMenu
repoId={repoId}
diff --git a/studio/frontend/src/features/hub/hooks/use-selected-model-view.ts b/studio/frontend/src/features/hub/hooks/use-selected-model-view.ts
index 32f59753af4..c0a38d12732 100644
--- a/studio/frontend/src/features/hub/hooks/use-selected-model-view.ts
+++ b/studio/frontend/src/features/hub/hooks/use-selected-model-view.ts
@@ -86,7 +86,10 @@ export function useSelectedModelView({
baseModelHubId: selectedDiscoverRow.result.baseModel ?? null,
isDownloaded: !selectedLocalRow.partial,
runtimeCanChat: selectedLocalRow.capabilities.canChat,
- isPartial: selectedLocalRow.partial ?? false,
+ isPartial:
+ Boolean(selectedLocalRow.partial) &&
+ !selectedLocalRow.companionPrefetch,
+ companionPrefetch: selectedLocalRow.companionPrefetch === true,
partialTransport: selectedLocalRow.partialTransport ?? null,
partialResumable: selectedLocalRow.partialResumable === true,
capabilities: selectedDiscoverRow.capabilities,
@@ -111,9 +114,11 @@ export function useSelectedModelView({
const onDevicePath =
selectedCachedRow?.cachePath ?? selectedLocalRow?.path ?? null;
const isResolvedPartial = selectedCachedRow
- ? Boolean(selectedCachedRow.partial)
+ ? Boolean(selectedCachedRow.partial) &&
+ !selectedCachedRow.companionPrefetch
: selectedLocalRow?.source === "hf_cache"
- ? Boolean(selectedLocalRow.partial)
+ ? Boolean(selectedLocalRow.partial) &&
+ !selectedLocalRow.companionPrefetch
: selectedDiscoverRow.isPartialOnDevice;
const isResolvedOnDevice = selectedCachedRow
? !selectedCachedRow.partial
@@ -162,6 +167,10 @@ export function useSelectedModelView({
selectedLocalRow?.capabilities.canChat ??
false,
isPartial: isResolvedPartial,
+ companionPrefetch: selectedCachedRow
+ ? selectedCachedRow.companionPrefetch === true
+ : selectedLocalRow?.source === "hf_cache" &&
+ selectedLocalRow.companionPrefetch === true,
partialTransport:
selectedCachedRow?.partialTransport ??
selectedLocalRow?.partialTransport ??
@@ -233,7 +242,10 @@ export function useSelectedModelView({
baseModelHubId: mergedBaseModel,
isDownloaded: !selectedCachedRow.partial,
runtimeCanChat: selectedCachedRow.capabilities.canChat,
- isPartial: selectedCachedRow.partial ?? false,
+ isPartial:
+ Boolean(selectedCachedRow.partial) &&
+ !selectedCachedRow.companionPrefetch,
+ companionPrefetch: selectedCachedRow.companionPrefetch === true,
partialTransport: selectedCachedRow.partialTransport ?? null,
partialResumable: selectedCachedRow.partialResumable === true,
capabilities: detectViewCapabilities(
@@ -270,6 +282,7 @@ export function useSelectedModelView({
selectedLocalRow.source === "hf_cache" &&
!!selectedLocalRow.partial &&
!!selectedLocalRow.repoId;
+ const isCompanionPrefetch = selectedLocalRow.companionPrefetch === true;
const mergedTags = selectedHfResult?.tags ?? selectedLocalRow.tags;
const mergedPipelineTag =
selectedHfResult?.pipelineTag ??
@@ -300,7 +313,9 @@ export function useSelectedModelView({
title: selectedLocalRow.title,
summary: selectedHfResult
? buildSummary(selectedHfResult)
- : "Partial download. Finish it from the card below, or delete it to free space.",
+ : isCompanionPrefetch
+ ? "Holds only the files a GGUF borrowed. Download the full model from the card below."
+ : "Partial download. Finish it from the card below, or delete it to free space.",
sourceLabel: "Hub cache",
path: selectedLocalRow.path,
isLocal: false,
@@ -309,7 +324,8 @@ export function useSelectedModelView({
modelFormat: selectedLocalRow.modelFormat,
isDownloaded: false,
runtimeCanChat: selectedLocalRow.capabilities.canChat,
- isPartial: true,
+ isPartial: !isCompanionPrefetch,
+ companionPrefetch: isCompanionPrefetch,
partialTransport: selectedLocalRow.partialTransport ?? null,
partialResumable: selectedLocalRow.partialResumable === true,
capabilities: detectViewCapabilities(
diff --git a/studio/frontend/src/features/hub/hub-page.tsx b/studio/frontend/src/features/hub/hub-page.tsx
index f909f4e8091..205b116f23f 100644
--- a/studio/frontend/src/features/hub/hub-page.tsx
+++ b/studio/frontend/src/features/hub/hub-page.tsx
@@ -114,6 +114,7 @@ import { studioPageForTask } from "./lib/unsloth-support";
import {
buildDiscoverRows,
detectResultFormat,
+ discoveryInventorySignature,
isUnslothFinetunable,
matchesCapability,
matchesFormat,
@@ -236,24 +237,6 @@ function buildFocusedHeading({
return isDataset ? "Datasets" : "Models";
}
-function discoveryInventorySignature(
- cachedRows: readonly CachedInventoryRow[],
- localRows: readonly LocalInventoryRow[],
-): string {
- const parts: string[] = [];
- for (const row of cachedRows) {
- parts.push(
- `c:${row.repoId.toLowerCase()}:${row.modelFormat}:${row.partial ? (row.downloading ? "d" : "p") : "c"}`,
- );
- }
- for (const row of localRows) {
- parts.push(
- `l:${(row.repoId ?? row.id).toLowerCase()}:${row.modelFormat}:${row.partial ? (row.downloading ? "d" : "p") : "c"}`,
- );
- }
- return parts.sort().join("|");
-}
-
function readModelsTabPreference(): ModelsTab | null {
if (typeof window === "undefined") {
return null;
diff --git a/studio/frontend/src/features/hub/inventory/api.ts b/studio/frontend/src/features/hub/inventory/api.ts
index 0d5e3cf3404..178a779d953 100644
--- a/studio/frontend/src/features/hub/inventory/api.ts
+++ b/studio/frontend/src/features/hub/inventory/api.ts
@@ -118,6 +118,8 @@ export interface LocalModelInfo {
partial_transport?: string | null;
/** This partial can be continued byte for byte. */
partial_resumable?: boolean;
+ /** Pipeline repo holding only a GGUF load's VAE / text encoder: not a download to continue. */
+ companion_prefetch?: boolean;
pipeline_tag?: string | null;
task?: string | null;
audio_type?: string | null;
diff --git a/studio/frontend/src/features/hub/inventory/types.ts b/studio/frontend/src/features/hub/inventory/types.ts
index 904682bb20f..efc9cd7ead0 100644
--- a/studio/frontend/src/features/hub/inventory/types.ts
+++ b/studio/frontend/src/features/hub/inventory/types.ts
@@ -60,6 +60,8 @@ export interface CachedInventoryRow {
// sd.cpp companion mirror: VAE / text encoders with no denoiser. Still listed, because these
// run to tens of GB and the row is how they are seen and deleted, but never a pick.
companion?: boolean;
+ // Holds only a GGUF load's VAE / text encoder: partial for loading, not a download to continue.
+ companionPrefetch?: boolean;
tags?: string[];
libraryName?: string | null;
quantMethod?: string | null;
@@ -98,6 +100,7 @@ export interface LocalInventoryRow {
/** This partial can be continued byte for byte. */
partialResumable?: boolean;
downloading?: boolean;
+ companionPrefetch?: boolean;
activeCache?: boolean | null;
pipelineTag?: string | null;
tags?: string[];
diff --git a/studio/frontend/src/features/hub/inventory/use-hub-inventory.ts b/studio/frontend/src/features/hub/inventory/use-hub-inventory.ts
index c8095221378..34f59ee4914 100644
--- a/studio/frontend/src/features/hub/inventory/use-hub-inventory.ts
+++ b/studio/frontend/src/features/hub/inventory/use-hub-inventory.ts
@@ -609,16 +609,21 @@ export function useHubInventory(
const availableSet = useMemo(() => {
const set = new Set<string>();
- for (const row of cachedRows) set.add(row.repoId.toLowerCase());
+ for (const row of cachedRows) {
+ if (!row.companionPrefetch) set.add(row.repoId.toLowerCase());
+ }
for (const row of effectiveLocalRows) {
- if (row.repoId) set.add(row.repoId.toLowerCase());
+ if (row.repoId && !row.companionPrefetch) set.add(row.repoId.toLowerCase());
}
return set;
}, [cachedRows, effectiveLocalRows]);
const partialSet = useMemo(() => {
return partialSetFromRows(
- [...cachedRows, ...effectiveLocalRows],
+ [
+ ...cachedRows.filter((row) => !row.companionPrefetch),
+ ...effectiveLocalRows.filter((row) => !row.companionPrefetch),
+ ],
(row) => row.repoId,
);
}, [cachedRows, effectiveLocalRows]);
diff --git a/studio/frontend/src/features/hub/inventory/view-models.ts b/studio/frontend/src/features/hub/inventory/view-models.ts
index 34d82ba49d7..dfdbd707224 100644
--- a/studio/frontend/src/features/hub/inventory/view-models.ts
+++ b/studio/frontend/src/features/hub/inventory/view-models.ts
@@ -163,6 +163,7 @@ export function buildCachedInventoryRow(
audio_type?: string | null;
single_file?: boolean;
companion?: boolean;
+ companion_prefetch?: boolean;
tags?: string[];
library_name?: string | null;
quant_method?: string | null;
@@ -220,6 +221,7 @@ export function buildCachedInventoryRow(
audioType: row.audio_type ?? null,
singleFile: row.single_file ?? false,
companion: row.companion ?? false,
+ companionPrefetch: row.companion_prefetch ?? false,
tags: row.tags,
libraryName: row.library_name ?? null,
quantMethod: row.quant_method ?? null,
@@ -298,6 +300,7 @@ export function buildLocalInventoryRows(
partial: model.partial ?? false,
partialTransport: model.partial_transport ?? null,
partialResumable: model.partial_resumable === true,
+ companionPrefetch: model.companion_prefetch === true,
activeCache: model.active_cache ?? null,
pipelineTag: model.pipeline_tag ?? null,
task: model.task ?? null,
diff --git a/studio/frontend/src/features/hub/lib/view-models.ts b/studio/frontend/src/features/hub/lib/view-models.ts
index cdd815af0c2..90662121817 100644
--- a/studio/frontend/src/features/hub/lib/view-models.ts
+++ b/studio/frontend/src/features/hub/lib/view-models.ts
@@ -190,6 +190,37 @@ export function toHfModelResult(raw: unknown): HfModelResult | null {
};
}
+// Must cover every row field buildDiscoverRows reads, or the memoised Discover grid goes stale.
+export function discoveryInventorySignature(
+ cachedRows: readonly CachedInventoryRow[],
+ localRows: readonly LocalInventoryRow[],
+): string {
+ const state = (row: {
+ partial?: boolean;
+ downloading?: boolean;
+ companionPrefetch?: boolean;
+ }) =>
+ row.companionPrefetch
+ ? "x"
+ : row.partial
+ ? row.downloading
+ ? "d"
+ : "p"
+ : "c";
+ const parts: string[] = [];
+ for (const row of cachedRows) {
+ parts.push(
+ `c:${row.repoId.toLowerCase()}:${row.modelFormat}:${state(row)}`,
+ );
+ }
+ for (const row of localRows) {
+ parts.push(
+ `l:${(row.repoId ?? row.id).toLowerCase()}:${row.modelFormat}:${state(row)}`,
+ );
+ }
+ return parts.sort().join("|");
+}
+
export function buildDiscoverRows(
results: HfModelResult[],
cachedRows: CachedInventoryRow[],
@@ -202,9 +233,14 @@ export function buildDiscoverRows(
localRows,
formatHint: result.isGguf ? "gguf" : "non-gguf",
});
- const partial = Boolean(
- resource.cachedRow?.partial ?? resource.localRow?.partial ?? false,
- );
+ const companionPrefetch =
+ (resource.cachedRow?.companionPrefetch ??
+ resource.localRow?.companionPrefetch) === true;
+ const partial =
+ !companionPrefetch &&
+ Boolean(
+ resource.cachedRow?.partial ?? resource.localRow?.partial ?? false,
+ );
const downloading =
partial &&
Boolean(
@@ -215,7 +251,8 @@ export function buildDiscoverRows(
owner: ownerOf(result.id),
repo: repoOf(result.id),
result,
- isAvailableOnDevice: Boolean(resource.cachedRow || resource.localRow),
+ isAvailableOnDevice:
+ !companionPrefetch && Boolean(resource.cachedRow || resource.localRow),
isPartialOnDevice: partial,
isDownloadingOnDevice: downloading,
summary: buildSummary(result),
diff --git a/studio/frontend/src/features/hub/types.ts b/studio/frontend/src/features/hub/types.ts
index 24bfec51959..ac20f096c86 100644
--- a/studio/frontend/src/features/hub/types.ts
+++ b/studio/frontend/src/features/hub/types.ts
@@ -66,6 +66,8 @@ export interface SelectedModelView {
isPartial?: boolean;
partialTransport?: string | null;
partialResumable?: boolean;
+ /** Holds only a GGUF load's borrowed companions: deletable, but neither on device nor partial. */
+ companionPrefetch?: boolean;
capabilities: Capability[];
license: string | null;
pipelineTag?: string;
diff --git a/studio/frontend/tests/hub-companion-prefetch.test.ts b/studio/frontend/tests/hub-companion-prefetch.test.ts
new file mode 100644
index 00000000000..5884a7df03e
--- /dev/null
+++ b/studio/frontend/tests/hub-companion-prefetch.test.ts
@@ -0,0 +1,176 @@
+// 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 { readSrc, registerStoreStubResolver } from "./helpers/kit.ts";
+
+registerStoreStubResolver();
+
+const { buildCachedInventoryRow, buildLocalInventoryRows } =
+ await import("../src/features/hub/inventory/view-models.ts");
+const { buildDiscoverRows, discoveryInventorySignature } =
+ await import("../src/features/hub/lib/view-models.ts");
+
+const REPO_ID = "Qwen/Qwen-Image-2.1";
+const RESULT = { id: REPO_ID, downloads: 1, likes: 1, isGguf: false };
+
+function localRow(companionPrefetch: boolean) {
+ return buildLocalInventoryRows([
+ {
+ id: REPO_ID,
+ display_name: "Qwen-Image-2.1",
+ path: "/cache/models--Qwen--Qwen-Image-2.1/snapshots/abc",
+ source: "hf_cache",
+ model_id: REPO_ID,
+ model_format: "unknown",
+ partial: true,
+ companion_prefetch: companionPrefetch,
+ },
+ ]);
+}
+
+test("a companion-only base repo is neither on device nor partial in model Discover", () => {
+ // The cached and the local listing both describe it; either one carrying the flag is enough.
+ const fromCached = buildDiscoverRows(
+ [RESULT],
+ [
+ buildCachedInventoryRow(
+ {
+ repo_id: REPO_ID,
+ model_format: "safetensors",
+ size_bytes: 1_350_989_512,
+ partial: true,
+ companion_prefetch: true,
+ },
+ "safetensors",
+ ),
+ ],
+ [],
+ );
+ const fromLocal = buildDiscoverRows([RESULT], [], localRow(true));
+ for (const [row] of [fromCached, fromLocal]) {
+ assert.equal(row.isAvailableOnDevice, false);
+ assert.equal(row.isPartialOnDevice, false);
+ }
+});
+
+test("an interrupted download of the same repo still reads as partial", () => {
+ const [row] = buildDiscoverRows([RESULT], [], localRow(false));
+ assert.equal(row.isAvailableOnDevice, true);
+ assert.equal(row.isPartialOnDevice, true);
+});
+
+test("the local listing's flag reaches the local inventory row", () => {
+ assert.equal(localRow(true)[0].companionPrefetch, true);
+ assert.equal(localRow(false)[0].companionPrefetch, false);
+});
+
+test("the detail pane offers a plain Download, never Run, for a companion-only repo", async () => {
+ const { useSelectedModelView } =
+ await import("../src/features/hub/hooks/use-selected-model-view.ts");
+ const { modelDownloadState } =
+ await import("../src/features/hub/catalog/model-download-state.ts");
+ const { downloadActionLabel } =
+ await import("../src/features/hub/catalog/use-download-card-state.ts");
+ const { createElement } = await import("react");
+ const { renderToStaticMarkup } = await import("react-dom/server");
+
+ const [local] = localRow(true);
+ const cached = buildCachedInventoryRow(
+ {
+ repo_id: REPO_ID,
+ model_format: "safetensors",
+ size_bytes: 1_350_989_512,
+ partial: true,
+ companion_prefetch: true,
+ },
+ "safetensors",
+ );
+ const [discover] = buildDiscoverRows([RESULT], [cached], [local]);
+ const base = {
+ selectedDiscoverRow: null,
+ selectedCachedRow: null,
+ selectedLocalRow: null,
+ selectedHfResult: null,
+ isDatasetMode: false,
+ };
+ const cases = {
+ "local row": { ...base, selectedLocalRow: local },
+ "cached row": { ...base, selectedCachedRow: cached },
+ "discover row over the local row": {
+ ...base,
+ selectedDiscoverRow: discover,
+ selectedLocalRow: local,
+ },
+ "discover row over the cached row": {
+ ...base,
+ selectedDiscoverRow: discover,
+ selectedCachedRow: cached,
+ },
+ };
+ for (const [name, input] of Object.entries(cases)) {
+ let view: ReturnType<typeof useSelectedModelView> = null;
+ function Harness() {
+ view = useSelectedModelView(input);
+ return null;
+ }
+ renderToStaticMarkup(createElement(Harness));
+ assert.ok(view, name);
+ const state = modelDownloadState(view);
+ assert.equal(state.isDownloaded, false, name);
+ assert.equal(state.isPartial, false, name);
+ assert.equal(
+ (view as { companionPrefetch?: boolean } | null)?.companionPrefetch,
+ true,
+ name,
+ );
+ assert.equal(
+ downloadActionLabel(state.isPartial, state.partialResumable),
+ "Download",
+ name,
+ );
+ }
+});
+
+test("a companion fetch finishing changes the Discover memo key", () => {
+ // Mid-fetch and finished, both rows are partial; only the flag moves.
+ const fetching = discoveryInventorySignature([], localRow(false));
+ const finished = discoveryInventorySignature([], localRow(true));
+ assert.notEqual(fetching, finished);
+ const cached = (companion_prefetch: boolean) =>
+ buildCachedInventoryRow(
+ {
+ repo_id: REPO_ID,
+ model_format: "safetensors",
+ size_bytes: 1,
+ partial: true,
+ companion_prefetch,
+ },
+ "safetensors",
+ );
+ assert.notEqual(
+ discoveryInventorySignature([cached(false)], []),
+ discoveryInventorySignature([cached(true)], []),
+ );
+});
+
+test("the download card keeps Delete for a companion-only repo", () => {
+ const card = readSrc("features/hub/catalog/safetensors-download-card.tsx");
+ assert.match(card, /hasCachedFiles = isDownloaded \|\| isPartial \|\| companionPrefetch/);
+ assert.match(card, /canDelete =\s+hasCachedFiles &&/);
+ assert.match(card, /\(isPartial \|\| companionPrefetch\) && !downloading/);
+ const section = readSrc("features/hub/catalog/download-section.tsx");
+ assert.match(section, /companionPrefetch=\{companionPrefetch\}/);
+ const inspector = readSrc("features/hub/catalog/model-inspector.tsx");
+ assert.match(inspector, /companionPrefetch=\{model\.companionPrefetch === true\}/);
+});
+
+test("a companion-only inventory row never gets the green On device dot", () => {
+ const rows = readSrc("features/hub/catalog/models-catalog-rows.tsx");
+ assert.match(
+ rows,
+ /<PartialStatusDot downloading=\{downloading\} \/>\s*\) : row\.companionPrefetch \? null : \(\s*<StatusDot tone="success" label="On device" \/>/,
+ );
+});