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: account for resident memory during model reloads (#10627)
Michael Hanab28823880b8
diff --git a/studio/backend/main.py b/studio/backend/main.pyindex f651f8399c3..6fc0ccec1ed 100644--- a/studio/backend/main.py+++ b/studio/backend/main.py@@ -1989,7 +1989,9 @@ async def shutdown_server(request: Request, current_subject: str = Depends(get_creturn {"status": "shutting_down"}-def _get_cached_system_gpu_info(logger) -> tuple[dict[str, Any], dict[str, Any]]:+def _get_cached_system_gpu_info(+ logger, *, refresh_memory: bool = False+) -> tuple[dict[str, Any], dict[str, Any]]:"""Return training and inference GPU info with bounded live-probe churn."""import timefrom utils.hardware import (@@ -2001,7 +2003,7 @@ def _get_cached_system_gpu_info(logger) -> tuple[dict[str, Any], dict[str, Any]]global _system_gpu_cachenow = time.monotonic()with _system_gpu_cache_lock:- if _system_gpu_cache is not None:+ if not refresh_memory and _system_gpu_cache is not None:cached_at, cached_gpu_info = _system_gpu_cacheif now - cached_at < _SYSTEM_GPU_CACHE_TTL_SECONDS:return cached_gpu_info@@ -2127,7 +2129,9 @@ def _get_cached_system_gpu_info(logger) -> tuple[dict[str, Any], dict[str, Any]]@app.get("/api/system")-def get_system_info(current_subject: str = Depends(get_current_subject)):+def get_system_info(+ current_subject: str = Depends(get_current_subject), refresh_memory: bool = False+):"""Get system information.Auth-gated: the response (platform, Python/GPU, memory, ML packages) can@@ -2149,7 +2153,9 @@ def get_system_info(current_subject: str = Depends(get_current_subject)):logger = logging.getLogger(__name__)- gpu_info, inference_gpu_info = _get_cached_system_gpu_info(logger)+ gpu_info, inference_gpu_info = _get_cached_system_gpu_info(+ logger, refresh_memory = refresh_memory+ )memory = psutil.virtual_memory()@@ -2188,6 +2194,7 @@ def get_system_info(current_subject: str = Depends(get_current_subject)):logger.debug(f"Failed to read {pkg} version: {e}")return {+ "memory_refreshed": refresh_memory,"platform": platform.platform(),"python_version": platform.python_version(),"device_backend": _backend_label(get_device()),diff --git a/studio/backend/tests/test_system_vulkan_gpu_info.py b/studio/backend/tests/test_system_vulkan_gpu_info.pyindex 8ca7ed29087..c18c8b54f10 100644--- a/studio/backend/tests/test_system_vulkan_gpu_info.py+++ b/studio/backend/tests/test_system_vulkan_gpu_info.py@@ -64,6 +64,18 @@ def test_system_gpu_info_preserves_vulkan_visibility_metrics(monkeypatch):assert inference_gpu["backend"] == "vulkan"assert inference_gpu["devices"] == [vulkan_device]+ fresh_device = {**vulkan_device, "vram_free_gb": 3.0}+ monkeypatch.setattr(+ hardware,+ "get_vulkan_inference_gpu_info",+ lambda: {**inference_gpu, "devices": [fresh_device]},+ )+ logger = SimpleNamespace(debug = lambda *args: None)+ assert main._get_cached_system_gpu_info(logger)[1]["devices"] == [vulkan_device]+ refreshed = main._get_cached_system_gpu_info(logger, refresh_memory = True)+ assert refreshed[1]["devices"] == [fresh_device]+ assert main._get_cached_system_gpu_info(logger) is refreshed+def test_system_gpu_info_withholds_gguf_pin_when_the_vulkan_probe_enumerates_nothing(monkeypatch):"""A Vulkan build whose probe returns no ordinals has nothing valid to pin,diff --git a/studio/frontend/src/features/chat/lib/apply-inference-status-to-store.ts b/studio/frontend/src/features/chat/lib/apply-inference-status-to-store.tsindex 02a85cb84c1..1135d0db7d4 100644--- a/studio/frontend/src/features/chat/lib/apply-inference-status-to-store.ts+++ b/studio/frontend/src/features/chat/lib/apply-inference-status-to-store.ts@@ -425,34 +425,44 @@ export function applyActiveModelStatusToStore(specFallbackReason: status.spec_fallback_reason ?? null,mmprojFallbackReason: status.mmproj_fallback_reason ?? null,specDrafterKind: status.spec_drafter_kind ?? null,- // The spec / KV seeds share the GPU-fields reseed below: a non-GGUF status leaves their- // baselines null so the "unseeded" guard re-fires every refresh -- hold them too while a- // staged pick is being edited. hydratingExistingModel reopens every seed, since after an- // auto-switch the old model's baselines are stale.+ // Controls follow the server while clean; loaded baselines always describe+ // the settled resident, including same-model reloads from another client....(seedLoadParams &&- (prevState.loadedSpeculativeType === null || hydratingExistingModel) && {- speculativeType: currentSpecType,+ (status.speculative_type !== undefined ||+ prevState.loadedSpeculativeType === null ||+ hydratingExistingModel) && {loadedSpeculativeType: currentSpecType,+ ...((prevState.loadedSpeculativeType === null ||+ hydratingExistingModel ||+ prevState.speculativeType === prevState.loadedSpeculativeType) && {+ speculativeType: currentSpecType,+ }),}),...(seedLoadParams &&- status.spec_draft_n_max !== undefined &&- (hydratingExistingModel ||- (prevState.loadedSpecDraftNMax === null &&- prevState.specDraftNMax === null)) && {- specDraftNMax: status.spec_draft_n_max ?? null,+ status.spec_draft_n_max !== undefined && {loadedSpecDraftNMax: status.spec_draft_n_max ?? null,+ ...((hydratingExistingModel ||+ prevState.specDraftNMax === prevState.loadedSpecDraftNMax) && {+ specDraftNMax: status.spec_draft_n_max ?? null,+ }),}),...(seedLoadParams &&- status.cache_type_kv !== undefined &&- (prevState.loadedKvCacheDtype === null || hydratingExistingModel) && {- kvCacheDtype: status.cache_type_kv,+ status.cache_type_kv !== undefined && {loadedKvCacheDtype: status.cache_type_kv,+ ...((prevState.loadedKvCacheDtype === null ||+ hydratingExistingModel ||+ prevState.kvCacheDtype === prevState.loadedKvCacheDtype) && {+ kvCacheDtype: status.cache_type_kv,+ }),}),...(seedLoadParams &&- status.tensor_parallel !== undefined &&- (prevState.loadedTensorParallel === null || hydratingExistingModel) && {- tensorParallel: status.tensor_parallel,+ status.tensor_parallel !== undefined && {loadedTensorParallel: status.tensor_parallel,+ ...((prevState.loadedTensorParallel === null ||+ hydratingExistingModel ||+ prevState.tensorParallel === prevState.loadedTensorParallel) && {+ tensorParallel: status.tensor_parallel,+ }),}),// A load knob like tensorParallel above. Without a reseed a tab that never performed the// load shows Vision ON over a projector-off server and the next Reload puts it back.@@ -518,10 +528,10 @@ export function applyActiveModelStatusToStore(}),// Baseline only, never the control: the echo is the RESOLVED count and would pin a blank// "server default" control. The rollback re-sends the baseline, so without this a rollback- // after a tab reload loses the override.+ // after a tab reload loses the override. Refresh on every echo: another client+ // can reload the same model with a different count....(seedLoadParams &&- status.requested_parallel_slots != null &&- (prevState.loadedNParallel === null || hydratingExistingModel) && {+ status.requested_parallel_slots != null && {loadedNParallel: status.requested_parallel_slots,}),// A slotless model must not keep the previous GGUF's baseline, since the rollback re-sendsdiff --git a/studio/frontend/src/features/model-picker/components/memory-estimate-row.tsx b/studio/frontend/src/features/model-picker/components/memory-estimate-row.tsxnew file mode 100644index 00000000000..701f8e7d1cc--- /dev/null+++ b/studio/frontend/src/features/model-picker/components/memory-estimate-row.tsx@@ -0,0 +1,315 @@+// 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 { ChevronDown } from "lucide-react";+import { useId, useLayoutEffect, useMemo, useRef, useState } from "react";+import {+ Tooltip,+ TooltipContent,+ TooltipTrigger,+} from "@/components/ui/tooltip";+import type { MemoryEstimate } from "../api/memory-estimate";+import {+ type MemoryFitVerdict,+ formatMemoryGb,+ glueNoteItems,+ memoryFigureCandidates,+ resolveDraftCacheNote,+ resolveKvNote,+ resolveMemoryFit,+} from "../model-config/memory-fit";++const MEMORY_VALUE_TONE: Record<MemoryFitVerdict, string> = {+ fits: "text-nav-fg",+ tight: "text-amber-500",+ exceeds: "text-red-500",+ unknown: "text-nav-fg",+};++/** Match the size and type of the surrounding numeric controls. */+function MemoryFigure({+ label,+ bytes,+ bounded,+ tone,+}: {+ label: string;+ bytes: number;+ bounded: boolean;+ tone?: string;+}) {+ const candidates = useMemo(+ () => memoryFigureCandidates(bytes, bounded),+ [bytes, bounded],+ );+ const value = candidates[0];+ const [displayIndex, setDisplayIndex] = useState(0);+ const buttonRef = useRef<HTMLButtonElement>(null);+ const measureRef = useRef<HTMLSpanElement>(null);+ useLayoutEffect(() => {+ const button = buttonRef.current;+ const measurement = measureRef.current;+ if (!button || !measurement) return;+ let active = true;+ const fit = () => {+ if (!active) return;+ const style = getComputedStyle(button);+ const width =+ button.clientWidth -+ Number.parseFloat(style.paddingLeft) -+ Number.parseFloat(style.paddingRight);+ const index = Array.from(measurement.children).findIndex(+ (child) => child.getBoundingClientRect().width <= width,+ );+ setDisplayIndex(index < 0 ? candidates.length - 1 : index);+ };+ fit();+ const observer = new ResizeObserver(fit);+ observer.observe(button);+ observer.observe(measurement);+ void document.fonts.ready.then(fit);+ return () => {+ active = false;+ observer.disconnect();+ };+ }, [candidates]);+ return (+ <div className="flex min-h-8 min-w-0 items-center justify-between gap-3">+ <span className="min-w-0 text-ui-13 font-medium leading-[1.25] tracking-nav text-muted-foreground">+ {label}+ </span>+ <Tooltip>+ <TooltipTrigger asChild>+ <button+ ref={buttonRef}+ type="button"+ aria-label={`${label}: ${value}`}+ className={`relative inline-flex h-8 w-[80px] shrink-0 cursor-default! items-center justify-center overflow-hidden rounded-full border-transparent bg-black/[0.04] px-2 text-ui-13 font-medium tabular-nums focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/60 dark:bg-white/[0.05] ${tone ?? "text-nav-fg"}`}+ >+ <span aria-hidden="true" className="min-w-0 truncate">+ {candidates[displayIndex] ?? value}+ </span>+ <span+ ref={measureRef}+ aria-hidden="true"+ className="pointer-events-none invisible absolute left-0 top-0 flex w-max flex-col items-start whitespace-nowrap"+ >+ {candidates.map((candidate) => (+ <span key={candidate}>{candidate}</span>+ ))}+ </span>+ </button>+ </TooltipTrigger>+ <TooltipContent>{value}</TooltipContent>+ </Tooltip>+ </div>+ );+}++function MemoryBreakdownLine({+ label,+ value,+ note,+ muted,+}: {+ label: string;+ value: string;+ note?: string;+ muted?: boolean;+}) {+ return (+ <div className="grid grid-cols-[minmax(0,1fr)_auto] items-baseline gap-x-4 gap-y-1">+ <span className="min-w-0 text-ui-12 text-muted-foreground">{label}</span>+ <span+ className={`whitespace-nowrap pr-2 text-ui-12 tabular-nums ${muted ? "text-muted-foreground" : "text-nav-fg"}`}+ >+ {value}+ </span>+ {note ? (+ <span className="col-span-2 min-w-0 text-ui-11 leading-relaxed text-muted-foreground/80">+ {glueNoteItems(note)}+ </span>+ ) : null}+ </div>+ );+}++/** Show the loader's estimate and an optional breakdown for the requested settings. */+export function MemoryEstimateRow({+ estimate,+ loading,+ stale,+ gpuCapacityGb,+ totalCapacityGb,+ systemRamCapacityGb,+ freeGpuCapacityGb,+ freeGpuCapacityKnown,+ freeGpuReserveDeficitGb,+ usableSystemRamGb,+ usableSystemRamKnown,+ systemRamReserveDeficitGb,+ isUnifiedMemory,+ singleMemoryPool,+ reclaimableTotalBytes,+ reclaimableGpuBytes,+ expanded,+ onExpandedChange,+}: {+ estimate: MemoryEstimate | null;+ loading: boolean;+ stale: boolean;+ /** GPU or shared capacity in GiB; 0 means unknown. */+ gpuCapacityGb: number;+ /** Combined capacity in GiB; 0 means unknown. */+ totalCapacityGb: number;+ /** Host RAM capacity in GiB. */+ systemRamCapacityGb: number;+ /** Free GPU memory in GiB; warnings only, since replacement can free memory. */+ freeGpuCapacityGb: number;+ freeGpuCapacityKnown?: boolean;+ freeGpuReserveDeficitGb?: number;+ /** Available host RAM minus the loader reserve, in GiB. */+ usableSystemRamGb: number;+ usableSystemRamKnown?: boolean;+ systemRamReserveDeficitGb?: number;+ isUnifiedMemory: boolean;+ /** Whether GPU and CPU share one memory pool. */+ singleMemoryPool: boolean;+ /** What the resident copy of this model hands back when it is unloaded for the reload. */+ reclaimableTotalBytes?: number;+ reclaimableGpuBytes?: number;+ expanded: boolean;+ onExpandedChange: (next: boolean) => void;+}) {+ const contentId = useId();+ if (!estimate?.available) {+ // Hide unavailable estimates without flickering during loading.+ return null;+ }+ const { gpuFit, totalFit, cpuOnly, bounded, advisory } = resolveMemoryFit(+ estimate,+ {+ gpuCapacityGb,+ totalCapacityGb,+ systemRamCapacityGb,+ freeGpuCapacityGb,+ freeGpuCapacityKnown,+ freeGpuReserveDeficitGb,+ usableSystemRamGb,+ usableSystemRamKnown,+ systemRamReserveDeficitGb,+ singleMemoryPool,+ reclaimableTotalBytes,+ reclaimableGpuBytes,+ },+ );+ const kvNote = resolveKvNote(estimate);+ const draftCacheNote = resolveDraftCacheNote(+ estimate.drafterRuntimeGpuBytes,+ estimate.drafterRuntimeBytes,+ );+ return (+ <div className="flex flex-col border-b border-border/60 pb-3.5">+ <button+ type="button"+ onClick={() => onExpandedChange(!expanded)}+ aria-expanded={expanded}+ aria-controls={contentId}+ aria-label={`Estimated Memory Usage: ${expanded ? "Hide" : "Show"} breakdown`}+ className="group flex min-h-7 w-full items-center justify-between gap-3 rounded-md text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/60 focus-visible:ring-offset-2 focus-visible:ring-offset-background"+ >+ <span className="flex min-w-0 items-center gap-2">+ <span className="min-w-0 text-ui-13 font-medium leading-[1.25] tracking-nav text-nav-fg">+ Estimated Memory Usage+ </span>+ <span className="shrink-0 rounded-md bg-black/[0.04] px-1.5 py-0.5 text-ui-10 font-medium uppercase tracking-wide text-muted-foreground dark:bg-white/[0.06]">+ Beta+ </span>+ </span>+ <ChevronDown+ aria-hidden="true"+ className={`size-3.5 shrink-0 text-muted-foreground transition-transform duration-200 group-hover:text-nav-fg motion-reduce:transition-none ${expanded ? "rotate-0" : "-rotate-90"}`}+ />+ </button>+ <div+ aria-busy={loading || stale}+ className={`space-y-3 transition-opacity ${stale || loading ? "opacity-50" : ""}`}+ >+ {/* A shared pool uses the total, regardless of CPU offloading. */}+ <MemoryFigure+ label={+ cpuOnly+ ? "RAM"+ : singleMemoryPool+ ? isUnifiedMemory+ ? "Unified"+ : "Shared"+ : "GPU"+ }+ bytes={+ singleMemoryPool || cpuOnly+ ? estimate.totalBytes+ : estimate.gpuBytes+ }+ bounded={bounded}+ tone={+ MEMORY_VALUE_TONE[singleMemoryPool || cpuOnly ? totalFit : gpuFit]+ }+ />+ {singleMemoryPool || cpuOnly ? null : (+ <MemoryFigure+ label="Total"+ bytes={estimate.totalBytes}+ bounded={bounded}+ tone={MEMORY_VALUE_TONE[totalFit]}+ />+ )}+ </div>+ <div id={contentId} hidden={!expanded} className="mt-3 space-y-3">+ <MemoryBreakdownLine+ label="Weights"+ value={formatMemoryGb(estimate.weightsBytes)}+ note={+ estimate.gpuLayers != null && estimate.layerCount != null+ ? `${estimate.gpuLayers} of ${estimate.layerCount + 1} layers on GPU`+ : undefined+ }+ />+ <MemoryBreakdownLine+ label="KV cache"+ value={+ estimate.kvEstimable ? formatMemoryGb(estimate.kvBytes) : "unknown"+ }+ note={estimate.kvEstimable ? kvNote : undefined}+ muted={!estimate.kvEstimable}+ />+ <MemoryBreakdownLine+ label="Compute buffers"+ value={formatMemoryGb(estimate.computeBytes)}+ />+ {/* Projector weights are already included above. */}+ {estimate.projectorRuntimeBytes > 0 && (+ <MemoryBreakdownLine+ label="Vision encoder"+ value={formatMemoryGb(estimate.projectorRuntimeBytes)}+ />+ )}+ {/* Draft cache is additional to the drafter's weights. */}+ {estimate.drafterRuntimeBytes > 0 && (+ <MemoryBreakdownLine+ label="Draft cache"+ value={formatMemoryGb(estimate.drafterRuntimeBytes)}+ note={draftCacheNote}+ />+ )}+ </div>+ {advisory && (+ <p+ className={`mt-1.5 text-pretty text-ui-12 leading-relaxed ${advisory.tone === "warn" ? "text-amber-700 dark:text-amber-400" : "text-muted-foreground"}`}+ >+ {advisory.text}+ </p>+ )}+ </div>+ );+}diff --git a/studio/frontend/src/features/model-picker/components/model-config-page.tsx b/studio/frontend/src/features/model-picker/components/model-config-page.tsxindex 9a52c3f5e61..974d97e582f 100644--- a/studio/frontend/src/features/model-picker/components/model-config-page.tsx+++ b/studio/frontend/src/features/model-picker/components/model-config-page.tsx@@ -48,11 +48,11 @@ import {import {DEFAULT_VRAM_FRACTION,aggregateUsableFreeVramGb,+ aggregateVramReserveDeficitGb,resolveMemoryCapacityGb,} from "@/hooks/gpu-vram";import { ChevronDownStandardIcon } from "@/lib/chevron-icons";import { toast } from "@/lib/toast";-import { HugeiconsIcon } from "@hugeicons/react";import {type ReactNode,type Ref,@@ -63,6 +63,7 @@ import {useState,useSyncExternalStore,} from "react";+import { useShallow } from "zustand/react/shallow";import {type ModelMemorySettings,loadModelMemorySettings,@@ -74,16 +75,12 @@ import {loadManagedLlamaFlags,subscribeLlamaFlagCatalog,} from "../api/llama-flags";-import { type MemoryEstimate } from "../api/memory-estimate";import { resolveEstimateContext } from "../model-config/estimate-context";+import { resolveReclaimableMemoryCredit } from "../model-config/memory-fit";import {- type MemoryFitVerdict,- formatMemoryGb,- glueNoteItems,- resolveDraftCacheNote,- resolveKvNote,- resolveMemoryFit,-} from "../model-config/memory-fit";+ resolveResidentEstimateRequest,+ selectResidentEstimateSettings,+} from "../model-config/resident-memory-request";import { useMemoryEstimate } from "../hooks/use-memory-estimate";import {fetchLoadModelOverride,@@ -149,6 +146,7 @@ import {vramPercentToFraction,} from "../model-config/per-model-config";import { ChatTemplateEditorDialog } from "./chat-template-editor-dialog";+import { MemoryEstimateRow } from "./memory-estimate-row";import type { ModelPickTarget } from "./model-selector/types";import {NumericValueInput,@@ -165,7 +163,7 @@ const LABEL_CLASS_WRAP ="min-w-0 text-ui-13 font-medium leading-[1.25] tracking-nav text-nav-fg";const CONTROL_SURFACE ="rounded-full border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.1]";-const SELECT_TRIGGER_CLASS = `grid h-8 min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-1 ${CONTROL_SURFACE} pl-3 pr-2 py-0 text-ui-13! font-medium text-nav-fg focus-visible:ring-0 focus-visible:border-transparent [&_[data-slot=select-value]]:min-w-0 [&_[data-slot=select-value]]:truncate [&>svg]:shrink-0`;+const SELECT_TRIGGER_CLASS = `grid h-8! min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-1 ${CONTROL_SURFACE} pl-3 pr-2 py-0 text-ui-13! font-medium text-nav-fg focus-visible:ring-0 focus-visible:border-transparent [&_[data-slot=select-value]]:min-w-0 [&_[data-slot=select-value]]:truncate [&>svg]:shrink-0`;const NUMBER_INPUT_CLASS = `h-8 w-[92px] ${CONTROL_SURFACE} pl-3 pr-2 py-0 text-right text-ui-13 font-medium text-nav-fg outline-none focus-visible:ring-0`;// Mirrors the backend's Auto default once GPU-only placement is impossible.@@ -908,223 +906,6 @@ function AdvancedSettingsToggle({);}-const MEMORY_VALUE_TONE: Record<MemoryFitVerdict, string> = {- fits: "text-nav-fg",- tight: "text-amber-500",- exceeds: "text-red-500",- unknown: "text-nav-fg",-};--/** One "GPU 29.41 GB" pill: dim caption, figure on the shared control surface. */-function MemoryFigure({- label,- value,- tone,-}: {- label: string;- value: string;- tone?: string;-}) {- return (- <div className="flex shrink-0 items-center gap-1.5">- <span className="text-ui-11 font-medium leading-none tracking-nav text-muted-foreground">- {label}- </span>- <span- className={`inline-flex h-6 items-center ${CONTROL_SURFACE} px-2 text-ui-12 font-medium tabular-nums ${tone ?? "text-nav-fg"}`}- >- {value}- </span>- </div>- );-}--function MemoryBreakdownLine({- label,- value,- note,- muted,-}: {- label: string;- value: string;- note?: string;- muted?: boolean;-}) {- return (- <div className="flex items-baseline justify-between gap-3">- <span className="min-w-0 text-ui-11 leading-relaxed text-muted-foreground">- {label}- {note ? (- <span className="ml-1 text-muted-foreground/70">{glueNoteItems(note)}</span>- ) : null}- </span>- <span- className={`shrink-0 text-ui-11 tabular-nums ${muted ? "text-muted-foreground" : "text-nav-fg"}`}- >- {value}- </span>- </div>- );-}--/** "Estimated Memory Usage": what the settings above would cost, before they are run. Figures- * come from the loader's own sizing, not a weights-times-a-constant rule of thumb, so KV- * gets its own line and an unsizable header quotes a floor instead of a confident total. */-function MemoryEstimateRow({- estimate,- loading,- stale,- gpuCapacityGb,- totalCapacityGb,- systemRamCapacityGb,- freeGpuCapacityGb,- usableSystemRamGb,- isUnifiedMemory,- singleMemoryPool,- expanded,- onExpandedChange,-}: {- estimate: MemoryEstimate | null;- loading: boolean;- stale: boolean;- /** VRAM available, or the shared pool where there is only one. 0 when unknown. */- gpuCapacityGb: number;- /** GPU plus host RAM, the ceiling an offloaded load works against. 0 when unknown. */- totalCapacityGb: number;- /** Host RAM alone. The bytes a load pins OUTSIDE the GPU have to fit in this, and unused VRAM cannot help them. */- systemRamCapacityGb: number;- /** VRAM free on the usable cards right now. Warns only: see the note at the call site. 0 when nothing was probed. */- freeGpuCapacityGb: number;- /** Host RAM the machine can hand out right now, less the reserve the loader keeps. Warns only,- * for the same reason. 0 when unknown. */- usableSystemRamGb: number;- isUnifiedMemory: boolean;- /** GPU and host draw on the same memory, so an offloaded byte is not a freed one. */- singleMemoryPool: boolean;- expanded: boolean;- onExpandedChange: (next: boolean) => void;-}) {- const contentId = useId();- if (!estimate?.available) {- // Nothing honest to show. Silent while loading too, so the row does not flicker.- return null;- }- // Every verdict and the one advisory paragraph, resolved in ../model-config/memory-fit. Kept- // out of this file so the node test runner can reach it: while it lived here an arm that- // could never be taken shipped unnoticed.- const { gpuFit, totalFit, prefix, advisory } = resolveMemoryFit(estimate, {- gpuCapacityGb,- totalCapacityGb,- systemRamCapacityGb,- freeGpuCapacityGb,- usableSystemRamGb,- singleMemoryPool,- });- const kvNote = resolveKvNote(estimate);- const draftCacheNote = resolveDraftCacheNote(- estimate.drafterRuntimeGpuBytes,- estimate.drafterRuntimeBytes,- );- return (- <div className="space-y-2">- {/* Wraps, unlike the other rows, because this is the only header carrying a title AND two- figures: under a ~460px window the title absorbed the whole shortfall and truncated to- "E..." at 320px. The panel is w-[min(468px,...)], so it shrinks with the viewport while- the figures do not. Letting them drop to their own line is identical above that. */}- <div className={`${ROW_CLASS} flex-wrap gap-y-1`}>- <button- type="button"- onClick={() => onExpandedChange(!expanded)}- aria-expanded={expanded}- aria-controls={contentId}- className="flex min-w-0 items-center gap-1.5 rounded-sm text-left focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"- >- <span className={LABEL_CLASS}>Estimated Memory Usage</span>- <span className="shrink-0 rounded-full bg-black/[0.06] px-1.5 py-px text-ui-10 font-medium uppercase leading-[1.4] tracking-wider text-muted-foreground dark:bg-white/[0.08]">- Beta- </span>- <HugeiconsIcon- icon={ChevronDownStandardIcon}- className={`size-3 shrink-0 text-muted-foreground transition-transform ${expanded ? "rotate-180" : ""}`}- strokeWidth={1.75}- />- </button>- {/* ml-auto so that on the wrapped line, where justify-between has nothing to push against, the- figures still sit under the right edge they had. */}- <div- className={`ml-auto flex shrink-0 items-center gap-3 transition-opacity ${stale || loading ? "opacity-50" : ""}`}- >- {/* One pool: offloading a layer moves it within the same memory rather than out of it, so the- honest single figure is the total. The GPU share let a zero-layer load read as free. */}- <MemoryFigure- label={singleMemoryPool ? (isUnifiedMemory ? "Unified" : "Shared") : "GPU"}- value={`${prefix}${formatMemoryGb(- singleMemoryPool ? estimate.totalBytes : estimate.gpuBytes,- )}`}- tone={MEMORY_VALUE_TONE[singleMemoryPool ? totalFit : gpuFit]}- />- {singleMemoryPool ? null : (- <MemoryFigure- label="Total"- value={`${prefix}${formatMemoryGb(estimate.totalBytes)}`}- tone={MEMORY_VALUE_TONE[totalFit]}- />- )}- </div>- </div>- {expanded && (- <div id={contentId} className="space-y-1 pl-0.5">- <MemoryBreakdownLine- label="Weights"- value={formatMemoryGb(estimate.weightsBytes)}- note={- estimate.gpuLayers != null && estimate.layerCount != null- ? `${estimate.gpuLayers} of ${estimate.layerCount + 1} layers on GPU`- : undefined- }- />- <MemoryBreakdownLine- label="KV cache"- value={- estimate.kvEstimable ? formatMemoryGb(estimate.kvBytes) : "unknown"- }- note={estimate.kvEstimable ? kvNote : undefined}- muted={!estimate.kvEstimable}- />- <MemoryBreakdownLine- label="Compute buffers"- value={formatMemoryGb(estimate.computeBytes)}- />- {/* The encoder's buffers, about 1.3x the projector file. Only on a vision load, and named- separately since the file is already in Weights. */}- {estimate.projectorRuntimeBytes > 0 && (- <MemoryBreakdownLine- label="Vision encoder"- value={formatMemoryGb(estimate.projectorRuntimeBytes)}- />- )}- {/* Only when speculation loads a separate drafter, and it is the term most likely to surprise:- its cache grows with context like the target's. */}- {estimate.drafterRuntimeBytes > 0 && (- <MemoryBreakdownLine- label="Draft cache"- value={formatMemoryGb(estimate.drafterRuntimeBytes)}- note={draftCacheNote}- />- )}- </div>- )}- {advisory && (- <p- className={`text-ui-11 leading-relaxed ${advisory.tone === "warn" ? "text-amber-500" : "text-muted-foreground"}`}- >- {advisory.text}- </p>- )}- </div>- );-}-function MlxAdvancedSettings({config,update,@@ -1980,6 +1761,13 @@ export function ModelConfigPage({const loadedChatTemplateOverride = useChatRuntimeStore((s) => s.loadedChatTemplateOverride,);+ const loadedLlamaExtraArgs = useChatRuntimeStore((s) => s.loadedLlamaExtraArgs);+ const loadedGpuIds = useChatRuntimeStore((s) => s.loadedGpuIds);+ const loadedGpuIndexKind = useChatRuntimeStore((s) => s.loadedGpuIndexKind);+ const loadedCpuFallback = useChatRuntimeStore((s) => s.loadedCpuFallback);+ const residentEstimateSettings = useChatRuntimeStore(+ useShallow(selectResidentEstimateSettings),+ );const mlxKvQuantNote = useChatRuntimeStore((s) => s.mlxKvQuantNote);const loadedMlxKvBitsRequested = useChatRuntimeStore((s) => s.loadedMlxKvBitsRequested,@@ -2720,6 +2508,43 @@ export function ModelConfigPage({}: null;const memoryEstimate = useMemoryEstimate(memoryEstimateRequest);+ // No resident credit without a reported context; pending settings cannot price it.+ const residentContext = servedWindow(activeLoadedContext);+ const residentEstimateRequest = resolveResidentEstimateRequest(+ isActiveModel ? memoryEstimateRequest : null,+ residentEstimateSettings,+ residentContext,+ );+ const residentEstimate = useMemoryEstimate(residentEstimateRequest, {+ refreshMemory: true,+ });+ // Only settled estimates can establish resident credit.+ const reclaimableEstimate =+ residentEstimateRequest &&+ residentEstimate.estimate?.available &&+ !residentEstimate.loading &&+ !residentEstimate.stale+ ? residentEstimate.estimate+ : null;+ const reclaimableCredit = resolveReclaimableMemoryCredit(+ reclaimableEstimate,+ { ids: loadedGpuIds, indexKind: loadedGpuIndexKind },+ {+ ids: runtimeConfig.selectedGpuIds ?? null,+ indexKind: runtimeConfig.selectedGpuIndexKind ?? null,+ },+ {+ cpuFallback: loadedCpuFallback,+ devices: gpuDevices,+ // Fitted placement does not report its final layer count.+ gpuPlacementKnown:+ residentEstimateRequest?.gpuMemoryMode === "manual" &&+ residentEstimateRequest.gpuLayers != null &&+ residentEstimateRequest.gpuLayers >= 0 &&+ !loadedLlamaExtraArgs?.length,+ appleUnifiedMemory: isAppleUnifiedMemory,+ },+ );const [memoryBreakdownOpen, setMemoryBreakdownOpen] = useState(false);const inferenceGpu = useInferenceGpuInfo();// A pin can only draw on the cards it names, so the verdict is measured against those: judging@@ -2786,7 +2611,15 @@ export function ModelConfigPage({0,(inferenceGpu.systemRamAvailableHostGb || 0) - 2,);- const memoryFreeGpuCapacityGb = useMemo(() => {+ const memorySystemRamReserveDeficitGb = Math.max(+ 0,+ 2 - (inferenceGpu.systemRamAvailableHostGb || 0),+ );+ const {+ gb: memoryFreeGpuCapacityGb,+ known: memoryFreeGpuCapacityKnown,+ reserveDeficitGb: memoryFreeGpuReserveDeficitGb,+ } = useMemo(() => {const pinned =pinnedGpuIds && pinnedGpuIds.length > 0? gpuDevices.filter((device) => pinnedGpuIds.includes(device.index))@@ -2799,6 +2632,9 @@ export function ModelConfigPage({pinned,memoryEffectiveBudgetFraction,);+ const freeVramKnown =+ pinned.length > 0 &&+ pinned.every((device) => device.memoryFreeKnown === true);// On a ROCm APU this figure is the free space inside a BIOS-carved window, and resolveMemoryFit// asks it the WHOLE-LOAD question as soon as the pool is single, so together they warned// that a 60 GiB load does not fit a 96 GiB machine with 60+ GiB free. The pool's real free@@ -2806,9 +2642,25 @@ export function ModelConfigPage({// Those two together warned that a 60 GiB load does not fit a 96 GiB machine with 60+ GiB free,// purely because it exceeds a 48 GiB window.if (hasUnifiedMemory && !isAppleUnifiedMemory) {- return Math.max(freeVram, memoryUsableSystemRamGb);+ return {+ gb: inferenceGpu.systemRamAvailableKnown ? memoryUsableSystemRamGb : 0,+ known: inferenceGpu.systemRamAvailableKnown === true,+ reserveDeficitGb: memorySystemRamReserveDeficitGb,+ };}- return freeVram;+ const residentDevices = loadedGpuIds?.length+ ? pinned.filter((device) =>+ device.indexKind === loadedGpuIndexKind &&+ loadedGpuIds.includes(device.index))+ : pinned;+ return {+ gb: freeVram,+ known: freeVramKnown,+ reserveDeficitGb: aggregateVramReserveDeficitGb(+ residentDevices,+ memoryEffectiveBudgetFraction,+ ),+ };}, [gpuDevices,pinnedGpuIds,@@ -2816,6 +2668,10 @@ export function ModelConfigPage({hasUnifiedMemory,isAppleUnifiedMemory,memoryUsableSystemRamGb,+ memorySystemRamReserveDeficitGb,+ inferenceGpu.systemRamAvailableKnown,+ loadedGpuIds,+ loadedGpuIndexKind,]);const {gpuCapacityGb: memoryGpuCapacityGb,@@ -3065,9 +2921,15 @@ export function ModelConfigPage({totalCapacityGb={memoryTotalCapacityGb}systemRamCapacityGb={inferenceGpu.systemRamTotalGb}freeGpuCapacityGb={memoryFreeGpuCapacityGb}+ freeGpuCapacityKnown={memoryFreeGpuCapacityKnown}+ freeGpuReserveDeficitGb={memoryFreeGpuReserveDeficitGb}usableSystemRamGb={memoryUsableSystemRamGb}+ usableSystemRamKnown={inferenceGpu.systemRamAvailableKnown}+ systemRamReserveDeficitGb={memorySystemRamReserveDeficitGb}isUnifiedMemory={isAppleUnifiedMemory}singleMemoryPool={singleMemoryPool}+ reclaimableTotalBytes={reclaimableCredit.totalBytes}+ reclaimableGpuBytes={reclaimableCredit.gpuBytes}expanded={memoryBreakdownOpen}onExpandedChange={setMemoryBreakdownOpen}/>diff --git a/studio/frontend/src/features/model-picker/hooks/use-memory-estimate.ts b/studio/frontend/src/features/model-picker/hooks/use-memory-estimate.tsindex 8b35ad5b01e..0d7e8486557 100644--- a/studio/frontend/src/features/model-picker/hooks/use-memory-estimate.ts+++ b/studio/frontend/src/features/model-picker/hooks/use-memory-estimate.ts@@ -2,6 +2,7 @@// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0import { useEffect, useRef, useState } from "react";+import { fetchSystemInfo } from "@/hooks/use-system";import {type MemoryEstimate,type MemoryEstimateRequest,@@ -57,6 +58,7 @@ function estimateKey(request: MemoryEstimateRequest | null): string | null {* cannot overwrite a newer one. */export function useMemoryEstimate(request: MemoryEstimateRequest | null,+ { refreshMemory = false }: { refreshMemory?: boolean } = {},): MemoryEstimateState {const key = estimateKey(request);// Computed during render, not read from a ref the effect updates after paint: the effect below@@ -71,11 +73,15 @@ export function useMemoryEstimate(tokenIdentity(request.hfToken),request.nativePathToken,);- const [state, setState] = useState<MemoryEstimateState & { identity: string | null }>({+ const [state, setState] = useState<MemoryEstimateState & {+ identity: string | null;+ probeKey: string | null;+ }>({estimate: null,loading: false,stale: false,identity: null,+ probeKey: null,});// Read inside the effect so it depends on the key alone: `request` is a fresh object every// render and would restart the debounce on any keystroke.@@ -90,7 +96,7 @@ export function useMemoryEstimate(const pending = latestRequest.current;if (key == null || pending == null) {shownModel.current = null;- setState({ estimate: null, loading: false, stale: false, identity: null });+ setState({ estimate: null, loading: false, stale: false, identity: null, probeKey: null });return;}const identity = resolveEstimateSourceIdentity(@@ -102,33 +108,42 @@ export function useMemoryEstimate(const modelChanged = shownModel.current !== identity;setState((current) =>modelChanged- ? { estimate: null, loading: true, stale: false, identity }+ ? { estimate: null, loading: true, stale: false, identity, probeKey: null }: { ...current, loading: current.estimate == null, stale: true, identity },);const controller = new AbortController();const timer = setTimeout(() => {fetchMemoryEstimate(pending, controller.signal)- .then((estimate) => {+ .then(async (estimate) => {+ if (controller.signal.aborted) return;+ if (refreshMemory && estimate.available) {+ const probe = await fetchSystemInfo({ refreshMemory: true });+ if (!probe?.memory_refreshed) throw new Error("Memory probe unavailable");+ }if (controller.signal.aborted) return;shownModel.current = identity;- setState({ estimate, loading: false, stale: false, identity });+ setState({ estimate, loading: false, stale: false, identity, probeKey: refreshMemory ? key : null });}).catch(() => {if (controller.signal.aborted) return;// A failed estimate is not a failed panel; drop the row.shownModel.current = identity;- setState({ estimate: null, loading: false, stale: false, identity });+ setState({ estimate: null, loading: false, stale: false, identity, probeKey: null });});}, ESTIMATE_DEBOUNCE_MS);return () => {clearTimeout(timer);controller.abort();};- }, [key]);+ }, [key, refreshMemory]);// State that belongs to a different source is not shown at all, not even for the frame before the effect clears it.if (state.identity !== currentIdentity) {return { estimate: null, loading: currentIdentity != null, stale: false };}- return { estimate: state.estimate, loading: state.loading, stale: state.stale };+ return {+ estimate: state.estimate,+ loading: state.loading,+ stale: state.stale || (refreshMemory && state.probeKey !== key),+ };}diff --git a/studio/frontend/src/features/model-picker/model-config/memory-fit.ts b/studio/frontend/src/features/model-picker/model-config/memory-fit.tsindex 90bf449d72d..6c874ee011f 100644--- a/studio/frontend/src/features/model-picker/model-config/memory-fit.ts+++ b/studio/frontend/src/features/model-picker/model-config/memory-fit.ts@@ -17,9 +17,17 @@ export {} from "../../../lib/memory/verdict.ts";export { MEMORY_FIT_TIGHT_RATIO } from "../../../lib/memory/thresholds.ts";-import { classifyMemoryFit, worseMemoryFit } from "../../../lib/memory/verdict.ts";+import {+ classifyMemoryFit,+ worseMemoryFit,+} from "../../../lib/memory/verdict.ts";import type { MemoryFitVerdict } from "../../../lib/memory/verdict.ts";import { formatBytesGiB } from "../../../lib/memory/format.ts";+import type {+ ReconciledGpuSelection,+ SystemGpuDevice,+} from "../../../hooks/gpu-selection.ts";+import { gpuMemoryTotalsGb, sharesHostMemory } from "../../../hooks/gpu-vram.ts";/** A memory figure in bytes, to two decimals. @deprecated Prefer `formatBytesGiB` from* `@/lib/memory/format`, whose name says which unit it takes. This alias exists because a@@ -28,6 +36,26 @@ import { formatBytesGiB } from "../../../lib/memory/format.ts";* every figure was a gibibyte labelled as a gigabyte, overstating each by 7.4% (#9570). */export const formatMemoryGb = formatBytesGiB;+/** Progressively shorter labels; compact lower bounds round down. */+export function memoryFigureCandidates(+ bytes: number,+ bounded: boolean,+): string[] {+ const safe = Number.isFinite(bytes) && bytes > 0 ? bytes : 0;+ const prefix = bounded ? "≥ " : "";+ const candidates: string[] = bounded ? [] : [formatMemoryGb(safe)];+ for (const [index, unit] of ["GiB", "TiB", "PiB", "EiB"].entries()) {+ const amount = safe / 1024 ** (index + 3);+ if (index > 0 && amount < 1) break;+ for (const decimals of [2, 1, 0]) {+ const factor = 10 ** decimals;+ const rounded = bounded ? Math.floor(amount * factor) / factor : amount;+ candidates.push(`${prefix}${rounded.toFixed(decimals)} ${unit}`);+ }+ }+ return [...new Set(candidates)];+}+/** At most one note under the figures, most actionable first. */export interface MemoryAdvisory {/** `warn` is amber; `muted` is body text. */@@ -59,20 +87,128 @@ export interface MemoryFitCapacity {/** Host RAM alone. Bytes pinned OUTSIDE the GPU have to fit in this, and unused VRAM cannot* help them, so it is a separate question from the total. */systemRamCapacityGb: number;- /** VRAM free on the usable cards right now. Warns only. 0 when nothing was probed. */+ /** VRAM free on the usable cards right now. Warns only. */freeGpuCapacityGb: number;- /** Host RAM the machine can hand out right now, less the loader's reserve. Warns only. 0 when unknown. */+ /** Distinguishes an exhausted GPU budget from an unknown reading. */+ freeGpuCapacityKnown?: boolean;+ /** Reserve hidden by clamping the current usable VRAM to zero. */+ freeGpuReserveDeficitGb?: number;+ /** Available host RAM after the loader's reserve. Warns only. */usableSystemRamGb: number;+ /** Distinguishes exhausted RAM from an unknown reading. */+ usableSystemRamKnown?: boolean;+ /** Host reserve hidden by clamping current usable RAM to zero. */+ systemRamReserveDeficitGb?: number;/** GPU and host draw on the same memory, so an offloaded byte is not a freed one. */singleMemoryPool: boolean;+ /** Resident bytes returned to the requested pools on unload. Free-memory verdicts only. */+ reclaimableTotalBytes?: number;+ /** The GPU share of the above. */+ reclaimableGpuBytes?: number;+}++/** Ignore invalid or negative credits. */+function reclaimableBytes(value: number | undefined): number {+ return Number.isFinite(value) && (value as number) > 0 ? (value as number) : 0;+}++/** Keep known host credit; require modelled placement in the requested pool for VRAM. */+export function resolveReclaimableMemoryCredit(+ estimate:+ | (Pick<MemoryFitEstimate, "totalBytes" | "gpuBytes"> & {+ weightsBytes: number;+ moeOffloadUnmodelled?: boolean;+ })+ | null,+ residentPool: ReconciledGpuSelection,+ requestedPool: ReconciledGpuSelection,+ {+ cpuFallback = false,+ devices = [],+ gpuPlacementKnown = false,+ appleUnifiedMemory = false,+ }: {+ cpuFallback?: boolean;+ devices?: SystemGpuDevice[];+ gpuPlacementKnown?: boolean;+ appleUnifiedMemory?: boolean;+ } = {},+): { totalBytes: number; gpuBytes: number } {+ const total = reclaimableBytes(estimate?.totalBytes);+ const gpu = Math.min(reclaimableBytes(estimate?.gpuBytes), total);+ if (+ !estimate ||+ !Number.isFinite(estimate.weightsBytes) ||+ estimate.weightsBytes < 0+ )+ return { totalBytes: 0, gpuBytes: 0 };+ const files = Math.min(estimate.weightsBytes, total);+ const includesResidentPool =+ !requestedPool.ids?.length ||+ (residentPool.ids != null &&+ residentPool.ids.length > 0 &&+ residentPool.indexKind != null &&+ residentPool.indexKind === requestedPool.indexKind &&+ residentPool.ids.every((id) => requestedPool.ids!.includes(id)));+ const residentDevices = residentPool.ids?.length+ ? devices.filter(+ (device) =>+ device.indexKind === residentPool.indexKind &&+ residentPool.ids!.includes(device.index),+ )+ : devices;+ const topologyKnown =+ residentDevices.length > 0 &&+ (!residentPool.ids?.length ||+ (residentPool.indexKind != null &&+ residentPool.ids.every((id) =>+ residentDevices.some((device) => device.index === id),+ ))) &&+ residentDevices.every(+ (device) =>+ (sharesHostMemory(device) && device.sharedMemoryHostBackedGb == null) ||+ (Number.isFinite(device.memoryTotalGb) && device.memoryTotalGb > 0),+ );+ const independentGb = appleUnifiedMemory+ ? 0+ : gpuMemoryTotalsGb(+ residentDevices.map((device) => ({+ memory_total_gb: device.memoryTotalGb,+ shared_memory: sharesHostMemory(device),+ shared_memory_host_backed_gb: device.sharedMemoryHostBackedGb,+ })),+ ).dedicated;+ // File-backed pages may already count as available RAM. Their pool split is unknown.+ const gpuMayUseHost =+ appleUnifiedMemory ||+ !topologyKnown ||+ residentDevices.some(sharesHostMemory);+ const gpuCredit =+ includesResidentPool &&+ gpuPlacementKnown &&+ !cpuFallback &&+ !estimate.moeOffloadUnmodelled+ ? Math.max(0, gpu - (gpuMayUseHost ? files : 0))+ : 0;+ // Only bytes beyond all independent capacity are certainly backed by host RAM.+ const sharedHostCredit =+ gpuCredit === 0 && (appleUnifiedMemory || topologyKnown)+ ? Math.max(0, gpu - independentGb * 1024 ** 3 - files)+ : 0;+ return {+ totalBytes: Math.max(0, total - gpu - files) + gpuCredit + sharedHostCredit,+ gpuBytes: gpuCredit,+ };}export interface MemoryFitResult {+ /** The estimate places the entire load in separate system RAM. */+ cpuOnly: boolean;/** The GPU verdict before the free-memory warning is folded in. */rawGpuFit: MemoryFitVerdict;/** What the GPU figure is coloured with: rawGpuFit, nudged to tight under pressure. */gpuFit: MemoryFitVerdict;- /** The pool against what is free right now, capped at a warning by its caller. */+ /** The footprint against post-unload availability, capped at a warning by its caller. */freeGpuFit: MemoryFitVerdict;gpuPressured: boolean;/** Bytes this placement pins outside the GPU. */@@ -100,13 +236,31 @@ export function resolveMemoryFit(capacity: MemoryFitCapacity,): MemoryFitResult {const { singleMemoryPool } = capacity;- const rawGpuFit = classifyMemoryFit(estimate.gpuBytes, capacity.gpuCapacityGb);+ const cpuOnly =+ !singleMemoryPool && estimate.gpuBytes === 0 && estimate.totalBytes > 0;+ const rawGpuFit = classifyMemoryFit(+ estimate.gpuBytes,+ capacity.gpuCapacityGb,+ );+ // Studio unloads the resident model BEFORE the replacement allocates, so its bytes are about to+ // be free rather than competing. Charging them counted a model against ITSELF: reloading an+ // unchanged config warned it would not fit the memory its own resident copy held. Free-memory+ // questions only -- unloading frees memory, it does not add any, so capacity is untouched.+ const reclaimableTotal = reclaimableBytes(capacity.reclaimableTotalBytes);+ // Clamped: a GPU share above its own total would credit the host share a negative amount.+ const reclaimableGpu = Math.min(+ reclaimableBytes(capacity.reclaimableGpuBytes),+ reclaimableTotal,+ );// One pool means the WHOLE load draws on that memory, so the pressure question goes to the// total rather than a GPU share that is not a separate reservation. Asking it of gpuBytes// alone let a partly CPU-offloaded load on a Vulkan iGPU look comfortable.- const freeGpuFit = classifyMemoryFit(+ const freeGpuFit = classifyAvailableMemory(singleMemoryPool ? estimate.totalBytes : estimate.gpuBytes,capacity.freeGpuCapacityGb,+ capacity.freeGpuCapacityKnown,+ singleMemoryPool ? reclaimableTotal : reclaimableGpu,+ capacity.freeGpuReserveDeficitGb,);const gpuPressured = freeGpuFit === "exceeds" || freeGpuFit === "tight";// Guarded, not subtracted blind: a non-finite figure makes the difference NaN, which@@ -115,12 +269,16 @@ export function resolveMemoryFit(Number.isFinite(estimate.totalBytes) && Number.isFinite(estimate.gpuBytes)? Math.max(0, estimate.totalBytes - estimate.gpuBytes): 0;- // Same question for the other pool. See the note above on why this warns.- const usableHostFit = classifyMemoryFit(+ // Same question for the other pool, with the same credit. See the two notes above.+ const usableHostFit = classifyAvailableMemory(singleMemoryPool ? estimate.totalBytes : hostShareBytes,capacity.usableSystemRamGb,+ capacity.usableSystemRamKnown,+ singleMemoryPool ? reclaimableTotal : reclaimableTotal - reclaimableGpu,+ capacity.systemRamReserveDeficitGb,);- const hostPressured = usableHostFit === "exceeds" || usableHostFit === "tight";+ const hostPressured =+ usableHostFit === "exceeds" || usableHostFit === "tight";const gpuFit = rawGpuFit === "fits" && gpuPressured ? "tight" : rawGpuFit;// The host share must fit host RAM on its own: unused VRAM cannot hold bytes pinned outside// the GPU, so the combined ceiling alone called a 70 GB CPU placement a fit on a 24 GB card@@ -128,16 +286,20 @@ export function resolveMemoryFit(const hostShareFit: MemoryFitVerdict = singleMemoryPool? "unknown": classifyMemoryFit(hostShareBytes, capacity.systemRamCapacityGb);- const totalFit = worseMemoryFit(- classifyMemoryFit(estimate.totalBytes, capacity.totalCapacityGb),- hostShareFit,+ const combinedFit = classifyMemoryFit(+ estimate.totalBytes,+ capacity.totalCapacityGb,);+ const totalFit = worseMemoryFit(combinedFit, hostShareFit);// Lower bound, not an estimate. Both routes here UNDER-count by a term that grows with// context: no attention dims, so the target cache is missing, or a drafter that is a// repository rather than a file, so its cache is missing while its weights are counted.const bounded =- !estimate.kvEstimable || estimate.drafterKvUnsized || estimate.adaptersUnsized;+ !estimate.kvEstimable ||+ estimate.drafterKvUnsized ||+ estimate.adaptersUnsized;return {+ cpuOnly,rawGpuFit,gpuFit,freeGpuFit,@@ -150,8 +312,10 @@ export function resolveMemoryFit(bounded,prefix: bounded ? "≥ " : "",advisory: resolveMemoryAdvisory(estimate, {+ cpuOnly,singleMemoryPool,totalFit,+ combinedFit,hostShareFit,gpuFit,rawGpuFit,@@ -162,8 +326,10 @@ export function resolveMemoryFit(}interface AdvisoryVerdicts {+ cpuOnly?: boolean;singleMemoryPool: boolean;totalFit: MemoryFitVerdict;+ combinedFit: MemoryFitVerdict;hostShareFit: MemoryFitVerdict;gpuFit: MemoryFitVerdict;rawGpuFit: MemoryFitVerdict;@@ -171,6 +337,30 @@ interface AdvisoryVerdicts {hostPressured: boolean;}+function classifyAvailableMemory(+ bytes: number,+ availableGb: number,+ known = false,+ reclaimedBytes = 0,+ reserveDeficitGb = 0,+): MemoryFitVerdict {+ if (+ !Number.isFinite(availableGb) ||+ availableGb < 0 ||+ (availableGb === 0 && !known)+ ) {+ return "unknown";+ }+ // Pressure is a fraction of post-unload availability, not just allocation growth.+ const afterUnloadGb = availableGb + Math.max(+ 0,+ reclaimedBytes / 1024 ** 3 - reclaimableBytes(reserveDeficitGb),+ );+ if (known && afterUnloadGb === 0 && Number.isFinite(bytes) && bytes > 0)+ return "exceeds";+ return classifyMemoryFit(bytes, afterUnloadGb);+}+/** At most one note, most actionable first. An unsizable cache outranks any verdict drawn from* the figures, since it says they are incomplete. Branches on `kvEstimable`, not `bounded`:* both make the figures a floor, but only this one is about the header. The pool split used@@ -183,26 +373,47 @@ export function resolveMemoryAdvisory(if (!estimate.kvEstimable) {return {tone: "warn",- text: "This GGUF's header doesn't carry the attention dimensions, so the KV cache can't be sized. The figures above are a floor, and the cache is usually the term that grows fastest with context.",+ text: "KV cache size is unknown: missing attention dimensions. Actual usage will be higher.",};}if (estimate.drafterKvUnsized) {return {tone: "warn",- text: "Part of this load is a file the server will fetch rather than one on this disk, so it can't be sized from here. The figures above are a floor.",+ text: "A remote draft model or vision component is partly unmeasured. Actual usage will be higher.",};}- if (estimate.moeOffloadUnmodelled) {+ if (estimate.adaptersUnsized) {+ return {+ tone: "warn",+ text: "An adapter or control vector is unmeasured. Actual usage will be higher.",+ };+ }+ if (estimate.moeOffloadUnmodelled && !verdicts.cpuOnly) {return {tone: "muted",- text: "Expert layers held on the CPU aren't modelled here, so the GPU figure reads high.",+ text: "Expert layers on the CPU are not reflected here. GPU usage may be lower.",};}+ if (verdicts.cpuOnly) {+ if (verdicts.totalFit === "exceeds") {+ return {+ tone: "warn",+ text: "Exceeds system RAM. Try a shorter context or smaller model.",+ };+ }+ if (verdicts.hostPressured) {+ return {+ tone: "muted",+ text: "Fits system RAM, but little is free right now. Free memory, or try a shorter context or smaller model.",+ };+ }+ return null;+ }if (verdicts.singleMemoryPool) {if (verdicts.totalFit === "exceeds") {return {tone: "warn",- text: "More than this machine's memory. The GPU and the rest of the system share one pool here, so there is nothing to offload to.",+ text: "Exceeds shared memory. Try a shorter context or smaller model; CPU offloading adds no memory.",};}// One pool, so one pressure question however it was measured: the GPU's free reading and the@@ -210,42 +421,52 @@ export function resolveMemoryAdvisory(if (verdicts.hostPressured || verdicts.gpuPressured) {return {tone: "muted",- text: "This fits the machine, but not what is free right now. If that memory is not the model being replaced, the context will be fitted down or the load refused.",+ text: "Fits this machine, but little memory is free right now. Free memory or try Auto context.",};}return null;}- // Discrete memory, so the two verdicts are separate questions and the aggregate one is asked- // FIRST. Reading gpuFit alone offered spilling to system RAM as the remedy for a load that- // does not fit in GPU and RAM combined.- if (verdicts.hostShareFit === "exceeds") {+ // Moving layers cannot fix a combined capacity shortfall.+ if (+ verdicts.combinedFit === "exceeds" ||+ (verdicts.hostShareFit === "exceeds" && verdicts.rawGpuFit === "exceeds")+ ) {return {tone: "warn",- text: "More than system RAM holds. This placement keeps most of the load outside the GPU, and spare VRAM cannot take those bytes.",+ text: "Exceeds combined GPU and system memory. Try a shorter context or smaller model.",};}- if (verdicts.totalFit === "exceeds") {+ if (+ (verdicts.gpuFit === "exceeds" && verdicts.hostPressured) ||+ (verdicts.hostShareFit === "exceeds" && verdicts.gpuPressured)+ ) {+ return {+ tone: "warn",+ text: "GPU and system memory are both under pressure. Try a shorter context or smaller model.",+ };+ }+ if (verdicts.hostShareFit === "exceeds") {return {tone: "warn",- text: "More than this machine holds. The GPU and system RAM together are not enough for this load, so spilling layers or fitting the context down will not recover it.",+ text: "CPU placement exceeds system RAM. Try fewer CPU layers or a smaller model.",};}if (verdicts.gpuFit === "exceeds") {return {tone: "warn",- text: "More than this GPU holds. Layers will spill to system RAM, or the context will be fitted down to what fits.",+ text: "Exceeds GPU memory. Try Auto context or fewer GPU layers; loading may still fail.",};}if (verdicts.hostPressured) {return {tone: "muted",- text: "The part of this load that runs from system RAM fits the machine, but not what is free right now. If that memory is not the model being replaced, the load will be refused.",+ text: "Fits system RAM, but little is free right now. Free memory, or try a shorter context or smaller model.",};}if (verdicts.rawGpuFit === "fits" && verdicts.gpuPressured) {return {tone: "muted",- text: "This fits the card, but something is using it right now. If that memory is not the model being replaced, layers will spill or the context will be fitted down.",+ text: "Fits this GPU, but little VRAM is free right now. Free memory or try Auto context.",};}return null;diff --git a/studio/frontend/src/features/model-picker/model-config/resident-memory-request.ts b/studio/frontend/src/features/model-picker/model-config/resident-memory-request.tsnew file mode 100644index 00000000000..5f66bd46d1d--- /dev/null+++ b/studio/frontend/src/features/model-picker/model-config/resident-memory-request.ts@@ -0,0 +1,90 @@+// 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 { useChatRuntimeStore } from "../../chat/index.ts";+import type { MemoryEstimateRequest } from "../api/memory-estimate.ts";++type ResidentState = Pick<+ ReturnType<typeof useChatRuntimeStore.getState>,+ | "modelLoading"+ | "loadedKvCacheDtype"+ | "loadedNParallel"+ | "loadedNBatch"+ | "loadedNUbatch"+ | "loadedCtxCheckpoints"+ | "loadedSpeculativeType"+ | "loadedSpecDraftNMax"+ | "loadedSpecDraftCacheDtype"+ | "loadedTensorParallel"+ | "loadedDisableVision"+ | "loadedGpuMemoryMode"+ | "loadedGpuLayers"+ | "loadedNCpuMoe"+ | "loadedGpuIds"+ | "loadedLlamaExtraArgs"+ | "loadedCpuFallback"+ | "specFallbackReason"+ | "mmprojFallbackReason"+>;++/** Editable controls can already describe the next load. */+export function selectResidentEstimateSettings(state: ResidentState) {+ if (+ state.modelLoading ||+ state.loadedGpuMemoryMode == null ||+ state.loadedSpeculativeType == null ||+ state.loadedTensorParallel == null ||+ state.loadedDisableVision == null ||+ (state.loadedGpuMemoryMode === "manual" &&+ (state.loadedGpuLayers == null || state.loadedNCpuMoe == null)) ||+ state.loadedCpuFallback ||+ state.specFallbackReason ||+ state.mmprojFallbackReason+ ) {+ return null;+ }+ return {+ cacheTypeKv: state.loadedKvCacheDtype,+ nParallel: state.loadedNParallel,+ nBatch: state.loadedNBatch,+ nUbatch: state.loadedNUbatch,+ ctxCheckpoints: state.loadedCtxCheckpoints,+ speculativeType: state.loadedSpeculativeType,+ specDraftNMax: state.loadedSpecDraftNMax,+ specDraftCacheType: state.loadedSpecDraftCacheDtype,+ tensorParallel: state.loadedTensorParallel,+ disableVision: state.loadedDisableVision,+ gpuMemoryMode: state.loadedGpuMemoryMode,+ gpuLayers:+ state.loadedGpuLayers != null && state.loadedGpuLayers >= 0+ ? state.loadedGpuLayers+ : null,+ nCpuMoe: state.loadedNCpuMoe,+ selectedGpuIds: state.loadedGpuIds,+ llamaExtraArgs: state.loadedLlamaExtraArgs,+ };+}++/** Copy only source identity from the pending request. */+export function resolveResidentEstimateRequest(+ source: MemoryEstimateRequest | null,+ settings: ReturnType<typeof selectResidentEstimateSettings>,+ context: number | null,+): MemoryEstimateRequest | null {+ if (+ !source ||+ !settings ||+ context == null ||+ !Number.isFinite(context) ||+ context <= 0+ )+ return null;+ return {+ modelPath: source.modelPath,+ ggufVariant: source.ggufVariant,+ hfToken: source.hfToken,+ nativePathToken: source.nativePathToken,+ ...settings,+ nCtx: Math.floor(context),+ };+}diff --git a/studio/frontend/src/hooks/gpu-selection.ts b/studio/frontend/src/hooks/gpu-selection.tsindex 2196ff25913..f0fb758ecd9 100644--- a/studio/frontend/src/hooks/gpu-selection.ts+++ b/studio/frontend/src/hooks/gpu-selection.ts@@ -10,6 +10,8 @@ export interface SystemGpuDevice {memoryTotalGb: number;/** Free VRAM at fetch time, or total VRAM when usage is unavailable. */memoryFreeGb: number;+ /** Whether free memory was reported, including a real zero. */+ memoryFreeKnown?: boolean;/** A Vulkan iGPU: memoryTotalGb is a capped view of system RAM rather than a* pool beside it. Per device, not per host: a mixed inventory pairs one of* these with a discrete card, and a pin naming only the discrete card candiff --git a/studio/frontend/src/hooks/gpu-vram.ts b/studio/frontend/src/hooks/gpu-vram.tsindex ef7612cc6c2..362ef6afc6a 100644--- a/studio/frontend/src/hooks/gpu-vram.ts+++ b/studio/frontend/src/hooks/gpu-vram.ts@@ -430,6 +430,42 @@ export interface FreeVramDevice {unifiedMemory?: boolean;}+/** Reserve still unmet before unloading; per-device reclaimed amounts are unknown. */+export function aggregateVramReserveDeficitGb(+ devices: FreeVramDevice[],+ fraction: number,+): number {+ let independent = 0;+ let shared: number | undefined;+ for (const device of devices) {+ const total = device.memoryTotalGb ?? 0;+ const free = device.memoryFreeGb ?? 0;+ if (+ !Number.isFinite(total) ||+ total <= 0 ||+ !Number.isFinite(free) ||+ free < 0+ )+ continue;+ const reserve = total - usableFreeVramGb(total, total, fraction);+ const deficit = Math.max(0, reserve - free);+ const hostBacked = device.sharedMemoryHostBackedGb;+ if (+ sharesHostMemory(device) &&+ (hostBacked == null ||+ !Number.isFinite(hostBacked) ||+ hostBacked < 0 ||+ hostBacked >= total)+ ) {+ // One pool becomes usable as soon as any of its views clears its reserve.+ shared = Math.min(shared ?? deficit, deficit);+ } else {+ independent += deficit;+ }+ }+ return independent + (shared ?? 0);+}+/*** Free memory a prospective load may claim across an inventory, counting a shared* host-memory pool only once.diff --git a/studio/frontend/src/hooks/use-gpu-info.ts b/studio/frontend/src/hooks/use-gpu-info.tsindex afe95c8631d..f90c3f179b7 100644--- a/studio/frontend/src/hooks/use-gpu-info.ts+++ b/studio/frontend/src/hooks/use-gpu-info.ts@@ -70,6 +70,8 @@ export interface GpuInfo {systemRamAvailableGb: number;/** raw host RAM free as the probe reported it. */systemRamAvailableHostGb: number;+ /** Whether host available memory was reported, including a real zero. */+ systemRamAvailableKnown?: boolean;systemRamTotalGb: number;}@@ -92,6 +94,7 @@ const DEFAULT_GPU: GpuInfo = {cpuThread: 0,systemRamAvailableGb: 0,systemRamAvailableHostGb: 0,+ systemRamAvailableKnown: false,systemRamTotalGb: 0,};@@ -107,6 +110,9 @@ function toGpuInfo(cpuThread: data?.cpu?.logical_count ?? 0,systemRamAvailableGb: data?.memory?.available_gb ?? 0,systemRamAvailableHostGb: data?.memory?.available_gb ?? 0,+ systemRamAvailableKnown:+ Number.isFinite(data?.memory?.available_gb) &&+ (data?.memory?.available_gb as number) >= 0,systemRamTotalGb: data?.memory?.total_gb ?? 0,};const gpuData =@@ -191,6 +197,8 @@ function toGpuDevices(name: d.name ?? `GPU ${d.index}`,memoryTotalGb: d.memory_total_gb ?? 0,memoryFreeGb: d.vram_free_gb ?? 0,+ memoryFreeKnown:+ Number.isFinite(d.vram_free_gb) && (d.vram_free_gb as number) >= 0,sharedMemory: d.shared_memory === true,sharedMemoryHostBackedGb: d.shared_memory_host_backed_gb,unifiedMemory: d.unified_memory === true,@@ -219,6 +227,8 @@ function toGpuDevices(name: d.name ?? `GPU ${d.index}`,memoryTotalGb: d.memory_total_gb ?? 0,memoryFreeGb: d.vram_free_gb ?? 0,+ memoryFreeKnown:+ Number.isFinite(d.vram_free_gb) && (d.vram_free_gb as number) >= 0,sharedMemory: d.shared_memory === true,sharedMemoryHostBackedGb: d.shared_memory_host_backed_gb,unifiedMemory: d.unified_memory === true,diff --git a/studio/frontend/src/hooks/use-system.ts b/studio/frontend/src/hooks/use-system.tsindex 50fab8b097a..54074d1093e 100644--- a/studio/frontend/src/hooks/use-system.ts+++ b/studio/frontend/src/hooks/use-system.ts@@ -46,6 +46,8 @@ export interface SystemGpuInfo {export { aggregateGpuMemoryTotalGb } from "./gpu-vram";export interface SystemInfoResponse {+ /** The server bypassed its GPU cache for this snapshot. */+ memory_refreshed?: boolean;/** Client-side, not sent by the backend. Readers rendering a host verdict -- "no GPU",* "CPU only" -- must check it, or they state the placeholder below as fact. */status: SystemInfoStatus;@@ -151,13 +153,21 @@ function scheduleVulkanRetry(): void {export async function fetchSystemInfo({force = false,-}: { force?: boolean } = {}): Promise<SystemInfoResponse | null> {- if (systemFetchPromise) return systemFetchPromise;- if (!force && cachedSystem) return cachedSystem;+ refreshMemory = false,+}: { force?: boolean; refreshMemory?: boolean } = {}): Promise<SystemInfoResponse | null> {+ if (systemFetchPromise) {+ if (!refreshMemory) return systemFetchPromise;+ // An in-flight snapshot may predate the resident model.+ await systemFetchPromise;+ return fetchSystemInfo({ force, refreshMemory });+ }+ if (!force && !refreshMemory && cachedSystem) return cachedSystem;systemFetchPromise = (async () => {try {- const res = await authFetch("/api/system");+ const res = await authFetch(+ refreshMemory ? "/api/system?refresh_memory=true" : "/api/system",+ );if (!res.ok) throw new Error(`HTTP ${res.status}`);const data = await res.json();diff --git a/studio/frontend/tests/memory-estimate-narrow-panel.test.ts b/studio/frontend/tests/memory-estimate-narrow-panel.test.tsindex ef64b93f18d..8027a5f0bb3 100644--- a/studio/frontend/tests/memory-estimate-narrow-panel.test.ts+++ b/studio/frontend/tests/memory-estimate-narrow-panel.test.ts@@ -1,66 +1,165 @@// 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 Estimated Memory Usage header is the only row in the panel carrying a title AND-// two figures, and the panel is w-[min(468px,calc(100vw-1rem))] -- so under a ~460px-// window it shrinks while the figures do not. Measured on the merged build at 320px-// the title had been squeezed from 150px to 11px and rendered as "E...", which is what-// was reported. The layout half is asserted against the source, the idiom-// tensor-parallel-row-gating already uses for markup that cannot be imported; the note-// half is a pure function and is exercised directly.+// Verify the memory row's disclosure markup and wrapping captions.import assert from "node:assert/strict";-import { readFileSync } from "node:fs";-import path from "node:path";import test from "node:test";-import { fileURLToPath } from "node:url";--import {- glueNoteItems,- resolveDraftCacheNote,- resolveKvNote,-} from "../src/features/model-picker/model-config/memory-fit.ts";--const HERE = path.dirname(fileURLToPath(import.meta.url));-const CONFIG_PAGE = readFileSync(- path.join(- HERE,- "..",- "src/features/model-picker/components/model-config-page.tsx",+import { ChevronDown } from "lucide-react";+import * as React from "react";+import * as jsxRuntime from "react/jsx-runtime";+import { renderToStaticMarkup } from "react-dom/server";+import type * as MemoryEstimateModule from "../src/features/model-picker/components/memory-estimate-row.tsx";+import * as memoryFit from "../src/features/model-picker/model-config/memory-fit.ts";+import { loadWithStubs } from "./helpers/module-stubs.ts";++const { glueNoteItems, resolveDraftCacheNote, resolveKvNote } = memoryFit;+const { MemoryEstimateRow } = loadWithStubs<typeof MemoryEstimateModule>(+ new URL(+ "../src/features/model-picker/components/memory-estimate-row.tsx",+ import.meta.url,),- "utf8",+ {+ react: React,+ "react/jsx-runtime": jsxRuntime,+ "lucide-react": { ChevronDown },+ "../model-config/memory-fit": memoryFit,+ "@/components/ui/tooltip": {+ Tooltip: ({ children }: { children: React.ReactNode }) => children,+ TooltipTrigger: ({ children }: { children: React.ReactNode }) => children,+ TooltipContent: () => null,+ },+ },);+type Props = React.ComponentProps<typeof MemoryEstimateRow>;+const GIB = 1024 ** 3;+const props: Props = {+ estimate: {+ available: true,+ reason: null,+ weightsBytes: 3.25 * GIB,+ kvBytes: 1.5 * GIB,+ computeBytes: 0.75 * GIB,+ drafterRuntimeBytes: 0,+ drafterRuntimeGpuBytes: 0,+ projectorRuntimeBytes: 0,+ drafterKvUnsized: false,+ adaptersUnsized: false,+ totalBytes: 5.5 * GIB,+ gpuBytes: 4.75 * GIB,+ kvEstimable: true,+ kvOnGpu: true,+ nCtx: 262144,+ cacheTypeKv: "f16",+ nParallel: 4,+ layerCount: 27,+ gpuLayers: 12,+ moeOffloadUnmodelled: false,+ },+ loading: false,+ stale: false,+ gpuCapacityGb: 24,+ totalCapacityGb: 88,+ systemRamCapacityGb: 64,+ freeGpuCapacityGb: 24,+ usableSystemRamGb: 60,+ isUnifiedMemory: false,+ singleMemoryPool: false,+ expanded: false,+ onExpandedChange: () => {},+};++function render(overrides: Partial<Props> = {}): string {+ return renderToStaticMarkup(+ React.createElement(MemoryEstimateRow, { ...props, ...overrides }),+ );+}+const NBSP = " ";-test("the memory header may wrap, so the figures drop rather than eat the title", () => {- assert.match(CONFIG_PAGE, /\$\{ROW_CLASS\} flex-wrap gap-y-1/);+test("the title and figures occupy separate rows", () => {+ const html = render();+ const button = html.match(/<button\b[^>]*>([\s\S]*?)<\/button>/)?.[1];+ assert.ok(button);+ assert.match(button, /Estimated Memory Usage/);+ assert.doesNotMatch(button, /GiB/);+ assert.match(html, />GPU<\/span>/);+ assert.match(html, />Total<\/span>/);+ assert.match(html, /4\.75 GiB/);+ assert.match(html, /5\.50 GiB/);+});++test("the disclosure controls an existing breakdown in both states", () => {+ for (const expanded of [false, true]) {+ const html = render({ expanded });+ assert.ok(html.includes(`aria-expanded="${expanded}"`));+ const contentId = html.match(/aria-controls="([^"]+)"/)?.[1];+ assert.ok(contentId);+ assert.ok(html.includes(`id="${contentId}"`));+ assert.equal(html.includes(`id="${contentId}" hidden=""`), !expanded);+ assert.match(html, /Weights/);+ assert.match(html, /KV cache/);+ }+});++test("a shared pool shows the total without a duplicate GPU figure", () => {+ const html = render({ singleMemoryPool: true, isUnifiedMemory: true });+ assert.match(html, />Unified<\/span>/);+ assert.match(html, /5\.50 GiB/);+ assert.doesNotMatch(html, />GPU<\/span>|>Total<\/span>|4\.75 GiB/);+});++test("an unavailable estimate stays hidden", () => {+ assert.equal(render({ estimate: null }), "");+ assert.equal(+ render({ estimate: { ...props.estimate!, available: false } }),+ "",+ );+});++test("a RAM-only load shows one figure with CPU-appropriate guidance", () => {+ const html = render({+ estimate: { ...props.estimate!, gpuBytes: 0, gpuLayers: 0, kvOnGpu: false },+ usableSystemRamGb: 2,+ });+ assert.match(html, />RAM<\/span>/);+ assert.match(html, /aria-label="RAM: 5\.50 GiB"/);+ assert.match(html, /Fits system RAM, but little is free right now/);+ assert.doesNotMatch(html, />GPU<\/span>|>Total<\/span>|fewer CPU layers/);});-test("the wrapped figures still sit at the right edge", () => {- // justify-between has nothing to push against on a line holding one item, so- // without this the figures jump to the left margin when they wrap.- assert.match(CONFIG_PAGE, /className=\{`ml-auto flex shrink-0 items-center gap-3/);+test("zero free VRAM keeps the GPU figure and its warning", () => {+ const html = render({ freeGpuCapacityGb: 0, freeGpuCapacityKnown: true });+ assert.match(html, />GPU<\/span>/);+ assert.match(html, />Total<\/span>/);+ assert.match(html, /little VRAM is free right now/);});-test("the header title is still allowed to truncate as a backstop", () => {- // Wrapping is what keeps it whole at the widths that matter; truncation stays for a- // locale whose title does not fit a line of its own. Dropping min-w-0 here would- // overflow the panel instead.+test("memory figures are keyboard targets with the full value as their name", () => {+ const html = render();assert.match(- CONFIG_PAGE,- /className="flex min-w-0 items-center gap-1\.5 rounded-sm text-left/,+ html,+ /<button[^>]*type="button"[^>]*aria-label="GPU: 4\.75 GiB"/,+ );+ assert.match(+ html,+ /<button[^>]*type="button"[^>]*aria-label="Total: 5\.50 GiB"/,);});-test("breakdown notes are rendered glued", () => {- assert.match(CONFIG_PAGE, /\{glueNoteItems\(note\)\}/);+test("breakdown captions preserve word groups", () => {+ assert.ok(+ render({ expanded: true }).includes(+ glueNoteItems("f16 · 262,144 tokens · 4 slots"),+ ),+ );});test("an item's own spaces do not break", () => {const glued = glueNoteItems("f16 · 262,144 tokens · 4 slots");assert.equal(glued, `f16 ·${NBSP}262,144${NBSP}tokens ·${NBSP}4${NBSP}slots`);- // The only ordinary spaces left are the ones a line may break at: one per bullet.+ // One breakable space remains per bullet.assert.equal(glued.split(" ").length - 1, 2);});@@ -71,9 +170,7 @@ test("the bullet leads its item, so a break cannot orphan it", () => {});test("a note with no separator keeps every break opportunity it had", () => {- // Only the KV caption is a list. Weights and Draft cache are ordinary prose, and- // gluing those bought nothing while costing them the ability to wrap at all, so a- // long one ran past the caption column into the value instead of wrapping inside it.+ // Prose captions must still wrap.for (const note of ["256 of 257 layers on GPU","2.14 GB on GPU",@@ -86,8 +183,7 @@ test("a note with no separator keeps every break opportunity it had", () => {});test("the notes the row actually builds are left breakable", () => {- // The two non-list note sources, at their real call sites in model-config-page.- assert.match(CONFIG_PAGE, /layers on GPU`/);+ assert.match(render({ expanded: true }), /12 of 28 layers on GPU/);const hostNote = resolveDraftCacheNote(0, 1e9);assert.equal(hostNote, "host RAM");for (const note of ["256 of 257 layers on GPU", hostNote ?? ""]) {@@ -103,6 +199,6 @@ test("gluing round-trips the note the row actually builds", () => {nParallel: 4,kvOnGpu: false,});- // Same text to a reader, and to anyone grepping the panel: only the spaces differ.+ // Only whitespace changes.assert.equal(glueNoteItems(note).replace(new RegExp(NBSP, "g"), " "), note);});diff --git a/studio/frontend/tests/memory-fit.test.ts b/studio/frontend/tests/memory-fit.test.tsindex ba43f1d0500..293f320382d 100644--- a/studio/frontend/tests/memory-fit.test.ts+++ b/studio/frontend/tests/memory-fit.test.ts@@ -17,6 +17,7 @@ import {type MemoryFitVerdict,classifyMemoryFit,formatMemoryGb,+ memoryFigureCandidates,resolveDraftCacheNote,resolveKvNote,resolveMemoryFit,@@ -135,19 +136,19 @@ test("worseMemoryFit is symmetric for every pair", () => {const ADVISORY_TEXTS = {singlePoolExceeds:- "More than this machine's memory. The GPU and the rest of the system share one pool here, so there is nothing to offload to.",+ "Exceeds shared memory. Try a shorter context or smaller model; CPU offloading adds no memory.",singlePoolPressure:- "This fits the machine, but not what is free right now. If that memory is not the model being replaced, the context will be fitted down or the load refused.",+ "Fits this machine, but little memory is free right now. Free memory or try Auto context.",hostShareExceeds:- "More than system RAM holds. This placement keeps most of the load outside the GPU, and spare VRAM cannot take those bytes.",+ "CPU placement exceeds system RAM. Try fewer CPU layers or a smaller model.",totalExceeds:- "More than this machine holds. The GPU and system RAM together are not enough for this load, so spilling layers or fitting the context down will not recover it.",+ "Exceeds combined GPU and system memory. Try a shorter context or smaller model.",gpuExceeds:- "More than this GPU holds. Layers will spill to system RAM, or the context will be fitted down to what fits.",+ "Exceeds GPU memory. Try Auto context or fewer GPU layers; loading may still fail.",hostPressure:- "The part of this load that runs from system RAM fits the machine, but not what is free right now. If that memory is not the model being replaced, the load will be refused.",+ "Fits system RAM, but little is free right now. Free memory, or try a shorter context or smaller model.",gpuPressure:- "This fits the card, but something is using it right now. If that memory is not the model being replaced, layers will spill or the context will be fitted down.",+ "Fits this GPU, but little VRAM is free right now. Free memory or try Auto context.",};test("D1: a single-pool host under memory pressure now says so", () => {@@ -184,6 +185,18 @@ test("D1: the single-pool pressure text is reachable from EITHER free reading",assert.equal(hostSide.advisory?.text, ADVISORY_TEXTS.singlePoolPressure);});+test("a tight reading warns without claiming the load exceeds available memory", () => {+ const result = fit(+ { gpuBytes: 26 * GB, totalBytes: 26 * GB },+ { freeGpuCapacityGb: 30, usableSystemRamGb: 30 },+ APPLE,+ );+ assert.equal(result.freeGpuFit, "tight");+ assert.equal(result.usableHostFit, "tight");+ assert.match(result.advisory?.text ?? "", /little memory is free right now/);+ assert.doesNotMatch(result.advisory?.text ?? "", /not what is free|will be|refused/);+});+test("D1: no discrete-host string can be chosen on a single-pool host", () => {// The other half of the dead branch: the two discrete pressure strings talk about// "the card" and "the part of this load that runs from system RAM", neither of@@ -241,8 +254,8 @@ test("the floor notes outrank every verdict, in their own order", () => {{ drafterKvUnsized: true, moeOffloadUnmodelled: true, totalBytes: 900 * GB },{},);- assert.match(drafter.advisory?.text ?? "", /fetch rather than one on this disk/);- const moe = fit({ moeOffloadUnmodelled: true, totalBytes: 900 * GB }, {});+ assert.match(drafter.advisory?.text ?? "", /remote draft model or vision component/);+ const moe = fit({ moeOffloadUnmodelled: true, gpuBytes: 8 * GB, totalBytes: 900 * GB }, {});assert.equal(moe.advisory?.tone, "muted");assert.match(moe.advisory?.text ?? "", /Expert layers/);});@@ -260,6 +273,19 @@ test("the aggregate verdict is asked before the GPU one", () => {// spilling to system RAM as the remedy, which is advice to do something that cannot// work.const result = fit({ gpuBytes: 20 * GB, totalBytes: 200 * GB }, {});+ assert.equal(result.advisory?.text, ADVISORY_TEXTS.totalExceeds);+});++test("both pools overflowing never recommends moving more layers to the GPU", () => {+ for (const gpuGb of [24, 30]) {+ const result = fit({ gpuBytes: gpuGb * GB, totalBytes: (gpuGb + 70) * GB }, {});+ assert.equal(result.advisory?.text, ADVISORY_TEXTS.totalExceeds);+ assert.doesNotMatch(result.advisory?.text ?? "", /fewer CPU layers/);+ }+});++test("host overflow with spare GPU capacity keeps placement advice", () => {+ const result = fit({ gpuBytes: 8 * GB, totalBytes: 78 * GB }, {});assert.equal(result.advisory?.text, ADVISORY_TEXTS.hostShareExceeds);});@@ -271,7 +297,7 @@ test("a load beyond GPU and RAM combined, with a host share that fits RAM", () =assert.equal(result.advisory?.text, ADVISORY_TEXTS.totalExceeds);});-test("a load that only overflows the card is told it will spill", () => {+test("a load that only overflows the card gets conditional offload advice", () => {const result = fit({ gpuBytes: 30 * GB, totalBytes: 30 * GB }, {});assert.equal(result.advisory?.text, ADVISORY_TEXTS.gpuExceeds);});@@ -284,6 +310,35 @@ test("a discrete host under host-RAM pressure keeps the system-RAM wording", ()assert.equal(result.advisory?.text, ADVISORY_TEXTS.hostPressure);});+test("pressure advice does not shift layers into another pressured pool", () => {+ for (const freeGpu of [24, 22, 0]) {+ const result = fit(+ { gpuBytes: 22 * GB, totalBytes: 40 * GB },+ {+ freeGpuCapacityGb: freeGpu,+ usableSystemRamGb: 10,+ reclaimableTotalBytes: 10 * GB,+ },+ );+ assert.equal(result.rawGpuFit, "tight");+ assert.equal(result.usableHostFit, "tight");+ assert.doesNotMatch(result.advisory?.text ?? "", /CPU layers|offload/);+ assert.match(result.advisory?.text ?? "", /shorter context or smaller model/);+ }+ for (const [gpuGb, hostGb, freeGpu, freeHost] of [+ [30, 5, 23, 2],+ [21, 65, 1, 60],+ ]) {+ const result = fit(+ { gpuBytes: gpuGb * GB, totalBytes: (gpuGb + hostGb) * GB },+ { freeGpuCapacityGb: freeGpu, usableSystemRamGb: freeHost },+ );+ assert.equal(result.advisory?.tone, "warn");+ assert.doesNotMatch(result.advisory?.text ?? "", /layers|offload/);+ assert.match(result.advisory?.text ?? "", /shorter context or smaller model/);+ }+});+test("a discrete host under VRAM pressure alone gets the card wording", () => {const result = fit({ gpuBytes: 20 * GB, totalBytes: 20 * GB },@@ -491,9 +546,101 @@ test("an unsizable pass-through adapter marks the total a floor", () => {IDLE_DISCRETE,);assert.equal(bounded.bounded, true);+ assert.equal(bounded.prefix, "≥ ");+ assert.equal(bounded.advisory?.tone, "warn");+ assert.match(bounded.advisory?.text ?? "", /adapter or control vector/);const sized = resolveMemoryFit({ ...SIZED, totalBytes: 8 * GB, gpuBytes: 8 * GB },IDLE_DISCRETE,);assert.equal(sized.bounded, false);});++test("an unsized adapter warning takes precedence over a placement verdict", () => {+ const result = fit(+ { adaptersUnsized: true, moeOffloadUnmodelled: true, totalBytes: 200 * GB },+ {},+ );+ assert.match(result.advisory?.text ?? "", /adapter or control vector/);+ assert.equal(result.advisory?.tone, "warn");+});++test("CPU-only estimates use RAM guidance without suggesting GPU placement", () => {+ for (const total of [25.61, 40]) {+ const result = fit(+ { gpuBytes: 0, totalBytes: total * GB },+ {+ gpuCapacityGb: 0,+ totalCapacityGb: 32,+ systemRamCapacityGb: 32,+ freeGpuCapacityGb: 0,+ usableSystemRamGb: 24,+ },+ );+ assert.equal(result.cpuOnly, true);+ assert.match(result.advisory?.text ?? "", /RAM/);+ assert.doesNotMatch(result.advisory?.text ?? "", /CPU layers|GPU layers/);+ }+});++test("a confirmed zero free reading warns, while an unknown reading stays unknown", () => {+ for (const known of [false, true]) {+ const gpu = fit(+ { gpuBytes: 20 * GB, totalBytes: 25 * GB },+ { freeGpuCapacityGb: 0, freeGpuCapacityKnown: known },+ );+ assert.equal(gpu.freeGpuFit, known ? "exceeds" : "unknown");+ assert.equal(gpu.gpuFit, known ? "tight" : "fits");+ assert.equal(gpu.cpuOnly, false);+ const ram = fit(+ { gpuBytes: 0, totalBytes: 25 * GB },+ { usableSystemRamGb: 0, usableSystemRamKnown: known },+ );+ assert.equal(ram.hostPressured, known);+ }+});++test("shared pools keep their label and warn when known free memory reaches zero", () => {+ const result = fit(+ { gpuBytes: 0, totalBytes: 25 * GB },+ {+ freeGpuCapacityGb: 0,+ usableSystemRamGb: 0,+ freeGpuCapacityKnown: true,+ usableSystemRamKnown: true,+ },+ APPLE,+ );+ assert.equal(result.cpuOnly, false);+ assert.equal(result.hostPressured, true);+ assert.equal(result.gpuPressured, true);+});++test("compact estimates retain units and never round a lower bound up", () => {+ const candidates = memoryFigureCandidates(25.61 * GB, true);+ assert.equal(candidates[0], "≥ 25.61 GiB");+ assert.ok(candidates.includes("≥ 25.6 GiB"));+ assert.ok(candidates.includes("≥ 25 GiB"));+ assert.ok(!candidates.includes("≥ 26 GiB"));+ assert.ok(memoryFigureCandidates(2048 * GB, false).includes("2 TiB"));+});++test("the primary lower-bound label also rounds down", () => {+ assert.equal(memoryFigureCandidates(25.619 * GB, true)[0], "≥ 25.61 GiB");+ assert.equal(memoryFigureCandidates(25.619 * GB, false)[0], "25.62 GiB");+ for (const gib of [0.009, 25.619, 1024.999, 2048.129]) {+ for (const label of memoryFigureCandidates(gib * GB, true)) {+ const [, amount, unit] = label.split(" ");+ const scaled = Number(amount) * (unit === "TiB" ? 1024 : 1);+ assert.ok(scaled <= gib, `${label} exceeds ${gib} GiB`);+ }+ }+});++test("capacity advice does not assume a pageable load mode", () => {+ for (const [gpu, total] of [[0, 100], [30, 100], [8, 78]]) {+ const result = fit({ gpuBytes: gpu * GB, totalBytes: total * GB }, {});+ assert.match(result.advisory?.text ?? "", /smaller model/);+ assert.doesNotMatch(result.advisory?.text ?? "", /paging|will load|will fit/);+ }+});diff --git a/studio/frontend/tests/memory-probe-known.test.ts b/studio/frontend/tests/memory-probe-known.test.tsnew file mode 100644index 00000000000..8c1526c22a1--- /dev/null+++ b/studio/frontend/tests/memory-probe-known.test.ts@@ -0,0 +1,92 @@+// 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 * as GpuHooks from "../src/hooks/use-gpu-info.ts";+import type * as SystemHooks from "../src/hooks/use-system.ts";+import { loadWithStubs } from "./helpers/module-stubs.ts";++let snapshot: unknown = null;+const hooks = loadWithStubs<typeof GpuHooks>(+ new URL("../src/hooks/use-gpu-info.ts", import.meta.url),+ {+ react: {+ useState: (initial: unknown) => [+ typeof initial === "function" ? initial() : initial,+ () => {},+ ],+ useEffect: () => {},+ useMemo: (read: () => unknown) => read(),+ },+ "./use-system": { getCachedSystemInfo: () => snapshot },+ },+ { relativePassthrough: true },+);++test("GPU and RAM probes distinguish zero from missing or invalid readings", () => {+ for (const backend of ["cuda", "vulkan"]) {+ for (const reading of [0, 8, undefined, null, -1, Number.NaN, Infinity]) {+ const gpu = {+ available: true,+ backend,+ devices: [+ {+ index: 0,+ index_kind: backend === "vulkan" ? "vulkan" : "physical",+ memory_total_gb: 24,+ vram_free_gb: reading,+ },+ ],+ };+ snapshot = {+ status: "ready",+ device_backend: "cuda",+ gpu,+ inference_gpu: gpu,+ memory: { total_gb: 32, available_gb: reading },+ };+ const known = reading === 0 || reading === 8;+ assert.equal(hooks.useGpuDevices()[0].memoryFreeKnown, known);+ assert.equal(hooks.useInferenceGpuInfo().systemRamAvailableKnown, known);+ }+ }+});++test("resident refresh bypasses cached and in-flight pre-load memory", async () => {+ const requests: { url: string; resolve: (response: Response) => void }[] = [];+ const system = loadWithStubs<typeof SystemHooks>(+ new URL("../src/hooks/use-system.ts", import.meta.url),+ {+ react: {},+ "@/features/auth": {+ authFetch: (url: string) =>+ new Promise<Response>((resolve) => {+ requests.push({ url, resolve });+ }),+ },+ },+ { relativePassthrough: true },+ );+ const initial = system.fetchSystemInfo();+ const refreshed = system.fetchSystemInfo({ refreshMemory: true });+ assert.equal(requests.length, 1);+ requests[0].resolve(Response.json({ memory: { available_gb: 20 } }));+ const idle = await initial;+ await Promise.resolve();+ assert.equal(requests[1].url, "/api/system?refresh_memory=true");+ requests[1].resolve(+ Response.json({+ memory_refreshed: true,+ memory: { available_gb: 10 },+ }),+ );+ const resident = await refreshed;+ assert.equal(idle?.memory.available_gb, 20);+ assert.equal(resident?.memory.available_gb, 10);+ assert.equal(await system.fetchSystemInfo(), resident);+ const again = system.fetchSystemInfo({ refreshMemory: true });+ assert.equal(requests.length, 3);+ requests[2].resolve(new Response(null, { status: 503 }));+ assert.equal(await again, null);+});diff --git a/studio/frontend/tests/resident-memory-credit.test.ts b/studio/frontend/tests/resident-memory-credit.test.tsnew file mode 100644index 00000000000..f427b0ee765--- /dev/null+++ b/studio/frontend/tests/resident-memory-credit.test.ts@@ -0,0 +1,229 @@+// 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 { SystemGpuDevice } from "../src/hooks/gpu-selection.ts";+import { aggregateVramReserveDeficitGb } from "../src/hooks/gpu-vram.ts";+import {+ type MemoryFitCapacity,+ resolveMemoryFit,+ resolveReclaimableMemoryCredit,+} from "../src/features/model-picker/model-config/memory-fit.ts";++const GiB = 1024 ** 3;+const pool = { ids: null, indexKind: null };+const estimate = (total: number, gpu = total, files = 0) => ({+ totalBytes: total * GiB,+ gpuBytes: gpu * GiB,+ weightsBytes: files * GiB,+ kvEstimable: true,+ drafterKvUnsized: false,+ adaptersUnsized: false,+ moeOffloadUnmodelled: false,+});+const capacity: MemoryFitCapacity = {+ gpuCapacityGb: 48,+ totalCapacityGb: 112,+ systemRamCapacityGb: 64,+ freeGpuCapacityGb: 24,+ usableSystemRamGb: 24,+ singleMemoryPool: false,+};++test("reload credit preserves pressure thresholds and physical limits", () => {+ assert.equal(resolveMemoryFit(estimate(25), capacity).freeGpuFit, "exceeds");+ for (const singleMemoryPool of [false, true]) {+ const available = {+ ...capacity,+ singleMemoryPool,+ ...(singleMemoryPool ? { gpuCapacityGb: 64, totalCapacityGb: 64 } : {}),+ reclaimableTotalBytes: (singleMemoryPool ? 10 : 20) * GiB,+ reclaimableGpuBytes: 10 * GiB,+ };+ for (const [wanted, verdict] of [+ [25, "fits"],+ [29, "tight"],+ [35, "exceeds"],+ ] as const) {+ const footprint = singleMemoryPool+ ? estimate(wanted, wanted / 2)+ : estimate(wanted * 2, wanted);+ const fit = resolveMemoryFit(footprint, available);+ assert.equal(fit.freeGpuFit, verdict);+ assert.equal(fit.usableHostFit, verdict);+ }+ const oversized = resolveMemoryFit(estimate(120, 70), available);+ assert.equal(oversized.rawGpuFit, "exceeds");+ assert.equal(oversized.totalFit, "exceeds");+ }+});++test("resident credit cannot turn an unknown probe into a known one", () => {+ for (const known of [false, true]) {+ const fit = resolveMemoryFit(estimate(9), {+ ...capacity,+ singleMemoryPool: true,+ freeGpuCapacityGb: 0,+ usableSystemRamGb: 0,+ freeGpuCapacityKnown: known,+ usableSystemRamKnown: known,+ reclaimableTotalBytes: 10 * GiB,+ });+ assert.equal(fit.freeGpuFit, known ? "tight" : "unknown");+ assert.equal(fit.usableHostFit, known ? "tight" : "unknown");+ }+});++test("credit fills unmet reserves without consuming already usable memory", () => {+ const deficit = aggregateVramReserveDeficitGb(+ [{ memoryTotalGb: 24, memoryFreeGb: 0 }],+ 0.9,+ );+ assert.ok(Math.abs(deficit - 2.4) < 1e-9);+ const fit = resolveMemoryFit(estimate(32, 16), {+ ...capacity,+ freeGpuCapacityGb: 0,+ usableSystemRamGb: 0,+ freeGpuCapacityKnown: true,+ usableSystemRamKnown: true,+ freeGpuReserveDeficitGb: deficit,+ systemRamReserveDeficitGb: 2,+ reclaimableTotalBytes: 40 * GiB,+ reclaimableGpuBytes: 20 * GiB,+ });+ assert.equal(fit.freeGpuFit, "tight");+ assert.equal(fit.usableHostFit, "tight");+ assert.equal(+ resolveMemoryFit(estimate(8), {+ ...capacity,+ freeGpuCapacityGb: 10,+ freeGpuReserveDeficitGb: deficit,+ reclaimableTotalBytes: GiB,+ reclaimableGpuBytes: GiB,+ }).freeGpuFit,+ "fits",+ );+});++test("GPU credit requires the complete resident pool in the same namespace", () => {+ for (const [loaded, requested, gpu] of [+ [[0], [1], 0],+ [[0, 1], [1], 0],+ [[0], [0, 1], 20],+ [null, [0], 0],+ [null, null, 20],+ ] as const) {+ const credit = resolveReclaimableMemoryCredit(+ estimate(40, 20),+ { ids: loaded && [...loaded], indexKind: "physical" },+ { ids: requested && [...requested], indexKind: "physical" },+ { gpuPlacementKnown: true },+ );+ assert.deepEqual(credit, {+ totalBytes: (20 + gpu) * GiB,+ gpuBytes: gpu * GiB,+ });+ }+ const wrongNamespace = resolveReclaimableMemoryCredit(+ estimate(40, 20),+ { ids: [0], indexKind: "physical" },+ { ids: [0], indexKind: "vulkan" },+ { gpuPlacementKnown: true },+ );+ assert.deepEqual(wrongNamespace, { totalBytes: 20 * GiB, gpuBytes: 0 });+});++const sharedDevice: SystemGpuDevice = {+ index: 0,+ indexKind: "vulkan",+ name: "Shared GPU",+ memoryTotalGb: 32,+ memoryFreeGb: 0,+ sharedMemory: true,+ pinnable: true,+ diffusionPinnable: false,+};++test("only guaranteed host-backed GPU allocations return to RAM after a GPU change", () => {+ const cases: [SystemGpuDevice[], number][] = [+ [[sharedDevice], 24],+ [[{ ...sharedDevice, sharedMemory: false, unifiedMemory: true }], 24],+ [[{ ...sharedDevice, sharedMemoryHostBackedGb: 24 }], 16],+ [[{ ...sharedDevice, sharedMemory: false }], 4],+ [[], 4],+ ];+ for (const [devices, total] of cases) {+ const credit = resolveReclaimableMemoryCredit(+ estimate(24, 20),+ { ids: [0], indexKind: "vulkan" },+ { ids: [1], indexKind: "vulkan" },+ { devices, gpuPlacementKnown: true },+ );+ assert.deepEqual(credit, { totalBytes: total * GiB, gpuBytes: 0 });+ }+});++test("fitted placement and fallback allocations earn no uncertain VRAM credit", () => {+ for (const options of [{}, { gpuPlacementKnown: true, cpuFallback: true }]) {+ assert.deepEqual(+ resolveReclaimableMemoryCredit(estimate(30, 24, 4), pool, pool, options),+ { totalBytes: 2 * GiB, gpuBytes: 0 },+ );+ }+ const experts = resolveReclaimableMemoryCredit(+ { ...estimate(30, 24, 4), moeOffloadUnmodelled: true },+ pool,+ pool,+ { gpuPlacementKnown: true },+ );+ assert.deepEqual(experts, { totalBytes: 2 * GiB, gpuBytes: 0 });+});++test("mapped weights are excluded from host credit, including unified memory", () => {+ const cpu = resolveReclaimableMemoryCredit(estimate(30, 0, 22), pool, pool);+ assert.deepEqual(cpu, { totalBytes: 8 * GiB, gpuBytes: 0 });+ const unified = resolveReclaimableMemoryCredit(+ estimate(30, 30, 22),+ pool,+ pool,+ { appleUnifiedMemory: true },+ );+ assert.deepEqual(unified, cpu);+ const discrete = resolveReclaimableMemoryCredit(+ estimate(30, 20, 22),+ pool,+ pool,+ {+ gpuPlacementKnown: true,+ devices: [{ ...sharedDevice, sharedMemory: false }],+ },+ );+ assert.deepEqual(discrete, { totalBytes: 20 * GiB, gpuBytes: 20 * GiB });+});++test("duplicate shared GPU views consume one reserve deficit", () => {+ const shared = { memoryTotalGb: 32, memoryFreeGb: 0, sharedMemory: true };+ assert.ok(+ Math.abs(aggregateVramReserveDeficitGb([shared, shared], 0.9) - 3.2) < 1e-9,+ );+ assert.ok(+ Math.abs(+ aggregateVramReserveDeficitGb(+ [+ shared,+ { ...shared, memoryFreeGb: 1 },+ { ...shared, sharedMemory: false },+ ],+ 0.9,+ ) - 5.4,+ ) < 1e-9,+ );+ assert.equal(+ aggregateVramReserveDeficitGb(+ [shared, { ...shared, memoryFreeGb: 4 }],+ 0.9,+ ),+ 0,+ );+});diff --git a/studio/frontend/tests/resident-memory-refresh.test.ts b/studio/frontend/tests/resident-memory-refresh.test.tsnew file mode 100644index 00000000000..d860820f9eb--- /dev/null+++ b/studio/frontend/tests/resident-memory-refresh.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 type * as EstimateHook from "../src/features/model-picker/hooks/use-memory-estimate.ts";+import { loadWithStubs } from "./helpers/module-stubs.ts";++test("resident estimates wait for fresh probes and discard obsolete refreshes", async (t) => {+ t.mock.timers.enable({ apis: ["setTimeout"] });+ let state: unknown;+ const refs: { current: unknown }[] = [];+ let cursor = 0;+ let previousDeps: unknown[] = [];+ let cleanup: (() => void) | undefined;+ let commit: (() => void) | undefined;+ const probes: ((result: unknown) => void)[] = [];+ const estimate = { available: true, totalBytes: 10 * 1024 ** 3 };+ const hook = loadWithStubs<typeof EstimateHook>(+ new URL(+ "../src/features/model-picker/hooks/use-memory-estimate.ts",+ import.meta.url,+ ),+ {+ react: {+ useState: (initial: unknown) => {+ state ??= initial;+ return [+ state,+ (next: unknown) => {+ state = typeof next === "function" ? next(state) : next;+ },+ ];+ },+ useRef: (initial: unknown) => (refs[cursor++] ??= { current: initial }),+ useEffect: (+ effect: () => (() => void) | undefined,+ deps: unknown[],+ ) => {+ if (deps.some((dep, i) => dep !== previousDeps[i])) {+ commit = () => {+ cleanup?.();+ previousDeps = deps;+ cleanup = effect();+ };+ }+ },+ },+ "../api/memory-estimate": { fetchMemoryEstimate: async () => estimate },+ "@/hooks/use-system": {+ fetchSystemInfo: (options: unknown) => {+ assert.deepEqual(options, { refreshMemory: true });+ return new Promise((resolve) => probes.push(resolve));+ },+ },+ },+ { relativePassthrough: true },+ );+ const render = (nCtx: number | null, refreshMemory = true) => {+ cursor = 0;+ const shown = hook.useMemoryEstimate(+ nCtx === null ? null : { modelPath: "model", nCtx },+ { refreshMemory },+ );+ commit?.();+ commit = undefined;+ return shown;+ };+ const settle = async () => {+ for (let i = 0; i < 8; i++) await Promise.resolve();+ };+ render(1024);+ t.mock.timers.tick(250);+ await settle();+ assert.equal(render(1024).estimate, null);+ probes[0]({ memory_refreshed: true });+ await settle();+ assert.equal(render(1024).estimate, estimate);+ assert.equal(render(2048).stale, true);+ t.mock.timers.tick(250);+ await settle();+ assert.equal(render(null).estimate, null);+ probes[1]({ memory_refreshed: true });+ await settle();+ assert.equal(render(2048).estimate, null);+ t.mock.timers.tick(250);+ await settle();+ probes[2]({});+ await settle();+ assert.equal(render(2048).estimate, null);+ render(2048, false);+ t.mock.timers.tick(250);+ await settle();+ assert.equal(render(2048, false).estimate, estimate);+ assert.equal(probes.length, 3);+ assert.equal(render(2048).stale, true);+ cleanup?.();+});diff --git a/studio/frontend/tests/resident-memory-request.test.ts b/studio/frontend/tests/resident-memory-request.test.tsnew file mode 100644index 00000000000..bc33520d3b5--- /dev/null+++ b/studio/frontend/tests/resident-memory-request.test.ts@@ -0,0 +1,136 @@+// 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 {+ resolveResidentEstimateRequest,+ selectResidentEstimateSettings,+} from "../src/features/model-picker/model-config/resident-memory-request.ts";++const loaded: Parameters<typeof selectResidentEstimateSettings>[0] = {+ modelLoading: false,+ loadedKvCacheDtype: "q8_0",+ loadedNParallel: 2,+ loadedNBatch: 512,+ loadedNUbatch: 128,+ loadedCtxCheckpoints: 8,+ loadedSpeculativeType: "off",+ loadedSpecDraftNMax: 3,+ loadedSpecDraftCacheDtype: "q8_0",+ loadedTensorParallel: false,+ loadedDisableVision: true,+ loadedGpuMemoryMode: "auto",+ loadedGpuLayers: null,+ loadedNCpuMoe: null,+ loadedGpuIds: [0],+ loadedLlamaExtraArgs: ["--no-kv-offload"],+ loadedCpuFallback: false,+ specFallbackReason: null,+ mmprojFallbackReason: null,+};++test("pending controls cannot change the loaded placement or memory requirements", () => {+ const pending = {+ modelPath: "model",+ ggufVariant: "Q4_K_M",+ nCtx: 262144,+ cacheTypeKv: "f16",+ nParallel: 8,+ nBatch: 4096,+ nUbatch: 2048,+ ctxCheckpoints: 64,+ speculativeType: "mtp",+ specDraftNMax: 16,+ specDraftCacheType: "f16",+ tensorParallel: true,+ disableVision: false,+ gpuMemoryMode: "manual",+ gpuLayers: 99,+ nCpuMoe: 0,+ selectedGpuIds: [1],+ llamaExtraArgs: ["--swa-full"],+ };+ const request = resolveResidentEstimateRequest(+ pending,+ selectResidentEstimateSettings({ ...pending, ...loaded }),+ 8192,+ );+ assert.deepEqual(request, {+ modelPath: "model",+ ggufVariant: "Q4_K_M",+ hfToken: undefined,+ nativePathToken: undefined,+ nCtx: 8192,+ cacheTypeKv: "q8_0",+ nParallel: 2,+ nBatch: 512,+ nUbatch: 128,+ ctxCheckpoints: 8,+ speculativeType: "off",+ specDraftNMax: 3,+ specDraftCacheType: "q8_0",+ tensorParallel: false,+ disableVision: true,+ gpuMemoryMode: "auto",+ gpuLayers: null,+ nCpuMoe: null,+ selectedGpuIds: [0],+ llamaExtraArgs: ["--no-kv-offload"],+ });+ const defaults = resolveResidentEstimateRequest(+ pending,+ selectResidentEstimateSettings({+ ...loaded,+ loadedNParallel: null,+ loadedLlamaExtraArgs: null,+ }),+ 8192,+ );+ assert.equal(defaults?.nParallel, null);+ assert.equal(defaults?.llamaExtraArgs, null);+});++test("missing baselines and recorded fallbacks withhold resident credit", () => {+ for (const patch of [+ { modelLoading: true },+ { loadedGpuMemoryMode: null },+ { loadedSpeculativeType: null },+ { loadedTensorParallel: null },+ { loadedDisableVision: null },+ { loadedGpuMemoryMode: "manual" as const, loadedGpuLayers: null, loadedNCpuMoe: 0 },+ { loadedGpuMemoryMode: "manual" as const, loadedGpuLayers: 12, loadedNCpuMoe: null },+ { loadedCpuFallback: true },+ { specFallbackReason: "runtime_error" },+ { mmprojFallbackReason: "cpu_offload" as const },+ { mmprojFallbackReason: "projector_startup_failure" as const },+ ]) {+ assert.equal(selectResidentEstimateSettings({ ...loaded, ...patch }), null);+ }+ const settings = selectResidentEstimateSettings(loaded);+ for (const context of [null, 0, Number.NaN]) {+ assert.equal(+ resolveResidentEstimateRequest(+ { modelPath: "model", nCtx: 262144 },+ settings,+ context,+ ),+ null,+ );+ }+ assert.equal(resolveResidentEstimateRequest(null, settings, 8192), null);+});++test("fixed Manual layers and automatic layers retain their loaded meaning", () => {+ for (const layers of [12, -1]) {+ const settings = selectResidentEstimateSettings({+ ...loaded,+ loadedGpuMemoryMode: "manual",+ loadedGpuLayers: layers,+ loadedNCpuMoe: 4,+ });+ assert.equal(settings?.gpuMemoryMode, "manual");+ assert.equal(settings?.gpuLayers, layers < 0 ? null : layers);+ assert.equal(settings?.nCpuMoe, 4);+ }+});diff --git a/studio/frontend/tests/resident-status-baselines.test.ts b/studio/frontend/tests/resident-status-baselines.test.tsnew file mode 100644index 00000000000..9c29f54509b--- /dev/null+++ b/studio/frontend/tests/resident-status-baselines.test.ts@@ -0,0 +1,215 @@+// 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 { readFileSync } from "node:fs";+import test from "node:test";+import { selectResidentEstimateSettings } from "../src/features/model-picker/model-config/resident-memory-request.ts";++// Execute the shipped status patch without importing the browser store graph.+const source = readFileSync(+ new URL(+ "../src/features/chat/lib/apply-inference-status-to-store.ts",+ import.meta.url,+ ),+ "utf8",+);+const start = source.indexOf(" // Controls follow the server while clean;");+const end = source.indexOf(+ " // A load knob like tensorParallel above.",+ start,+);+assert.ok(start >= 0 && end > start);+const apply = new Function(+ "prevState",+ "status",+ "seedLoadParams",+ "hydratingExistingModel",+ "currentSpecType",+ `return { ...prevState, ${source.slice(start, end)} };`,+) as (+ previous: typeof loaded,+ status: Record<string, unknown>,+ settled: boolean,+ changed: boolean,+ specType: string,+) => typeof loaded;++const loaded = {+ modelLoading: false,+ kvCacheDtype: "f16",+ loadedKvCacheDtype: "f16",+ speculativeType: "off",+ loadedSpeculativeType: "off",+ specDraftNMax: 3,+ loadedSpecDraftNMax: 3,+ tensorParallel: false,+ loadedTensorParallel: false,+ loadedNParallel: 2,+ loadedNBatch: 512,+ loadedNUbatch: 128,+ loadedCtxCheckpoints: 8,+ loadedSpecDraftCacheDtype: "q8_0",+ loadedDisableVision: true,+ loadedGpuMemoryMode: "manual" as const,+ loadedGpuLayers: 12,+ loadedNCpuMoe: 0,+ loadedGpuIds: [0],+ loadedLlamaExtraArgs: [],+ loadedCpuFallback: false,+ specFallbackReason: null,+ mmprojFallbackReason: null,+};+const status = {+ cache_type_kv: "q4_0",+ speculative_type: "mtp",+ spec_draft_n_max: 8,+ tensor_parallel: true,+};++function checkBaselines(state: typeof loaded) {+ const settings = selectResidentEstimateSettings(state);+ assert.equal(settings?.cacheTypeKv, "q4_0");+ assert.equal(settings?.speculativeType, "mtp");+ assert.equal(settings?.specDraftNMax, 8);+ assert.equal(settings?.tensorParallel, true);+}++test("same-model external reload advances resident pricing and clean controls", () => {+ const next = apply(loaded, status, true, false, "mtp");+ checkBaselines(next);+ assert.equal(next.kvCacheDtype, "q4_0");+ assert.equal(next.speculativeType, "mtp");+ assert.equal(next.specDraftNMax, 8);+ assert.equal(next.tensorParallel, true);+});++test("pending edits survive external reloads and subsequent steady polls", () => {+ const dirty = {+ ...loaded,+ kvCacheDtype: "q8_0",+ speculativeType: "auto",+ specDraftNMax: 16,+ tensorParallel: true,+ };+ const next = apply(+ dirty,+ { ...status, tensor_parallel: false },+ true,+ false,+ "mtp",+ );+ assert.equal(next.loadedTensorParallel, false);+ assert.equal(next.tensorParallel, true);+ assert.equal(next.loadedKvCacheDtype, "q4_0");+ for (const key of [+ "kvCacheDtype",+ "speculativeType",+ "specDraftNMax",+ "tensorParallel",+ ] as const) {+ assert.equal(next[key], dirty[key]);+ }+ assert.deepEqual(+ apply(next, { ...status, tensor_parallel: false }, true, false, "mtp"),+ next,+ );+});++test("in-flight loads and absent echoes cannot overwrite recorded baselines", () => {+ assert.deepEqual(apply(loaded, status, false, false, "mtp"), loaded);+ assert.deepEqual(apply(loaded, {}, true, false, "auto"), loaded);+});++test("model or variant changes replace controls belonging to the old model", () => {+ const next = apply(+ {+ ...loaded,+ kvCacheDtype: "q8_0",+ speculativeType: "auto",+ specDraftNMax: 16,+ },+ status,+ true,+ true,+ "mtp",+ );+ checkBaselines(next);+ assert.equal(next.kvCacheDtype, "q4_0");+ assert.equal(next.speculativeType, "mtp");+ assert.equal(next.specDraftNMax, 8);+});++test("explicit null clears nullable baselines rather than keeping stale allocations", () => {+ const next = apply(+ loaded,+ { cache_type_kv: null, spec_draft_n_max: null },+ true,+ false,+ "off",+ );+ assert.equal(next.loadedKvCacheDtype, null);+ assert.equal(next.loadedSpecDraftNMax, null);+ assert.equal(next.kvCacheDtype, null);+ assert.equal(next.specDraftNMax, null);+});++test("speculative defaults still seed on adoption when older backends omit the mode", () => {+ const next = apply(loaded, {}, true, true, "auto");+ assert.equal(next.speculativeType, "auto");+ assert.equal(next.loadedSpeculativeType, "auto");+});++// The slot echo is resolved, so unlike the controls above it only advances the+// baseline. A blank control must continue to mean server default.+const slotStart = source.indexOf(" // Baseline only, never the control:");+const slotEnd = source.indexOf(+ " // Per-model: a change underneath this tab",+ slotStart,+);+assert.ok(slotStart >= 0 && slotEnd > slotStart);+const applySlots = new Function(+ "prevState",+ "status",+ "seedLoadParams",+ "hydratingExistingModel",+ `return { ...prevState, ${source.slice(slotStart, slotEnd)} };`,+) as (+ previous: typeof loaded & { nParallel: number | null },+ status: Record<string, unknown>,+ settled: boolean,+ changed: boolean,+) => typeof loaded & { nParallel: number | null };++test("external slot reductions update resident pricing without pinning or replacing controls", () => {+ for (const nParallel of [null, 2, 8]) {+ const previous = { ...loaded, nParallel };+ const echo = { is_gguf: true, requested_parallel_slots: 1 };+ const next = applySlots(previous, echo, true, false);+ assert.equal(next.loadedNParallel, 1);+ assert.equal(selectResidentEstimateSettings(next)?.nParallel, 1);+ assert.equal(next.nParallel, nParallel);+ assert.deepEqual(applySlots(next, echo, true, false), next);+ }+});++test("slot baselines ignore in-flight loads and absent GGUF echoes", () => {+ const previous = { ...loaded, nParallel: null };+ assert.deepEqual(+ applySlots(previous, { requested_parallel_slots: 1 }, false, false),+ previous,+ );+ assert.deepEqual(+ applySlots(previous, { is_gguf: true }, true, false),+ previous,+ );+});++test("slotless statuses still clear the baseline without editing the control", () => {+ const previous = { ...loaded, nParallel: 8 };+ for (const echo of [{ is_gguf: false }, { requested_parallel_slots: null }]) {+ const next = applySlots(previous, echo, true, false);+ assert.equal(next.loadedNParallel, null);+ assert.equal(next.nParallel, 8);+ }+});