Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: advise raising the iGPU memory allocation when a model overflows it (#10486)

Daniel Han2d2d5008df98
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 0d3acaae567..d436e15cbbb 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -5924,6 +5924,18 @@ def _report_live_llama_timings(callback, chunk) -> None:
# system RAM, so hold back the same margin rather than inventing a larger one.
_IGPU_HOST_RESERVE_MIB = 1024
_HOST_RAM_HEADROOM_MIB = 2048
+# What the advice refuses to take from the host: this many GB or this share of the
+# machine, whichever is larger. The carve-out comes out of the RAM the OS sees, so
+# ignoring the host turns a slow load into an unusable desktop.
+_CARVEOUT_ADVICE_MIN_HOST_GB = 8
+# A fifth, not a quarter: the 128 GB Strix Halo firmware offers 96 GB and runs it. A
+# quarter would cap at 95.83 GB and rule out a setting we measured.
+_CARVEOUT_ADVICE_HOST_FRACTION = 0.20
+# A driver reports the pool it kept, not the firmware menu number (95.83 against a
+# 96.00 GB setting here). Without slack a model between the two earns the rung the
+# user is ALREADY on, so the advice reads "allocate 96 GB" to someone running 96 GB.
+# Half a GB is well under the gap between rungs.
+_CARVEOUT_NOMINAL_SLACK_GB = 0.5
# Appended to whichever shortfall warning an oversized non-pageable launch produced,
# after _page_an_oversized_unmapped_load rewrote the mode. One string, so the three
# call sites cannot describe the same override differently.
@@ -6236,6 +6248,8 @@ class LlamaCppBackend:
# Reset by _begin_load_warnings so one load's notice is never reported against
# the next.
self._last_load_warning: Optional[str] = None
+ # Set per launch by _record_carveout_advice; None on nearly every load.
+ self._last_carveout_advice: Optional[dict] = None
self._model_identifier: Optional[str] = None
self._gguf_path: Optional[str] = None
# Snapshot of the exact file(s) handed to the resident process. A local
@@ -10678,6 +10692,297 @@ class LlamaCppBackend:
".wslconfig)."
)
+ @staticmethod
+ def _igpu_dedicated_memory_bytes(
+ gpu_indices = None, *, ordinals_are_vulkan = False
+ ) -> Optional[int]:
+ """Memory dedicated to the selected integrated GPU, in bytes, or ``None``.
+
+ Two readings, since no single source covers every platform: the DirectX
+ registry (Windows, no vendor runtime needed, already parsed for the GPU
+ inventory) and ``_rocm_selected_pool_mib`` (Linux, needs a ROCm torch,
+ reports the carve-out as the device's total memory).
+
+ ``None`` whenever the reading would be a guess; every caller treats absence
+ as "say nothing".
+
+ The registry goes first despite being the less authoritative answer, because
+ it is the cheap one: a few ``winreg`` queries against a torch import plus a
+ ``get_device_properties`` per device, which this file documents as leaking a
+ ~700 MiB primary context. Off Windows it returns nothing instantly.
+ """
+ # Every adapter the registry lists, not only those with a readable allocation:
+ # the count IS the attribution test. Filtering the unreadable ones out hid a
+ # shared APU, leaving a discrete Radeon looking like the only candidate and its
+ # fixed VRAM quoted as the APU's carve-out.
+ answers: list[Optional[dict]] = []
+ try:
+ from utils.hardware.hardware import (
+ _AMD_PCI_VENDOR_ID,
+ _INTEL_PCI_VENDOR_ID,
+ _windows_amd_adapter_records_by_luid,
+ )
+ for vendor_id in (_AMD_PCI_VENDOR_ID, _INTEL_PCI_VENDOR_ID):
+ answers.append(
+ _windows_amd_adapter_records_by_luid(vendor_id, distinguish_failure = True)
+ )
+ except Exception:
+ answers = []
+ if any(answer is not None for answer in answers):
+ # A vendor answered, so this is Windows. A vendor that could not be read
+ # leaves the inventory incomplete, and an incomplete inventory cannot call
+ # the adapter it did see the only one, so fail closed.
+ if any(answer is None for answer in answers):
+ return None
+ adapters = sum(len(answer) for answer in answers)
+ # AMD only, though Intel is counted. On an APU the DirectX value is the
+ # firmware carve-out; on Intel UMA it is a small dedicated block beside
+ # memory handed out dynamically, so quoting it would advise a setting that
+ # may not exist and promise residency it cannot deliver.
+ amd_sizes = [
+ int(record["dedicated_memory_bytes"])
+ for record in (answers[0] or {}).values()
+ if record.get("dedicated_memory_bytes")
+ ]
+ if adapters == 1 and len(amd_sizes) == 1 and amd_sizes[0] > 0:
+ return amd_sizes[0]
+ if adapters:
+ # Two adapters need the inventory's LUID-to-device join; attributing
+ # the wrong one would advise about the wrong GPU. An APU paired with a
+ # discrete Radeon lands here, and silence is right.
+ return None
+ if ordinals_are_vulkan:
+ # No Linux reading for a Vulkan launch, for two reasons. gpu_indices holds
+ # VULKAN ordinals while _rocm_selected_pool_mib compares PHYSICAL HIP ids,
+ # and nothing in the Vulkan inventory carries a HIP id to join on, so the
+ # reading could land on a device this launch never touches. And it is not
+ # free: it creates a HIP primary context in THIS process (~800 MiB) out of
+ # the very pool it would then call too small.
+ return None
+ pool_mib = LlamaCppBackend._rocm_selected_pool_mib(gpu_indices)
+ return int(pool_mib) * 1024 * 1024 if pool_mib and pool_mib > 0 else None
+
+ @staticmethod
+ def _igpu_carveout_ladder_gb(cap_gb: float) -> list[int]:
+ """Plausible dedicated-GPU-memory sizes up to ``cap_gb``, ascending.
+
+ Firmware and driver panels offer a menu, not a slider, built from powers of
+ two and their halves (…16, 24, 32, 48, 64, 96, 128…). Generated rather than
+ tabulated so an unusually large machine still gets a suggestion; the caller
+ picks the smallest entry that fits, so an entry the user's firmware lacks is
+ a recommendation one notch off, not a wrong one.
+ """
+ # A `while` on the model-load path: the caller's try/except catches a raise,
+ # not a hang. A non-finite cap makes the condition permanently true, so reject
+ # it before the loop.
+ if not isinstance(cap_gb, (int, float)) or not math.isfinite(cap_gb):
+ return []
+ rungs: set[int] = set()
+ # From 1 GB, not 4: an APU on its automatic setting reports a few hundred
+ # megabytes, and starting at 4 took two more gigabytes from the host than the
+ # smallest-setting-that-fits rule needed.
+ step = 1
+ while step <= cap_gb:
+ rungs.add(step)
+ if step * 1.5 <= cap_gb:
+ rungs.add(int(step * 1.5))
+ step *= 2
+ return sorted(rungs)
+
+ @staticmethod
+ def _igpu_carveout_advice(
+ model_size_bytes: Optional[int],
+ carve_out_bytes: Optional[int],
+ host_total_bytes: Optional[int],
+ *,
+ is_igpu: bool,
+ min_host_gb: int = _CARVEOUT_ADVICE_MIN_HOST_GB,
+ host_fraction: float = _CARVEOUT_ADVICE_HOST_FRACTION,
+ nominal_slack_gb: float = _CARVEOUT_NOMINAL_SLACK_GB,
+ ) -> Optional[dict]:
+ """Advice payload when an integrated GPU's dedicated memory is too small to
+ hold this model's weights, else ``None``.
+
+ Weights spilling out of the allocation run from shared system memory, which
+ is markedly slower. Raising the allocation is a firmware/driver-panel setting
+ only the user can make, so this only ever advises.
+
+ Silent on a discrete GPU (``is_igpu`` false): that allocation is fixed
+ silicon. Nothing is hardcoded to one machine -- the ceiling comes from what
+ this host has, so a 32 GB laptop and a 512 GB workstation are each sized to
+ themselves, and a model too large for ANY allocation here gets no advice.
+ """
+ if not is_igpu:
+ return None
+ # Strictly positive, not merely truthy: -1 is truthy, so a bare falsiness test
+ # would carry a nonsense driver reading into confident wrong advice.
+ if not all(
+ isinstance(value, (int, float)) and math.isfinite(value) and value > 0
+ for value in (model_size_bytes, carve_out_bytes, host_total_bytes)
+ ):
+ return None
+ if model_size_bytes <= carve_out_bytes:
+ return None # already fits: nothing to advise
+
+ gb = float(1024**3)
+ # Windows subtracts the carve-out from the RAM it reports, so the machine has
+ # both; reading one under-counts by exactly the amount this advice is about.
+ machine_gb = (host_total_bytes + carve_out_bytes) / gb
+ need_gb = model_size_bytes / gb
+ current_gb = carve_out_bytes / gb
+
+ # Whatever is suggested, the rest of the system still has to run.
+ reserve_gb = max(float(min_host_gb), machine_gb * host_fraction)
+ cap_gb = machine_gb - reserve_gb
+ if need_gb > cap_gb:
+ # No allocation this machine can offer holds the weights, so advice would
+ # be something the user cannot act on.
+ return None
+
+ suggested = next(
+ (rung for rung in LlamaCppBackend._igpu_carveout_ladder_gb(cap_gb) if rung >= need_gb),
+ None,
+ )
+ # Not `<= current_gb`: the reading is the pool the driver kept, so the rung the
+ # user is already on sits just above it. See _CARVEOUT_NOMINAL_SLACK_GB.
+ if suggested is None or suggested <= current_gb + nominal_slack_gb:
+ return None
+
+ return {
+ "current_gb": round(current_gb, 1),
+ "needed_gb": round(need_gb, 1),
+ "suggested_gb": int(suggested),
+ "machine_gb": round(machine_gb, 1),
+ "host_left_gb": round(machine_gb - suggested, 1),
+ }
+
+ def _record_carveout_advice(
+ self,
+ gpu_indices,
+ need_bytes,
+ *,
+ is_vulkan_backend = False,
+ shared_gpu_ids = None,
+ detected_gpus = None,
+ target_unknown = False,
+ forced_cpu = False,
+ ) -> None:
+ """Work out whether this load is worth advising about, and stash the result.
+
+ Advisory only, and never raises: the launch decides whether to spill the
+ weights into shared memory, this only says whether the user could stop the
+ spill existing at all, and an advisory must not break a model load.
+
+ Tests are ordered cheapest first because this runs on every load, including
+ the Vulkan ones that skip the managed-memory branch above. The allocation
+ reading is arithmetic over a registry query; the integrated-GPU probe behind
+ it imports torch and reads device properties, so the common load whose model
+ fits pays only the cheap half.
+
+ ``forced_cpu``: the architecture gate emptied the pool and the env block below
+ masks every device away, so no allocation would hold a single weight. Priced
+ before that mask is written, so without this it would offer exactly that.
+
+ ``target_unknown``: the cache tuning's test, borrowed. With no ``gpu_ids`` a
+ user ``--device`` (or ``LLAMA_ARG_DEVICE``) survives into the child and wins
+ last-wins over the generated pin, so the placement this would advise about is
+ not the one the child gets. Decline rather than re-derive it from argv.
+ """
+ self._last_carveout_advice = None
+ try:
+ if not need_bytes or target_unknown or forced_cpu:
+ return
+ # Gated HERE, not beside the ROCm gate below: on Vulkan gpu_indices holds
+ # VULKAN ORDINALS, and _amd_apu_wants_unified_memory would read them as
+ # physical HIP ids, which on a mixed host advises about an integrated GPU
+ # the model is not using or hides advice that was valid. This branch is
+ # also free (a set test against the planner's shared_gpu_ids, no torch), so
+ # a dGPU-only Vulkan launch returns before the allocation reading.
+ if is_vulkan_backend and not self._offload_target_shares_system_memory(
+ is_vulkan_backend = True,
+ shared_gpu_ids = shared_gpu_ids,
+ detected_gpus = detected_gpus,
+ gpu_indices = gpu_indices,
+ ):
+ return
+ carve_out = self._igpu_dedicated_memory_bytes(
+ gpu_indices, ordinals_are_vulkan = is_vulkan_backend
+ )
+ if not carve_out or need_bytes <= carve_out:
+ return # fits, or nothing to compare it against
+ total_mib = self._total_system_memory_mib()
+ advice = self._igpu_carveout_advice(
+ need_bytes,
+ carve_out,
+ int(total_mib) * 1024 * 1024 if total_mib else None,
+ is_igpu = True,
+ )
+ if advice is None:
+ return
+ # Only now, with a shortfall confirmed and a followable suggestion, is the
+ # probe worth paying for. AMD only: a CUDA integrated part has no readable
+ # allocation on either branch above, so carve_out is already None and we
+ # returned, and calling _integrated_cuda_unified_memory anyway would create
+ # a CUDA primary context per device for nothing. Not on Vulkan either: that
+ # launch was classified above, in the index space it actually uses.
+ if not is_vulkan_backend and not self._amd_apu_wants_unified_memory(gpu_indices):
+ return
+ # Asked last, so the common path never pays a database round trip.
+ from utils.igpu_carveout_notice_settings import notice_already_dismissed
+
+ if notice_already_dismissed(advice.get("current_gb")):
+ return
+ advice["message"] = self._igpu_carveout_advice_message(advice)
+ self._last_carveout_advice = advice
+ logger.info(
+ "Integrated GPU has %.0f GB dedicated but this model needs about "
+ "%.0f GB; suggesting %d GB.",
+ advice["current_gb"],
+ advice["needed_gb"],
+ advice["suggested_gb"],
+ )
+ except Exception:
+ logger.debug("Carve-out advice declined", exc_info = True)
+ self._last_carveout_advice = None
+
+ @property
+ def last_carveout_advice(self) -> Optional[dict]:
+ """Advice from the most recent load, or None. Read by the route."""
+ return getattr(self, "_last_carveout_advice", None)
+
+ @staticmethod
+ def _fmt_gb(value: float) -> str:
+ """A GB quantity as the user should read it: whole numbers above 10 GB, one
+ decimal below, so an APU's few-hundred-megabyte automatic allocation does not
+ print as "only about 0 GB is allocated" and read like a bug.
+ """
+ if value < 10:
+ return f"{value:.1f}".rstrip("0").rstrip(".")
+ return f"{value:.0f}"
+
+ @staticmethod
+ def _igpu_carveout_advice_message(advice: dict) -> str:
+ """The advice as user-facing prose: two sentences, because it is a toast.
+
+ Names no vendor, menu or key: the control is firmware on one machine and a
+ driver panel on the next, and a confident wrong instruction costs the user
+ more than a neutral one.
+
+ Length is a correctness constraint, not a preference, for the reason
+ xet_progress_notice.ts records: a toast tall enough to cover the controls
+ under it takes them away for as long as it is up. So it carries the four
+ numbers that make the advice actionable -- needed, allocated, suggested, left
+ for the system -- and stops.
+ """
+ fmt = LlamaCppBackend._fmt_gb
+ return (
+ f"Weights need about {fmt(advice['needed_gb'])} GB but only "
+ f"{fmt(advice['current_gb'])} GB is allocated to the integrated GPU, so the rest "
+ f"runs from slower shared memory. Raising it to {advice['suggested_gb']} GB in "
+ "your firmware or GPU control panel leaves about "
+ f"{fmt(advice['host_left_gb'])} GB for the system."
+ )
+
@staticmethod
def _host_offload_shortfall_message(
offload_bytes: int,
@@ -10804,6 +11109,9 @@ class LlamaCppBackend:
reverse -- the placement everything was priced against is the one that just
died."""
self._last_load_warning = None
+ # Same lifetime, same reason: the advice describes the placement the dying
+ # child was priced against and must not be reported against its replacement.
+ self._last_carveout_advice = None
def _record_load_warning(self, message: Optional[str]) -> None:
"""Log an advisory memory notice and keep it for the route to hand back.
@@ -10957,7 +11265,12 @@ class LlamaCppBackend:
any other notice first-notice-wins kept, is left exactly as it is. The note
follows the message: an override on a silenced load stays in the log alone,
exactly as it does on the main launch path.
+
+ The carve-out advice is dropped rather than re-priced: this replay runs
+ ``--gpu-layers 0 --device none``, so no allocation holds any of the weights.
+ Here rather than at either call site, since both reach this same state.
"""
+ self._last_carveout_advice = None
repriced = self._launch_host_shortfall_message(
cpu_cmd,
(),
@@ -23328,6 +23641,25 @@ class LlamaCppBackend:
):
"""Drop the variable THIS launch set once a respawn stops needing it."""
nonlocal _unified_env_applied
+ # Before the withdrawal test and outside it: every caller is a retry
+ # whose argv differs from what the advice was priced against, and
+ # dropping a projector or the MTP blocks can take the footprint back
+ # under the carve-out. Re-priced rather than cleared, so a spill that
+ # still stands is still reported. Computed here rather than in the
+ # argument list, which is evaluated OUTSIDE the recorder's try.
+ try:
+ _carveout_need = _unified_need_now(argv = run_cmd, mtp_engages = mtp_engages)
+ except Exception:
+ _carveout_need = None
+ self._record_carveout_advice(
+ _unified_gpu_indices,
+ _carveout_need,
+ is_vulkan_backend = is_vulkan_backend,
+ shared_gpu_ids = _shared_gpu_ids,
+ detected_gpus = _detected_gpus,
+ target_unknown = _cache_target_unknown,
+ forced_cpu = _arch_gate_forced_cpu,
+ )
if not _unified_env_applied:
return
if self._unified_memory_for_launch(
@@ -23364,6 +23696,20 @@ class LlamaCppBackend:
else "the weights outgrow the carve-out and host RAM is the larger pool",
)
+ # Whether the user could stop the spill existing at all, independent of
+ # the managed-memory decision above, which only copes with one that is.
+ # The placement facts go with it: the index space gpu_indices is in, and
+ # whether a user --device makes the child's target unknowable.
+ self._record_carveout_advice(
+ gpu_indices,
+ _unified_need,
+ is_vulkan_backend = is_vulkan_backend,
+ shared_gpu_ids = _shared_gpu_ids,
+ detected_gpus = _detected_gpus,
+ target_unknown = _cache_target_unknown,
+ forced_cpu = _arch_gate_forced_cpu,
+ )
+
# DC NVIDIA GPUs: FP32 accum (+ P2P / launch queues for multi-GPU).
# See _apply_datacenter_env; opt out with UNSLOTH_DISABLE_DC_TUNING=1.
if not is_vulkan_backend and self._apply_datacenter_env(env, gpu_indices):
@@ -23543,6 +23889,23 @@ class LlamaCppBackend:
_child_gpu_physical_ids = tuple(int(i) for i in _survivors)
# Narrower than any pin above, so it replaces it.
_launch_pinned_ids = list(_survivors)
+ # And the carve-out advice with it: upstream priced the
+ # UNNARROWED set, which _rocm_selected_pool_mib declines on a
+ # mixed host, so a model outgrowing the surviving APU's
+ # carve-out was never advised about.
+ try:
+ _gated_carveout_need = _unified_need_now(argv = cmd)
+ except Exception:
+ _gated_carveout_need = None
+ self._record_carveout_advice(
+ _survivors,
+ _gated_carveout_need,
+ is_vulkan_backend = is_vulkan_backend,
+ shared_gpu_ids = _shared_gpu_ids,
+ detected_gpus = _detected_gpus,
+ target_unknown = _cache_target_unknown,
+ forced_cpu = _arch_gate_forced_cpu,
+ )
elif manual_tensor_split_emitted:
# A manual per-GPU ratio across ALL GPUs (no explicit pick, so
# no mask above): the UI built --tensor-split in ascending
@@ -24656,6 +25019,23 @@ class LlamaCppBackend:
# From the argv, like the fit-strip above: `cmd` is what
# the respawn runs, and the record has to match it.
self._memory_state = resolve_effective_memory_state(cmd, env)
+ # And the carve-out advice with them. _begin_load_warnings()
+ # dropped the one priced for the crashed placement, but the
+ # respawn can land on a unified-memory APU whose allocation the
+ # same weights outgrow. Priced against `cmd` and _remaining, so
+ # the spill reported is this placement's.
+ try:
+ _retry_carveout_need = _unified_need_now(argv = cmd)
+ except Exception:
+ _retry_carveout_need = None
+ self._record_carveout_advice(
+ _remaining,
+ _retry_carveout_need,
+ is_vulkan_backend = is_vulkan_backend,
+ shared_gpu_ids = _shared_gpu_ids,
+ detected_gpus = _retry_rows or _detected_gpus,
+ target_unknown = _cache_target_unknown,
+ )
healthy = _spawn_and_wait(cmd, label = "-archfallback")
# Studio adds --kv-unified itself above one slot, so nothing the user
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 400a23bb9e0..11f40a4e816 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -1394,6 +1394,15 @@ class LoadResponse(_InferenceRuntimeFields):
"weights do not fit in free VRAM plus available system RAM, so llama.cpp pages "
"them in from disk and generation will be slow. The model still loaded.",
)
+ carveout_advice: Optional[dict] = Field(
+ None,
+ description = "Non-blocking advisory, or null: this machine's integrated GPU has "
+ "less memory dedicated to it than this model's weights need, so they run from "
+ "shared system memory and generation is slower than it could be. Carries "
+ "current_gb, needed_gb, suggested_gb, machine_gb, host_left_gb and a prose "
+ "message. Null once the user has dismissed it at this allocation, and on every "
+ "load where enlarging the allocation would not help. The model still loaded.",
+ )
class UnloadResponse(BaseModel):
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index e38153872b7..60e5e81167e 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -6722,6 +6722,29 @@ def _llama_runtime_fields(llama_backend: LlamaCppBackend) -> dict:
return fields
+def _live_carveout_advice(llama_backend: LlamaCppBackend) -> Optional[dict]:
+ """The recorded carve-out advice, unless it has been dismissed since the load.
+
+ The launch-time gate cannot cover the already-resident path: picking a model that
+ is still up answers from ``_reuse_loaded_gguf`` without launching, so a dismissal
+ taken in between was ignored and the notice came straight back. Re-read here
+ rather than cleared on dismissal, since the settings route holds no reference to
+ the backend.
+ """
+ advice = getattr(llama_backend, "last_carveout_advice", None)
+ if not advice:
+ return None
+ try:
+ from utils.igpu_carveout_notice_settings import notice_already_dismissed
+ if notice_already_dismissed(advice.get("current_gb")):
+ return None
+ except Exception:
+ # A failure here must not affect a load that succeeded, and showing the notice
+ # once more is the safe side.
+ pass
+ return advice
+
+
def _gguf_load_response(
llama_backend: LlamaCppBackend,
status: str,
@@ -6747,6 +6770,10 @@ def _gguf_load_response(
# weights outgrow fast memory, so the client can say why generation is slow.
# getattr: older/custom backend doubles predate this additive field.
memory_warning = getattr(llama_backend, "last_load_warning", None),
+ # Also advisory and usually None: the integrated GPU's dedicated memory is
+ # smaller than the weights. Re-checked against the dismissal store, since the
+ # already-resident path returns this response too.
+ carveout_advice = _live_carveout_advice(llama_backend),
**_llama_runtime_fields(llama_backend),
)
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
index 9060229d679..ceabaa7fe9e 100644
--- a/studio/backend/routes/settings.py
+++ b/studio/backend/routes/settings.py
@@ -624,6 +624,16 @@ class XetNoticeResponse(BaseModel):
limit: int
+class IgpuCarveoutNoticeDismissPayload(BaseModel):
+ # The allocation being dismissed at, so raising it and running short again can
+ # speak once more. Absent means "keep whatever is recorded", never lowering it.
+ current_gb: Optional[float] = None
+
+
+class IgpuCarveoutNoticeResponse(BaseModel):
+ dismissed_at_gb: Optional[float] = None
+
+
class ChatPreferencesPayload(BaseModel):
show_model_disclaimer: StrictBool
@@ -1185,6 +1195,30 @@ def post_xet_notice_reserve(
return XetNoticeResponse(**result)
[email protected]("/igpu-carveout-notice/dismiss", response_model = IgpuCarveoutNoticeResponse)
+def post_igpu_carveout_notice_dismiss(
+ payload: IgpuCarveoutNoticeDismissPayload, current_subject: str = Depends(get_current_subject)
+) -> IgpuCarveoutNoticeResponse:
+ """Stop offering the integrated-GPU memory advice at this allocation.
+
+ Stored server-side rather than in the browser: an Unsloth origin is not stable,
+ so a per-origin store hands out a fresh notice every time the port moves.
+ """
+ from utils.igpu_carveout_notice_settings import dismiss_notice
+
+ try:
+ stored = dismiss_notice(payload.current_gb)
+ except Exception as exc:
+ raise log_and_http_error(
+ exc,
+ 500,
+ safe_error_detail(exc, fallback = "Could not dismiss the GPU memory notice."),
+ event = "settings.dismiss_igpu_carveout_notice_failed",
+ log = logger,
+ ) from exc
+ return IgpuCarveoutNoticeResponse(dismissed_at_gb = stored)
+
+
@router.get("/chat-preferences", response_model = ChatPreferencesResponse)
def get_chat_preferences(
current_subject: str = Depends(get_current_subject),
diff --git a/studio/backend/tests/test_igpu_carveout_advice.py b/studio/backend/tests/test_igpu_carveout_advice.py
new file mode 100644
index 00000000000..90c06a341f6
--- /dev/null
+++ b/studio/backend/tests/test_igpu_carveout_advice.py
@@ -0,0 +1,955 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+"""Advice to enlarge an integrated GPU's dedicated memory.
+
+Measured on a Ryzen AI Max+ PRO 395 (gfx1151, 128 GB): the same 42.90 GiB model runs
+3-4x faster with the weights inside the GPU allocation than spilling out of it (decode
+11.58 -> 46.70 t/s, prefill 150.88 -> 579.68 t/s on ROCm). Worth telling the user, but
+only when raising the setting would help and only where the setting exists.
+"""
+
+import ast
+import re
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from core.inference.llama_cpp import LlamaCppBackend # noqa: E402
+
+_GB = 1024**3
+_advice = LlamaCppBackend._igpu_carveout_advice
+_message = LlamaCppBackend._igpu_carveout_advice_message
+
+
+def gb(n: float) -> int:
+ return int(n * _GB)
+
+
+class TestGating:
+ """Who must never see this."""
+
+ def test_a_discrete_gpu_is_never_advised(self):
+ # A discrete card's VRAM is fixed silicon, however badly the model fits.
+ assert _advice(gb(40), gb(8), gb(64), is_igpu = False) is None
+
+ def test_a_model_that_already_fits_says_nothing(self):
+ # 20 GB of weights inside a 32 GB allocation: nothing to fix.
+ assert _advice(gb(20), gb(32), gb(96), is_igpu = True) is None
+
+ def test_a_model_too_large_for_the_machine_says_nothing(self):
+ # 120 GB of weights on a 128 GB machine: no allocation here holds it.
+ assert _advice(gb(120), gb(32), gb(95.78), is_igpu = True) is None
+
+ def test_unknown_inputs_never_advise(self):
+ assert _advice(None, gb(32), gb(96), is_igpu = True) is None
+ assert _advice(gb(40), None, gb(96), is_igpu = True) is None
+ assert _advice(gb(40), gb(32), None, is_igpu = True) is None
+ assert _advice(gb(40), 0, gb(96), is_igpu = True) is None
+
+
+class TestTheMeasuredMachine:
+ """The Strix Halo host the 3-4x was measured on, at both carve-outs."""
+
+ def test_the_slow_configuration_is_advised(self):
+ # 32 GiB allocation, 95.78 GiB visible, a 42.90 GiB model: the 3-4x slower one.
+ got = _advice(gb(42.90), gb(32), gb(95.78), is_igpu = True)
+ assert got is not None
+ assert got["current_gb"] == 32.0
+ assert got["needed_gb"] == 42.9
+ # Smallest rung that holds the weights: every GB suggested leaves the desktop.
+ assert got["suggested_gb"] == 48
+ assert got["machine_gb"] == 127.8
+
+ def test_the_fast_configuration_is_silent(self):
+ # Same model after raising it to 96 GiB: weights resident, nothing to say.
+ assert _advice(gb(42.90), gb(96), gb(31.78), is_igpu = True) is None
+
+ def test_a_bigger_model_on_the_raised_machine_is_advised_again(self):
+ # 67.56 GiB (Qwen3.8-Flash-Next UD-IQ1_S) against a 64 GiB allocation.
+ got = _advice(gb(67.56), gb(64), gb(63.78), is_igpu = True)
+ assert got is not None and got["suggested_gb"] == 96
+
+
+class TestGeneralisesToOtherMachines:
+ """Nothing may be pinned to 128 GB or to one vendor's menu."""
+
+ def test_a_small_laptop(self):
+ # 16 GB machine, 2 GB allocated, an 8 GB model.
+ got = _advice(gb(8), gb(2), gb(14), is_igpu = True)
+ assert got is not None
+ assert got["suggested_gb"] == 8
+ assert got["host_left_gb"] == 8.0
+
+ def test_a_large_workstation(self):
+ # 512 GB machine, 32 GB allocated, a 300 GB model.
+ got = _advice(gb(300), gb(32), gb(480), is_igpu = True)
+ assert got is not None
+ assert got["suggested_gb"] == 384
+ assert got["machine_gb"] == 512.0
+
+ def test_the_host_always_keeps_a_share(self):
+ # A fifth of the machine, or 8 GB, whichever is larger, stays with the OS.
+ for machine, carve, need in ((64, 8, 40), (128, 32, 80), (256, 16, 150)):
+ got = _advice(gb(need), gb(carve), gb(machine - carve), is_igpu = True)
+ assert got is not None, (machine, carve, need)
+ assert got["suggested_gb"] <= machine - max(8, machine * 0.20)
+
+ def test_a_suggestion_is_always_an_increase(self):
+ # A rung at or below what is already set is not advice.
+ got = _advice(gb(33), gb(32), gb(95.78), is_igpu = True)
+ assert got is None or got["suggested_gb"] > got["current_gb"]
+
+ def test_the_ladder_is_ascending_and_bounded(self):
+ for cap in (7, 16, 100, 1000):
+ rungs = LlamaCppBackend._igpu_carveout_ladder_gb(cap)
+ assert rungs == sorted(rungs)
+ assert all(r <= cap for r in rungs)
+
+
+class TestRecordingItOnALoad:
+ """The launch-site wiring: what actually reaches the client."""
+
+ @staticmethod
+ def _backend(
+ monkeypatch,
+ *,
+ is_igpu = True,
+ carve_bytes = 32 * _GB,
+ total_mib = 95 * 1024,
+ ):
+ # __new__: no real server, config or filesystem. The method under test only
+ # reads the stubs below and writes one attribute.
+ backend = LlamaCppBackend.__new__(LlamaCppBackend)
+ monkeypatch.setattr(
+ LlamaCppBackend, "_amd_apu_wants_unified_memory", staticmethod(lambda _i = None: is_igpu)
+ )
+ monkeypatch.setattr(
+ LlamaCppBackend, "_integrated_cuda_unified_memory", staticmethod(lambda _i = None: False)
+ )
+ monkeypatch.setattr(
+ LlamaCppBackend,
+ "_igpu_dedicated_memory_bytes",
+ staticmethod(lambda _i = None, **_kwargs: carve_bytes),
+ )
+ monkeypatch.setattr(
+ LlamaCppBackend, "_total_system_memory_mib", staticmethod(lambda: total_mib)
+ )
+ return backend
+
+ def test_a_spilling_load_records_advice_with_prose(self, monkeypatch):
+ backend = self._backend(monkeypatch)
+ backend._record_carveout_advice(None, gb(42.90))
+ advice = backend.last_carveout_advice
+ assert advice is not None
+ assert advice["suggested_gb"] == 48
+ assert "48 GB" in advice["message"]
+
+ def test_a_discrete_gpu_records_nothing(self, monkeypatch):
+ backend = self._backend(monkeypatch, is_igpu = False)
+ backend._record_carveout_advice(None, gb(42.90))
+ assert backend.last_carveout_advice is None
+
+ def test_an_unknown_model_size_records_nothing(self, monkeypatch):
+ # _unified_need is None unless the launch forces a full offload.
+ backend = self._backend(monkeypatch)
+ backend._record_carveout_advice(None, None)
+ assert backend.last_carveout_advice is None
+
+ def test_an_unreadable_allocation_records_nothing(self, monkeypatch):
+ backend = self._backend(monkeypatch, carve_bytes = None)
+ backend._record_carveout_advice(None, gb(42.90))
+ assert backend.last_carveout_advice is None
+
+ def test_a_dismissed_notice_is_not_recorded_again(self, monkeypatch):
+ from utils.igpu_carveout_notice_settings import dismiss_notice
+
+ backend = self._backend(monkeypatch)
+ dismiss_notice(32.0)
+ backend._record_carveout_advice(None, gb(42.90))
+ assert backend.last_carveout_advice is None
+
+ def test_a_raised_allocation_speaks_again_after_dismissal(self, monkeypatch):
+ # Dismissed at 32 GB, user raised it to 64 GB, still short: say it once more.
+ from utils.igpu_carveout_notice_settings import dismiss_notice
+
+ dismiss_notice(32.0)
+ backend = self._backend(monkeypatch, carve_bytes = 64 * _GB, total_mib = int(63.78 * 1024))
+ backend._record_carveout_advice(None, gb(67.56))
+ assert backend.last_carveout_advice is not None
+
+ def test_a_broken_reading_never_breaks_the_load(self, monkeypatch):
+ def boom(_i = None):
+ raise RuntimeError("driver went away")
+
+ backend = self._backend(monkeypatch)
+ monkeypatch.setattr(LlamaCppBackend, "_igpu_dedicated_memory_bytes", staticmethod(boom))
+ backend._record_carveout_advice(None, gb(42.90)) # must not raise
+ assert backend.last_carveout_advice is None
+
+
+class TestTheMessage:
+ """What the user reads."""
+
+ def test_it_names_the_numbers_and_the_cost(self):
+ msg = _message(_advice(gb(42.90), gb(32), gb(95.78), is_igpu = True))
+ assert "43 GB" in msg and "32 GB" in msg and "48 GB" in msg
+ assert "80 GB" in msg # what the host keeps: the trade-off, stated
+
+ def test_it_says_where_the_setting_lives_without_claiming_a_menu(self):
+ # Firmware on one machine, a driver panel on the next, under different names.
+ # Naming both and neither specifically is as far as this can honestly go.
+ msg = _message(_advice(gb(42.90), gb(32), gb(95.78), is_igpu = True))
+ assert "firmware" in msg and "control panel" in msg
+ # No menu path, key or control name is claimed.
+ for invented in ("F10", "UMA Frame Buffer", "Variable Graphics Memory", "Advanced >"):
+ assert invented not in msg
+
+ def test_it_stays_short_enough_for_a_toast(self):
+ # A tall toast covers the controls under it for as long as it is up (see
+ # xet-progress-notice.ts, #9293). Bounded at the widest plausible reading,
+ # since a 4-digit machine renders longer than the development one.
+ widest = _message(_advice(gb(400), gb(0.5), gb(1023.5), is_igpu = True))
+ assert len(widest) <= 260, (len(widest), widest)
+ # Two sentences, and no paragraph breaks: the dialog's three-paragraph body
+ # is what this replaced.
+ assert "\n" not in widest
+
+ def test_it_names_no_vendor(self):
+ msg = _message(_advice(gb(42.90), gb(32), gb(95.78), is_igpu = True))
+ for vendor in ("AMD", "Adrenalin", "Intel", "NVIDIA", "HP", "Ryzen", "Radeon"):
+ assert vendor not in msg
+
+
+class TestPropertiesOverEveryPlausibleMachine:
+ """Swept rather than exampled. These caught three defects the chosen examples did
+ not: a negative allocation read as truthy, a sub-1 GB allocation printing as
+ "0 GB", and the integrated-GPU probe running on loads that could never advise."""
+
+ MACHINES_GB = [8, 12, 16, 24, 32, 48, 64, 96, 128, 192, 256, 512, 1024]
+ ALLOCATIONS_GB = [0.125, 0.5, 1, 2, 4, 8, 16, 24, 32, 48, 64, 96]
+ MODELS_GB = [0.5, 2, 7, 13, 20, 30, 43, 60, 80, 110, 200, 400]
+
+ def _cases(self):
+ for machine in self.MACHINES_GB:
+ for carve in self.ALLOCATIONS_GB:
+ if carve >= machine:
+ continue
+ host = gb(machine - carve)
+ for model in self.MODELS_GB:
+ yield machine, carve, model, host
+
+ def test_following_the_advice_always_ends_it(self):
+ # An advisory that survives being followed is a nag, and one that cannot be
+ # satisfied is a bug.
+ checked = 0
+ for machine, carve, model, host in self._cases():
+ first = _advice(gb(model), gb(carve), host, is_igpu = True)
+ if first is None:
+ continue
+ applied = float(first["suggested_gb"])
+ again = _advice(gb(model), gb(applied), gb(machine - applied), is_igpu = True)
+ assert again is None, (machine, carve, model, first, again)
+ checked += 1
+ assert checked > 200, checked
+
+ def test_the_host_always_keeps_a_workable_share(self):
+ for machine, carve, model, host in self._cases():
+ result = _advice(gb(model), gb(carve), host, is_igpu = True)
+ if result is None:
+ continue
+ floor = max(8, result["machine_gb"] * 0.20)
+ assert result["host_left_gb"] >= floor - 0.15, (result, floor)
+
+ def test_the_suggestion_is_always_an_increase_that_covers_the_model(self):
+ for machine, carve, model, host in self._cases():
+ result = _advice(gb(model), gb(carve), host, is_igpu = True)
+ if result is None:
+ continue
+ assert result["suggested_gb"] > result["current_gb"], result
+ assert result["suggested_gb"] >= result["needed_gb"] - 0.05, result
+
+ def test_a_discrete_gpu_is_never_advised_anywhere_in_the_sweep(self):
+ for machine, carve, model, host in self._cases():
+ assert _advice(gb(model), gb(carve), host, is_igpu = False) is None
+
+ @pytest.mark.parametrize("bad", [-1, -(10**12), 0, None, float("nan"), float("inf")])
+ def test_a_nonsense_reading_produces_no_advice(self, bad):
+ # -1 is truthy, so a bare falsiness test produced confident wrong advice.
+ assert _advice(bad, gb(32), gb(96), is_igpu = True) is None
+ assert _advice(gb(43), bad, gb(96), is_igpu = True) is None
+ assert _advice(gb(43), gb(32), bad, is_igpu = True) is None
+
+
+class TestASmallAutomaticAllocation:
+ """An APU left on its automatic setting reports a few hundred megabytes, not
+ a round number of GB. The DirectX record really does read that way."""
+
+ def test_it_is_described_rather_than_rounded_to_zero(self):
+ result = _advice(gb(12), gb(0.5), gb(31.5), is_igpu = True)
+ assert result is not None
+ msg = _message(result)
+ assert "0.5 GB" in msg, msg
+ assert not re.search(r"(?<![\d.])0 GB", msg), msg
+
+ def test_no_sweep_case_prints_a_zero_or_negative_quantity(self):
+ for carve in (0.125, 0.25, 0.5, 0.75, 1, 2):
+ for model in (1, 4, 12, 30):
+ result = _advice(gb(model), gb(carve), gb(64 - carve), is_igpu = True)
+ if result is None:
+ continue
+ msg = _message(result)
+ assert not re.search(r"(?<![\d.])0 GB", msg), msg
+ assert not re.search(r"-\d", msg), msg
+
+
+class TestTheSmallAllocationsTheLadderMustOffer:
+ """An APU on its automatic setting reports a few hundred megabytes."""
+
+ def test_the_low_rungs_exist(self):
+ # Firmware offers 1 and 2 GB, so a ladder starting at 4 could only advise
+ # past them.
+ assert LlamaCppBackend._igpu_carveout_ladder_gb(8) == [1, 2, 3, 4, 6, 8]
+
+ def test_a_small_model_is_advised_onto_the_smallest_rung_that_fits(self):
+ # 1 GB allocated, 2 GB of weights, a 16 GB machine.
+ advice = _advice(gb(2), gb(1), gb(15), is_igpu = True)
+ assert advice is not None
+ assert advice["suggested_gb"] == 2
+ assert advice["host_left_gb"] == 14.0
+
+ def test_the_measured_machine_is_unchanged(self):
+ # The low rungs must not perturb the case this feature was built for.
+ advice = _advice(gb(42.90), gb(32), gb(95.78), is_igpu = True)
+ assert advice is not None and advice["suggested_gb"] == 48
+
+
+class TestTheLadderTerminates:
+ """It is a `while` loop on the model-load path, and the caller's try/except
+ cannot rescue a hang."""
+
+ @pytest.mark.parametrize("cap", [float("inf"), float("-inf"), float("nan"), 0, -5, 2**60])
+ def test_it_returns_promptly_for_any_cap(self, cap):
+ import threading
+
+ done = threading.Event()
+
+ def run():
+ LlamaCppBackend._igpu_carveout_ladder_gb(cap)
+ done.set()
+
+ thread = threading.Thread(target = run, daemon = True)
+ thread.start()
+ thread.join(timeout = 5)
+ assert done.is_set(), f"ladder({cap}) did not terminate"
+
+
+class TestTheRungTheUserIsAlreadyOn:
+ """A driver reports the pool it kept, not the number in the firmware menu."""
+
+ def test_a_reading_just_under_its_own_rung_is_not_advised_back_to_it(self):
+ # 95.83 GB is the 96 GB setting as the driver reports it, so the rung covering
+ # a 95.9 GB model is 96: the setting already in force.
+ assert _advice(gb(95.9), gb(95.83), gb(31.78), is_igpu = True) is None
+
+ def test_the_next_real_rung_is_still_advised(self):
+ # The slack must not swallow a genuine step up: a 32 GB reading still earns 48.
+ assert _advice(gb(42.9), gb(32), gb(95.8), is_igpu = True)["suggested_gb"] == 48
+
+ def test_the_slack_is_narrower_than_the_gap_between_rungs(self):
+ # 0.5 GB of drift, against a ladder whose closest pair is 4 -> 6.
+ assert _advice(gb(5), gb(4.4), gb(27.6), is_igpu = True)["suggested_gb"] == 6
+
+
+class TestThePlacementItAdvisesAbout:
+ """Which device the advice is about, in the index space that device is named in.
+
+ A Vulkan launch numbers devices with VULKAN ORDINALS; the ROCm gate reads the same
+ integers as physical HIP ids. On a mixed APU/dGPU host that is how a dGPU load
+ earns advice to resize an integrated GPU it never touched.
+ """
+
+ @staticmethod
+ def _backend(
+ monkeypatch,
+ *,
+ probes,
+ rocm_gate = True,
+ carve_bytes = 32 * _GB,
+ ):
+ backend = LlamaCppBackend.__new__(LlamaCppBackend)
+
+ def _read(_i = None, **_kwargs):
+ probes.append(_i)
+ return carve_bytes
+
+ monkeypatch.setattr(LlamaCppBackend, "_igpu_dedicated_memory_bytes", staticmethod(_read))
+ monkeypatch.setattr(
+ LlamaCppBackend,
+ "_amd_apu_wants_unified_memory",
+ staticmethod(lambda _i = None: rocm_gate),
+ )
+ monkeypatch.setattr(
+ LlamaCppBackend, "_total_system_memory_mib", staticmethod(lambda: 95 * 1024)
+ )
+ return backend
+
+ def test_a_vulkan_launch_on_a_discrete_device_is_never_even_priced(self, monkeypatch):
+ # Ordinal 1 is not in the planner's shared set, so this offloads to a discrete
+ # card. No advice, and no allocation reading either: on Linux that falls
+ # through to the ROCm pool, which imports torch for a load that cannot be
+ # advised.
+ probes = []
+ backend = self._backend(monkeypatch, probes = probes)
+ backend._record_carveout_advice(
+ [1],
+ gb(42.90),
+ is_vulkan_backend = True,
+ shared_gpu_ids = {0},
+ detected_gpus = [(0, 0), (1, 0)],
+ )
+ assert backend.last_carveout_advice is None
+ assert probes == [], "the allocation was read for a device that shares nothing"
+
+ def test_a_vulkan_launch_on_the_shared_device_is_advised(self, monkeypatch):
+ # The ROCm gate answers False, having read the Vulkan ordinal as a physical id.
+ # The Vulkan classification applies, and it says this device shares memory.
+ backend = self._backend(monkeypatch, probes = [], rocm_gate = False)
+ backend._record_carveout_advice(
+ [0],
+ gb(42.90),
+ is_vulkan_backend = True,
+ shared_gpu_ids = {0},
+ detected_gpus = [(0, 0)],
+ )
+ advice = backend.last_carveout_advice
+ assert advice is not None and advice["suggested_gb"] == 48
+
+ def test_an_unknown_vulkan_inventory_says_nothing(self, monkeypatch):
+ # Fails closed like every other reading here: no shared set, no advice.
+ probes = []
+ backend = self._backend(monkeypatch, probes = probes)
+ backend._record_carveout_advice(
+ [0],
+ gb(42.90),
+ is_vulkan_backend = True,
+ shared_gpu_ids = None,
+ detected_gpus = [],
+ )
+ assert backend.last_carveout_advice is None
+ assert probes == []
+
+ def test_a_user_device_override_declines(self, monkeypatch):
+ # With no gpu_ids a user --device wins last-wins over the generated pin, so the
+ # placement this would describe is not the one that runs. The cache tuning
+ # declines for the same reason and with the same test.
+ probes = []
+ backend = self._backend(monkeypatch, probes = probes)
+ backend._record_carveout_advice([0], gb(42.90), target_unknown = True)
+ assert backend.last_carveout_advice is None
+ assert probes == []
+
+ def test_a_non_vulkan_launch_still_uses_the_rocm_gate(self, monkeypatch):
+ # The ROCm path is unchanged, gate still asked last, after the shortfall.
+ backend = self._backend(monkeypatch, probes = [], rocm_gate = False)
+ backend._record_carveout_advice([0], gb(42.90))
+ assert backend.last_carveout_advice is None
+
+
+class TestTheCpuOnlyReplay:
+ """A Vulkan crash replays with --gpu-layers 0 --device none."""
+
+ def test_the_advice_does_not_survive_it(self, monkeypatch):
+ # No allocation holds any weights after this replay. Both CPU-fallback call
+ # sites reach this one function, which is why the clear lives here.
+ backend = LlamaCppBackend.__new__(LlamaCppBackend)
+ backend._last_carveout_advice = {"current_gb": 32.0, "suggested_gb": 48}
+ backend._last_load_warning = None
+ monkeypatch.setattr(LlamaCppBackend, "_launch_host_shortfall_message", lambda *a, **k: None)
+ monkeypatch.setattr(LlamaCppBackend, "_record_load_warning", lambda self, msg: None)
+ backend._reprice_after_cpu_only_fallback(
+ host_msg = None, cpu_cmd = ["llama-server"], env = {}, avail_mib = 1024
+ )
+ assert backend.last_carveout_advice is None
+
+
+class TestTheResponseRechecksTheDismissal:
+ """The already-resident path returns a cached payload, not a fresh launch."""
+
+ @staticmethod
+ def _backend(advice):
+ backend = LlamaCppBackend.__new__(LlamaCppBackend)
+ backend._last_carveout_advice = advice
+ return backend
+
+ def test_a_dismissed_notice_is_stripped_from_the_response(self):
+ # The already-resident path never runs the launch-time gate, so the toast came
+ # back on every later load of the same model.
+ from routes.inference import _live_carveout_advice
+ from utils.igpu_carveout_notice_settings import dismiss_notice
+
+ advice = {"current_gb": 32.0, "suggested_gb": 48, "message": "..."}
+ backend = self._backend(advice)
+ assert _live_carveout_advice(backend) == advice
+ dismiss_notice(32.0)
+ assert _live_carveout_advice(backend) is None
+
+ def test_a_larger_allocation_still_speaks(self):
+ # Dismissed at 32, now running 64 and short again: the launch path's rule.
+ from routes.inference import _live_carveout_advice
+ from utils.igpu_carveout_notice_settings import dismiss_notice
+
+ dismiss_notice(32.0)
+ backend = self._backend({"current_gb": 64.0, "suggested_gb": 96, "message": "..."})
+ assert _live_carveout_advice(backend) is not None
+
+ def test_no_advice_stays_no_advice(self):
+ from routes.inference import _live_carveout_advice
+ assert _live_carveout_advice(self._backend(None)) is None
+
+
+class TestTheArchitectureGatedCpuLaunch:
+ """Every GPU unsupported by this llama.cpp build, so the child runs on the CPU."""
+
+ def test_a_forced_cpu_launch_is_never_advised(self, monkeypatch):
+ # Priced before the env block masks every device away, so the argv still reads
+ # as a full GPU offload. Without the gate an unsupported APU's CPU-only load
+ # returns a toast about a GPU this build cannot use at all.
+ probes = []
+
+ def _read(_i = None, **_kwargs):
+ probes.append(_i)
+ return 32 * _GB
+
+ backend = LlamaCppBackend.__new__(LlamaCppBackend)
+ monkeypatch.setattr(LlamaCppBackend, "_igpu_dedicated_memory_bytes", staticmethod(_read))
+ monkeypatch.setattr(
+ LlamaCppBackend, "_amd_apu_wants_unified_memory", staticmethod(lambda _i = None: True)
+ )
+ monkeypatch.setattr(
+ LlamaCppBackend, "_total_system_memory_mib", staticmethod(lambda: 95 * 1024)
+ )
+ backend._record_carveout_advice([0], gb(42.90), forced_cpu = True)
+ assert backend.last_carveout_advice is None
+ assert probes == [], "the allocation was read for a launch that reaches no GPU"
+
+
+class TestEveryCallSitePricesThePlacementItRuns:
+ """The gate and the retry, pinned at the call sites rather than in prose.
+
+ Both are one keyword argument, and both were missing at first: a launch reaching
+ no GPU was advised to enlarge one, and a crash retry landing on a different GPU
+ said nothing about it.
+ """
+
+ @staticmethod
+ def _calls():
+ source = Path(sys.modules[LlamaCppBackend.__module__].__file__)
+ tree = ast.parse(source.read_text(encoding = "utf-8"))
+ return [
+ node
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Attribute)
+ and node.func.attr == "_record_carveout_advice"
+ ]
+
+ def test_the_launch_call_sites_pass_the_forced_cpu_gate(self):
+ by_target = {
+ ast.unparse(call.args[0]): {kw.arg for kw in call.keywords} for call in self._calls()
+ }
+ assert "forced_cpu" in by_target["gpu_indices"]
+ assert "forced_cpu" in by_target["_unified_gpu_indices"]
+
+ def test_the_proactive_arch_gate_reprices_against_the_survivors(self):
+ # The gate narrows onto supported devices before the spawn, and
+ # _rocm_selected_pool_mib declines the unnarrowed set on a mixed host, so a
+ # model outgrowing the surviving APU's carve-out was never advised about.
+ by_target = {
+ ast.unparse(call.args[0]): {kw.arg for kw in call.keywords} for call in self._calls()
+ }
+ assert (
+ "_survivors" in by_target
+ ), "the proactive architecture gate does not re-price the carve-out advice"
+ assert "forced_cpu" in by_target["_survivors"]
+
+ def test_the_architecture_retry_reprices_against_the_surviving_gpus(self):
+ # _begin_load_warnings() drops the advice priced for the crashed placement, but
+ # the respawn can land on an APU the same weights outgrow, so the retry has to
+ # price it again rather than only clear.
+ by_target = {
+ ast.unparse(call.args[0]): {kw.arg for kw in call.keywords} for call in self._calls()
+ }
+ assert (
+ "_remaining" in by_target
+ ), "the arch-crash retry does not re-price the carve-out advice"
+ assert "shared_gpu_ids" in by_target["_remaining"]
+
+
+class TestWhichAdapterTheAllocationBelongsTo:
+ """A registry record is only the integrated GPU's when nothing else could be."""
+
+ @staticmethod
+ def _with_records(monkeypatch, by_vendor):
+ import utils.hardware.hardware as hw
+
+ def _records(vendor_id = hw._AMD_PCI_VENDOR_ID, *, distinguish_failure = False):
+ answer = by_vendor.get(vendor_id, {})
+ if answer is None and not distinguish_failure:
+ return {}
+ return answer
+
+ monkeypatch.setattr(hw, "_windows_amd_adapter_records_by_luid", _records)
+ monkeypatch.setattr(
+ LlamaCppBackend, "_rocm_selected_pool_mib", staticmethod(lambda _i = None: None)
+ )
+
+ def test_one_adapter_is_the_one_being_advised_about(self, monkeypatch):
+ import utils.hardware.hardware as hw
+ self._with_records(
+ monkeypatch, {hw._AMD_PCI_VENDOR_ID: {1: {"dedicated_memory_bytes": 32 * _GB}}}
+ )
+ assert LlamaCppBackend._igpu_dedicated_memory_bytes([0]) == 32 * _GB
+
+ def test_an_intel_igpu_beside_a_discrete_radeon_declines(self, monkeypatch):
+ # What the AMD-only query got wrong: the Intel iGPU is the shared one, but the
+ # single AMD record is the discrete card, whose fixed VRAM was then quoted as
+ # the integrated GPU's allocation.
+ import utils.hardware.hardware as hw
+ self._with_records(
+ monkeypatch,
+ {
+ hw._AMD_PCI_VENDOR_ID: {1: {"dedicated_memory_bytes": 16 * _GB}},
+ hw._INTEL_PCI_VENDOR_ID: {2: {"dedicated_memory_bytes": 2 * _GB}},
+ },
+ )
+ assert LlamaCppBackend._igpu_dedicated_memory_bytes([0]) is None
+
+ def test_an_intel_only_host_is_counted_but_never_quoted(self, monkeypatch):
+ # Intel is read for the COUNT, which makes the attribution above safe, never
+ # for the answer: on Intel UMA the DirectX value is a small dedicated block
+ # beside memory the driver hands out dynamically.
+ import utils.hardware.hardware as hw
+ self._with_records(
+ monkeypatch, {hw._INTEL_PCI_VENDOR_ID: {2: {"dedicated_memory_bytes": 8 * _GB}}}
+ )
+ assert LlamaCppBackend._igpu_dedicated_memory_bytes([0]) is None
+
+ def test_an_adapter_with_no_readable_allocation_still_counts(self, monkeypatch):
+ # The count IS the attribution test: filtering out an APU record with no
+ # dedicated-memory value left the discrete Radeon beside it as the only
+ # candidate, with its fixed 16 GB quoted as the APU's carve-out.
+ import utils.hardware.hardware as hw
+ self._with_records(
+ monkeypatch,
+ {
+ hw._AMD_PCI_VENDOR_ID: {
+ 1: {"gfx": "gfx1151"},
+ 2: {"dedicated_memory_bytes": 16 * _GB},
+ }
+ },
+ )
+ assert LlamaCppBackend._igpu_dedicated_memory_bytes([0]) is None
+
+ def test_a_vendor_the_registry_could_not_read_fails_closed(self, monkeypatch):
+ # An incomplete inventory cannot say the adapter it did see is the only one.
+ import utils.hardware.hardware as hw
+ self._with_records(
+ monkeypatch,
+ {
+ hw._AMD_PCI_VENDOR_ID: {1: {"dedicated_memory_bytes": 32 * _GB}},
+ hw._INTEL_PCI_VENDOR_ID: None,
+ },
+ )
+ assert LlamaCppBackend._igpu_dedicated_memory_bytes([0]) is None
+
+ def test_no_registry_record_at_all_falls_through_to_rocm(self, monkeypatch):
+ # The Linux path: no adapter records, so the ROCm pool is the reading, and the
+ # vendor rule above must not swallow it.
+ self._with_records(monkeypatch, {})
+ monkeypatch.setattr(
+ LlamaCppBackend, "_rocm_selected_pool_mib", staticmethod(lambda _i = None: 32 * 1024)
+ )
+ assert LlamaCppBackend._igpu_dedicated_memory_bytes([0]) == 32 * _GB
+
+
+class TestTheRoutingIsDeterministic:
+ """Every gate this advisory routes through, enumerated rather than sampled.
+
+ Seven interacting inputs: a Vulkan launch is classified by the planner's shared
+ set and a non-Vulkan one by the ROCm unified-memory ids, two gates decline before
+ any reading is taken, and the dismissal is asked last. Each was added for a defect
+ found one at a time, so the value is the whole product rather than the cases
+ anyone thought to write.
+
+ Nothing here touches the host -- both classifiers, the allocation reading and the
+ total memory are pinned -- so the table is the same everywhere.
+ """
+
+ _NEED = gb(42.90)
+ _HOST_MIB = 95 * 1024
+ # None is "no reading", 64 GB holds the weights, 32 GB is the measured shortfall.
+ _CARVE_OUTS = (None, 64 * _GB, 32 * _GB)
+
+ @staticmethod
+ def _expected(
+ *, carve, is_vulkan, shared_ids, unified_ids, forced_cpu, target_unknown, dismissed
+ ) -> bool:
+ """The routing, written out independently of the code under test."""
+ if forced_cpu or target_unknown:
+ return False
+ if is_vulkan:
+ if not shared_ids or 0 not in shared_ids:
+ return False
+ elif 0 not in unified_ids:
+ return False
+ if carve is None or TestTheRoutingIsDeterministic._NEED <= carve:
+ return False
+ return not dismissed
+
+ def _run(self, monkeypatch, **case):
+ probes = []
+
+ def _read(_i = None, **_kwargs):
+ probes.append(_i)
+ return case["carve"]
+
+ monkeypatch.setattr(LlamaCppBackend, "_igpu_dedicated_memory_bytes", staticmethod(_read))
+ monkeypatch.setattr(
+ LlamaCppBackend,
+ "_rocm_unified_memory_gpu_ids",
+ staticmethod(lambda: set(case["unified_ids"])),
+ )
+ monkeypatch.setattr(
+ LlamaCppBackend, "_total_system_memory_mib", staticmethod(lambda: self._HOST_MIB)
+ )
+ import utils.igpu_carveout_notice_settings as notice_settings
+
+ monkeypatch.setattr(
+ notice_settings, "notice_already_dismissed", lambda _gb: case["dismissed"]
+ )
+
+ backend = LlamaCppBackend.__new__(LlamaCppBackend)
+ backend._record_carveout_advice(
+ [0],
+ self._NEED,
+ is_vulkan_backend = case["is_vulkan"],
+ shared_gpu_ids = case["shared_ids"],
+ detected_gpus = [(0, 0)],
+ target_unknown = case["target_unknown"],
+ forced_cpu = case["forced_cpu"],
+ )
+ return backend.last_carveout_advice, probes
+
+ @staticmethod
+ def _cases():
+ import itertools
+ for (
+ carve,
+ is_vulkan,
+ shared_ids,
+ unified_ids,
+ forced_cpu,
+ target_unknown,
+ dismissed,
+ ) in itertools.product(
+ TestTheRoutingIsDeterministic._CARVE_OUTS,
+ (False, True),
+ (None, frozenset(), frozenset({0}), frozenset({1})),
+ (frozenset(), frozenset({0})),
+ (False, True),
+ (False, True),
+ (False, True),
+ ):
+ yield {
+ "carve": carve,
+ "is_vulkan": is_vulkan,
+ "shared_ids": shared_ids,
+ "unified_ids": unified_ids,
+ "forced_cpu": forced_cpu,
+ "target_unknown": target_unknown,
+ "dismissed": dismissed,
+ }
+
+ def test_every_combination_routes_the_way_the_table_says(self, monkeypatch):
+ wrong = []
+ spoke = 0
+ for case in self._cases():
+ advice, _probes = self._run(monkeypatch, **case)
+ expected = self._expected(**case)
+ spoke += bool(advice)
+ if bool(advice) != expected:
+ wrong.append((case, bool(advice), expected))
+ assert not wrong, f"{len(wrong)} of the routing cases disagree: {wrong[:3]}"
+ # A table where nothing ever speaks would pass every assertion above.
+ assert spoke, "no combination produced advice, so this proves nothing"
+
+ def test_the_same_inputs_always_reach_the_same_answer(self, monkeypatch):
+ # Nothing here is time, order or host dependent, message included.
+ first = [self._run(monkeypatch, **case)[0] for case in self._cases()]
+ second = [self._run(monkeypatch, **case)[0] for case in self._cases()]
+ assert first == second
+
+ def test_a_declined_placement_is_never_priced(self, monkeypatch):
+ # The cheap gates all sit BEFORE the allocation reading, which on Linux imports
+ # torch. A load that could never be advised must not pay for it.
+ for case in self._cases():
+ declined_early = (
+ case["forced_cpu"]
+ or case["target_unknown"]
+ or (case["is_vulkan"] and (not case["shared_ids"] or 0 not in case["shared_ids"]))
+ )
+ if not declined_early:
+ continue
+ _advice, probes = self._run(monkeypatch, **case)
+ assert probes == [], f"the allocation was read for a declined load: {case}"
+
+
+class TestTheAdvisoryCannotReachTheLaunch:
+ """Static, because "it only sets a field" is a claim about every path at once.
+
+ A test can only show that the paths it drives change nothing. These read the
+ module instead: what the recorder may write, and what the launch may do with what
+ it returns.
+ """
+
+ @staticmethod
+ def _module_tree():
+ source = Path(sys.modules[LlamaCppBackend.__module__].__file__)
+ return ast.parse(source.read_text(encoding = "utf-8"))
+
+ @staticmethod
+ def _recorder(tree):
+ for node in ast.walk(tree):
+ if isinstance(node, ast.FunctionDef) and node.name == "_record_carveout_advice":
+ return node
+ raise AssertionError("_record_carveout_advice is gone")
+
+ def test_it_writes_one_attribute_and_no_other(self):
+ # Any other `self.x = ...` here would be launch state written by an advisory.
+ written = set()
+ for node in ast.walk(self._recorder(self._module_tree())):
+ targets = []
+ if isinstance(node, ast.Assign):
+ targets = node.targets
+ elif isinstance(node, (ast.AugAssign, ast.AnnAssign)):
+ targets = [node.target]
+ for target in targets:
+ if (
+ isinstance(target, ast.Attribute)
+ and isinstance(target.value, ast.Name)
+ and target.value.id == "self"
+ ):
+ written.add(target.attr)
+ assert written == {"_last_carveout_advice"}, written
+
+ def test_no_call_site_computes_anything_of_its_own(self):
+ # Arguments are evaluated OUTSIDE the recorder's try/except, so a call in the
+ # argument list is a way for an advisory to raise into a launch.
+ tree = self._module_tree()
+ calls = [
+ node
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Attribute)
+ and node.func.attr == "_record_carveout_advice"
+ ]
+ assert calls
+
+ def cannot_raise(node) -> bool:
+ # A name, a constant, an attribute of one, or an `or` over those. Anything
+ # else -- a call above all -- is work outside the recorder's guard.
+ if isinstance(node, (ast.Name, ast.Constant)):
+ return True
+ if isinstance(node, ast.Attribute):
+ return cannot_raise(node.value)
+ if isinstance(node, ast.BoolOp):
+ return all(cannot_raise(value) for value in node.values)
+ return False
+
+ for call in calls:
+ for argument in [*call.args, *(kw.value for kw in call.keywords)]:
+ assert cannot_raise(
+ argument
+ ), f"an advisory call site evaluates {ast.unparse(argument)}"
+
+ def test_no_caller_can_branch_on_what_it_returns(self):
+ # Every call is a bare expression statement, so a launch cannot branch on it.
+ tree = self._module_tree()
+ statements = {
+ id(node.value)
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Expr) and isinstance(node.value, ast.Call)
+ }
+ calls = [
+ node
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Attribute)
+ and node.func.attr == "_record_carveout_advice"
+ ]
+ assert calls, "the recorder is never called"
+ assert all(
+ id(call) in statements for call in calls
+ ), "a call site uses the return value of an advisory"
+
+
+class TestTheIndexSpaceTheAllocationIsReadIn:
+ """The Linux fallback reads HIP ids, and a Vulkan launch does not name devices that way.
+
+ Two reasons it must not run there. `_rocm_selected_pool_mib` compares its argument
+ with physical HIP ids, so Vulkan ordinals would land on another device wherever
+ the enumerations differ. And the reading creates a HIP primary context in the
+ backend process -- about 800 MiB, out of the pool the advice would then call too
+ small. The Windows registry answer is unaffected: a few winreg queries, no ordinal.
+ """
+
+ @staticmethod
+ def _readers(
+ monkeypatch,
+ *,
+ pool_mib = 32 * 1024,
+ records = None,
+ ):
+ """Record what the ROCm pool reader is asked, and stub the Windows registry."""
+ asked = []
+
+ def _pool(indices = None):
+ asked.append(indices)
+ return pool_mib
+
+ monkeypatch.setattr(LlamaCppBackend, "_rocm_selected_pool_mib", staticmethod(_pool))
+ import utils.hardware.hardware as hw
+
+ monkeypatch.setattr(
+ hw,
+ "_windows_amd_adapter_records_by_luid",
+ lambda vendor_id = hw._AMD_PCI_VENDOR_ID, **_kw: (records or {}).get(vendor_id, {}),
+ )
+ return asked
+
+ def test_a_vulkan_launch_never_reaches_the_hip_reader(self, monkeypatch):
+ asked = self._readers(monkeypatch)
+ got = LlamaCppBackend._igpu_dedicated_memory_bytes([1], ordinals_are_vulkan = True)
+ assert got is None
+ assert asked == [], f"a Vulkan launch paid for a HIP context: {asked}"
+
+ def test_a_vulkan_launch_still_reads_the_windows_registry(self, monkeypatch):
+ # The half that must keep working: per adapter, and never touches an ordinal.
+ import utils.hardware.hardware as hw
+
+ asked = self._readers(
+ monkeypatch,
+ records = {hw._AMD_PCI_VENDOR_ID: {1: {"dedicated_memory_bytes": 32 * _GB}}},
+ )
+ got = LlamaCppBackend._igpu_dedicated_memory_bytes([0], ordinals_are_vulkan = True)
+ assert got == 32 * _GB
+ assert asked == []
+
+ def test_a_non_vulkan_launch_still_scopes_by_physical_id(self, monkeypatch):
+ # Those integers ARE HIP ids, and narrowing keeps a dGPU out of the answer.
+ asked = self._readers(monkeypatch)
+ LlamaCppBackend._igpu_dedicated_memory_bytes([0])
+ assert asked == [[0]]
diff --git a/studio/backend/tests/test_igpu_carveout_notice_settings.py b/studio/backend/tests/test_igpu_carveout_notice_settings.py
new file mode 100644
index 00000000000..dfbd8a33fa8
--- /dev/null
+++ b/studio/backend/tests/test_igpu_carveout_notice_settings.py
@@ -0,0 +1,143 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+"""Dismissal of the integrated-GPU memory notice.
+
+Once dismissed it must stay dismissed, but only for the allocation it was dismissed
+at: a user who acts on the advice, raises the allocation and later runs short again
+is in a new situation and worth telling.
+"""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from utils import igpu_carveout_notice_settings as notice # noqa: E402
+
+
+class TestAFreshInstall:
+ def test_nothing_is_dismissed(self):
+ assert notice.get_dismissed_at_gb() is None
+ assert notice.notice_already_dismissed(32.0) is False
+
+ def test_an_unknown_allocation_is_not_silenced(self):
+ # Nothing dismissed yet, so even an unreadable allocation may speak.
+ assert notice.notice_already_dismissed(None) is False
+
+
+class TestDismissal:
+ def test_dismissing_silences_the_same_allocation(self):
+ notice.dismiss_notice(32.0)
+ assert notice.get_dismissed_at_gb() == 32.0
+ assert notice.notice_already_dismissed(32.0) is True
+
+ def test_it_stays_silent_at_a_smaller_allocation(self):
+ # Lowering the allocation is not new information: they were already told.
+ notice.dismiss_notice(64.0)
+ assert notice.notice_already_dismissed(32.0) is True
+
+ def test_it_speaks_again_after_the_user_raises_the_allocation(self):
+ # Acted on the advice and hit the ceiling again: worth one more mention.
+ notice.dismiss_notice(32.0)
+ assert notice.notice_already_dismissed(64.0) is False
+
+ def test_a_driver_rounding_difference_does_not_re_show_it(self):
+ # A driver-reported byte count reads 95.83 against a 96.00 setting.
+ notice.dismiss_notice(95.83)
+ assert notice.notice_already_dismissed(95.9) is True
+
+ def test_dismissal_only_ever_rises(self):
+ # A stale client reporting an old, smaller allocation must not re-arm it.
+ notice.dismiss_notice(64.0)
+ notice.dismiss_notice(16.0)
+ assert notice.get_dismissed_at_gb() == 64.0
+
+ def test_an_unknown_allocation_is_silent_once_dismissed(self):
+ notice.dismiss_notice(32.0)
+ assert notice.notice_already_dismissed(None) is True
+
+
+class TestCorruptRows:
+ """A bad row must fail toward showing the notice, never toward hiding it."""
+
+ def test_junk_reads_as_never_dismissed(self):
+ from storage.studio_db import upsert_app_settings
+ for junk in ("banana", "", -5, 0, True, False, None):
+ upsert_app_settings({notice.IGPU_CARVEOUT_NOTICE_KEY: junk})
+ assert notice.get_dismissed_at_gb() is None, junk
+ assert notice.notice_already_dismissed(32.0) is False, junk
+
+ def test_a_numeric_string_is_honoured(self):
+ from storage.studio_db import upsert_app_settings
+ upsert_app_settings({notice.IGPU_CARVEOUT_NOTICE_KEY: "48"})
+ assert notice.get_dismissed_at_gb() == 48.0
+
+ def test_dismissing_with_junk_does_not_crash_or_store(self):
+ assert notice.dismiss_notice(None) is None
+ assert notice.dismiss_notice(-1) is None
+ assert notice.get_dismissed_at_gb() is None
+
+
+class TestAHostileDismissalValue:
+ """`current_gb` arrives in a client-controlled POST body, and Python's json accepts
+ `Infinity`, so a value no machine will ever exceed really can reach this -- and
+ storing it would silence the notice permanently."""
+
+ @pytest.mark.parametrize(
+ "value",
+ [
+ float("inf"),
+ float("-inf"),
+ float("nan"),
+ 10**9,
+ 2**53,
+ -1,
+ 0,
+ ],
+ )
+ def test_it_cannot_silence_the_notice_forever(self, value):
+ notice.dismiss_notice(value)
+ assert notice.notice_already_dismissed(32.0) is False, value
+
+ @pytest.mark.parametrize(
+ "stored",
+ [
+ float("inf"),
+ float("nan"),
+ "Infinity",
+ "1e999",
+ "-inf",
+ ],
+ )
+ def test_a_corrupt_row_reads_as_never_dismissed(self, stored):
+ from storage.studio_db import upsert_app_settings
+ upsert_app_settings({notice.IGPU_CARVEOUT_NOTICE_KEY: stored})
+ assert notice.notice_already_dismissed(32.0) is False, stored
+
+
+class TestTheToleranceBoundary:
+ """The slack is a tenth of a GB, and both sides arrive rounded to a tenth."""
+
+ def test_a_reading_exactly_one_tenth_above_stays_dismissed(self):
+ # The client dismisses at the rounded value the advice showed (95.8), and a
+ # later boot reading 95.9 is one tenth away. Binary floats put 95.8 + 0.1 at
+ # 95.89999999999999, so the float comparison called it not dismissed.
+ assert 95.8 + 0.1 == pytest.approx(95.9), "the float is only 1 ulp off"
+ assert (95.9 <= 95.8 + 0.1) is False, "which is what the old comparison read"
+ notice.dismiss_notice(95.8)
+ assert notice.notice_already_dismissed(95.9) is True
+
+ def test_two_tenths_above_still_speaks(self):
+ # The slack is one tenth, not "anything close". A real change must be heard.
+ notice.dismiss_notice(95.8)
+ assert notice.notice_already_dismissed(96.0) is False
+
+ def test_the_boundary_holds_across_the_ladder(self):
+ # Every rung the ladder can suggest, dismissed at its rounded reading.
+ for rung in (4, 6, 8, 12, 16, 24, 32, 48, 64, 96, 128):
+ reading = round(rung - 0.2, 1)
+ notice.dismiss_notice(reading)
+ assert notice.notice_already_dismissed(round(reading + 0.1, 1)) is True, rung
+ assert notice.notice_already_dismissed(round(reading + 0.2, 1)) is False, rung
diff --git a/studio/backend/utils/igpu_carveout_notice_settings.py b/studio/backend/utils/igpu_carveout_notice_settings.py
new file mode 100644
index 00000000000..83d6f032b77
--- /dev/null
+++ b/studio/backend/utils/igpu_carveout_notice_settings.py
@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Whether the "enlarge the integrated GPU's memory" notice has been dismissed.
+
+Server-side rather than localStorage, for the reason xet_notice_settings.py gives:
+an Unsloth origin is not stable, so a per-origin store hands out a fresh notice
+every time the port moves.
+
+Dismissal records the allocation it was dismissed AT, not a bare boolean: someone who
+acts on the advice, raises 32 GB to 64 GB and still runs short is in a new situation
+worth one more mention, which a flag would silence forever.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Optional
+
+IGPU_CARVEOUT_NOTICE_KEY = "igpu_carveout_notice_dismissed_at_gb"
+
+
+def _coerce_gb(value: Any) -> Optional[float]:
+ """Anything unparseable reads as "never dismissed", matching a fresh install: a
+ corrupt row must not wedge the notice off permanently, so this fails toward
+ showing it rather than hiding it.
+ """
+ if isinstance(value, bool):
+ return None
+ if isinstance(value, (int, float)):
+ return float(value) if _is_plausible_gb(value) else None
+ if isinstance(value, str):
+ try:
+ parsed = float(value.strip())
+ except ValueError:
+ return None
+ return parsed if _is_plausible_gb(parsed) else None
+ return None
+
+
+def _is_plausible_gb(value: float) -> bool:
+ """Whether a number could be a GPU allocation someone actually has.
+
+ Infinity is the one that matters: Python's json accepts ``Infinity``, so a client
+ could otherwise dismiss at a value no machine will ever exceed and silence the
+ notice permanently, the opposite of the rule above.
+ """
+ return math.isfinite(value) and 0 < value < 1024 * 1024
+
+
+def get_dismissed_at_gb() -> Optional[float]:
+ """The GPU allocation the notice was last dismissed at, or None."""
+ try:
+ from storage.studio_db import get_app_setting
+ stored = get_app_setting(IGPU_CARVEOUT_NOTICE_KEY, None)
+ except Exception:
+ return None
+ return _coerce_gb(stored)
+
+
+def notice_already_dismissed(current_gb: Optional[float]) -> bool:
+ """Whether the notice should stay silent at an allocation of ``current_gb``.
+
+ Silent only while the allocation is unchanged or smaller. An unknown allocation
+ counts as dismissed once anything has been, since re-showing on a reading we
+ cannot compare is the nagging this exists to avoid.
+ """
+ dismissed_at = get_dismissed_at_gb()
+ if dismissed_at is None:
+ return False
+ if current_gb is None:
+ return True
+ # A tenth of a GB of slack: the driver-reported byte count need not be identical
+ # across boots (95.83 against a 96.00 setting here), and a rounding redisplay would
+ # look like the notice ignoring the dismissal. Compared in TENTHS because binary
+ # floats miss that grid: 95.8 + 0.1 is 95.89999999999999, so a 95.9 reading -- one
+ # tenth away, the case this slack exists for -- read as not dismissed.
+ return round(float(current_gb) * 10) <= round(dismissed_at * 10) + 1
+
+
+def dismiss_notice(current_gb: Optional[float]) -> Optional[float]:
+ """Record dismissal at ``current_gb``. Returns what was stored, or None.
+
+ Only ever raises the stored value, so a stale client reporting an old, smaller
+ allocation cannot re-arm a notice the user already dismissed at a larger one.
+ """
+ if current_gb is None:
+ return get_dismissed_at_gb()
+ try:
+ value = float(current_gb)
+ except (TypeError, ValueError):
+ return get_dismissed_at_gb()
+ if not _is_plausible_gb(value):
+ return get_dismissed_at_gb()
+
+ existing = get_dismissed_at_gb()
+ if existing is not None and existing >= value:
+ return existing
+ try:
+ from storage.studio_db import upsert_app_settings
+ upsert_app_settings({IGPU_CARVEOUT_NOTICE_KEY: value})
+ except Exception:
+ return existing
+ return value
diff --git a/studio/frontend/src/features/chat/api/chat-api.ts b/studio/frontend/src/features/chat/api/chat-api.ts
index 4d1a3062284..f14bdd365b4 100644
--- a/studio/frontend/src/features/chat/api/chat-api.ts
+++ b/studio/frontend/src/features/chat/api/chat-api.ts
@@ -13,6 +13,7 @@ import {
import { hubTokenHeader } from "@/features/hub/lib/hub-token-header";
// eslint-disable-next-line no-restricted-imports
import { isHuggingFaceOffline } from "@/features/hub/lib/network";
+import { dismissCarveoutAdviceForModel, showCarveoutAdvice } from "@/features/igpu-carveout";
// eslint-disable-next-line no-restricted-imports
import { consumeNativePathToken } from "@/features/native-intents/api";
import { formatApiErrorBody } from "@/lib/format-fastapi-error";
@@ -292,7 +293,13 @@ export async function loadModel(
}),
signal: options?.signal,
});
- return parseJsonOrThrow<LoadModelResponse>(response, "Model load");
+ const loaded = await parseJsonOrThrow<LoadModelResponse>(response, "Model load");
+ // Unconditional: absent on nearly every load, anything malformed is ignored,
+ // and the model is already resident by the time this runs. Both identities are
+ // passed -- a cached Hub candidate is requested by its loadId while the runtime
+ // keeps `loaded.model`, and the unload is issued with the second.
+ showCarveoutAdvice(loaded.carveout_advice, loaded.model, payload.model_path);
+ return loaded;
},
);
}
@@ -435,6 +442,9 @@ export async function unloadModel(payload: UnloadModelRequest): Promise<void> {
body: JSON.stringify(payload),
});
await parseJsonOrThrow<unknown>(response, "Model unload");
+ // Only after the unload is known to have happened: a rejected one leaves the model
+ // resident and the notice true. A different model's unload leaves it standing.
+ dismissCarveoutAdviceForModel(payload.model_path);
}
/** Allow or deny a tool call paused awaiting user confirmation, identified by the backend
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index a1ac05fea47..a91c5c9e471 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -208,6 +208,10 @@ export interface LoadModelResponse {
is_lora: boolean;
is_gguf?: boolean;
is_local_model?: boolean;
+ /** Advisory, absent on nearly every load: the integrated GPU has less memory
+ * dedicated to it than the weights need. Unknown-shaped on purpose so an older or
+ * proxied backend cannot render "undefined GB"; narrowed by parseCarveoutAdvice. */
+ carveout_advice?: unknown;
is_diffusion?: boolean;
/** GPU-layer count the diffusion runner was ASKED for, when it differs from what it applied: a shim
* without --ngl runs Auto, so gpu_layers reports -1 while this carries the request. */
diff --git a/studio/frontend/src/features/igpu-carveout/api/igpu-carveout-notice.ts b/studio/frontend/src/features/igpu-carveout/api/igpu-carveout-notice.ts
new file mode 100644
index 00000000000..77a9c52e070
--- /dev/null
+++ b/studio/frontend/src/features/igpu-carveout/api/igpu-carveout-notice.ts
@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// Dismissal lives on the backend, not localStorage: an Unsloth origin moves whenever
+// port 8888 is taken, and a per-origin store would re-notice on every new origin --
+// the same defect the Xet notice already hit.
+
+import { authFetch } from "@/features/auth";
+
+/** Stop offering the advice at this allocation.
+ *
+ * `current_gb` is what the user is dismissing AT, so raising the allocation and
+ * running short again can say so once more. Never throws and never retries: a
+ * failure costs at most one repeat of the notice, and a retry whose predecessor
+ * reached the backend is a second pointless write.
+ */
+export async function dismissCarveoutNotice(currentGb: number | null): Promise<boolean> {
+ try {
+ const response = await authFetch(
+ "/api/settings/igpu-carveout-notice/dismiss",
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ current_gb: currentGb }),
+ },
+ { retryNetworkErrors: false },
+ );
+ return response.ok;
+ } catch {
+ return false;
+ }
+}
diff --git a/studio/frontend/src/features/igpu-carveout/igpu-carveout-toast.ts b/studio/frontend/src/features/igpu-carveout/igpu-carveout-toast.ts
new file mode 100644
index 00000000000..aebb9da4d83
--- /dev/null
+++ b/studio/frontend/src/features/igpu-carveout/igpu-carveout-toast.ts
@@ -0,0 +1,86 @@
+// 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 integrated-GPU memory advice, as a toast rather than a modal: the model has
+// already loaded, nothing is being asked, and there is no decision to block on, so a
+// modal would dim the app and eat the next click for a setting the user cannot change
+// from here. Every other "worth knowing, carry on" notice in Studio is a toast.
+//
+// No store and no mounted component either: the toast owns its text for as long as it
+// is up, so there is no state to keep or invalidate.
+
+import { toast } from "@/lib/toast";
+
+import { dismissCarveoutNotice } from "./api/igpu-carveout-notice";
+import { parseCarveoutAdvice } from "./types";
+
+/** One id for the notice, so a second load REPLACES rather than stacks: it is
+ * transient and describes the model that just loaded, so a stack of two would sit
+ * over the composer describing a model that is no longer resident. */
+export const IGPU_CARVEOUT_TOAST_ID = "igpu-carveout-notice";
+
+/** Longer than the Toaster's 5s default, like the other explanatory toasts, and
+ * longer than those because this one carries an action worth reading first. */
+export const IGPU_CARVEOUT_NOTICE_DURATION_MS = 12000;
+
+export const IGPU_CARVEOUT_NOTICE_TITLE = "This model could run faster";
+
+/** The action, outlined and right-aligned rather than sonner's filled default.
+ *
+ * A solid button reads as the thing to do, and the thing to do here is nothing. And
+ * the shared toast CSS puts an action at `justify-self: start`, which under six lines
+ * of description floats it mid-toast, aligned to neither edge. Overridden here rather
+ * than in that shared rule because every other toast's action IS the thing to do. */
+export const IGPU_CARVEOUT_ACTION_CLASS =
+ "!justify-self-end !h-[26px] !border !border-border !bg-transparent !px-3 " +
+ "!font-medium !text-foreground hover:!bg-accent";
+
+/** The model the notice on screen is about, so an unload can take it down.
+ *
+ * Paths rather than a flag: several models can be resident, and unloading another
+ * leaves this notice true. More than one path, because a cached Hub candidate is
+ * requested by its `loadId` while the runtime stores the checkpoint the backend
+ * echoes back, and the unload is issued with the second. Empty when the caller named
+ * none, and an unload then clears it: an unmatchable notice is worse left up. */
+let advisedModelPaths: string[] = [];
+
+/** Take the notice down when the model it describes is unloaded: it says "this model
+ * could run faster" beside an offer to remember the dismissal, and both stop being
+ * true the moment the model is gone, with no load happening to clear them. */
+export function dismissCarveoutAdviceForModel(modelPath?: string | null): void {
+ if (advisedModelPaths.length > 0 && modelPath && !advisedModelPaths.includes(modelPath)) return;
+ advisedModelPaths = [];
+ toast.dismiss(IGPU_CARVEOUT_TOAST_ID);
+}
+
+/** Hand a load response's advice field to the notice. Safe to call on every load:
+ * the field is absent on nearly every one, and anything malformed is treated as no
+ * advice, since the notice quotes numbers and a partial payload must produce no
+ * toast rather than one reading "undefined GB". */
+export function showCarveoutAdvice(
+ value: unknown,
+ ...modelPaths: (string | null | undefined)[]
+): void {
+ const advice = parseCarveoutAdvice(value);
+ if (!advice) {
+ // This load has nothing to advise, so the previous load's numbers are stale.
+ advisedModelPaths = [];
+ toast.dismiss(IGPU_CARVEOUT_TOAST_ID);
+ return;
+ }
+ advisedModelPaths = [...new Set(modelPaths.filter((path): path is string => !!path))];
+ toast.info(IGPU_CARVEOUT_NOTICE_TITLE, {
+ id: IGPU_CARVEOUT_TOAST_ID,
+ description: advice.message,
+ duration: IGPU_CARVEOUT_NOTICE_DURATION_MS,
+ classNames: { actionButton: IGPU_CARVEOUT_ACTION_CLASS },
+ action: {
+ label: "Don't show again",
+ // Fire and forget: dismissCarveoutNotice swallows its own failures, and the
+ // worst case is the notice returning on a later load.
+ onClick: () => {
+ void dismissCarveoutNotice(advice.current_gb);
+ },
+ },
+ });
+}
diff --git a/studio/frontend/src/features/igpu-carveout/index.ts b/studio/frontend/src/features/igpu-carveout/index.ts
new file mode 100644
index 00000000000..d31e2e978a6
--- /dev/null
+++ b/studio/frontend/src/features/igpu-carveout/index.ts
@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export {
+ dismissCarveoutAdviceForModel,
+ IGPU_CARVEOUT_NOTICE_DURATION_MS,
+ IGPU_CARVEOUT_NOTICE_TITLE,
+ IGPU_CARVEOUT_TOAST_ID,
+ showCarveoutAdvice,
+} from "./igpu-carveout-toast";
+export { parseCarveoutAdvice, type IgpuCarveoutAdvice } from "./types";
diff --git a/studio/frontend/src/features/igpu-carveout/types.ts b/studio/frontend/src/features/igpu-carveout/types.ts
new file mode 100644
index 00000000000..f8a956ebca9
--- /dev/null
+++ b/studio/frontend/src/features/igpu-carveout/types.ts
@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+/** Advice attached to a model load when the integrated GPU has less memory dedicated
+ * to it than the weights need, so they run from shared system memory. Sent at most
+ * once per allocation, and never on hardware where the setting does not exist. */
+export interface IgpuCarveoutAdvice {
+ /** GB currently dedicated to the integrated GPU. */
+ current_gb: number;
+ /** GB of weights this model wants resident. */
+ needed_gb: number;
+ /** GB to suggest: the smallest plausible setting that holds the weights. */
+ suggested_gb: number;
+ /** GB the machine has in total (visible RAM plus the current allocation). */
+ machine_gb: number;
+ /** GB left for the rest of the system if the suggestion is taken. */
+ host_left_gb: number;
+ /** Prose written by the backend, which owns the wording. */
+ message: string;
+}
+
+/** Narrow an unknown load-response field. The notice quotes numbers, so a partial
+ * payload from an older or proxied backend is treated as no advice at all rather
+ * than rendered as "undefined GB". */
+export function parseCarveoutAdvice(value: unknown): IgpuCarveoutAdvice | null {
+ if (!value || typeof value !== "object") return null;
+ const raw = value as Record<string, unknown>;
+ const num = (key: string): number | null => {
+ const n = raw[key];
+ return typeof n === "number" && Number.isFinite(n) ? n : null;
+ };
+ const current_gb = num("current_gb");
+ const needed_gb = num("needed_gb");
+ const suggested_gb = num("suggested_gb");
+ const machine_gb = num("machine_gb");
+ const host_left_gb = num("host_left_gb");
+ const message = raw.message;
+ if (
+ current_gb === null ||
+ needed_gb === null ||
+ suggested_gb === null ||
+ machine_gb === null ||
+ host_left_gb === null ||
+ typeof message !== "string" ||
+ !message.trim()
+ ) {
+ return null;
+ }
+ return { current_gb, needed_gb, suggested_gb, machine_gb, host_left_gb, message };
+}
diff --git a/studio/frontend/tests/chat-save-conflict-detail.test.ts b/studio/frontend/tests/chat-save-conflict-detail.test.ts
index e8d6ec6868e..4b0ef3bad5e 100644
--- a/studio/frontend/tests/chat-save-conflict-detail.test.ts
+++ b/studio/frontend/tests/chat-save-conflict-detail.test.ts
@@ -67,6 +67,12 @@ function harness(response: ReturnType<typeof jsonResponse>) {
"./gguf-variants-request": {},
"./padded-response": { assertCompletedPaddedBody: () => {} },
"@/features/hf-auth": { prepareHfTokenForUse: async () => undefined },
+ // loadModel calls the notice on every load, and this harness names chat-api's
+ // imports exactly, so the stub must exist even though no toast is raised here.
+ "@/features/igpu-carveout": {
+ dismissCarveoutAdviceForModel: () => {},
+ showCarveoutAdvice: () => {},
+ },
"@/features/hub/lib/abort-signals": {},
"@/features/hub/lib/hub-token-header": { hubTokenHeader: () => ({}) },
"@/features/hub/lib/network": { isHuggingFaceOffline: () => false },
diff --git a/studio/frontend/tests/helpers/igpu-carveout-resolver.mjs b/studio/frontend/tests/helpers/igpu-carveout-resolver.mjs
new file mode 100644
index 00000000000..885a62090a1
--- /dev/null
+++ b/studio/frontend/tests/helpers/igpu-carveout-resolver.mjs
@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// bundler-resolver's two rules, plus the two redirects this notice needs at once:
+// "@/lib/toast" -> toast-stub.mjs, which records the whole options bag (id, duration,
+// action -- none of which the store-stubs toast keeps), and "@/features/auth" -> the
+// store stub, so the dismissal POST never reaches the network.
+//
+// Its own resolver rather than registering the toast and store-stub ones together:
+// whichever ran first would resolve "@/..." to a real path, hiding the bare specifier
+// from the other.
+import { existsSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const SRC = fileURLToPath(new URL("../../src/", import.meta.url));
+const REDIRECTS = new Map([
+ ["@/lib/toast", new URL("./toast-stub.mjs", import.meta.url).href],
+ ["@/features/auth", new URL("./store-stubs/auth.ts", import.meta.url).href],
+]);
+
+function firstExisting(base) {
+ for (const candidate of [`${base}.ts`, `${base}/index.ts`, base]) {
+ if (existsSync(candidate)) return pathToFileURL(candidate).href;
+ }
+ return null;
+}
+
+export function resolve(specifier, context, next) {
+ const redirect = REDIRECTS.get(specifier);
+ if (redirect) return next(redirect, context);
+ if (specifier.startsWith("@/")) {
+ const resolved = firstExisting(SRC + specifier.slice(2));
+ return next(resolved ?? specifier, context);
+ }
+ if (specifier.startsWith(".") && context.parentURL?.startsWith("file:")) {
+ const resolved = firstExisting(
+ fileURLToPath(new URL(specifier, context.parentURL)),
+ );
+ if (resolved) return next(resolved, context);
+ }
+ return next(specifier, context);
+}
diff --git a/studio/frontend/tests/helpers/toast-stub.d.mts b/studio/frontend/tests/helpers/toast-stub.d.mts
index 6876c558d90..c03c5a95523 100644
--- a/studio/frontend/tests/helpers/toast-stub.d.mts
+++ b/studio/frontend/tests/helpers/toast-stub.d.mts
@@ -11,6 +11,8 @@ export interface ToastCall {
description?: string;
duration?: number;
classNames?: Record<string, string>;
+ // The notice's dismissal hangs off this.
+ action?: { label?: string; onClick: () => void };
};
id?: string;
}
diff --git a/studio/frontend/tests/igpu-carveout-advice.test.ts b/studio/frontend/tests/igpu-carveout-advice.test.ts
new file mode 100644
index 00000000000..6a376e3f166
--- /dev/null
+++ b/studio/frontend/tests/igpu-carveout-advice.test.ts
@@ -0,0 +1,71 @@
+// 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 notice quotes numbers back at the user, so a partial or hostile payload must
+// produce nothing at all rather than something reading "undefined GB".
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+
+const { parseCarveoutAdvice } = await import(
+ "../src/features/igpu-carveout/types.ts"
+);
+
+const GOOD = {
+ current_gb: 32,
+ needed_gb: 42.9,
+ suggested_gb: 48,
+ machine_gb: 127.8,
+ host_left_gb: 79.8,
+ message: "This model's weights are about 43 GB...",
+};
+
+test("a complete payload parses", () => {
+ const parsed = parseCarveoutAdvice(GOOD);
+ assert.ok(parsed);
+ assert.equal(parsed.suggested_gb, 48);
+ assert.equal(parsed.current_gb, 32);
+});
+
+test("absent advice is not an error", () => {
+ // Missing on nearly every load, and the caller passes it through unconditionally.
+ for (const empty of [null, undefined, "", 0, false]) {
+ assert.equal(parseCarveoutAdvice(empty), null);
+ }
+});
+
+test("a payload missing any number is rejected whole", () => {
+ for (const key of [
+ "current_gb",
+ "needed_gb",
+ "suggested_gb",
+ "machine_gb",
+ "host_left_gb",
+ ]) {
+ const partial: Record<string, unknown> = { ...GOOD };
+ delete partial[key];
+ assert.equal(parseCarveoutAdvice(partial), null, key);
+ }
+});
+
+test("non-finite numbers are rejected", () => {
+ // JSON cannot carry these, but a proxy or a hand-rolled backend double can.
+ for (const bad of [Number.NaN, Number.POSITIVE_INFINITY]) {
+ assert.equal(parseCarveoutAdvice({ ...GOOD, suggested_gb: bad }), null);
+ }
+});
+
+test("a missing or blank message is rejected", () => {
+ // The backend owns the wording; without it there is nothing to render.
+ assert.equal(parseCarveoutAdvice({ ...GOOD, message: undefined }), null);
+ assert.equal(parseCarveoutAdvice({ ...GOOD, message: " " }), null);
+ assert.equal(parseCarveoutAdvice({ ...GOOD, message: 42 }), null);
+});
+
+test("a string where a number belongs is rejected", () => {
+ assert.equal(parseCarveoutAdvice({ ...GOOD, current_gb: "32" }), null);
+});
diff --git a/studio/frontend/tests/igpu-carveout-toast.test.ts b/studio/frontend/tests/igpu-carveout-toast.test.ts
new file mode 100644
index 00000000000..c1efb52ee17
--- /dev/null
+++ b/studio/frontend/tests/igpu-carveout-toast.test.ts
@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// Every model load calls showCarveoutAdvice, including the loads carrying no advice,
+// so this is where one model's numbers could outlive the model they describe, two
+// loads could stack two notices over the composer, or a dismissal could report an
+// allocation the user is no longer running.
+//
+// One resolver redirects both dependencies: the toast stub records the full options
+// bag (id, duration, action -- none of which the store-stubs toast keeps), and the
+// auth stub answers authFetch so no test reaches the network.
+
+import assert from "node:assert/strict";
+import { register } from "node:module";
+import test from "node:test";
+
+register("./helpers/igpu-carveout-resolver.mjs", import.meta.url);
+
+const { calls } = await import("./helpers/toast-stub.mjs");
+const { setAuthFetchHandler } = await import("./helpers/store-stubs/auth.ts");
+const {
+ IGPU_CARVEOUT_ACTION_CLASS,
+ IGPU_CARVEOUT_NOTICE_TITLE,
+ IGPU_CARVEOUT_TOAST_ID,
+ dismissCarveoutAdviceForModel,
+ showCarveoutAdvice,
+} = await import("../src/features/igpu-carveout/igpu-carveout-toast.ts");
+
+const ADVICE = {
+ current_gb: 32,
+ needed_gb: 42.9,
+ suggested_gb: 48,
+ machine_gb: 127.8,
+ host_left_gb: 79.8,
+ message:
+ "Weights need about 43 GB but only 32 GB is allocated to the integrated GPU, " +
+ "so the rest runs from slower shared memory. Raising it to 48 GB in your " +
+ "firmware or GPU control panel leaves about 80 GB for the system.",
+};
+
+function reset() {
+ calls.length = 0;
+ setAuthFetchHandler(null);
+}
+
+test("advice raises one toast carrying the backend's prose", () => {
+ reset();
+ showCarveoutAdvice(ADVICE);
+ assert.equal(calls.length, 1);
+ assert.equal(calls[0].kind, "info");
+ assert.equal(calls[0].title, IGPU_CARVEOUT_NOTICE_TITLE);
+ assert.equal(calls[0].options?.description, ADVICE.message);
+ // Never an error or a warning: the load succeeded and the user did nothing wrong.
+ assert.notEqual(calls[0].kind, "error");
+});
+
+test("it is not a modal, so it holds an id and a finite duration", () => {
+ // A toast without an id stacks, and one without a duration stays until it is
+ // clicked, which is a dialog with extra steps.
+ reset();
+ showCarveoutAdvice(ADVICE);
+ assert.equal(calls[0].options?.id, IGPU_CARVEOUT_TOAST_ID);
+ assert.ok(
+ Number.isFinite(calls[0].options?.duration) &&
+ (calls[0].options?.duration as number) > 5000,
+ "long enough to read an action, short enough to leave on its own",
+ );
+});
+
+test("the action is styled down from sonner's filled default", () => {
+ // An outline because nothing here is the thing to do, and end-alignment because the
+ // shared toast CSS starts an action at the left and floats it under six lines.
+ reset();
+ showCarveoutAdvice(ADVICE);
+ const classes = (calls[0].options?.classNames as { actionButton?: string })
+ ?.actionButton;
+ assert.equal(classes, IGPU_CARVEOUT_ACTION_CLASS);
+ assert.match(classes ?? "", /!justify-self-end/);
+ assert.match(classes ?? "", /!bg-transparent/);
+});
+
+test("a second load replaces the notice rather than stacking one over it", () => {
+ // Two toasts over the composer, the older one stale, is what the id prevents.
+ reset();
+ showCarveoutAdvice(ADVICE);
+ showCarveoutAdvice({ ...ADVICE, suggested_gb: 96 });
+ assert.equal(calls.length, 2);
+ assert.equal(calls[0].options?.id, calls[1].options?.id);
+});
+
+test("a malformed payload raises nothing", () => {
+ reset();
+ for (const bad of [null, undefined, {}, "advice", { ...ADVICE, message: "" }]) {
+ showCarveoutAdvice(bad);
+ }
+ assert.equal(
+ calls.filter((call) => call.kind !== "dismiss").length,
+ 0,
+ "the notice quotes numbers, so a partial payload must produce no toast",
+ );
+});
+
+test("a later load carrying no advice takes the previous notice down", () => {
+ // The moment the old figures stop being true; a toast has no copy, so it dismisses.
+ reset();
+ showCarveoutAdvice(ADVICE);
+ showCarveoutAdvice(undefined);
+ const dismissals = calls.filter((call) => call.kind === "dismiss");
+ assert.equal(dismissals.length, 1);
+ assert.equal(dismissals[0].id, IGPU_CARVEOUT_TOAST_ID);
+});
+
+test("the action posts the allocation it was dismissed at", async () => {
+ reset();
+ const seen: Array<{ url: string; body: unknown; method?: string }> = [];
+ setAuthFetchHandler((url, init) => {
+ seen.push({
+ url,
+ method: init?.method,
+ body: init?.body ? JSON.parse(String(init.body)) : null,
+ });
+ return new Response(JSON.stringify({ dismissed_at_gb: 32 }), { status: 200 });
+ });
+ showCarveoutAdvice(ADVICE);
+ const action = calls[0].options?.action as { onClick: () => void };
+ action.onClick();
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ assert.equal(seen.length, 1);
+ assert.equal(seen[0].method, "POST");
+ assert.match(seen[0].url, /igpu-carveout-notice\/dismiss/);
+ assert.deepEqual(seen[0].body, { current_gb: 32 });
+});
+
+test("letting the toast expire sends nothing", async () => {
+ // Ignoring a toast is not a decision, so the notice may return on a later load.
+ reset();
+ let called = false;
+ setAuthFetchHandler(() => {
+ called = true;
+ return new Response("{}", { status: 200 });
+ });
+ showCarveoutAdvice(ADVICE);
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ assert.equal(called, false);
+});
+
+test("a failing dismissal is swallowed rather than rejected", async () => {
+ // Worst case the notice returns on a later load, which beats an unhandled
+ // rejection.
+ reset();
+ setAuthFetchHandler(() => {
+ throw new TypeError("network down");
+ });
+ showCarveoutAdvice(ADVICE);
+ const action = calls[0].options?.action as { onClick: () => void };
+ assert.doesNotThrow(() => action.onClick());
+ await new Promise((resolve) => setTimeout(resolve, 0));
+});
+
+test("unloading the advised model takes its notice down", () => {
+ // Unload inside the toast's 12 seconds and "this model could run faster" is false,
+ // with no load coming to correct it.
+ reset();
+ showCarveoutAdvice(ADVICE, "/models/qwen3-30b.gguf");
+ dismissCarveoutAdviceForModel("/models/qwen3-30b.gguf");
+ const dismissed = calls.filter((call) => call.kind === "dismiss");
+ assert.equal(dismissed.length, 1);
+ assert.equal(dismissed[0].id, IGPU_CARVEOUT_TOAST_ID);
+});
+
+test("unloading a different model leaves it up", () => {
+ // Several models can be resident at once, and the notice is about one of them.
+ reset();
+ showCarveoutAdvice(ADVICE, "/models/qwen3-30b.gguf");
+ dismissCarveoutAdviceForModel("/models/gemma3-27b.gguf");
+ assert.equal(
+ calls.filter((call) => call.kind === "dismiss").length,
+ 0,
+ );
+});
+
+test("every dismissal names this notice and only this notice", () => {
+ // The id also keeps these dismissals off every other toast on screen.
+ reset();
+ showCarveoutAdvice(ADVICE, "/models/qwen3-30b.gguf");
+ dismissCarveoutAdviceForModel("/models/qwen3-30b.gguf");
+ dismissCarveoutAdviceForModel("/models/gemma3-27b.gguf");
+ showCarveoutAdvice(null);
+ for (const call of calls.filter((entry) => entry.kind === "dismiss")) {
+ assert.equal(call.id, IGPU_CARVEOUT_TOAST_ID);
+ }
+});
+
+test("either identity the load was known by takes the notice down", () => {
+ // A cached Hub candidate is requested by its loadId while the unload uses the
+ // checkpoint. Matching one identity only left the toast up for a gone model.
+ reset();
+ showCarveoutAdvice(ADVICE, "unsloth/Qwen3-30B-GGUF", "/cache/hub/qwen3-30b.gguf");
+ dismissCarveoutAdviceForModel("unsloth/Qwen3-30B-GGUF");
+ assert.equal(calls.filter((call) => call.kind === "dismiss").length, 1);
+
+ reset();
+ showCarveoutAdvice(ADVICE, "unsloth/Qwen3-30B-GGUF", "/cache/hub/qwen3-30b.gguf");
+ dismissCarveoutAdviceForModel("/cache/hub/qwen3-30b.gguf");
+ assert.equal(calls.filter((call) => call.kind === "dismiss").length, 1);
+
+ // And a third model is still not this one.
+ reset();
+ showCarveoutAdvice(ADVICE, "unsloth/Qwen3-30B-GGUF", "/cache/hub/qwen3-30b.gguf");
+ dismissCarveoutAdviceForModel("unsloth/gemma-3-27b");
+ assert.equal(calls.filter((call) => call.kind === "dismiss").length, 0);
+});