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: MCP agents choose how and where a model loads, preview the load, and queue videos (#14090)

Etherl21e201bfaded
diff --git a/studio/MCP.md b/studio/MCP.md
index 0393274293e..d6c71f0d79e 100644
--- a/studio/MCP.md
+++ b/studio/MCP.md
@@ -277,7 +277,8 @@ api_key_format = "Bearer {token}"
| `studio_status` | What is loaded, loading and running: chat, image, video, speech-to-text and embedding models, training, export and GPUs. |
| `list_models` | Models Unsloth Studio can serve, by kind or by Audio page `workflow`. With `model`, its training defaults. With `source="catalog"`, the image, video and audio models it can download, with their size and whether they fit on the GPU now. |
| `load_model` | Load a chat, image, video or speech-to-text model, downloading it first if needed. Reports progress, waits up to `wait_s` (240 s by default) and lists what it unloaded. |
-| `unload_model` | Unload a model. |
+| `unload_model` | Unload a model, or every chat, speech, image, video and speech-to-text model with `kind="all"`. The embedding model stays. |
+| `plan_load` | Preview a load without loading anything: GGUF variants and sizes, bytes to download, and the models it would unload. |
| `chat` | Ask the loaded model, with optional images, thinking controls and a `response_format`. Reports progress and returns a `cancel_id`. |
| `embed` | Embed up to 2048 texts, or rank them against a `query` and return the `top_k` best matches. |
| `system_one` | Ask the Decision API typed questions. The Decision API must be on. |
diff --git a/studio/backend/studio_mcp/forward.py b/studio/backend/studio_mcp/forward.py
index cd8e654b1e5..a918a65454b 100644
--- a/studio/backend/studio_mcp/forward.py
+++ b/studio/backend/studio_mcp/forward.py
@@ -30,6 +30,8 @@ ALLOWED_PREFIXES = (
"/api/data-recipe/",
"/api/hub/datasets/",
"/api/hub/gguf-variants",
+ # Read only: load_model and plan_load check whether Unsloth Studio is still downloading a variant.
+ "/api/hub/download-status",
"/api/settings/embedding-model",
)
diff --git a/studio/backend/studio_mcp/loading.py b/studio/backend/studio_mcp/loading.py
index 0cab29bb820..7de58a55a7d 100644
--- a/studio/backend/studio_mcp/loading.py
+++ b/studio/backend/studio_mcp/loading.py
@@ -18,9 +18,10 @@ from fastmcp import Context
from fastmcp.exceptions import ToolError
from studio_mcp import job_store
+from studio_mcp import placement as place
from studio_mcp.caller import Caller
from studio_mcp.errors import tool_error
-from studio_mcp.outputs import EvictedSlot, LoadResult, UnloadResult
+from studio_mcp.outputs import EvictedSlot, LoadResult, SlotModel, UnloadAllResult, UnloadResult
from studio_mcp.tools import as_dict, number, opt_text, route_json, strings, try_json
POLL_INTERVAL_S = 2.0
@@ -212,6 +213,7 @@ async def start_load(
run: Callable[[LoadJob, dict[str, list[str]]], Awaitable[LoadResult]],
options: Any = None,
hub_token: Optional[str] = None,
+ attach: bool = True,
) -> LoadResult:
"""Run a load as a job and wait for it until ``deadline``. A repeat call for the same load while it runs follows it; one with another Hub token (a retry with a fixed token, say) starts its own."""
token = hub_token or caller.hf_token
@@ -230,9 +232,15 @@ async def start_load(
# A chat load Unsloth Studio is already running (started elsewhere) is followed, not started
# again. The status names only the repo, so a load asking for a variant always posts.
loading_now = strings(chat.get("loading"))
- if slot in CHAT_ROUTE_KINDS and not variant and any(_same(n, model) for n in loading_now):
+ if (
+ slot in CHAT_ROUTE_KINDS
+ and attach
+ and not variant
+ and any(_same(n, model) for n in loading_now)
+ ):
return await _watch_llm(caller, slot, model, before, job)
# K16, after the attach: M5 waits on a download of the same model here, then M7 refuses a partial one.
+ await place.refuse_partial_variant(caller, model, slot, variant)
return await run(job, before)
job = _in_flight(caller, asked) or LOADS.start(asked, drive)
@@ -359,6 +367,11 @@ async def load_llm(
hf_token: Optional[str],
kind: str = "llm",
deadline: Optional[float] = None,
+ device: Optional[str] = None,
+ alongside: Optional[bool] = None,
+ kv_cache_type: Optional[str] = None,
+ gpu_layers: Optional[int] = None,
+ is_lora: bool = False,
) -> LoadResult:
body: dict[str, Any] = {
"model_path": model,
@@ -367,12 +380,30 @@ async def load_llm(
}
if variant:
body["gguf_variant"] = variant
+ if is_lora:
+ body["is_lora"] = True
# The load routes read the Hub token from the body, not the header.
token = hf_token or caller.hf_token
if token:
body["hf_token"] = token
+ if hf_token:
+ # The variant lookups before the load read the Hub token from the header.
+ caller = dataclasses.replace(caller, hf_token = hf_token)
async def run(job: LoadJob, before: dict[str, list[str]]) -> LoadResult:
+ # The GGUF listing and status reads run inside the job, so a slow one never holds the call
+ # past ``wait_s``; device='cpu' for a chat model that is not a GGUF is refused here.
+ gguf = await place.require_cpu_gguf(caller, kind, model, variant, device, gpu_layers)
+ body.update(
+ place.llm_fields(
+ kind,
+ gguf = gguf,
+ device = device,
+ alongside = await place.auto_alongside(caller, device, alongside, gpu_layers),
+ kv_cache_type = kv_cache_type,
+ gpu_layers = gpu_layers,
+ )
+ )
payload = await with_progress(
None,
route_json("POST", "/api/inference/load", caller = caller, json_body = body),
@@ -381,13 +412,22 @@ async def load_llm(
)
if not isinstance(payload, dict):
raise ToolError("Unsloth Studio did not confirm the load")
+ loaded = opt_text(payload.get("model")) or model
+ chat = before.get("llm") or []
+ # Serving only: a model merely held in memory behind the new primary no longer serves.
+ # Bounded: the model is loaded, and a stalled read must not keep the job open.
+ status = await _read_json(caller, "/api/inference/status") if chat else None
+ # A failed read leaves it unknown whether the previous model still serves.
+ after = strings(status.get("serving")) if isinstance(status, dict) else None
return await finish_load(
caller,
kind,
- opt_text(payload.get("model")) or model,
+ loaded,
before,
payload,
display_name = opt_text(payload.get("display_name")),
+ placement = place.llm_placement(payload, device),
+ alongside_applied = place.alongside_applied(chat, after, loaded),
)
return await start_load(
@@ -398,8 +438,21 @@ async def load_llm(
variant = variant,
deadline = deadline or deadline_after(None),
run = run,
- options = (max_seq_length or 0, load_in_4bit),
+ # A load asked with other placement fields is a different load, not one to follow.
+ options = (
+ max_seq_length or 0,
+ load_in_4bit,
+ device,
+ alongside,
+ kv_cache_type,
+ gpu_layers,
+ ),
hub_token = token,
+ # A load asked with its own settings is never the one already running; following it would
+ # skip them (and the CPU check).
+ attach = not max_seq_length
+ and load_in_4bit
+ and all(v is None for v in (device, alongside, kv_cache_type, gpu_layers)),
)
@@ -531,20 +584,17 @@ def _resident_matches(
return h3_task.lower() == h3_transformer_task(wanted).lower()
-async def _gguf_filename(caller: Caller, model: str, variant: Optional[str]) -> Optional[str]:
- """The checkpoint file to load from a GGUF repo: the named variant, else the repo's default."""
+async def _gguf_filename(caller: Caller, model: str, variant: Optional[str]) -> Optional[dict]:
+ """The variant to load from a GGUF repo (the named one, else the repo's default), with its filename, size_bytes, downloaded and partial."""
listing = await route_json(
"GET", "/api/hub/gguf-variants", caller = caller, params = {"repo_id": model}, hub_header = True
)
- listing = as_dict(listing)
- variants = [v for v in listing.get("variants") or [] if isinstance(v, dict)]
- wanted = (variant or opt_text(listing.get("default_variant")) or "").lower()
- for entry in variants:
- if str(entry.get("quant", "")).lower() == wanted and opt_text(entry.get("filename")):
- return entry["filename"]
+ entry = place.pick_variant(listing, variant)
+ if entry is not None and opt_text(entry.get("filename")):
+ return entry
if variant:
raise ToolError(f"{model} has no GGUF variant {variant}")
- return opt_text(variants[0].get("filename")) if variants else None
+ return None
async def load_media(
@@ -556,8 +606,10 @@ async def load_media(
variant: Optional[str],
hf_token: Optional[str],
deadline: Optional[float] = None,
+ knobs: Optional[dict[str, str]] = None,
) -> LoadResult:
routes = MEDIA_ROUTES[kind]
+ knobs = knobs or {}
if hf_token:
# The GGUF lookup reads the Hub token from the header, so a gated repo needs it there too.
caller = dataclasses.replace(caller, hf_token = hf_token)
@@ -569,12 +621,12 @@ async def load_media(
async def prepare() -> None:
# Hub and plan reads run inside the job, so a slow one never holds the call past ``wait_s``.
if variant or "gguf" in model.lower():
- filename = await _gguf_filename(caller, model, variant)
- if filename:
- body["gguf_filename"] = filename
+ entry = await _gguf_filename(caller, model, variant)
+ if entry:
+ body["gguf_filename"] = entry["filename"]
body["model_kind"] = "gguf"
# The plan validates the pick the way the load does, before any download.
- plan = await route_json("POST", routes["plan"], caller = caller, json_body = body)
+ plan = await place.post_plan(caller, routes["plan"], body, knobs)
if isinstance(plan, dict):
if opt_text(plan.get("incompatible_reason")):
raise tool_error(plan["incompatible_reason"])
@@ -592,7 +644,7 @@ async def load_media(
await prepare()
# The answer names what the arbiter unloaded to make room; the load itself goes on in the background.
job.post = asyncio.ensure_future(
- route_json("POST", routes["load"], caller = caller, json_body = body)
+ route_json("POST", routes["load"], caller = caller, json_body = {**body, **knobs})
)
job.post.add_done_callback(lambda post: post.cancelled() or post.exception())
answer = await with_progress(
@@ -600,7 +652,9 @@ async def load_media(
)
status = await _media_ready(caller, kind, model, routes, job, body)
name = _media_name(status) or model
- return await finish_load(caller, kind, name, before, answer)
+ return await finish_load(
+ caller, kind, name, before, answer, placement = place.media_placement(status)
+ )
return await start_load(
caller,
@@ -610,6 +664,7 @@ async def load_media(
variant = variant,
deadline = deadline or deadline_after(None),
run = run,
+ options = tuple(sorted(knobs.items())),
)
@@ -879,3 +934,73 @@ async def unload_stt(caller: Caller, model: Optional[str]) -> UnloadResult:
after = (await stt_status(caller)).get(engine)
still = isinstance(after, dict) and after.get("loaded_model") == name
return UnloadResult(kind = "stt", model = name, unloaded = not still)
+
+
+async def unload_all(caller: Caller) -> UnloadAllResult:
+ """Unload every chat slot, then the image, video and speech-to-text models. The embedding model is Unsloth Studio's own and stays. A step that fails does not stop the rest; the error then names what was unloaded and what was not."""
+ failed: list[str] = []
+
+ async def unload(name: str, target: str) -> None:
+ try:
+ await route_json(
+ "POST", "/api/inference/unload", caller = caller, json_body = {"model_path": target}
+ )
+ except ToolError as exc:
+ failed.append(f"{name}: {exc}")
+
+ async def resident() -> tuple[list[str], list[str], set[str]]:
+ # Bounded: a stalled status read fails the chat step, and the other slots still go.
+ try:
+ return await asyncio.wait_for(_llm_resident(caller), READ_S)
+ except asyncio.TimeoutError:
+ raise ToolError("Unsloth Studio did not say which chat models are loaded") from None
+
+ unloaded: list[SlotModel] = []
+ try:
+ serving, checkpoints, _before = await resident()
+ pairs = list(zip(serving, checkpoints))
+ # Kept models first, so unloading the primary never promotes one of them in between.
+ for name, target in reversed(pairs):
+ await unload(name, target)
+ now_serving, now_checkpoints, after = await resident()
+ # A model the unloads promoted still serves (by name and by checkpoint): unload it too.
+ promoted = [pair for pair in zip(now_serving, now_checkpoints) if pair not in pairs]
+ for name, target in promoted:
+ await unload(name, target)
+ # Models held in memory behind the active one are listed only under loaded.
+ known = {*serving, *checkpoints, *now_serving, *now_checkpoints}
+ held = [name for name in after if name not in known]
+ for name in held:
+ await unload(name, name)
+ if held or promoted:
+ _serving, _checkpoints, after = await resident()
+ pairs += promoted + [(name, name) for name in held]
+ unloaded += [
+ SlotModel(kind = "llm", model = name)
+ for name, target in pairs
+ if not {name, target} & after
+ ]
+ except ToolError as exc:
+ # Unsloth Studio could not say which chat models are loaded; the other slots still go.
+ failed.append(f"llm: {exc}")
+ for kind in MEDIA_ROUTES:
+ try:
+ result = await unload_media(caller, kind)
+ except ToolError as exc:
+ failed.append(f"{kind}: {exc}")
+ continue
+ if result.unloaded and result.model:
+ unloaded.append(SlotModel(kind = kind, model = result.model))
+ for _engine in STT_ENGINES:
+ try:
+ result = await unload_stt(caller, None)
+ except ToolError as exc:
+ failed.append(f"stt: {exc}")
+ break
+ if not (result.unloaded and result.model):
+ break
+ unloaded.append(SlotModel(kind = "stt", model = result.model))
+ if failed:
+ done = ", ".join(f"{slot.kind} {slot.model}" for slot in unloaded) or "nothing"
+ raise ToolError(f"Unloaded {done}; could not unload {'; '.join(failed)}")
+ return UnloadAllResult(unloaded = unloaded)
diff --git a/studio/backend/studio_mcp/outputs.py b/studio/backend/studio_mcp/outputs.py
index 57e393dd000..7e295a64b2e 100644
--- a/studio/backend/studio_mcp/outputs.py
+++ b/studio/backend/studio_mcp/outputs.py
@@ -79,6 +79,18 @@ def audio_options(rows: Any) -> Optional[list[AudioOption]]:
return options or None
+class Placement(ToolOutput):
+ """Where a model ended up, as Unsloth Studio reports it after the load."""
+
+ # "cpu" or "gpu"; for a speech model that asked for the GPU and fell back, "cpu".
+ device: Optional[RouteText] = None
+ memory_mode: Optional[RouteText] = None
+ # How much of an image or video model is moved off the GPU: none, model, group, streaming or sequential.
+ offload_policy: Optional[RouteText] = None
+ transformer_quant: Optional[RouteText] = None
+ text_encoder_quant: Optional[RouteText] = None
+
+
class MusicModeBounds(ToolOutput):
# A music mode's duration_s range and default, in seconds.
id: RouteText
@@ -140,6 +152,7 @@ class ImageSlot(ToolOutput):
# How the loaded model reads prompts, in one or two sentences.
prompt_hint: Optional[RouteText] = None
generating: bool = False
+ placement: Optional[Placement] = None
class VideoSlot(ToolOutput):
@@ -153,6 +166,7 @@ class VideoSlot(ToolOutput):
# "WIDTHxHEIGHT" sizes the loaded model renders.
size_presets: list[RouteText] = []
generating: bool = False
+ placement: Optional[Placement] = None
class SttDownload(ToolOutput):
@@ -268,6 +282,9 @@ class LoadResult(ToolOutput):
job_id: Optional[RouteText] = None
poll_after_s: Optional[float] = None
display_name: Optional[RouteText] = None
+ placement: Optional[Placement] = None
+ # True when the chat model that was serving before the load still serves; None when none was.
+ alongside_applied: Optional[bool] = None
evicted: list[RouteText] = []
evicted_slots: list[EvictedSlot] = []
@@ -284,6 +301,43 @@ class UnloadResult(ToolOutput):
unloaded: bool
+class SlotModel(ToolOutput):
+ # llm (chat, TTS and audio models share it), image, video or stt.
+ kind: RouteText
+ model: RouteText
+
+
+class UnloadAllResult(ToolOutput):
+ kind: RouteText = "all"
+ unloaded: list[SlotModel] = []
+
+
+class PlanVariant(ToolOutput):
+ variant: RouteText
+ size_bytes: Optional[int] = None
+ downloaded: bool = False
+ # Some files are on disk but not all: a download still running, or one that stopped.
+ partial: bool = False
+
+
+class PlanLoadResult(ToolOutput):
+ model: RouteText
+ kind: RouteText
+ variants: list[PlanVariant] = []
+ # Bytes still to download for this load; None when Unsloth Studio cannot tell before downloading.
+ download_bytes: Optional[int] = None
+ # The GPU memory the load is estimated to take; only known for a downloaded GGUF chat model.
+ est_gpu_bytes: Optional[int] = None
+ residents: list[SlotModel] = []
+ # off, fit or always (Keep multiple models loaded); None when this Unsloth Studio does not report it.
+ multi_model_mode: Optional[RouteText] = None
+ would_evict: list[SlotModel] = []
+ # False when would_evict is an upper bound: the load may keep some of them.
+ would_evict_exact: bool = True
+ # True when Keep multiple models loaded is Always and the load may be refused instead of unloading a model.
+ would_refuse: bool = False
+
+
class Usage(ToolOutput):
prompt_tokens: Optional[int] = None
completion_tokens: Optional[int] = None
@@ -493,6 +547,10 @@ class AnalysisResult(ToolOutput):
class VideoJobRef(ToolOutput):
id: RouteText
status: RouteText
+ # Set while the video waits in this MCP server's queue behind another video; 1 is next.
+ queue_position: Optional[int] = None
+ # Seconds until the queued video is expected to start, from the running video's progress.
+ eta_s: Optional[float] = None
progress: Optional[int] = None
progress_percent: Optional[float] = None
@@ -594,6 +652,8 @@ class JobStatus(ToolOutput):
poll_after_s: Optional[float] = None
training: Optional[TrainingJob] = None
load: Optional[LoadResult] = None
+ queue_position: Optional[int] = None
+ eta_s: Optional[float] = None
error: Optional[RouteText] = None
error_code: Optional[RouteText] = None
video: Optional[VideoInfo] = None
diff --git a/studio/backend/studio_mcp/placement.py b/studio/backend/studio_mcp/placement.py
new file mode 100644
index 00000000000..2a57328465c
--- /dev/null
+++ b/studio/backend/studio_mcp/placement.py
@@ -0,0 +1,548 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""How and where ``load_model`` puts a model: the media memory knobs, the chat and audio device fields, the placement Unsloth Studio reports back, and ``plan_load``'s read-only preview of what a load would download and unload."""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+from typing import Any, Optional
+
+from fastmcp.exceptions import ToolError
+
+from studio_mcp.caller import Caller
+from studio_mcp.errors import raise_for_route, tool_error
+from studio_mcp.forward import forward
+from studio_mcp.outputs import Placement, PlanLoadResult, PlanVariant, SlotModel
+from studio_mcp.tools import as_dict, integer, opt_text, strings, try_json
+
+CHAT_KINDS = ("llm", "tts", "audio")
+# Each media knob and the kinds whose load request takes it.
+MEDIA_KNOBS = {
+ "memory_mode": ("image", "video"),
+ "speed_mode": ("image", "video"),
+ "transformer_quant": ("image",),
+ "text_encoder_quant": ("image",),
+ "h3_task": ("video",),
+}
+MULTI_MODEL_MODES = ("off", "fit", "always")
+STATUS = "/api/inference/status"
+MEDIA_STATUS = {"image": "/api/inference/images/status", "video": "/api/inference/video/status"}
+MEDIA_PLAN = {
+ "image": "/api/inference/images/download-plan",
+ "video": "/api/inference/video/download-plan",
+}
+MEDIA_PROGRESS = {
+ "image": "/api/inference/images/load-progress",
+ "video": "/api/inference/video/load-progress",
+}
+STT_STATUS = "/api/inference/audio/stt/status"
+# audio.cpp folder ids name a GGUF repo but run on audio.cpp, which honours audio_device itself.
+AUDIO_CPP_PREFIX = "audio-cpp/audio.cpp-gguf/"
+IN_FLIGHT = ("running", "cancelling")
+READ_S = 15.0
+PARTIAL_MESSAGE = "this variant is still downloading or incomplete; wait for it or redownload it"
+
+
+def media_knobs(kind: str, **knobs: Optional[str]) -> dict[str, str]:
+ """The knobs that were set, refused for a kind whose load does not take them."""
+ chosen = {name: value for name, value in knobs.items() if value is not None}
+ for name in chosen:
+ if kind not in MEDIA_KNOBS[name]:
+ only = " and ".join(MEDIA_KNOBS[name])
+ raise ToolError(f"{name} is only for {only} loads, not kind={kind!r}.")
+ return chosen
+
+
+def is_local(model: str) -> bool:
+ # `ref:<digest>` is the handle an API-key caller gets for a local model: whole, never repo:variant.
+ return model.startswith(("/", "\\", ".", "~", "ref:")) or ":" in model[:3]
+
+
+def is_gguf(model: str, variant: Optional[str]) -> bool:
+ return bool(variant) or "gguf" in model.lower()
+
+
+def check_placement(
+ kind: str,
+ *,
+ device: Optional[str],
+ alongside: Optional[bool],
+ kv_cache_type: Optional[str],
+ gpu_layers: Optional[int],
+) -> None:
+ """Refuse a placement field the load of this kind would ignore, before anything is sent."""
+ if kind not in CHAT_KINDS:
+ given = {
+ "device": device,
+ "alongside": alongside,
+ "kv_cache_type": kv_cache_type,
+ "gpu_layers": gpu_layers,
+ }
+ for name, value in given.items():
+ if value is not None:
+ raise ToolError(f"{name} is only for llm, tts and audio loads, not kind={kind!r}.")
+ return
+ if gpu_layers is not None and (
+ (device == "cpu" and gpu_layers > 0) or (device == "gpu" and gpu_layers == 0)
+ ):
+ raise ToolError(f"gpu_layers={gpu_layers} contradicts device={device!r}.")
+
+
+CPU_NEEDS_GGUF = (
+ "device='cpu' needs a GGUF model for kind='llm': Unsloth Studio places only GGUF "
+ "chat models on the CPU. Pick a GGUF repo or a variant."
+)
+
+
+async def listed_gguf(caller: Caller, model: str, variant: Optional[str]) -> Optional[bool]:
+ """Whether the load runs on llama-server: Unsloth Studio lists GGUF files for the model (a name with "gguf" in it proves nothing). audio.cpp models never do. None when the listing could not be read."""
+ repo, variant = _split(model, variant)
+ if repo.lower().startswith(AUDIO_CPP_PREFIX):
+ return False
+ if repo.lower().endswith(".gguf"):
+ return True
+ listing = await _variants(caller, repo)
+ if listing is None:
+ # Unsloth Studio could not list it (offline, say): the name is all there is to go on.
+ return None
+ listing = as_dict(listing)
+ # MLX precision folders come back from the same listing; they never run on llama-server.
+ if listing.get("variant_format") == "mlx":
+ return False
+ return any(isinstance(row, dict) for row in listing.get("variants") or [])
+
+
+async def require_cpu_gguf(
+ caller: Caller,
+ kind: str,
+ model: str,
+ variant: Optional[str],
+ device: Optional[str],
+ gpu_layers: Optional[int] = None,
+) -> Optional[bool]:
+ """For device='cpu' or gpu_layers, whether the model is a llama-server GGUF (None otherwise). A placement only llama-server honours is refused for any other model."""
+ if kind not in CHAT_KINDS or (device != "cpu" and gpu_layers is None):
+ return None
+ gguf = await listed_gguf(caller, model, variant)
+ if gguf is None and kind != "llm":
+ # A TTS still goes to the CPU; only llama-server needs its layers kept off the GPU too.
+ gguf = is_gguf(model, variant)
+ if not gguf and kind == "llm" and device == "cpu":
+ raise ToolError(CPU_NEEDS_GGUF)
+ if not gguf and gpu_layers is not None:
+ raise ToolError("gpu_layers is only for GGUF models that run on llama-server.")
+ repo, variant = _split(model, variant)
+ if gguf and variant and not is_local(repo):
+ listing = await _variants(caller, repo)
+ # Only a listing that was read can say the variant is missing.
+ if isinstance(listing, dict) and pick_variant(listing, variant) is None:
+ raise ToolError(f"{repo} has no GGUF variant {variant}")
+ return gguf
+
+
+def llm_fields(
+ kind: str,
+ *,
+ gguf: Optional[bool],
+ device: Optional[str],
+ alongside: Optional[bool],
+ kv_cache_type: Optional[str],
+ gpu_layers: Optional[int],
+) -> dict[str, Any]:
+ """The /api/inference/load fields for the placement asked for; ``gguf`` says the load runs on llama-server."""
+ fields: dict[str, Any] = {}
+ # audio_device is read by native and audio.cpp audio only; a chat GGUF sent it is refused.
+ if kind != "llm" and device is not None:
+ fields["audio_device"] = device
+ if (device == "cpu" or (device in (None, "auto") and gpu_layers == 0)) and gguf:
+ # No layers, and no speculative drafter, which would put the GPU back to use.
+ fields.update(gpu_memory_mode = "manual", gpu_layers = 0, speculative_type = "off")
+ elif gpu_layers is not None:
+ fields.update(gpu_memory_mode = "manual", gpu_layers = gpu_layers)
+ if alongside is not None:
+ fields["alongside"] = alongside
+ if kv_cache_type is not None:
+ fields["cache_type_kv"] = kv_cache_type
+ return fields
+
+
+def multi_model_mode(status: Any) -> Optional[str]:
+ mode = as_dict(status).get("multi_model_mode")
+ return mode if mode in MULTI_MODEL_MODES else None
+
+
+async def auto_alongside(
+ caller: Caller,
+ device: Optional[str],
+ alongside: Optional[bool],
+ gpu_layers: Optional[int] = None,
+) -> Optional[bool]:
+ """Under Always, a CPU load (device='cpu', or no GPU layers) joins the serving chat model rather than being refused for replacing it."""
+ cpu = device == "cpu" or (device in (None, "auto") and gpu_layers == 0)
+ if not cpu or alongside is not None:
+ return alongside
+ try:
+ # Bounded: a stalled read decides nothing rather than holding the load.
+ status = await asyncio.wait_for(try_json(caller, STATUS), READ_S)
+ except asyncio.TimeoutError:
+ return None
+ if multi_model_mode(status) == "always" and strings(as_dict(status).get("serving")):
+ return True
+ return None
+
+
+def llm_placement(answer: Any, device: Optional[str]) -> Optional[Placement]:
+ """The device a chat or audio load ended on, from the load answer."""
+ answer = as_dict(answer)
+ offloaded = integer(answer.get("offloaded_layers"))
+ # What the load reports beats what was asked for.
+ if answer.get("audio_device_fallback") == "cpu":
+ placed = "cpu"
+ elif offloaded is not None:
+ placed = "gpu" if offloaded > 0 else "cpu"
+ else:
+ # An asked-for GPU is not proof: native audio runs on the CPU when there is no GPU.
+ placed = "cpu" if device == "cpu" else None
+ return Placement(device = placed) if placed else None
+
+
+def media_placement(status: Any) -> Optional[Placement]:
+ """The placement an image or video status reports, with the device as cpu or gpu."""
+ status = as_dict(status)
+ if status.get("loaded") is not True:
+ return None
+ device = opt_text(status.get("device"))
+ if device is not None:
+ device = "cpu" if device.lower() == "cpu" else "gpu"
+ placed = Placement.from_route(status, device = device)
+ return placed if any(placed.model_dump().values()) else None
+
+
+def alongside_applied(before: list[str], after: Optional[list[str]], loaded: str) -> Optional[bool]:
+ """Whether the chat model that served before the load still serves; None when none did, or when status could not say."""
+ previous = before[0] if before else None
+ if previous is None or after is None or previous.lower() == loaded.lower():
+ return None
+ return previous in after
+
+
+async def post_plan(caller: Caller, path: str, body: dict, knobs: dict) -> Any:
+ """The download plan, priced with the knobs; an Unsloth Studio whose plan refuses them is asked without."""
+ response = await forward(caller, "POST", path, json_body = {**body, **knobs})
+ if knobs and response.status_code == 422:
+ response = await forward(caller, "POST", path, json_body = body)
+ return raise_for_route(response)
+
+
+def pick_variant(listing: Any, variant: Optional[str]) -> Optional[dict]:
+ """The named variant's row in a gguf-variants listing, else the repo's default."""
+ listing = as_dict(listing)
+ rows = [row for row in listing.get("variants") or [] if isinstance(row, dict)]
+ wanted = (variant or opt_text(listing.get("default_variant")) or "").lower()
+ for row in rows:
+ if str(row.get("quant", "")).lower() == wanted:
+ return row
+ return None if variant else (rows[0] if rows else None)
+
+
+def _split(model: str, variant: Optional[str]) -> tuple[str, Optional[str]]:
+ # A GGUF may be named "repo:variant".
+ if variant is None and ":" in model and not is_local(model):
+ model, _, variant = model.partition(":")
+ return model, variant
+
+
+async def _variants(caller: Caller, model: str) -> Any:
+ return await try_json(
+ caller, "/api/hub/gguf-variants", params = {"repo_id": model}, hub_header = True
+ )
+
+
+async def refuse_partial_variant(
+ caller: Caller, model: str, kind: str, variant: Optional[str]
+) -> None:
+ """Refuse a GGUF variant with only part of its files on disk that Unsloth Studio is not downloading itself; loading it fails with a misleading memory error."""
+ if kind == "stt" or is_local(model) or model.lower().startswith(AUDIO_CPP_PREFIX):
+ return
+ repo, variant = _split(model, variant)
+ # A chat model is a GGUF when the listing has rows, whatever it is called; an image or video
+ # load uses a GGUF file only for a named variant or a GGUF repo, as load_media does.
+ if kind in MEDIA_PROGRESS and not is_gguf(repo, variant):
+ return
+ row = pick_variant(await _variants(caller, repo), variant)
+ if row is None or row.get("partial") is not True or row.get("downloaded") is True:
+ return
+ quant = opt_text(row.get("quant"))
+ if kind in MEDIA_PROGRESS:
+ # An image or video load already downloading it (from the Images or Video page) is not refused.
+ progress = await try_json(caller, MEDIA_PROGRESS[kind])
+ if as_dict(progress).get("phase") not in (None, "ready", "error"):
+ return
+ # A download Unsloth Studio manages is waited on before this, never refused.
+ state = await try_json(
+ caller, "/api/hub/download-status", params = {"repo_id": repo, "gguf_variant": quant}
+ )
+ if as_dict(state).get("state") in IN_FLIGHT:
+ return
+ raise ToolError(
+ f"{repo} {quant}: {PARTIAL_MESSAGE}." if quant else f"{repo}: {PARTIAL_MESSAGE}."
+ )
+
+
+def _named(status: Any) -> Optional[str]:
+ status = as_dict(status)
+ if status.get("loaded") is not True:
+ return None
+ return opt_text(status.get("display_repo_id")) or opt_text(status.get("repo_id"))
+
+
+def residents(status: Any, image: Any, video: Any, stt: Any) -> list[SlotModel]:
+ status = as_dict(status)
+ # Serving first (the primary leads), then models held in memory behind it.
+ chat = dict.fromkeys([*strings(status.get("serving")), *strings(status.get("loaded"))])
+ slots = [SlotModel(kind = "llm", model = name) for name in chat]
+ for kind, payload in (("image", image), ("video", video)):
+ if _named(payload):
+ slots.append(SlotModel(kind = kind, model = _named(payload)))
+ for state in as_dict(stt).values():
+ if isinstance(state, dict) and opt_text(state.get("loaded_model")):
+ slots.append(SlotModel(kind = "stt", model = state["loaded_model"]))
+ # Status repeats the active STT model at its top level for older clients: list each once.
+ return list({(slot.kind, slot.model): slot for slot in slots}.values())
+
+
+def _cpu_primary(status: Any) -> bool:
+ # A primary that holds no VRAM gives up the GPU claim, so a media load leaves it alone.
+ status = as_dict(status)
+ manual = status.get("gpu_memory_mode") == "manual" and status.get("gpu_layers") == 0
+ return manual or status.get("audio_device_fallback") == "cpu"
+
+
+def _ident(name: str) -> str:
+ # Local paths keep their case, as the loaders do; Hub ids do not.
+ return name if is_local(name) else name.lower()
+
+
+def _repo(name: str) -> str:
+ return name if is_local(name) else name.split(":", 1)[0].lower()
+
+
+def predict(
+ *,
+ kind: str,
+ model: str,
+ device: Optional[str],
+ alongside: Optional[bool],
+ mode: Optional[str],
+ status: Any,
+ slots: list[SlotModel],
+ has_vision: bool = False,
+) -> tuple[list[SlotModel], bool, bool]:
+ """(would_evict, would_evict_exact, would_refuse) for one load. Exact under Off; under When they fit and Always, or when the mode is unknown, an upper bound."""
+ slot_kind = "llm" if kind in CHAT_KINDS else kind
+ if kind == "stt":
+ # A speech-to-text load releases the other engines' models, unless one is transcribing.
+ others = [s for s in slots if s.kind == "stt" and _ident(s.model) != _ident(model)]
+ return others, not others, False
+ same_repo = [s for s in slots if s.kind == slot_kind and _repo(s.model) == _repo(model)]
+ # A load of a resident repo may load it again (another variant, context, device or build), so it
+ # is predicted as a new load and reported as an upper bound.
+ exact = not same_repo
+ chat = [s for s in slots if s.kind == "llm"]
+ media = [s for s in slots if s.kind in ("image", "video")]
+ if kind in CHAT_KINDS:
+ gpu = device != "cpu" or has_vision
+ joins = (
+ alongside
+ if alongside is not None
+ else (mode == "always" and device == "cpu" and bool(chat))
+ )
+ # Off replaces the primary and unloads the idle kept models whatever alongside says. A model
+ # only held in memory (not serving) may stay, so with one the prediction is an upper bound.
+ if set(strings(as_dict(status).get("loaded"))) - set(
+ strings(as_dict(status).get("serving"))
+ ):
+ exact = False
+ off_set = chat + (media if gpu else [])
+ upper = [] if joins and not gpu else off_set
+ # Always lets a load replace its own repo, as another file or setting of it.
+ same, holders = same_repo, upper
+ if joins:
+ # Joining keeps the chat models: only another owner (image, video) can refuse it.
+ holders = [s for s in upper if s.kind != "llm"]
+ else:
+ # Only another build of the same repo may replace the resident under Always; another model is refused.
+ same = same_repo
+ held = chat
+ if chat and _cpu_primary(status):
+ held, exact = chat[1:], False
+ elif chat and as_dict(status).get("is_audio") is True:
+ # A native TTS primary on the CPU holds no VRAM, but status does not say where it runs.
+ exact = False
+ off_set = held + media
+ upper = chat + media
+ # A chat model holding no VRAM gave up its GPU claim, so Always does not protect it.
+ holders = off_set
+ if mode == "off":
+ return off_set, exact, False
+ if mode == "fit":
+ return upper, False, False
+ if mode == "always":
+ return [], False, any(s not in same for s in holders)
+ # Unknown mode (an Unsloth Studio that does not report it): whatever either rule could unload.
+ return upper + [s for s in off_set if s not in upper], False, False
+
+
+async def _bounded(caller: Caller, path: str) -> Any:
+ # A stalled read is an unreadable one: the plan then says it is an upper bound.
+ try:
+ return await asyncio.wait_for(try_json(caller, path), READ_S)
+ except asyncio.TimeoutError:
+ return None
+
+
+async def _post_json(caller: Caller, path: str, body: dict) -> Any:
+ try:
+ response = await forward(caller, "POST", path, json_body = body, hub_header = True)
+ return response.json() if response.status_code == 200 else None
+ except Exception:
+ return None
+
+
+async def plan_load(
+ caller: Caller,
+ *,
+ model: str,
+ kind: str,
+ variant: Optional[str],
+ device: Optional[str],
+ alongside: Optional[bool],
+ knobs: Optional[dict[str, str]] = None,
+ hf_token: Optional[str] = None,
+ gpu_layers: Optional[int] = None,
+ kv_cache_type: Optional[str] = None,
+) -> PlanLoadResult:
+ if hf_token:
+ # As in load_model: the listing reads it from the header, the plan routes from the body.
+ caller = dataclasses.replace(caller, hf_token = hf_token)
+ # The same refusals load_model makes, so a plan is never shown for a load that cannot run.
+ where = {
+ "device": device,
+ "alongside": alongside,
+ "kv_cache_type": kv_cache_type,
+ "gpu_layers": gpu_layers,
+ }
+ check_placement(kind, **where)
+ await require_cpu_gguf(caller, kind, model, variant, device, gpu_layers)
+ await refuse_partial_variant(caller, model, kind, variant)
+ status, image, video, stt = await asyncio.gather(
+ *(_bounded(caller, path) for path in (STATUS, *MEDIA_STATUS.values(), STT_STATUS))
+ )
+ repo, variant = _split(model, variant)
+ rows: list[dict] = []
+ row = listing = None
+ # Whether it is a GGUF repo is the listing's answer, not the repo's spelling.
+ if kind != "stt" and not (is_local(repo) and repo.lower().endswith(".gguf")):
+ # A failed lookup stays None (unknown), not an empty listing.
+ listing = await _variants(caller, repo)
+ rows = [r for r in as_dict(listing).get("variants") or [] if isinstance(r, dict)]
+ row = pick_variant(listing, variant)
+ if variant and row is None and isinstance(listing, dict):
+ raise ToolError(f"{repo} has no GGUF variant {variant}")
+ if device in (None, "auto") and gpu_layers is not None and kind in CHAT_KINDS:
+ # llama-server honours gpu_layers, so a GGUF load is placed by it: 0 keeps it off the GPU.
+ if rows or repo.lower().endswith(".gguf"):
+ device = "cpu" if gpu_layers == 0 else "gpu"
+ download = est = None
+ if row is not None:
+ download = (
+ 0
+ if row.get("downloaded") is True
+ else next(
+ (
+ integer(row.get(key))
+ for key in ("download_remaining_bytes", "download_size_bytes", "size_bytes")
+ if integer(row.get(key)) is not None
+ ),
+ None,
+ )
+ )
+ if kind in MEDIA_PLAN:
+ body: dict[str, Any] = {"model_path": repo}
+ # The file load_media sends: a GGUF only for a named variant or a GGUF repo.
+ if (
+ (variant or "gguf" in repo.lower())
+ and row is not None
+ and opt_text(row.get("filename"))
+ ):
+ body.update(gguf_filename = row["filename"], model_kind = "gguf")
+ # The plan routes read the Hub token from the body, as the load routes do.
+ if caller.hf_token:
+ body["hf_token"] = caller.hf_token
+ # The plan load_model would read first, with the same knobs; its refusal is the load's.
+ plan = as_dict(await post_plan(caller, MEDIA_PLAN[kind], body, knobs or {}))
+ if opt_text(plan.get("incompatible_reason")):
+ raise tool_error(plan["incompatible_reason"])
+ download = integer(plan.get("total_bytes"))
+ # The estimate prices the default GPU placement, so a CPU load leaves it unknown.
+ elif row is not None and row.get("downloaded") is True and device != "cpu":
+ estimate = as_dict(
+ await _post_json(
+ caller,
+ "/api/inference/estimate-memory",
+ {
+ "model_path": repo,
+ "gguf_variant": opt_text(row.get("quant")),
+ # Read from the body, like the plan routes.
+ **({"hf_token": caller.hf_token} if caller.hf_token else {}),
+ **({"cache_type_kv": kv_cache_type} if kv_cache_type else {}),
+ **(
+ {"gpu_memory_mode": "manual", "gpu_layers": gpu_layers}
+ if gpu_layers is not None
+ else {}
+ ),
+ },
+ )
+ )
+ est = integer(estimate.get("gpu_bytes")) if estimate.get("available") is True else None
+ slots = residents(status, image, video, stt)
+ mode = multi_model_mode(status)
+ would_evict, exact, refuse = predict(
+ kind = kind,
+ model = repo,
+ device = device,
+ alongside = alongside,
+ mode = mode,
+ status = status,
+ slots = slots,
+ # A local GGUF file is not listed, so whether a projector keeps it on the GPU is unknown.
+ has_vision = listing is None or as_dict(listing).get("has_vision") is True,
+ )
+ # Unloading another kind's model depends on the load reaching the GPU, which no setting
+ # guarantees: Unsloth Studio may run a load on the CPU (always, without a GPU) and leave the
+ # other slots alone, so such a prediction is an upper bound.
+ slot_kind = "llm" if kind in CHAT_KINDS else kind
+ unpinned = any(s.kind != slot_kind for s in would_evict)
+ unlisted = kind in CHAT_KINDS and listing is None
+ reads = (image, video, stt) if kind == "stt" else (status, image, video)
+ # A chat model still loading is not a resident yet, but may be one by the time this load runs.
+ loading = bool(strings(as_dict(status).get("loading")))
+ if unlisted or unpinned or loading or not all(isinstance(read, dict) for read in reads):
+ # A slot whose status could not be read may hold a model the load would unload.
+ exact = False
+ return PlanLoadResult(
+ model = repo,
+ kind = kind,
+ variants = [
+ PlanVariant.from_route(r, variant = r["quant"]) for r in rows if opt_text(r.get("quant"))
+ ],
+ download_bytes = download,
+ est_gpu_bytes = est,
+ residents = slots,
+ multi_model_mode = mode,
+ would_evict = would_evict,
+ would_evict_exact = exact,
+ would_refuse = refuse,
+ )
diff --git a/studio/backend/studio_mcp/tools/cancel.py b/studio/backend/studio_mcp/tools/cancel.py
index 6fdc65ecab8..eab7505b451 100644
--- a/studio/backend/studio_mcp/tools/cancel.py
+++ b/studio/backend/studio_mcp/tools/cancel.py
@@ -10,7 +10,7 @@ from urllib.parse import quote
from fastmcp.exceptions import ToolError
-from studio_mcp import export_jobs, job_store
+from studio_mcp import export_jobs, job_store, video_queue
from studio_mcp.caller import current_caller
from studio_mcp.outputs import CancelResult
from studio_mcp.tools import DESTRUCTIVE, EXPORT_STATUS, as_dict, opt_text, route_json
@@ -167,6 +167,8 @@ async def cancel(
if not _stopped(kind, answer):
return done(False, _message(answer))
return done(True, "The export was stopped and its checkpoint unloaded.")
+ elif kind == "video" and id and video_queue.is_queue_id(id):
+ return done(*video_queue.cancel(caller.account_id, id))
else:
path, id_field = ROUTES[kind]
answer = await route_json(
diff --git a/studio/backend/studio_mcp/tools/jobs.py b/studio/backend/studio_mcp/tools/jobs.py
index e869016842c..9151f86864f 100644
--- a/studio/backend/studio_mcp/tools/jobs.py
+++ b/studio/backend/studio_mcp/tools/jobs.py
@@ -16,7 +16,7 @@ from fastmcp.tools import ToolResult
from pydantic import Field
from studio_mcp import checkpoints as named
-from studio_mcp import export_jobs, loading
+from studio_mcp import export_jobs, loading, video_queue
from studio_mcp.caller import Caller, current_caller
from studio_mcp.errors import raise_for_route
from studio_mcp.forward import forward
@@ -304,6 +304,14 @@ async def _read_once(
return await _training_job(caller, kind, job_id)
if job_id is None:
return await _video_jobs(caller)
+ if video_queue.is_queue_id(job_id):
+ item = video_queue.lookup(caller.account_id, job_id)
+ if not item.video_id:
+ queued = await video_queue.job_status(item)
+ # Unless it started while that was read: then it is the video it became.
+ if not item.video_id:
+ return media_result([], queued)
+ return await _video_job(caller, item.video_id, return_media, preview_px)
return await _video_job(caller, job_id, return_media, preview_px)
diff --git a/studio/backend/studio_mcp/tools/models.py b/studio/backend/studio_mcp/tools/models.py
index d72ab5cc198..212745a0212 100644
--- a/studio/backend/studio_mcp/tools/models.py
+++ b/studio/backend/studio_mcp/tools/models.py
@@ -11,11 +11,21 @@ from urllib.parse import quote
from fastmcp import Context
from fastmcp.exceptions import ToolError
+from fastmcp.tools import ToolResult
from pydantic import Field
-from studio_mcp import loading
+from studio_mcp import loading, placement
from studio_mcp.caller import current_caller
-from studio_mcp.outputs import HardwareSlot, LoadResult, ModelEntry, ModelList, UnloadResult
+from studio_mcp.media import media_result
+from studio_mcp.outputs import (
+ HardwareSlot,
+ LoadResult,
+ ModelEntry,
+ ModelList,
+ PlanLoadResult,
+ UnloadAllResult,
+ UnloadResult,
+)
from studio_mcp.tools import (
DESTRUCTIVE,
READ_ONLY,
@@ -32,6 +42,66 @@ from studio_mcp.tools.status import SLOT_ROUTES, _hardware
# "tts" and "audio" are what list_models reports for audio models; they load in the llm slot.
ModelKind = Literal["llm", "image", "video", "stt", "tts", "audio"]
AudioWorkflow = Literal["speak", "clone", "edit", "convert", "music", "separate", "transcribe"]
+UnloadKind = Literal["llm", "image", "video", "stt", "tts", "audio", "all"]
+
+MemoryMode = Annotated[
+ Optional[Literal["auto", "fast", "balanced", "low_vram"]],
+ Field(
+ description = 'Image and video. "auto" (the default) measures free VRAM and picks how much of the model to move off the GPU; "low_vram" keeps the least on the GPU, for when other GPU work is resident; "fast" and "balanced" keep more. With Keep multiple models loaded set to When they fit, an image or video model whose transformer stays on the GPU loads beside the chat model.'
+ ),
+]
+SpeedMode = Annotated[
+ Optional[Literal["off", "eager", "default", "max"]],
+ Field(
+ description = "Image and video: how hard Unsloth Studio compiles the model for speed; unset uses the model's default."
+ ),
+]
+TransformerQuant = Annotated[
+ Optional[Literal["auto", "none", "off", "int8", "fp8", "nvfp4", "mxfp8"]],
+ Field(
+ description = 'Image only: quantize the transformer on load to save VRAM; unset or "auto" lets Unsloth Studio choose.'
+ ),
+]
+TextEncoderQuant = Annotated[
+ Optional[Literal["auto", "none", "off", "fp8", "fp8_dynamic", "int8", "nvfp4"]],
+ Field(
+ description = 'Image only: quantize the text encoder on load; unset or "auto" lets Unsloth Studio choose.'
+ ),
+]
+H3Task = Annotated[
+ Optional[Literal["fl2va", "ref2va"]],
+ Field(
+ description = 'Video, H3 models only: "fl2va" animates from a first and last frame, "ref2va" from reference images.'
+ ),
+]
+Device = Annotated[
+ Optional[Literal["auto", "cpu", "gpu"]],
+ Field(
+ description = 'llm, tts and audio: where the model runs. "cpu" keeps the GPU free, so a resident image or video model stays loaded; to keep the chat model loaded as well, also pass alongside=true. For kind "llm" it needs a GGUF model, and a vision GGUF still uses the GPU for its projector. "gpu" is never moved to the CPU silently; placement.device reports where the model ended up. Unset leaves the choice to Unsloth Studio.'
+ ),
+]
+Alongside = Annotated[
+ Optional[bool],
+ Field(
+ description = 'llm, tts and audio: keep the chat and speech models already loaded instead of replacing the active one. Needs Keep multiple models loaded set to When they fit or Always; under Off it is ignored. It never keeps image or video models. Under Always, a device="cpu" load beside a serving chat model sends it automatically. alongside_applied says whether the earlier chat model is still serving.'
+ ),
+]
+KvCacheType = Annotated[
+ Optional[Literal["f16", "bf16", "q8_0", "q4_0", "q4_1", "q5_0", "q5_1", "iq4_nl", "f32"]],
+ Field(
+ description = 'GGUF chat models: the KV cache type; "q8_0" roughly halves the context memory of "f16".'
+ ),
+]
+GpuLayers = Annotated[
+ Optional[int],
+ Field(
+ ge = 0,
+ description = "GGUF models: how many layers to put on the GPU (0 runs on the CPU); unset lets Unsloth Studio fit as many as it can.",
+ ),
+]
+
+# plan_load's overall bound, above the 15 s each of its reads may take.
+PLAN_S = 60
KIND_BY_TASK = {
"text-to-image": "image",
@@ -259,8 +329,17 @@ async def load_model(
model: str,
kind: ModelKind = "llm",
variant: Optional[str] = None,
+ memory_mode: MemoryMode = None,
+ speed_mode: SpeedMode = None,
+ transformer_quant: TransformerQuant = None,
+ text_encoder_quant: TextEncoderQuant = None,
+ h3_task: H3Task = None,
max_seq_length: Optional[int] = None,
load_in_4bit: bool = True,
+ device: Device = None,
+ alongside: Alongside = None,
+ kv_cache_type: KvCacheType = None,
+ gpu_layers: GpuLayers = None,
hf_token: Optional[str] = None,
wait_s: Annotated[
Optional[int],
@@ -285,6 +364,21 @@ async def load_model(
Loading may unload other models to make room, for example a chat model to fit an image model; ``evicted`` lists them and ``evicted_slots`` gives each one's kind."""
caller = current_caller()
deadline = loading.deadline_after(wait_s)
+ knobs = placement.media_knobs(
+ kind,
+ memory_mode = memory_mode,
+ speed_mode = speed_mode,
+ transformer_quant = transformer_quant,
+ text_encoder_quant = text_encoder_quant,
+ h3_task = h3_task,
+ )
+ where = {
+ "device": device,
+ "alongside": alongside,
+ "kv_cache_type": kv_cache_type,
+ "gpu_layers": gpu_layers,
+ }
+ placement.check_placement(kind, **where)
if kind == "stt":
async def load_stt(job: loading.LoadJob, _before: Any) -> LoadResult:
@@ -311,6 +405,7 @@ async def load_model(
variant = variant,
hf_token = hf_token,
deadline = deadline,
+ knobs = knobs,
)
return await loading.load_llm(
caller,
@@ -322,16 +417,89 @@ async def load_model(
hf_token = hf_token,
kind = kind,
deadline = deadline,
+ **where,
)
-async def unload_model(kind: ModelKind = "llm", model: Optional[str] = None) -> UnloadResult:
- """Unload a model to free memory. Without ``model`` the active one of that kind is unloaded; image and video have one slot each, so ``model`` is ignored there. The embedding model is managed by Unsloth Studio and is not unloaded here. ``unloaded`` is false when nothing matching was loaded. For "image", "video" and "stt", a load_model of that kind still running is stopped too (a speech-to-text load past its download is unloaded once it finishes, after this call if it takes longer than 240 s)."""
+async def unload_model(kind: UnloadKind = "llm", model: Optional[str] = None) -> ToolResult:
+ """Unload a model to free memory.
+ Without ``model`` the active one of that kind is unloaded; image and video have one slot each, so ``model`` is ignored there.
+ For "image", "video" and "stt", a load_model of that kind still running is stopped too (a speech-to-text load past its download is unloaded once it finishes, after this call if it takes longer than 240 s).
+ kind "all" unloads every chat, speech, image, video and speech-to-text model in one call, stopping image, video and speech-to-text loads as those kinds do, and lists them under ``unloaded``.
+ The embedding model is managed by Unsloth Studio and is not unloaded here.
+ ``unloaded`` is false when nothing matching was loaded."""
+ if kind == "all":
+ if model is not None:
+ raise ToolError("unload_model(kind='all') takes no model.")
+ return media_result([], await loading.unload_all(current_caller()))
if kind == "stt":
- return await loading.unload_stt(current_caller(), model)
+ return media_result([], await loading.unload_stt(current_caller(), model))
if kind in loading.MEDIA_ROUTES:
- return await loading.unload_media(current_caller(), kind)
- return await loading.unload_llm(current_caller(), model, kind)
+ return media_result([], await loading.unload_media(current_caller(), kind))
+ return media_result([], await loading.unload_llm(current_caller(), model, kind))
+
+
+def _unload_schema() -> dict[str, Any]:
+ # One object for both answers: ``unloaded`` is a bool for one kind and the list of models for "all".
+ one, every = UnloadResult.model_json_schema(), UnloadAllResult.model_json_schema()
+ unloaded = {"anyOf": [one["properties"]["unloaded"], every["properties"]["unloaded"]]}
+ return {
+ "type": "object",
+ "$defs": every.get("$defs", {}),
+ "properties": {**one["properties"], "unloaded": unloaded},
+ "required": ["kind", "unloaded"],
+ }
-TOOLS = ((list_models, READ_ONLY), (load_model, WRITES), (unload_model, DESTRUCTIVE))
+async def plan_load(
+ model: str,
+ kind: ModelKind = "llm",
+ variant: Optional[str] = None,
+ device: Device = None,
+ alongside: Alongside = None,
+ memory_mode: MemoryMode = None,
+ speed_mode: SpeedMode = None,
+ transformer_quant: TransformerQuant = None,
+ text_encoder_quant: TextEncoderQuant = None,
+ h3_task: H3Task = None,
+ hf_token: Optional[str] = None,
+ gpu_layers: GpuLayers = None,
+ kv_cache_type: KvCacheType = None,
+) -> PlanLoadResult:
+ """Preview a load_model call without loading or downloading anything.
+ ``variants`` lists a GGUF repo's quantizations with their size and whether each is downloaded or only partly on disk; ``download_bytes`` is what the load would still download, and ``est_gpu_bytes`` the GPU memory a downloaded GGUF chat model is estimated to take.
+ ``residents`` are the models loaded now, and ``would_evict`` the ones this load would unload; pass the same ``device``, ``gpu_layers``, ``kv_cache_type``, ``alongside``, image or video options and ``hf_token`` you would pass to load_model.
+ Under Keep multiple models loaded set to Off the prediction is exact when it does not depend on where Unsloth Studio places the load; unloading another kind of model (which happens only when the load reaches the GPU), and every prediction under When they fit, is an upper bound (``would_evict_exact`` false).
+ Under Always nothing is unloaded and ``would_refuse`` says the load may be refused instead; unload_model(kind="all"), alongside=true or device="cpu" avoid that."""
+ # A preview never hangs: each read inside is bounded, and so is the whole plan.
+ plan = placement.plan_load(
+ current_caller(),
+ model = model,
+ kind = kind,
+ variant = variant,
+ device = device,
+ alongside = alongside,
+ knobs = placement.media_knobs(
+ kind,
+ memory_mode = memory_mode,
+ speed_mode = speed_mode,
+ transformer_quant = transformer_quant,
+ text_encoder_quant = text_encoder_quant,
+ h3_task = h3_task,
+ ),
+ hf_token = hf_token,
+ gpu_layers = gpu_layers,
+ kv_cache_type = kv_cache_type,
+ )
+ try:
+ return await asyncio.wait_for(plan, PLAN_S)
+ except asyncio.TimeoutError:
+ raise ToolError(f"Unsloth Studio did not answer within {PLAN_S} s; try plan_load again.")
+
+
+TOOLS = (
+ (list_models, READ_ONLY),
+ (load_model, WRITES),
+ (unload_model, DESTRUCTIVE, _unload_schema()),
+ (plan_load, READ_ONLY),
+)
diff --git a/studio/backend/studio_mcp/tools/status.py b/studio/backend/studio_mcp/tools/status.py
index d9eba465ecb..6f10c64feaf 100644
--- a/studio/backend/studio_mcp/tools/status.py
+++ b/studio/backend/studio_mcp/tools/status.py
@@ -14,6 +14,7 @@ from fastmcp.exceptions import ToolError
from studio_mcp.caller import Caller, current_caller
from studio_mcp.errors import raise_for_route
from studio_mcp.forward import forward
+from studio_mcp.placement import media_placement
from studio_mcp.outputs import (
ChatModel,
ChatSlot,
@@ -101,6 +102,13 @@ def _media(slot: type, payload: dict) -> Any:
return slot.from_route(payload, loaded = True, model = model, **family, **overrides)
+def _placed(slot: type, payload: dict) -> Any:
+ built = _media(slot, payload)
+ return (
+ built.model_copy(update = {"placement": media_placement(payload)}) if built.loaded else built
+ )
+
+
def _stt(payload: dict) -> SttSlot:
engine = model = None
loading = False
@@ -176,8 +184,8 @@ def _hardware(payload: dict) -> HardwareSlot:
BUILDERS: dict[str, Callable[[dict], Any]] = {
"chat": _chat,
- "image": partial(_media, ImageSlot),
- "video": partial(_media, VideoSlot),
+ "image": partial(_placed, ImageSlot),
+ "video": partial(_placed, VideoSlot),
"stt": _stt,
"embedder": _embedder,
"training": _training,
diff --git a/studio/backend/studio_mcp/tools/video.py b/studio/backend/studio_mcp/tools/video.py
index d527b572ffa..27ee8c580f1 100644
--- a/studio/backend/studio_mcp/tools/video.py
+++ b/studio/backend/studio_mcp/tools/video.py
@@ -12,6 +12,7 @@ from typing import Annotated, Any, Optional, Union
from fastmcp.exceptions import ToolError
from pydantic import Field
+from studio_mcp import video_queue
from studio_mcp.caller import current_caller
from studio_mcp.inputs import (
AudioInput,
@@ -22,7 +23,7 @@ from studio_mcp.inputs import (
resolve_images,
)
from studio_mcp.outputs import VideoJobRef
-from studio_mcp.tools import WRITES, opt_text, present, route_json
+from studio_mcp.tools import WRITES, opt_text, present
from utils.upload_limits import (
VIDEO_INPUT_REFERENCE_JSON_MAX_BYTES,
VIDEO_INPUT_REFERENCE_MAX_BYTES,
@@ -188,15 +189,8 @@ async def generate_video(
raise ToolError(TOO_MANY_IMAGE_BYTES)
if reference_audios:
body["reference_audios"] = [await audio_ref(caller, audio) for audio in reference_audios]
- job = await route_json(
- "POST",
- "/v1/videos",
- caller = caller,
- json_body = body,
- hub_header = True,
- hints = {503: LOAD_VIDEO_HINT},
- )
- return job_ref(job)
+ job = await video_queue.post_or_queue(caller, body, hints = {503: LOAD_VIDEO_HINT})
+ return job if isinstance(job, VideoJobRef) else job_ref(job)
TOOLS = ((generate_video, WRITES),)
diff --git a/studio/backend/studio_mcp/video_queue.py b/studio/backend/studio_mcp/video_queue.py
new file mode 100644
index 00000000000..1e7dfa9959f
--- /dev/null
+++ b/studio/backend/studio_mcp/video_queue.py
@@ -0,0 +1,355 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Videos queued over MCP. Unsloth Studio makes one video at a time and refuses a second while one runs, so an agent submitting a shot list would have to retry each clip itself. generate_video instead queues a refused clip here, in order, and a background task per account submits each one once the video before it ends; get_job and cancel take the queue id.
+
+The queue lives only as long as the Unsloth Studio MCP server process: a restart drops every queued video that has not started. It is per account, shared by that account's keys, and an id from another account reads as unknown."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import secrets
+import time
+from collections import OrderedDict, deque
+from dataclasses import dataclass, field
+from typing import Any, Optional, Union
+from urllib.parse import quote
+
+import httpx
+from fastmcp.exceptions import ToolError
+
+from studio_mcp.caller import Caller
+from studio_mcp.errors import raise_for_route
+from studio_mcp.forward import forward, parse_json
+from studio_mcp.outputs import JobStatus, VideoJobRef
+from studio_mcp.tools import as_dict, number, opt_text, try_json
+
+# core/inference/video_families.py VIDEO_GENERATION_BUSY_MSG; a test pins the two together.
+BUSY_MESSAGE = "A video generation is already in progress."
+PREFIX = "vq_"
+POLL_S = 2.0
+RETRY_S = 5.0
+MAX_MISSES = 15
+READ_S = 15.0
+MAX_RETRY_AFTER_S = 120.0
+CAPACITY = 64
+MAX_WAITING = 32
+RUNNING = ("queued", "in_progress")
+PROGRESS = "/api/inference/video/generate-progress"
+
+
+@dataclass
+class QueuedVideo:
+ id: str
+ account_id: str
+ caller: Caller = field(repr = False)
+ body: dict = field(repr = False)
+ hints: Optional[dict] = field(default = None, repr = False)
+ # queued, submitted, failed or cancelled.
+ status: str = "queued"
+ video_id: Optional[str] = None
+ error: Optional[str] = None
+ # True while its POST is in flight, when it can no longer be withdrawn.
+ posting: bool = False
+ enqueued_at: float = field(default_factory = time.monotonic)
+
+
+_items: "OrderedDict[str, QueuedVideo]" = OrderedDict()
+_waiting: dict[str, deque] = {}
+# account -> (video id, monotonic submission time) of the video this account's queue waits on.
+_running: dict[str, tuple[str, float]] = {}
+_admission: dict[str, asyncio.Lock] = {}
+# account -> seconds the last video in this queue took.
+_clip_s: dict[str, float] = {}
+# Held here so each pump outlives the tool call that started it.
+_pumps: dict[str, asyncio.Task] = {}
+
+
+def is_queue_id(value: Any) -> bool:
+ return isinstance(value, str) and value.startswith(PREFIX)
+
+
+def _video_path(video_id: str) -> str:
+ return f"/v1/videos/{quote(video_id, safe = '')}"
+
+
+def _json(response: httpx.Response) -> dict:
+ try:
+ return as_dict(parse_json(response.content))
+ except (ValueError, UnicodeDecodeError):
+ return {}
+
+
+def _is_busy(response: httpx.Response) -> bool:
+ if response.status_code != 409:
+ return False
+ error = _json(response).get("error")
+ return (
+ isinstance(error, dict)
+ and error.get("code") is None
+ and error.get("message") == BUSY_MESSAGE
+ )
+
+
+def _ended(item: QueuedVideo) -> bool:
+ # A submitted video runs until the next one starts (one at a time), so only the one this
+ # account's queue still waits on may be running; its queue id must keep working until then.
+ if item.status == "queued" or item.posting:
+ return False
+ running = _running.get(item.account_id)
+ return not (item.status == "submitted" and running and running[0] == item.video_id)
+
+
+def _evict() -> None:
+ while len(_items) > CAPACITY:
+ oldest = next((k for k, item in _items.items() if _ended(item)), None)
+ if oldest is None:
+ return
+ _items.pop(oldest)
+
+
+def _enqueue(caller: Caller, body: dict, hints: Optional[dict]) -> QueuedVideo:
+ waiting = _waiting.setdefault(caller.account_id, deque())
+ if len(waiting) >= MAX_WAITING:
+ raise ToolError(
+ f"{MAX_WAITING} videos are already queued for this account in Unsloth Studio; "
+ "wait for one to start or cancel one."
+ )
+ if sum(len(queue) for queue in _waiting.values()) >= CAPACITY:
+ raise ToolError(
+ f"{CAPACITY} videos are already queued in Unsloth Studio; try again once some have started."
+ )
+ item = QueuedVideo(PREFIX + secrets.token_urlsafe(12), caller.account_id, caller, body, hints)
+ waiting.append(item)
+ _items[f"{item.account_id}:{item.id}"] = item
+ _evict()
+ return item
+
+
+def _ensure_pump(account_id: str) -> None:
+ task = _pumps.get(account_id)
+ if task is None or task.done():
+ _pumps[account_id] = asyncio.get_running_loop().create_task(_pump(account_id))
+
+
+def _settle(
+ item: QueuedVideo,
+ status: str,
+ *,
+ error: Optional[str] = None,
+) -> None:
+ waiting = _waiting.get(item.account_id)
+ if waiting and item in waiting:
+ waiting.remove(item)
+ item.status, item.error, item.posting = status, error, False
+
+
+async def _wait_for_running(caller: Caller) -> None:
+ """Until the video this queue waits on is no longer queued or in progress (or gone)."""
+ seen, misses = False, 0
+ while (running := _running.get(caller.account_id)) is not None:
+ video_id, submitted_at = running
+ try:
+ # Bounded: a stalled read counts as a failed one rather than holding the queue forever.
+ read = await asyncio.wait_for(try_json(caller, _video_path(video_id)), READ_S)
+ except asyncio.TimeoutError:
+ read = None
+ job = as_dict(read)
+ # A failed read is no proof the video ended: only a run of them (it is gone) ends the wait.
+ misses = 0 if isinstance(read, dict) else misses + 1
+ if job.get("status") in RUNNING or 0 < misses < MAX_MISSES:
+ seen = seen or job.get("status") in RUNNING
+ await asyncio.sleep(POLL_S)
+ continue
+ # Only a video this wait saw running gives a clip time; an old one would inflate every ETA.
+ if job.get("status") == "completed" and seen:
+ _clip_s[caller.account_id] = time.monotonic() - submitted_at
+ if _running.get(caller.account_id) == running:
+ _running.pop(caller.account_id)
+
+
+def _retry_after(response: httpx.Response) -> Optional[float]:
+ # gpu_busy comes flat ({error, retry_after}) or inside detail / an OpenAI error.
+ body = _json(response) if response.status_code in (409, 503) else {}
+ busy = next(
+ (
+ c
+ for c in (body, body.get("detail"), body.get("error"))
+ if isinstance(c, dict) and "gpu_busy" in (c.get("error"), c.get("code"))
+ ),
+ None,
+ )
+ if busy is None:
+ return None
+ try:
+ seconds = float(response.headers.get("retry-after") or busy.get("retry_after"))
+ except (TypeError, ValueError):
+ seconds = RETRY_S
+ return min(max(seconds, 0.0), MAX_RETRY_AFTER_S)
+
+
+async def _submit(item: QueuedVideo) -> Optional[float]:
+ """POST the head once. Returns how long to wait before trying again, or None once it is settled."""
+ item.posting = True
+ try:
+ response = await forward(
+ item.caller, "POST", "/v1/videos", json_body = item.body, hub_header = True
+ )
+ except httpx.HTTPError:
+ # Unsloth Studio restarting or slow to answer: the clip stays queued.
+ return RETRY_S
+ finally:
+ item.posting = False
+ if _is_busy(response):
+ return RETRY_S
+ delay = _retry_after(response)
+ if delay is not None:
+ return delay
+ try:
+ job = raise_for_route(response, hints = item.hints)
+ except ToolError as exc:
+ _settle(item, "failed", error = str(exc))
+ return None
+ video_id = opt_text(as_dict(job).get("id"))
+ if video_id is None:
+ _settle(item, "failed", error = "Unsloth Studio returned no video job")
+ return None
+ item.video_id = video_id
+ _settle(item, "submitted")
+ _running[item.account_id] = (video_id, time.monotonic())
+ return None
+
+
+async def _pump(account_id: str) -> None:
+ while True:
+ caller = None
+ while waiting := _waiting.get(account_id):
+ head = waiting[0]
+ caller = head.caller
+ try:
+ await _wait_for_running(head.caller)
+ if head.status != "queued" or not waiting or waiting[0] is not head:
+ continue
+ delay = await _submit(head)
+ if delay is not None:
+ await asyncio.sleep(delay)
+ except asyncio.CancelledError:
+ raise
+ except Exception:
+ _settle(head, "failed", error = "Unsloth Studio could not start the queued video.")
+ if caller is None:
+ return
+ # Follow the last clip it started to the end, so its record can be dropped once it is done.
+ with contextlib.suppress(Exception):
+ await _wait_for_running(caller)
+ if not _waiting.get(account_id):
+ return
+
+
+async def post_or_queue(
+ caller: Caller,
+ body: dict,
+ *,
+ hints: Optional[dict] = None,
+) -> Union[dict, VideoJobRef]:
+ """POST the video, or queue it when Unsloth Studio is busy with another video (or this account already has videos waiting, to keep their order). Returns the route's job, or the queued video's reference."""
+ # One admission at a time per account: a second call must not start while the first, refused as
+ # busy, is still on its way into the queue, or it would overtake it.
+ async with _admission.setdefault(caller.account_id, asyncio.Lock()):
+ return await _admit(caller, body, hints)
+
+
+async def _admit(caller: Caller, body: dict, hints: Optional[dict]) -> Union[dict, VideoJobRef]:
+ if not _waiting.get(caller.account_id):
+ response = await forward(caller, "POST", "/v1/videos", json_body = body, hub_header = True)
+ if not _is_busy(response):
+ job = raise_for_route(response, hints = hints)
+ video_id = opt_text(as_dict(job).get("id"))
+ if video_id:
+ _running[caller.account_id] = (video_id, time.monotonic())
+ return job
+ item = _enqueue(caller, body, hints)
+ _ensure_pump(caller.account_id)
+ position, eta = await _position_eta(item)
+ return VideoJobRef.from_route(
+ body, id = item.id, status = "queued", queue_position = position, eta_s = eta
+ )
+
+
+async def _position_eta(item: QueuedVideo) -> tuple[Optional[int], Optional[float]]:
+ waiting = _waiting.get(item.account_id) or deque()
+ if item not in waiting:
+ return None, None
+ position = waiting.index(item) + 1
+ try:
+ # Bounded, like every status read here: a stalled one leaves the ETA unknown.
+ return position, await asyncio.wait_for(_eta(item.caller, position), READ_S)
+ except Exception:
+ return position, None
+
+
+async def _eta(caller: Caller, position: int) -> Optional[float]:
+ """remaining(running) + (position - 1) * clip; None when Unsloth Studio gives nothing to go on."""
+ running = _running.get(caller.account_id)
+ if running is None:
+ return None
+ video_id, submitted_at = running
+ elapsed = time.monotonic() - submitted_at
+ remaining = None
+ progress = as_dict(await try_json(caller, PROGRESS))
+ if progress.get("active") is True:
+ remaining = number(progress.get("eta_seconds"))
+ if remaining is None:
+ percent = number(as_dict(await try_json(caller, _video_path(video_id))).get("progress"))
+ if percent is None or not 0 < percent < 100:
+ return None
+ remaining = elapsed * (100 - percent) / percent
+ clip = _clip_s.get(caller.account_id) or (elapsed + remaining)
+ return round(max(remaining, 0.0) + (position - 1) * clip, 1)
+
+
+def lookup(account_id: str, queue_id: str) -> QueuedVideo:
+ item = _items.get(f"{account_id}:{queue_id}")
+ if item is None:
+ raise ToolError("No such video job")
+ return item
+
+
+async def job_status(item: QueuedVideo) -> JobStatus:
+ """get_job's answer for a queue id that has not become a real video."""
+ # Read before the await: the queue can start the item while its position is being priced.
+ status = item.status
+ position, eta = await _position_eta(item) if status == "queued" else (None, None)
+ return JobStatus(
+ kind = "video",
+ id = item.id,
+ status = status,
+ queue_position = position,
+ eta_s = eta,
+ error = item.error,
+ )
+
+
+def cancel(account_id: str, queue_id: str) -> tuple[bool, str]:
+ item = lookup(account_id, queue_id)
+ if item.video_id:
+ return (
+ False,
+ f"It already started as {item.video_id}; cancel(kind='video') stops the running video.",
+ )
+ if item.posting:
+ return False, "It is being started now; cancel(kind='video') stops the running video."
+ if item.status != "queued":
+ return False, f"The queued video already {item.status}."
+ _settle(item, "cancelled")
+ return True, "Removed the queued video before it started."
+
+
+def _reset() -> None:
+ """Test hook."""
+ for task in _pumps.values():
+ with contextlib.suppress(RuntimeError): # its event loop may be closed already
+ task.cancel()
+ for state in (_items, _waiting, _running, _clip_s, _pumps, _admission):
+ state.clear()
diff --git a/studio/backend/tests/test_mcp_no_host_paths.py b/studio/backend/tests/test_mcp_no_host_paths.py
index d9b1c7dd54f..ffb900f5e20 100644
--- a/studio/backend/tests/test_mcp_no_host_paths.py
+++ b/studio/backend/tests/test_mcp_no_host_paths.py
@@ -39,6 +39,7 @@ from .test_mcp_tools_images import PAYLOADS as IMAGES_PAYLOADS
from .test_mcp_tools_library import PAYLOADS as LIBRARY_PAYLOADS
from .test_mcp_tools_library import VOICE_PAYLOADS
from .test_mcp_tools_loading import PAYLOADS as LOADING_PAYLOADS
+from .test_mcp_tools_plan_load import _world as plan_world
from .test_mcp_tools_models import PAYLOADS as MODELS_PAYLOADS
from .test_mcp_tools_recipe import PAYLOADS as RECIPE_PAYLOADS
from .test_mcp_tools_status import PAYLOADS as STATUS_PAYLOADS
@@ -77,6 +78,10 @@ CASES: dict[str, Any] = {
],
"load_model": (LOADING_PAYLOADS, {"model": "unsloth/Llama-3.2-1B-Instruct-GGUF"}),
"unload_model": (LOADING_PAYLOADS, {}),
+ "plan_load": (
+ plan_world("off", ["unsloth/Qwen3-0.6B-GGUF"]),
+ {"model": "unsloth/Qwen3-0.6B-GGUF"},
+ ),
"chat": (TEXT_PAYLOADS, {"prompt": "hi"}),
"embed": (TEXT_PAYLOADS, {"texts": ["a", "b"]}),
"system_one": (TEXT_PAYLOADS, {"state": "x", "questions": {"urgent": {"type": "noul"}}}),
diff --git a/studio/backend/tests/test_mcp_server.py b/studio/backend/tests/test_mcp_server.py
index fe25dcc82f6..32d4f534922 100644
--- a/studio/backend/tests/test_mcp_server.py
+++ b/studio/backend/tests/test_mcp_server.py
@@ -13,6 +13,7 @@ READ_ONLY = {
"list_models",
"list_media",
"list_training_runs",
+ "plan_load",
"studio_status",
"system_one",
}
diff --git a/studio/backend/tests/test_mcp_status_media_slots.py b/studio/backend/tests/test_mcp_status_media_slots.py
index 247984a41bc..f3a9cd47d81 100644
--- a/studio/backend/tests/test_mcp_status_media_slots.py
+++ b/studio/backend/tests/test_mcp_status_media_slots.py
@@ -4,7 +4,7 @@
"""studio_status image and video slots carry what an agent needs to call the generate tools right: workflows, the defaults an omitted value resolves to, the size multiple, the image cap, the prompt tip and the video controls."""
from studio_mcp.outputs import ImageSlot, VideoSlot
-from studio_mcp.tools.status import BUILDERS, _media
+from studio_mcp.tools.status import BUILDERS, _media, _placed
from .test_mcp_tools_status import PAYLOADS, _status
@@ -83,9 +83,9 @@ def test_unloaded_slots_keep_their_defaults():
def test_builders_still_use_media():
- # Placement wraps these entries later, so they stay plain _media partials.
+ # _placed builds the slot with _media, then adds where the model ended up.
for name, slot in (("image", ImageSlot), ("video", VideoSlot)):
- assert BUILDERS[name].func is _media
+ assert BUILDERS[name].func is _placed
assert BUILDERS[name].args == (slot,)
diff --git a/studio/backend/tests/test_mcp_tools_loading.py b/studio/backend/tests/test_mcp_tools_loading.py
index ff5d8fbffa4..e72047549cc 100644
--- a/studio/backend/tests/test_mcp_tools_loading.py
+++ b/studio/backend/tests/test_mcp_tools_loading.py
@@ -77,6 +77,8 @@ def test_load_sends_the_body_and_reports_the_result(monkeypatch, kind):
"loaded": True,
**SETTLED,
"display_name": "Llama 3.2 1B",
+ "placement": None,
+ "alongside_applied": None,
"evicted": ["unsloth/Qwen3-0.6B"],
"evicted_slots": [{"kind": "llm", "model": "unsloth/Qwen3-0.6B"}],
}
@@ -241,6 +243,7 @@ def test_a_gguf_image_repo_sends_its_gguf_filename(monkeypatch, fast_polls, extr
monkeypatch, studio, "load_model", {"model": FLUX_GGUF, "kind": "image", **extra}
)
loaded = {"kind": "image", "model": FLUX_GGUF, "loaded": True, **SETTLED, "display_name": None}
+ loaded.update(placement = None, alongside_applied = None)
assert result["structuredContent"] == {**loaded, "evicted": [], "evicted_slots": []}
expected = {"model_path": FLUX_GGUF, "gguf_filename": filename, "model_kind": "gguf"}
expected.update({"hf_token": extra["hf_token"]} if "hf_token" in extra else {})
@@ -349,7 +352,8 @@ def test_another_variant_of_the_resident_repo_waits_for_its_own_load(
if filename:
async def pick(*_args):
- return filename
+ # The variant row, as _gguf_filename returns it here.
+ return {"filename": filename}
monkeypatch.setattr(loading, "_gguf_filename", pick)
resident = {"loaded": True, "repo_id": FLUX_GGUF, "model_kind": "gguf"}
diff --git a/studio/backend/tests/test_mcp_tools_placement.py b/studio/backend/tests/test_mcp_tools_placement.py
new file mode 100644
index 00000000000..cfc0a6a0582
--- /dev/null
+++ b/studio/backend/tests/test_mcp_tools_placement.py
@@ -0,0 +1,532 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""load_model's media knobs and device/alongside placement, the placement echo, the partial-variant refusal and unload_model(kind="all")."""
+
+import asyncio
+
+import pytest
+from fastapi.responses import JSONResponse
+
+from studio_mcp import forward
+
+from .mcp_harness import ( # noqa: F401
+ bodies,
+ fake_studio,
+ fast_polls,
+ run_tool,
+ sequence,
+ slow,
+ stt_state,
+)
+from .test_mcp_tools_loading import (
+ EMPTY_STATUS,
+ FLUX_GGUF,
+ LLM,
+ LOAD,
+ LOADED,
+ PAYLOADS,
+ READY,
+ STATUS,
+ STATUS_ROUTE,
+ _media_studio,
+)
+
+KOKORO = "audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF"
+OUTETTS = "OuteAI/OuteTTS-1.0-0.6B-GGUF"
+QWEN = "unsloth/Qwen3-0.6B-GGUF"
+PLACED = {
+ "loaded": True,
+ "repo_id": FLUX_GGUF,
+ "gguf_filename": "flux1-schnell-Q4_K_S.gguf",
+ "device": "cuda",
+ "memory_mode": "low_vram",
+ "offload_policy": "group",
+ "transformer_quant": None,
+ "text_encoder_quant": "fp8",
+}
+CPU = {"gpu_memory_mode": "manual", "gpu_layers": 0, "speculative_type": "off"}
+GGUF_FILES = {"default_variant": "Q4_K_M", "variants": [{"quant": "Q4_K_M", "filename": "q.gguf"}]}
+
+
+def _load(
+ monkeypatch,
+ args,
+ routes = PAYLOADS,
+):
+ result, studio = run_tool(monkeypatch, routes, "load_model", args)
+ return result, studio, bodies(studio, "/api/inference/load")
+
+
+def test_media_knobs_reach_the_plan_and_the_load(monkeypatch, fast_polls):
+ studio = _media_studio("image", progress = [READY], statuses = [PLACED])
+ knobs = {"memory_mode": "low_vram", "transformer_quant": "int8", "speed_mode": "off"}
+ result, _studio = run_tool(
+ monkeypatch, studio, "load_model", {"model": FLUX_GGUF, "kind": "image", **knobs}
+ )
+ for path in ("download-plan", "load"):
+ (sent,) = bodies(studio, f"/api/inference/images/{path}")
+ assert {key: sent[key] for key in knobs} == knobs
+ assert result["structuredContent"]["placement"] == {
+ "device": "gpu",
+ "memory_mode": "low_vram",
+ "offload_policy": "group",
+ "transformer_quant": None,
+ "text_encoder_quant": "fp8",
+ }
+
+
+def test_a_plan_that_refuses_the_knobs_is_asked_without_them(monkeypatch, fast_polls):
+ refused = JSONResponse({"detail": "extra fields not permitted"}, status_code = 422)
+ studio = _media_studio(
+ "video",
+ statuses = [{"loaded": True, "repo_id": "a/v"}],
+ plan = sequence(refused, {"entries": []}),
+ )
+ run_tool(
+ monkeypatch, studio, "load_model", {"model": "a/v", "kind": "video", "h3_task": "fl2va"}
+ )
+ plans = bodies(studio, "/api/inference/video/download-plan")
+ assert plans == [{"model_path": "a/v", "h3_task": "fl2va"}, {"model_path": "a/v"}]
+ assert bodies(studio, "/api/inference/video/load") == [
+ {"model_path": "a/v", "h3_task": "fl2va"}
+ ]
+
+
+ "kind,args",
+ [
+ ("llm", {"memory_mode": "low_vram"}),
+ ("tts", {"h3_task": "fl2va"}),
+ ("video", {"transformer_quant": "int8"}),
+ ("image", {"device": "cpu"}),
+ ("stt", {"alongside": True}),
+ ("llm", {"device": "cpu", "model": "unsloth/Qwen3-0.6B"}),
+ ("llm", {"device": "gpu", "gpu_layers": 0}),
+ ],
+)
+def test_a_knob_the_kind_does_not_take_is_refused_before_any_call(monkeypatch, kind, args):
+ studio = fake_studio(fallback = {})
+ result, _studio = run_tool(
+ monkeypatch, studio, "load_model", {"model": LLM, "kind": kind, **args}
+ )
+ assert result["isError"] is True
+ assert not [call for call in studio.state.calls if call[0] == "POST"]
+
+
+ "listing,args,refusal",
+ [
+ # "gguf" in a repo name proves nothing: only listed GGUF files do.
+ ({"variants": []}, {"model": "someone/not-a-gguf-repo"}, "needs a GGUF model"),
+ (None, {"model": QWEN}, "needs a GGUF model"),
+ (GGUF_FILES, {"model": QWEN, "variant": "Q8_0"}, "has no GGUF variant Q8_0"),
+ ],
+)
+def test_cpu_needs_a_confirmed_gguf(monkeypatch, listing, args, refusal):
+ routes = {**PAYLOADS}
+ if listing is not None:
+ routes[("GET", "/api/hub/gguf-variants")] = listing
+ result, studio, sent = _load(monkeypatch, {"kind": "llm", "device": "cpu", **args}, routes)
+ assert result["isError"] is True and refusal in str(result["content"])
+ assert sent == []
+
+
+ "model,kind,device,expected",
+ [
+ # audio.cpp honours audio_device; it is a GGUF repo that llama-server never sees.
+ (KOKORO, "tts", "cpu", {"audio_device": "cpu"}),
+ # llama-server TTS (OuteTTS, snac/bicodec/dac) ignores audio_device: no GPU layers either.
+ (OUTETTS, "tts", "cpu", {"audio_device": "cpu", **CPU}),
+ # A chat GGUF must never be sent audio_device, which the route refuses for it.
+ (QWEN, "llm", "cpu", CPU),
+ (OUTETTS, "audio", "gpu", {"audio_device": "gpu"}),
+ (QWEN, "llm", "gpu", {}),
+ ],
+)
+def test_device_maps_to_the_load_fields(monkeypatch, model, kind, device, expected):
+ routes = {**PAYLOADS, ("GET", "/api/hub/gguf-variants"): GGUF_FILES}
+ args = {"model": model, "kind": kind, "device": device}
+ _result, _studio, (body,) = _load(monkeypatch, args, routes)
+ base = {"model_path": model, "load_in_4bit": True, "max_seq_length": 0}
+ assert body == {**base, **expected}
+
+
[email protected]("model,kind", [("/models/qwen3", "llm"), ("someone/outetts", "tts")])
+def test_cpu_fields_follow_the_listing_not_the_name(monkeypatch, model, kind):
+ routes = {**PAYLOADS, ("GET", "/api/hub/gguf-variants"): GGUF_FILES}
+ _result, _studio, (body,) = _load(
+ monkeypatch, {"model": model, "kind": kind, "device": "cpu"}, routes
+ )
+ assert {key: body.get(key) for key in CPU} == CPU
+
+
+def test_kv_cache_and_gpu_layers(monkeypatch):
+ args = {"model": QWEN, "kv_cache_type": "q8_0", "gpu_layers": 20, "alongside": False}
+ routes = {**PAYLOADS, ("GET", "/api/hub/gguf-variants"): GGUF_FILES}
+ _result, _studio, (body,) = _load(monkeypatch, args, routes)
+ assert body["cache_type_kv"] == "q8_0"
+ assert (body["gpu_memory_mode"], body["gpu_layers"], body["alongside"]) == ("manual", 20, False)
+
+
+ "answer,device,placed",
+ [
+ # An explicit gpu that audio.cpp could not honour reports where the model really is.
+ ({"audio_device_fallback": "cpu"}, "gpu", "cpu"),
+ ({"offloaded_layers": 0}, None, "cpu"),
+ ({"offloaded_layers": 28}, None, "gpu"),
+ # A load that kept its layers on the GPU is not reported as on the CPU because cpu was asked.
+ ({"offloaded_layers": 28}, "cpu", "gpu"),
+ # An asked-for GPU the load does not confirm is not reported: it may have run on the CPU.
+ ({}, "gpu", None),
+ ({}, None, None),
+ ],
+)
+def test_the_resolved_device_is_echoed(monkeypatch, answer, device, placed):
+ routes = {**PAYLOADS, LOAD: {**LOADED, **answer}}
+ args = {"model": OUTETTS, "kind": "tts", **({"device": device} if device else {})}
+ result, _studio, _bodies = _load(monkeypatch, args, routes)
+ placement = result["structuredContent"]["placement"]
+ assert (placement or {}).get("device") == placed
+
+
+ "mode,after,applied",
+ [
+ # Off replaces the primary; When they fit kept it serving next to the new model.
+ ("off", {**STATUS, "serving": [OUTETTS]}, False),
+ ("fit", {**STATUS, "serving": [LLM, OUTETTS]}, True),
+ ],
+)
+def test_alongside_applied_reports_whether_the_chat_model_still_serves(
+ monkeypatch, mode, after, applied
+):
+ before = {**STATUS, "multi_model_mode": mode}
+ routes = {
+ **PAYLOADS,
+ LOAD: {**LOADED, "model": OUTETTS, "evicted": []},
+ STATUS_ROUTE: sequence(before, after),
+ }
+ args = {"model": OUTETTS, "kind": "tts", "alongside": True}
+ result, _studio, _bodies = _load(monkeypatch, args, routes)
+ assert result["structuredContent"]["alongside_applied"] is applied
+
+
+ "model,placement", [(KOKORO, {"device": "cpu"}), (OUTETTS, {"gpu_layers": 0})]
+)
+def test_always_with_cpu_joins_the_serving_chat_model(monkeypatch, model, placement):
+ always = {**STATUS, "multi_model_mode": "always"}
+ routes = {
+ **PAYLOADS,
+ LOAD: {**LOADED, "model": model, "evicted": []},
+ STATUS_ROUTE: sequence(always, always, {**always, "serving": [LLM, model]}),
+ ("GET", "/api/hub/gguf-variants"): GGUF_FILES,
+ }
+ result, _studio, (body,) = _load(
+ monkeypatch, {"model": model, "kind": "tts", **placement}, routes
+ )
+ assert body["alongside"] is True
+ assert result["structuredContent"]["evicted"] == []
+ assert result["structuredContent"]["alongside_applied"] is True
+
+
+def _partial_routes(state):
+ variants = {
+ "default_variant": "Q4_K_M",
+ "variants": [
+ {"quant": "Q4_K_M", "filename": "q.gguf", "downloaded": False, "partial": True}
+ ],
+ }
+ return {
+ **PAYLOADS,
+ ("GET", "/api/hub/gguf-variants"): variants,
+ ("GET", "/api/hub/download-status"): {"state": state},
+ }
+
+
+def test_a_partial_variant_is_refused(monkeypatch):
+ result, studio, sent = _load(monkeypatch, {"model": QWEN}, _partial_routes("idle"))
+ assert result["isError"] is True
+ assert (
+ "still downloading or incomplete; wait for it or redownload it"
+ in result["content"][0]["text"]
+ )
+ assert sent == []
+
+
+def test_a_variant_unsloth_studio_is_downloading_is_not_refused(monkeypatch):
+ # The real allowlist: download-status is forwarded, so a managed download in flight is seen.
+ result, _studio, sent = _load(monkeypatch, {"model": QWEN}, _partial_routes("running"))
+ assert result.get("isError") is not True
+ assert len(sent) == 1
+
+
+def test_unload_all_frees_every_slot_but_the_embedder(monkeypatch):
+ serving = {
+ "loaded": [LLM, QWEN],
+ "serving": [LLM, QWEN],
+ "serving_checkpoints": ["/m/llm.gguf", "/m/qwen.gguf"],
+ }
+ image = "/api/inference/images"
+ video = "/api/inference/video"
+ stt = "/api/inference/audio/stt/status"
+ routes = {
+ STATUS_ROUTE: sequence(serving, EMPTY_STATUS),
+ ("POST", "/api/inference/unload"): {"status": "unloaded"},
+ ("GET", f"{image}/status"): {"loaded": True, "repo_id": FLUX_GGUF},
+ ("POST", f"{image}/unload"): {"loaded": False},
+ ("GET", f"{video}/status"): {"loaded": True, "repo_id": "a/v"},
+ ("POST", f"{video}/unload"): {"loaded": False},
+ ("GET", stt): sequence({"transformers": stt_state(loaded = "openai/whisper-small")}, {}),
+ ("POST", "/api/inference/audio/stt/unload"): {"status": "unloaded"},
+ }
+ result, studio = run_tool(monkeypatch, routes, "unload_model", {"kind": "all"}, fallback = {})
+ assert result["structuredContent"] == {
+ "kind": "all",
+ "unloaded": [
+ {"kind": "llm", "model": LLM},
+ {"kind": "llm", "model": QWEN},
+ {"kind": "image", "model": FLUX_GGUF},
+ {"kind": "video", "model": "a/v"},
+ {"kind": "stt", "model": "openai/whisper-small"},
+ ],
+ }
+ # The kept model goes first, so the primary is never replaced by it mid-way.
+ assert bodies(studio, "/api/inference/unload") == [
+ {"model_path": "/m/qwen.gguf"},
+ {"model_path": "/m/llm.gguf"},
+ ]
+ assert not [call for call in studio.state.calls if "embedding-model" in call[1]]
+
+
+def test_a_media_load_already_downloading_the_variant_is_not_refused(monkeypatch, fast_polls):
+ studio = _media_studio(
+ "image",
+ progress = [{"phase": "downloading"}, READY],
+ statuses = [{"loaded": True, "repo_id": FLUX_GGUF}],
+ )
+ partial = {
+ "default_variant": "Q4_K_S",
+ "variants": [{"quant": "Q4_K_S", "filename": "f.gguf", "partial": True}],
+ }
+ studio.router.routes = [
+ r for r in studio.router.routes if getattr(r, "path", "") != "/api/hub/gguf-variants"
+ ]
+ studio.add_api_route("/api/hub/gguf-variants", lambda: partial, methods = ["GET"])
+ result, _studio = run_tool(
+ monkeypatch, studio, "load_model", {"model": FLUX_GGUF, "kind": "image"}
+ )
+ assert result.get("isError") is not True, result
+
+
+def test_unload_all_also_frees_models_held_behind_the_active_one(monkeypatch):
+ held = {"loaded": [LLM, QWEN], "serving": [LLM], "serving_checkpoints": ["/m/llm.gguf"]}
+ routes = {
+ STATUS_ROUTE: sequence(held, {**EMPTY_STATUS, "loaded": [QWEN]}, EMPTY_STATUS),
+ ("POST", "/api/inference/unload"): {"status": "unloaded"},
+ }
+ result, studio = run_tool(monkeypatch, routes, "unload_model", {"kind": "all"}, fallback = {})
+ assert bodies(studio, "/api/inference/unload") == [
+ {"model_path": "/m/llm.gguf"},
+ {"model_path": QWEN},
+ ]
+ assert [row["model"] for row in result["structuredContent"]["unloaded"]] == [LLM, QWEN]
+
+
+def test_unload_all_keeps_going_past_a_failed_unload(monkeypatch):
+ serving = {
+ "loaded": [LLM, QWEN],
+ "serving": [LLM, QWEN],
+ "serving_checkpoints": ["/m/llm.gguf", "/m/qwen.gguf"],
+ }
+ busy = JSONResponse({"detail": "a generation is running"}, status_code = 409)
+
+ def unload(request, body):
+ return busy if b"qwen" in body else {"status": "unloaded"}
+
+ routes = {
+ STATUS_ROUTE: sequence(
+ serving, {"loaded": [QWEN], "serving": [QWEN], "serving_checkpoints": ["/m/qwen.gguf"]}
+ ),
+ ("POST", "/api/inference/unload"): unload,
+ ("GET", "/api/inference/images/status"): {"loaded": True, "repo_id": FLUX_GGUF},
+ ("POST", "/api/inference/images/unload"): {"loaded": False},
+ }
+ result, studio = run_tool(monkeypatch, routes, "unload_model", {"kind": "all"}, fallback = {})
+ assert result["isError"] is True
+ text = str(result["content"])
+ assert f"llm {LLM}" in text and f"image {FLUX_GGUF}" in text and QWEN in text
+ # The failed kept model did not stop the primary or the image model from unloading.
+ assert bodies(studio, "/api/inference/unload")[-1] == {"model_path": "/m/llm.gguf"}
+ assert ("POST", "/api/inference/images/unload") in [call[:2] for call in studio.state.calls]
+
+
+def test_the_cpu_check_reads_a_gated_listing_with_the_calls_hub_token(monkeypatch):
+ def listing(request, body):
+ token = request.headers.get("X-Unsloth-HF-Token")
+ return GGUF_FILES if token == "hf_arg" else {"variants": []}
+
+ routes = {**PAYLOADS, ("GET", "/api/hub/gguf-variants"): listing}
+ args = {"model": "someone/gated-qwen", "device": "cpu", "hf_token": "hf_arg"}
+ result, _studio, (body,) = _load(monkeypatch, args, routes)
+ assert result.get("isError") is not True
+ assert {key: body.get(key) for key in CPU} == CPU
+
+
+def test_cpu_tts_falls_back_to_the_name_when_the_listing_cannot_be_read(monkeypatch):
+ # No gguf-variants route: the listing is unreadable (an offline host, say).
+ _result, _studio, (body,) = _load(
+ monkeypatch, {"model": OUTETTS, "kind": "tts", "device": "cpu"}
+ )
+ assert body == {
+ "model_path": OUTETTS,
+ "load_in_4bit": True,
+ "max_seq_length": 0,
+ "audio_device": "cpu",
+ **CPU,
+ }
+
+
+def test_unload_all_still_frees_media_when_chat_status_cannot_be_read(monkeypatch):
+ routes = {
+ STATUS_ROUTE: JSONResponse({"detail": "restarting"}, status_code = 503),
+ ("GET", "/api/inference/images/status"): {"loaded": True, "repo_id": FLUX_GGUF},
+ ("POST", "/api/inference/images/unload"): {"loaded": False},
+ }
+ result, studio = run_tool(monkeypatch, routes, "unload_model", {"kind": "all"}, fallback = {})
+ assert result["isError"] is True
+ assert f"image {FLUX_GGUF}" in str(result["content"]) and "llm:" in str(result["content"])
+ assert ("POST", "/api/inference/images/unload") in [call[:2] for call in studio.state.calls]
+
+
+def test_only_the_download_status_read_joins_the_allowlist():
+ assert "/api/hub/download-status" in forward.ALLOWED_PREFIXES
+ for path in ("/api/hub/download", "/api/hub/download/cancel", "/api/hub/download-progress"):
+ assert not path.startswith(forward.ALLOWED_PREFIXES)
+
+
+def test_alongside_applied_is_unknown_when_status_cannot_be_read(monkeypatch):
+ posted = []
+
+ def load(request, body):
+ posted.append(body)
+ return {**LOADED, "model": OUTETTS, "evicted": []}
+
+ def status(request, body):
+ return JSONResponse({"detail": "restarting"}, status_code = 503) if posted else STATUS
+
+ routes = {**PAYLOADS, LOAD: load, STATUS_ROUTE: status}
+ result, _studio, _bodies = _load(monkeypatch, {"model": OUTETTS, "kind": "tts"}, routes)
+ assert result["structuredContent"]["alongside_applied"] is None
+
+
+def test_a_stalled_gguf_listing_never_holds_a_cpu_load_past_wait_s(monkeypatch):
+ routes = {**PAYLOADS, ("GET", "/api/hub/gguf-variants"): slow(GGUF_FILES, 5.0)}
+ args = {"model": QWEN, "device": "cpu", "wait_s": 0}
+ result, _studio, sent = _load(monkeypatch, args, routes)
+ assert result["structuredContent"]["status"] == "loading" and sent == []
+
+
+ "asked", [{"device": "cpu"}, {"max_seq_length": 8192}, {"load_in_4bit": False}]
+)
+def test_a_load_with_its_own_settings_never_follows_one_already_running(monkeypatch, asked):
+ # Unsloth Studio is loading this model already (started elsewhere), set up its own way.
+ routes = {
+ **PAYLOADS,
+ STATUS_ROUTE: {**EMPTY_STATUS, "loading": [QWEN]},
+ ("GET", "/api/hub/gguf-variants"): GGUF_FILES,
+ }
+ _result, _studio, sent = _load(monkeypatch, {"model": QWEN, **asked}, routes)
+ assert len(sent) == 1
+
+
[email protected]("model", ["~/models/qwen.gguf", "models/qwen.gguf"])
+def test_a_gguf_file_path_needs_no_listing(monkeypatch, model):
+ args = {"model": model, "device": "cpu"}
+ _result, studio, (body,) = _load(monkeypatch, args, PAYLOADS)
+ assert {key: body.get(key) for key in CPU} == CPU
+ assert not [call for call in studio.state.calls if call[1] == "/api/hub/gguf-variants"]
+
+
+def test_a_partial_default_variant_is_refused_whatever_the_repo_is_called(monkeypatch):
+ result, _studio, sent = _load(
+ monkeypatch, {"model": "someone/qwen-quants"}, _partial_routes("idle")
+ )
+ assert result["isError"] is True and "still downloading or incomplete" in str(result["content"])
+ assert sent == []
+
+
+def test_a_stalled_status_read_after_the_load_leaves_alongside_unknown(monkeypatch):
+ from studio_mcp import loading
+
+ posted = []
+
+ def load(request, body):
+ posted.append(body)
+ return {**LOADED, "model": OUTETTS, "evicted": []}
+
+ async def status(request, body):
+ if posted:
+ await asyncio.sleep(10)
+ return STATUS
+
+ monkeypatch.setattr(loading, "READ_S", 0.05)
+ routes = {**PAYLOADS, LOAD: load, STATUS_ROUTE: status}
+ result, _studio, _bodies = _load(monkeypatch, {"model": OUTETTS, "kind": "tts"}, routes)
+ assert result["structuredContent"]["loaded"] is True
+ assert result["structuredContent"]["alongside_applied"] is None
+
+
[email protected]("model,kind", [(KOKORO, "tts"), ("unsloth/Qwen3-0.6B", "llm")])
+def test_gpu_layers_is_refused_for_a_model_llama_server_does_not_run(monkeypatch, model, kind):
+ routes = {**PAYLOADS, ("GET", "/api/hub/gguf-variants"): {"variants": []}}
+ result, _studio, sent = _load(
+ monkeypatch, {"model": model, "kind": kind, "gpu_layers": 0}, routes
+ )
+ assert result["isError"] is True and "only for GGUF models" in str(result["content"])
+ assert sent == []
+
+
+def test_unload_all_unloads_a_promoted_model_once_by_its_checkpoint(monkeypatch):
+ # The kept model could not go first, so unloading the primary promoted it.
+ first = {
+ "loaded": [LLM, QWEN],
+ "serving": [LLM, QWEN],
+ "serving_checkpoints": ["/m/llm", "/m/qwen"],
+ }
+ promoted = {"loaded": [QWEN], "serving": [QWEN], "serving_checkpoints": ["/m/qwen-2"]}
+ routes = {
+ STATUS_ROUTE: sequence(first, promoted, EMPTY_STATUS),
+ ("POST", "/api/inference/unload"): {"status": "unloaded"},
+ }
+ result, studio = run_tool(monkeypatch, routes, "unload_model", {"kind": "all"}, fallback = {})
+ assert bodies(studio, "/api/inference/unload")[-1] == {"model_path": "/m/qwen-2"}
+ assert len(bodies(studio, "/api/inference/unload")) == 3
+
+
+def test_unload_all_still_frees_media_when_chat_status_stalls(monkeypatch):
+ from studio_mcp import loading
+
+ async def stalled(request, body):
+ await asyncio.sleep(10)
+ return STATUS
+
+ monkeypatch.setattr(loading, "READ_S", 0.05)
+ routes = {
+ STATUS_ROUTE: stalled,
+ ("GET", "/api/inference/images/status"): {"loaded": True, "repo_id": FLUX_GGUF},
+ ("POST", "/api/inference/images/unload"): {"loaded": False},
+ }
+ result, studio = run_tool(monkeypatch, routes, "unload_model", {"kind": "all"}, fallback = {})
+ assert result["isError"] is True and f"image {FLUX_GGUF}" in str(result["content"])
+ assert ("POST", "/api/inference/images/unload") in [call[:2] for call in studio.state.calls]
+
+
+def test_zero_gpu_layers_is_a_cpu_load_without_a_drafter(monkeypatch):
+ routes = {**PAYLOADS, ("GET", "/api/hub/gguf-variants"): GGUF_FILES}
+ _result, _studio, (body,) = _load(monkeypatch, {"model": QWEN, "gpu_layers": 0}, routes)
+ assert {key: body.get(key) for key in CPU} == CPU
diff --git a/studio/backend/tests/test_mcp_tools_plan_load.py b/studio/backend/tests/test_mcp_tools_plan_load.py
new file mode 100644
index 00000000000..fd50592cbca
--- /dev/null
+++ b/studio/backend/tests/test_mcp_tools_plan_load.py
@@ -0,0 +1,555 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""plan_load: what a load would download and unload, checked against what the same load then does."""
+
+import asyncio
+
+import pytest
+from fastapi.responses import JSONResponse
+
+from .mcp_harness import bodies, fast_polls, run_tool, stt_state # noqa: F401
+from .test_mcp_tools_loading import FLUX_GGUF, LOADED, LTX, READY, _media_studio
+
+QWEN = "unsloth/Qwen3-0.6B-GGUF"
+KEPT = "unsloth/gemma-3-1b-it-GGUF"
+OUTETTS = "OuteAI/OuteTTS-1.0-0.6B-GGUF"
+IMAGE, VIDEO = "/api/inference/images/status", "/api/inference/video/status"
+STATUS = ("GET", "/api/inference/status")
+VARIANTS = {
+ "default_variant": "Q4_K_M",
+ "has_vision": False,
+ "variants": [
+ {"quant": "Q4_K_M", "filename": "a.gguf", "size_bytes": 400, "downloaded": True},
+ {
+ "quant": "Q8_0",
+ "filename": "b.gguf",
+ "size_bytes": 800,
+ "download_remaining_bytes": 300,
+ "partial": True,
+ },
+ ],
+}
+
+
+def _chat(mode, serving, **fields):
+ return {
+ "serving": serving,
+ "serving_checkpoints": [f"/m/{n}" for n in serving],
+ "loaded": serving,
+ **({"multi_model_mode": mode} if mode else {}),
+ **fields,
+ }
+
+
+def _world(
+ mode,
+ serving,
+ image = None,
+ video = None,
+ **chat_fields,
+):
+ return {
+ STATUS: _chat(mode, serving, **chat_fields),
+ ("GET", IMAGE): {"loaded": True, "repo_id": image} if image else {"loaded": False},
+ ("GET", VIDEO): {"loaded": True, "repo_id": video} if video else {"loaded": False},
+ ("GET", "/api/inference/audio/stt/status"): {
+ "transformers": stt_state(loaded = "openai/whisper-small")
+ },
+ ("GET", "/api/hub/gguf-variants"): VARIANTS,
+ # The partial Q8_0 is one Unsloth Studio is still downloading, so a load waits on it.
+ ("GET", "/api/hub/download-status"): {"state": "running"},
+ ("POST", "/api/inference/estimate-memory"): {"available": True, "gpu_bytes": 1234},
+ ("POST", "/api/inference/images/download-plan"): {"entries": [], "total_bytes": 9000},
+ }
+
+
+def _plan(monkeypatch, routes, args):
+ result, _studio = run_tool(monkeypatch, routes, "plan_load", args, fallback = {})
+ return result["structuredContent"]
+
+
+def _names(slots):
+ return {(s["kind"], s["model"]) for s in slots}
+
+
+def _unloaded(monkeypatch, before, after_routes, args):
+ # What the load really unloaded: the residents before minus the residents after.
+ after = _plan(monkeypatch, after_routes, {"model": "x/y"})
+ return _names(before["residents"]) - _names(after["residents"])
+
+
+ "args,after_serving,after_image",
+ [
+ # A CPU TTS load still replaces the chat primary (TTS loads in the chat slot), and the kept
+ # model goes with it; the image model stays because nothing touched the GPU.
+ ({"model": OUTETTS, "kind": "tts", "device": "cpu"}, [OUTETTS], FLUX_GGUF),
+ # A GPU chat load also takes the GPU from the image model.
+ ({"model": OUTETTS, "kind": "tts", "device": "gpu"}, [OUTETTS], None),
+ # Off ignores alongside.
+ (
+ {"model": OUTETTS, "kind": "tts", "device": "cpu", "alongside": True},
+ [OUTETTS],
+ FLUX_GGUF,
+ ),
+ ],
+)
+def test_off_is_exact_and_matches_the_load(monkeypatch, args, after_serving, after_image):
+ before = _world("off", [QWEN, KEPT], image = FLUX_GGUF)
+ plan = _plan(monkeypatch, before, args)
+ # Unloading the image model is a bound: the load reaches the GPU only on a GPU host.
+ assert plan["multi_model_mode"] == "off" and plan["would_evict_exact"] is (
+ after_image is not None
+ )
+ assert plan["would_refuse"] is False
+ after = _world("off", after_serving, image = after_image)
+ loaded = []
+
+ def load_route(request, body):
+ loaded.append(body)
+ # No evicted list: load_model reports what the load unloaded from the slots before and after.
+ return {key: value for key, value in LOADED.items() if key != "evicted"} | {
+ "model": OUTETTS
+ }
+
+ def switch(route):
+ return lambda request, body: (after if loaded else before)[route]
+
+ # Status reads give the world before the load until the load POST lands, then the world after.
+ load = {
+ **before,
+ **{route: switch(route) for route in (STATUS, ("GET", IMAGE), ("GET", VIDEO))},
+ ("POST", "/api/inference/load"): load_route,
+ }
+ result, _studio = run_tool(monkeypatch, load, "load_model", args, fallback = {})
+ reported = result["structuredContent"]
+ assert reported["model"] == OUTETTS
+ assert _names(plan["would_evict"]) == _names(reported["evicted_slots"])
+ assert _names(plan["would_evict"]) == _unloaded(monkeypatch, plan, after, args)
+
+
+def test_off_media_load_evicts_chat_on_the_gpu_and_the_other_media_model(monkeypatch, fast_polls):
+ before = _world("off", [QWEN], video = LTX)
+ plan = _plan(monkeypatch, before, {"model": FLUX_GGUF, "kind": "image"})
+ assert _names(plan["would_evict"]) == {("llm", QWEN), ("video", LTX)}
+ # An image load may run on the CPU and leave the chat model, so this is an upper bound.
+ assert plan["would_evict_exact"] is False and plan["download_bytes"] == 9000
+ alone = _plan(monkeypatch, _world("off", [], video = LTX), {"model": FLUX_GGUF, "kind": "image"})
+ assert _names(alone["would_evict"]) == {("video", LTX)}
+ # A primary on the CPU holds no GPU claim, so the image load leaves it: no longer exact.
+ cpu = _world("off", [QWEN], video = LTX, gpu_memory_mode = "manual", gpu_layers = 0)
+ plan = _plan(monkeypatch, cpu, {"model": FLUX_GGUF, "kind": "image"})
+ assert _names(plan["would_evict"]) == {("video", LTX)} and plan["would_evict_exact"] is False
+ studio = _media_studio(
+ "image",
+ progress = [READY],
+ statuses = [
+ {"loaded": True, "repo_id": FLUX_GGUF, "gguf_filename": "flux1-schnell-Q4_K_S.gguf"}
+ ],
+ chat_statuses = [_chat("off", [QWEN]), _chat("off", [])],
+ )
+ result, _studio = run_tool(
+ monkeypatch, studio, "load_model", {"model": FLUX_GGUF, "kind": "image"}
+ )
+ assert result["structuredContent"]["evicted"] == [QWEN]
+
+
[email protected]("mode", ["fit", None])
+def test_fit_and_an_unknown_mode_give_an_upper_bound(monkeypatch, mode):
+ before = _world(mode, [QWEN, KEPT], image = FLUX_GGUF)
+ plan = _plan(monkeypatch, before, {"model": OUTETTS, "kind": "tts", "alongside": True})
+ assert plan["would_evict_exact"] is False and plan["would_refuse"] is False
+ # When they fit kept both chat models and the image model: a subset of the bound.
+ actual = _unloaded(monkeypatch, plan, _world(mode, [QWEN, KEPT, OUTETTS], image = FLUX_GGUF), {})
+ assert actual <= _names(plan["would_evict"])
+ assert _names(plan["would_evict"]) >= {("llm", QWEN), ("llm", KEPT), ("image", FLUX_GGUF)}
+
+
+ "args,refuse",
+ [
+ ({"model": OUTETTS, "kind": "tts"}, True),
+ # Under Always a CPU load joins the serving chat model, so nothing needs unloading.
+ ({"model": OUTETTS, "kind": "tts", "device": "cpu"}, False),
+ ({"model": LTX, "kind": "video"}, True),
+ ({"model": "openai/whisper-small", "kind": "stt"}, False),
+ ],
+)
+def test_always_never_evicts_and_bounds_the_refusal(monkeypatch, args, refuse):
+ plan = _plan(monkeypatch, _world("always", [QWEN], image = FLUX_GGUF), args)
+ assert plan["would_evict"] == [] and plan["would_refuse"] is refuse
+
+
+def test_variants_sizes_and_the_gpu_estimate(monkeypatch):
+ plan = _plan(monkeypatch, _world("off", []), {"model": QWEN})
+ assert plan["variants"] == [
+ {"variant": "Q4_K_M", "size_bytes": 400, "downloaded": True, "partial": False},
+ {"variant": "Q8_0", "size_bytes": 800, "downloaded": False, "partial": True},
+ ]
+ assert (plan["download_bytes"], plan["est_gpu_bytes"]) == (0, 1234)
+ plan = _plan(monkeypatch, _world("off", []), {"model": QWEN, "variant": "Q8_0"})
+ assert (plan["download_bytes"], plan["est_gpu_bytes"]) == (300, None)
+ assert _names(plan["residents"]) == {("stt", "openai/whisper-small")}
+ missing, _studio = run_tool(
+ monkeypatch, _world("off", []), "plan_load", {"model": QWEN, "variant": "Q2_K"}
+ )
+ assert missing["isError"] is True and "no GGUF variant Q2_K" in missing["content"][0]["text"]
+
+
+def test_another_variant_of_a_resident_repo_is_a_new_load(monkeypatch):
+ world = _world("off", [f"{QWEN}:Q4_K_M"], image = FLUX_GGUF)
+ plan = _plan(monkeypatch, world, {"model": QWEN, "variant": "Q8_0"})
+ assert _names(plan["would_evict"]) == {("llm", f"{QWEN}:Q4_K_M"), ("image", FLUX_GGUF)}
+ # Status naming only the bare repo cannot tell which variant serves.
+ plan = _plan(monkeypatch, _world("off", [QWEN]), {"model": QWEN, "variant": "Q8_0"})
+ assert plan["would_evict_exact"] is False
+
+
+def test_nothing_left_to_download_is_zero(monkeypatch):
+ rows = [
+ {
+ "quant": "Q8_0",
+ "filename": "b.gguf",
+ "download_remaining_bytes": 0,
+ "download_size_bytes": 800,
+ }
+ ]
+ world = {**_world("off", []), ("GET", "/api/hub/gguf-variants"): {"variants": rows}}
+ assert _plan(monkeypatch, world, {"model": QWEN, "variant": "Q8_0"})["download_bytes"] == 0
+
+
+ "routes,args",
+ [
+ # Each of these load_model refuses before sending anything, so plan_load refuses too.
+ ({}, {"model": FLUX_GGUF, "kind": "image", "device": "cpu"}),
+ ({}, {"model": QWEN, "kind": "stt", "alongside": True}),
+ (
+ {("GET", "/api/hub/gguf-variants"): {"variants": []}},
+ {"model": "someone/not-a-gguf-repo", "device": "cpu"},
+ ),
+ ],
+)
+def test_a_load_that_load_model_refuses_gets_no_plan(monkeypatch, routes, args):
+ world = {**_world("off", [QWEN]), **routes}
+ result, _studio = run_tool(monkeypatch, world, "plan_load", args, fallback = {})
+ assert result["isError"] is True
+
+
+def test_the_plan_of_a_gated_media_repo_carries_the_hub_token(monkeypatch):
+ result, studio = run_tool(
+ monkeypatch,
+ _world("off", []),
+ "plan_load",
+ {"model": FLUX_GGUF, "kind": "image"},
+ headers = {"X-Unsloth-HF-Token": "hf_header"},
+ fallback = {},
+ )
+ assert result["structuredContent"]["download_bytes"] == 9000
+ (body,) = bodies(studio, "/api/inference/images/download-plan")
+ assert body["hf_token"] == "hf_header"
+
+
+def test_the_media_options_reach_the_download_plan(monkeypatch):
+ world = {
+ **_world("off", []),
+ ("POST", "/api/inference/video/download-plan"): {"total_bytes": 7},
+ }
+ args = {"model": LTX, "kind": "video", "h3_task": "ref2va"}
+ result, studio = run_tool(monkeypatch, world, "plan_load", args, fallback = {})
+ assert result["structuredContent"]["download_bytes"] == 7
+ assert bodies(studio, "/api/inference/video/download-plan") == [
+ {"model_path": LTX, "h3_task": "ref2va"}
+ ]
+
+
+def test_a_download_plan_refusal_is_the_plans_error(monkeypatch):
+ refused = JSONResponse({"detail": "no such precision"}, status_code = 400)
+ world = {**_world("off", []), ("POST", "/api/inference/images/download-plan"): refused}
+ args = {"model": FLUX_GGUF, "kind": "image", "transformer_quant": "int8"}
+ result, _studio = run_tool(monkeypatch, world, "plan_load", args, fallback = {})
+ assert result["isError"] is True and "no such precision" in str(result["content"])
+
+
+def test_a_model_held_behind_the_primary_is_a_resident_off_may_unload(monkeypatch):
+ world = _world("off", [QWEN])
+ world[STATUS] = {**world[STATUS], "loaded": [QWEN, KEPT]}
+ plan = _plan(monkeypatch, world, {"model": OUTETTS, "kind": "tts", "device": "cpu"})
+ assert ("llm", KEPT) in _names(plan["residents"])
+ # A held standard model can outlive a GGUF load, so it is listed as an upper bound.
+ assert _names(plan["would_evict"]) == {("llm", QWEN), ("llm", KEPT)}
+ assert plan["would_evict_exact"] is False
+
+
+def test_a_pick_the_plan_calls_incompatible_gets_no_plan(monkeypatch):
+ plan = {"entries": [], "total_bytes": 9, "incompatible_reason": "base and GGUF sizes differ"}
+ world = {**_world("off", []), ("POST", "/api/inference/images/download-plan"): plan}
+ args = {"model": FLUX_GGUF, "kind": "image"}
+ result, _studio = run_tool(monkeypatch, world, "plan_load", args, fallback = {})
+ assert result["isError"] is True and "sizes differ" in str(result["content"])
+
+
+def test_a_partial_variant_load_model_refuses_gets_no_plan(monkeypatch):
+ partial = {"variants": [{"quant": "Q8_0", "filename": "b.gguf", "partial": True}]}
+ world = {
+ **_world("off", []),
+ ("GET", "/api/hub/gguf-variants"): partial,
+ ("GET", "/api/hub/download-status"): {"state": "idle"},
+ }
+ args = {"model": QWEN, "variant": "Q8_0"}
+ result, _studio = run_tool(monkeypatch, world, "plan_load", args, fallback = {})
+ assert result["isError"] is True and "still downloading or incomplete" in str(result["content"])
+
+
+def test_an_unreadable_media_status_makes_the_plan_an_upper_bound(monkeypatch):
+ world = _world("off", [QWEN])
+ world[("GET", VIDEO)] = JSONResponse({"detail": "busy"}, status_code = 503)
+ plan = _plan(monkeypatch, world, {"model": FLUX_GGUF, "kind": "image"})
+ assert plan["multi_model_mode"] == "off" and plan["would_evict_exact"] is False
+
+
+def test_the_hf_token_argument_reaches_the_listing_and_the_plan(monkeypatch):
+ args = {"model": FLUX_GGUF, "kind": "image", "hf_token": "hf_arg"}
+ result, studio = run_tool(monkeypatch, _world("off", []), "plan_load", args, fallback = {})
+ assert result.get("isError") is not True
+ (body,) = bodies(studio, "/api/inference/images/download-plan")
+ assert body["hf_token"] == "hf_arg"
+
+
+def test_always_refuses_another_model_in_an_occupied_media_slot(monkeypatch):
+ world = _world("always", [], video = "other/video-model")
+ plan = _plan(monkeypatch, world, {"model": LTX, "kind": "video"})
+ assert plan["would_refuse"] is True and plan["would_evict"] == []
+
+
+def test_a_gguf_repo_is_known_by_its_listing_not_its_name(monkeypatch):
+ plan = _plan(monkeypatch, _world("off", []), {"model": "someone/qwen3-quants"})
+ assert [row["variant"] for row in plan["variants"]] == ["Q4_K_M", "Q8_0"]
+
+
+def test_a_native_tts_primary_makes_a_media_plan_an_upper_bound(monkeypatch):
+ # It may run on the CPU and keep its place, and status does not say which.
+ world = _world("off", [OUTETTS], is_audio = True)
+ plan = _plan(monkeypatch, world, {"model": FLUX_GGUF, "kind": "image"})
+ assert _names(plan["would_evict"]) == {("llm", OUTETTS)}
+ assert plan["would_evict_exact"] is False
+
+
+ "resident,args",
+ [
+ # An omitted task loads H3's keyframe partition, not the resident reference one.
+ ({"h3_task": "ref2va"}, {"model": LTX, "kind": "video"}),
+ ({"h3_task": "fl2va"}, {"model": LTX, "kind": "video", "h3_task": "ref2va"}),
+ ],
+)
+def test_a_load_of_the_resident_media_repo_may_load_it_again(monkeypatch, resident, args):
+ world = _world("off", [QWEN], video = LTX)
+ world[("GET", VIDEO)] = {**world[("GET", VIDEO)], **resident}
+ plan = _plan(monkeypatch, world, args)
+ assert _names(plan["would_evict"]) == {("llm", QWEN), ("video", LTX)}
+ assert plan["would_evict_exact"] is False
+
+
+def test_a_local_gguf_file_may_be_a_vision_model_on_the_gpu(monkeypatch):
+ plan = _plan(
+ monkeypatch,
+ _world("off", [QWEN], image = FLUX_GGUF),
+ {"model": "/models/vision.gguf", "device": "cpu"},
+ )
+ assert ("image", FLUX_GGUF) in _names(plan["would_evict"])
+ assert plan["would_evict_exact"] is False
+
+
+def test_unloading_another_kind_is_always_an_upper_bound(monkeypatch):
+ # A TTS may run on the CPU (UNSLOTH_AUDIO_DEVICE=cpu, or no GPU at all) and leave the image model.
+ world = _world("off", [QWEN], image = FLUX_GGUF)
+ for args in (
+ {"model": OUTETTS, "kind": "tts"},
+ {"model": OUTETTS, "kind": "tts", "device": "gpu"},
+ ):
+ plan = _plan(monkeypatch, world, args)
+ assert _names(plan["would_evict"]) == {("llm", QWEN), ("image", FLUX_GGUF)}
+ assert plan["would_evict_exact"] is False
+
+
+def test_a_speech_to_text_load_may_release_the_other_engines_model(monkeypatch):
+ plan = _plan(
+ monkeypatch, _world("off", []), {"model": "openai/whisper-large-v3", "kind": "stt"}
+ )
+ assert _names(plan["would_evict"]) == {("stt", "openai/whisper-small")}
+ assert plan["would_evict_exact"] is False
+
+
+ "args",
+ [
+ # The same variant may still load again (another context, device or cache type).
+ {"model": QWEN, "variant": "Q4_K_M"},
+ {"model": QWEN, "variant": "Q4_K_M", "kv_cache_type": "q8_0"},
+ {"model": QWEN},
+ ],
+)
+def test_a_load_of_a_resident_chat_repo_is_a_possible_reload(monkeypatch, args):
+ plan = _plan(monkeypatch, _world("off", [f"{QWEN}:Q4_K_M"]), args)
+ assert _names(plan["would_evict"]) == {("llm", f"{QWEN}:Q4_K_M")}
+ assert plan["would_evict_exact"] is False
+
+
+def test_local_paths_keep_their_case(monkeypatch):
+ plan = _plan(monkeypatch, _world("always", ["/models/Foo.gguf"]), {"model": "/models/foo.gguf"})
+ assert plan["would_refuse"] is True
+
+
+def test_an_unreadable_stt_status_makes_an_stt_plan_an_upper_bound(monkeypatch):
+ world = _world("off", [])
+ world[("GET", "/api/inference/audio/stt/status")] = JSONResponse({}, status_code = 503)
+ plan = _plan(monkeypatch, world, {"model": "openai/whisper-large-v3", "kind": "stt"})
+ assert plan["would_evict"] == [] and plan["would_evict_exact"] is False
+
+
+def test_always_does_not_protect_a_chat_model_holding_no_vram(monkeypatch):
+ world = _world("always", [QWEN], gpu_memory_mode = "manual", gpu_layers = 0)
+ plan = _plan(monkeypatch, world, {"model": FLUX_GGUF, "kind": "image"})
+ assert plan["would_refuse"] is False
+
+
+def test_an_unreadable_chat_status_makes_the_plan_an_upper_bound(monkeypatch):
+ world = _world("off", [QWEN], image = FLUX_GGUF)
+ world[STATUS] = JSONResponse({}, status_code = 503)
+ plan = _plan(monkeypatch, world, {"model": QWEN, "variant": "Q4_K_M", "device": "gpu"})
+ assert plan["would_evict_exact"] is False
+
+
+def on_gpu_estimate(monkeypatch, world):
+ return _plan(monkeypatch, world, {"model": QWEN, "gpu_layers": 20})["est_gpu_bytes"]
+
+
+def test_gpu_layers_places_a_gguf_plan_like_device(monkeypatch):
+ world = _world("off", [], image = FLUX_GGUF)
+ off_gpu = _plan(monkeypatch, world, {"model": QWEN, "gpu_layers": 0})
+ on_gpu = _plan(monkeypatch, world, {"model": QWEN, "gpu_layers": 20})
+ auto = _plan(monkeypatch, world, {"model": QWEN, "gpu_layers": 0, "device": "auto"})
+ assert auto["would_evict"] == []
+ assert off_gpu["would_evict"] == [] and off_gpu["would_evict_exact"] is True
+ # The memory estimate prices a GPU load, so it is left out for one kept off the GPU.
+ assert off_gpu["est_gpu_bytes"] is None and on_gpu_estimate(monkeypatch, world) == 1234
+ assert (
+ _names(on_gpu["would_evict"]) == {("image", FLUX_GGUF)}
+ and on_gpu["would_evict_exact"] is False
+ )
+
+
+def test_a_failed_listing_leaves_vision_unknown(monkeypatch):
+ calls = []
+
+ def listing(request, body):
+ # The CPU check reads it; the plan's own read then fails.
+ calls.append(1)
+ return VARIANTS if len(calls) == 1 else JSONResponse({}, status_code = 503)
+
+ world = {**_world("off", [], image = FLUX_GGUF), ("GET", "/api/hub/gguf-variants"): listing}
+ plan = _plan(monkeypatch, world, {"model": QWEN, "device": "cpu"})
+ assert plan["would_evict_exact"] is False
+
+
+def test_a_chat_model_still_loading_makes_the_plan_an_upper_bound(monkeypatch):
+ world = _world("off", [], loading = [KEPT])
+ plan = _plan(monkeypatch, world, {"model": FLUX_GGUF, "kind": "image"})
+ assert plan["would_evict_exact"] is False
+
+
+def test_an_stt_model_status_repeats_is_listed_once(monkeypatch):
+ world = _world("off", [])
+ whisper = stt_state(loaded = "openai/whisper-small")
+ world[("GET", "/api/inference/audio/stt/status")] = {"transformers": whisper, "active": whisper}
+ plan = _plan(monkeypatch, world, {"model": "openai/whisper-large-v3", "kind": "stt"})
+ assert plan["would_evict"] == [{"kind": "stt", "model": "openai/whisper-small"}]
+
+
+def test_the_memory_estimate_carries_the_hub_token(monkeypatch):
+ args = {"model": QWEN, "hf_token": "hf_arg"}
+ result, studio = run_tool(monkeypatch, _world("off", []), "plan_load", args, fallback = {})
+ assert result["structuredContent"]["est_gpu_bytes"] == 1234
+ (body,) = bodies(studio, "/api/inference/estimate-memory")
+ assert body["hf_token"] == "hf_arg"
+
+
+def test_a_hub_repo_named_like_a_gguf_file_is_still_listed(monkeypatch):
+ plan = _plan(monkeypatch, _world("off", []), {"model": "org/model.gguf"})
+ assert [row["variant"] for row in plan["variants"]] == ["Q4_K_M", "Q8_0"]
+
+
+def test_the_memory_estimate_is_priced_with_the_cache_type_and_layers(monkeypatch):
+ args = {"model": QWEN, "kv_cache_type": "q8_0", "gpu_layers": 20}
+ _result, studio = run_tool(monkeypatch, _world("off", []), "plan_load", args, fallback = {})
+ (body,) = bodies(studio, "/api/inference/estimate-memory")
+ assert (body["cache_type_kv"], body["gpu_memory_mode"], body["gpu_layers"]) == (
+ "q8_0",
+ "manual",
+ 20,
+ )
+
+
+def test_an_unreadable_listing_is_no_proof_a_variant_is_missing(monkeypatch):
+ world = {
+ **_world("off", []),
+ ("GET", "/api/hub/gguf-variants"): JSONResponse({}, status_code = 503),
+ }
+ plan = _plan(monkeypatch, world, {"model": QWEN, "variant": "Q4_K_M"})
+ assert plan["variants"] == [] and plan["would_evict_exact"] is False
+
+
+def test_a_stalled_status_read_gives_an_upper_bound_not_a_hang(monkeypatch):
+ from studio_mcp import placement
+
+ async def stalled(request, body):
+ await asyncio.sleep(10)
+ return {}
+
+ monkeypatch.setattr(placement, "READ_S", 0.05)
+ world = {**_world("off", [QWEN]), ("GET", "/api/inference/audio/stt/status"): stalled}
+ plan = _plan(monkeypatch, world, {"model": "openai/whisper-large-v3", "kind": "stt"})
+ assert plan["would_evict_exact"] is False
+
+
+def test_always_a_load_joining_the_chat_models_is_refused_only_over_media(monkeypatch):
+ args = {"model": OUTETTS, "kind": "tts", "alongside": True}
+ alone = _plan(monkeypatch, _world("always", [QWEN]), args)
+ beside_image = _plan(monkeypatch, _world("always", [QWEN], image = FLUX_GGUF), args)
+ assert (alone["would_refuse"], beside_image["would_refuse"]) == (False, True)
+
+
+def _listed(monkeypatch, listing):
+ from studio_mcp import placement
+
+ asked = []
+
+ async def variants(_caller, repo):
+ asked.append(repo)
+ return listing
+
+ monkeypatch.setattr(placement, "_variants", variants)
+ return placement, asked
+
+
+def test_a_local_model_handle_is_never_split_into_repo_and_variant(monkeypatch):
+ # An API-key caller names a local model by its `ref:<digest>` handle.
+ placement, asked = _listed(monkeypatch, VARIANTS)
+ handle = "ref:0123456789abcdef0123456789abcdef"
+ gguf = asyncio.run(placement.require_cpu_gguf(None, "llm", handle, None, "cpu"))
+ assert gguf is True
+ assert asked == [handle]
+
+
+def test_an_mlx_precision_listing_is_no_gguf_for_cpu_placement(monkeypatch):
+ mlx = {
+ "variant_format": "mlx",
+ "variants": [{"quant": "4bit", "filename": "4bit/", "size_bytes": 10}],
+ }
+ placement, _asked = _listed(monkeypatch, mlx)
+ with pytest.raises(Exception, match = "needs a GGUF"):
+ asyncio.run(placement.require_cpu_gguf(None, "llm", "org/model-mlx", None, "cpu"))
+ with pytest.raises(Exception, match = "gpu_layers is only for GGUF"):
+ asyncio.run(placement.require_cpu_gguf(None, "llm", "org/model-mlx", None, None, 0))
diff --git a/studio/backend/tests/test_mcp_tools_status.py b/studio/backend/tests/test_mcp_tools_status.py
index 4e69157a4d9..1d93d76f1e4 100644
--- a/studio/backend/tests/test_mcp_tools_status.py
+++ b/studio/backend/tests/test_mcp_tools_status.py
@@ -146,12 +146,14 @@ def test_every_slot_is_reported(monkeypatch):
"family": "flux",
**IMAGE_EXTRAS,
"generating": False,
+ "placement": None,
}
assert status["video"] == {
"loaded": True,
"model": "Lightricks/LTX-Video",
**VIDEO_EXTRAS,
"generating": False,
+ "placement": None,
}
assert status["stt"] == {
"engine": "gguf",
@@ -236,7 +238,13 @@ def test_failing_and_owner_only_slots_do_not_fail_the_tool(monkeypatch):
assert set(status["unavailable"]) == {"video"}
assert "Video backend crashed" in status["unavailable"]["video"]
assert "/srv/hf" not in status["unavailable"]["video"]
- assert status["video"] == {"loaded": False, "model": None, **VIDEO_EXTRAS, "generating": False}
+ assert status["video"] == {
+ "loaded": False,
+ "model": None,
+ **VIDEO_EXTRAS,
+ "generating": False,
+ "placement": None,
+ }
assert status["embedder"] == {"available": False, "loaded": False, "model": None}
assert status["image"]["generating"] is True
assert status["chat"]["loaded"]
@@ -295,8 +303,15 @@ def test_unloaded_slots_name_no_model(monkeypatch):
"family": None,
**IMAGE_EXTRAS,
"generating": False,
+ "placement": None,
+ }
+ assert status["video"] == {
+ "loaded": False,
+ "model": None,
+ **VIDEO_EXTRAS,
+ "generating": False,
+ "placement": None,
}
- assert status["video"] == {"loaded": False, "model": None, **VIDEO_EXTRAS, "generating": False}
def _training_slot(monkeypatch, details):
diff --git a/studio/backend/tests/test_mcp_tools_video.py b/studio/backend/tests/test_mcp_tools_video.py
index b1d10384ba3..a8d91ed23cd 100644
--- a/studio/backend/tests/test_mcp_tools_video.py
+++ b/studio/backend/tests/test_mcp_tools_video.py
@@ -84,6 +84,8 @@ def test_generate_video_starts_a_job_with_string_fields(monkeypatch):
assert result["structuredContent"] == {
"id": "video-1",
"status": "queued",
+ "queue_position": None,
+ "eta_s": None,
"progress": 0,
"progress_percent": 0.0,
"model": "Lightricks/LTX-Video",
@@ -114,6 +116,8 @@ def test_a_completed_job_returns_its_thumbnail_and_a_link_never_the_mp4(monkeypa
"poll_after_s": None,
"training": None,
"load": None,
+ "queue_position": None,
+ "eta_s": None,
"error": None,
"error_code": None,
"video": {
diff --git a/studio/backend/tests/test_mcp_video_queue.py b/studio/backend/tests/test_mcp_video_queue.py
new file mode 100644
index 00000000000..193f76dbf63
--- /dev/null
+++ b/studio/backend/tests/test_mcp_video_queue.py
@@ -0,0 +1,357 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import asyncio
+import contextlib
+import json
+import time
+
+import httpx
+import pytest
+from fastmcp.exceptions import ToolError
+from fastapi.responses import JSONResponse
+from fastapi.testclient import TestClient
+
+from studio_mcp import video_queue
+
+from .mcp_harness import call_tool, fake_studio, make_caller, openai_error, run_tool, served
+
+BUSY = openai_error(video_queue.BUSY_MESSAGE, 409, type = "conflict_error")
+MODEL_CHANGED = openai_error(
+ "The requested video model changed before generation was reserved.",
+ 409,
+ type = "conflict_error",
+ param = "model",
+ code = "model_changed",
+)
+GPU_BUSY = JSONResponse(
+ {"error": "gpu_busy", "message": "Another account is generating.", "retry_after": 0},
+ status_code = 409,
+ headers = {"Retry-After": "0"},
+)
+ETA = 30.0
+
+
[email protected](autouse = True)
+def fresh_queue(monkeypatch):
+ monkeypatch.setattr(video_queue, "POLL_S", 0.01)
+ monkeypatch.setattr(video_queue, "RETRY_S", 0.01)
+ video_queue._reset()
+ yield
+ video_queue._reset()
+
+
+class OneVideoStudio:
+ """A fake Unsloth Studio that makes one video at a time: a POST while one runs is the busy 409, and a video runs until the test calls ``finish``. ``answers`` are POST answers given first, in order."""
+
+ def __init__(self, *answers):
+ self.answers = list(answers)
+ self.active = None
+ self.made = 0
+ self.done = set()
+ self.app = fake_studio(
+ {
+ ("POST", "/v1/videos"): self._create,
+ ("GET", "/v1/videos/{video_id}"): self._get,
+ ("GET", video_queue.PROGRESS): self._progress,
+ }
+ )
+
+ def _create(self, request, body):
+ if self.answers:
+ return self.answers.pop(0)
+ if self.active is not None:
+ return BUSY
+ self.made += 1
+ self.active = f"video-{self.made}"
+ return {
+ "id": self.active,
+ "status": "queued",
+ "progress": 0,
+ "prompt": json.loads(body)["prompt"],
+ }
+
+ def _get(self, request, body):
+ video_id = request.path_params["video_id"]
+ status = "completed" if video_id in self.done else "in_progress"
+ return {"id": video_id, "object": "video", "status": status, "progress": 50}
+
+ def _progress(self, request, body):
+ return {"active": self.active is not None, "eta_seconds": ETA if self.active else None}
+
+ def finish(self):
+ self.done.add(self.active)
+ self.active = None
+
+ def prompts(self):
+ return [json.loads(c[3])["prompt"] for c in self.app.state.calls if c[0] == "POST"]
+
+
+def open_client(monkeypatch, fake):
+ # One client for the whole test: the queue's background task runs on its event loop.
+ from mcp_server import create_studio_mcp
+ with TestClient(served(create_studio_mcp(), fake.app, monkeypatch = monkeypatch)) as http:
+ yield http
+
+
+def generate(http, prompt):
+ return call_tool(http, "generate_video", {"prompt": prompt, "seconds": "4"})[
+ "structuredContent"
+ ]
+
+
+def get_video(http, video_id):
+ result = call_tool(http, "get_job", {"kind": "video", "id": video_id})
+ assert result["isError"] is False, result
+ return result["structuredContent"]
+
+
+def wait_until(http, video_id, check):
+ deadline = time.monotonic() + 30.0
+ while True:
+ job = get_video(http, video_id)
+ if check(job) or time.monotonic() > deadline:
+ return job
+ time.sleep(0.02)
+
+
+def test_a_shot_list_runs_in_order_one_video_after_another(monkeypatch):
+ fake = OneVideoStudio()
+ with open_client(monkeypatch, fake) as http:
+ a, b, c = generate(http, "A"), generate(http, "B"), generate(http, "C")
+ assert a["id"] == "video-1" and a["queue_position"] is None
+ assert [b["status"], b["queue_position"], c["status"], c["queue_position"]] == [
+ "queued",
+ 1,
+ "queued",
+ 2,
+ ]
+ assert b["id"].startswith("vq_") and b["seconds"] == "4"
+ # C queues behind B without trying: only B met the busy answer.
+ assert fake.prompts() == ["A", "B"]
+
+ fake.finish()
+ job_b = wait_until(http, b["id"], lambda job: job["status"] != "queued")
+ assert job_b["id"] == "video-2" and job_b["status"] == "in_progress"
+ assert fake.prompts() == ["A", "B", "B"]
+ assert get_video(http, c["id"])["queue_position"] == 1
+
+ fake.finish()
+ job_c = wait_until(http, c["id"], lambda job: job["id"] == "video-3")
+ assert job_c["id"] == "video-3"
+ assert fake.prompts() == ["A", "B", "B", "C"]
+
+
+def test_a_queued_video_reports_when_it_should_start(monkeypatch):
+ fake = OneVideoStudio()
+ with open_client(monkeypatch, fake) as http:
+ generate(http, "A")
+ b, c = generate(http, "B"), generate(http, "C")
+ # Next in line starts when the running video's denoise ends; each later one a clip later.
+ assert b["eta_s"] == ETA
+ assert c["eta_s"] > ETA
+ job_b, job_c = get_video(http, b["id"]), get_video(http, c["id"])
+ assert [job_b["status"], job_b["queue_position"], job_b["eta_s"]] == ["queued", 1, ETA]
+ assert job_c["queue_position"] == 2 and job_c["eta_s"] > job_b["eta_s"]
+
+
+def test_cancelling_a_waiting_video_withdraws_it_and_moves_the_rest_up(monkeypatch):
+ fake = OneVideoStudio()
+ with open_client(monkeypatch, fake) as http:
+ generate(http, "A")
+ b, c = generate(http, "B"), generate(http, "C")
+ result = call_tool(http, "cancel", {"kind": "video", "id": b["id"]})["structuredContent"]
+ assert result["cancelled"] is True
+ assert result["message"] == "Removed the queued video before it started."
+ assert get_video(http, c["id"])["queue_position"] == 1
+ assert get_video(http, b["id"])["status"] == "cancelled"
+
+ fake.finish()
+ job_c = wait_until(http, c["id"], lambda job: job["status"] != "queued")
+ assert job_c["id"] == "video-2"
+ # B met the busy answer once and was never sent again.
+ assert fake.prompts() == ["A", "B", "C"]
+ again = call_tool(http, "cancel", {"kind": "video", "id": c["id"]})["structuredContent"]
+ assert again["cancelled"] is False
+ assert (
+ again["message"]
+ == "It already started as video-2; cancel(kind='video') stops the running video."
+ )
+
+
+def test_the_queue_waits_out_gpu_busy_and_fails_a_refused_video_with_its_reason(monkeypatch):
+ refused = openai_error("Unsupported size 1x1.", 400, param = "size")
+ fake = OneVideoStudio()
+ with open_client(monkeypatch, fake) as http:
+ generate(http, "A")
+ b, c = generate(http, "B"), generate(http, "C")
+ fake.answers = [GPU_BUSY, refused]
+ fake.finish()
+ job_b = wait_until(http, b["id"], lambda job: job["status"] != "queued")
+ job_c = wait_until(http, c["id"], lambda job: job["status"] != "queued")
+ assert job_b["status"] == "failed"
+ assert job_b["error"] == "Invalid arguments: Unsupported size 1x1."
+ # The gpu_busy try is retried, and the next video still goes after the refused one.
+ assert fake.prompts() == ["A", "B", "B", "B", "C"]
+ assert job_c["id"] == "video-2"
+
+
+ "answer, text",
+ [
+ (MODEL_CHANGED, "[model_changed] The requested video model changed"),
+ (GPU_BUSY, "GPU busy: Another account is generating. Retry after 0 s."),
+ (openai_error("No video model is loaded.", 503), "Load a video model with load_model"),
+ ],
+)
+def test_other_refusals_raise_as_before_and_queue_nothing(monkeypatch, answer, text):
+ result, studio = run_tool(
+ monkeypatch, {("POST", "/v1/videos"): answer}, "generate_video", {"prompt": "A"}
+ )
+ assert result["isError"] is True
+ assert text in result["content"][0]["text"]
+ assert [c[1] for c in studio.state.calls] == ["/v1/videos"]
+ assert not video_queue._items and not video_queue._pumps
+
+
+def test_a_queue_id_belongs_to_its_account():
+ owner = make_caller(account_id = "owner")
+ item = video_queue._enqueue(owner, {"prompt": "A"}, None)
+ for call in (video_queue.lookup, video_queue.cancel):
+ with pytest.raises(Exception, match = "No such video job"):
+ call("someone-else", item.id)
+ assert video_queue.lookup("owner", item.id) is item
+
+
+def test_an_unknown_queue_id_reads_as_no_such_video_job(monkeypatch):
+ result, studio = run_tool(monkeypatch, {}, "get_job", {"kind": "video", "id": "vq_nope"})
+ assert result["isError"] is True
+ assert "No such video job" in result["content"][0]["text"]
+ assert studio.state.calls == []
+
+
+def test_a_full_queue_is_refused():
+ owner = make_caller(account_id = "owner")
+ for n in range(video_queue.MAX_WAITING):
+ video_queue._enqueue(owner, {"prompt": str(n)}, None)
+ with pytest.raises(Exception, match = "already queued"):
+ video_queue._enqueue(owner, {"prompt": "one more"}, None)
+
+
+def test_the_busy_message_matches_unsloth_studio():
+ from core.inference.video_families import VIDEO_GENERATION_BUSY_MSG
+ assert video_queue.BUSY_MESSAGE == VIDEO_GENERATION_BUSY_MSG
+
+
+def test_a_video_that_starts_while_its_place_is_read_is_not_reported_queued(monkeypatch):
+ item = video_queue.QueuedVideo(id = "vq_x", account_id = "a", caller = make_caller(), body = {})
+
+ async def starts_meanwhile(queued):
+ queued.status, queued.video_id = "submitted", "video-9"
+ return 1, 0.0
+
+ monkeypatch.setattr(video_queue, "_position_eta", starts_meanwhile)
+ status = asyncio.run(video_queue.job_status(item))
+ # The status read before the await goes with the position read during it.
+ assert (status.status, status.queue_position) == ("queued", 1)
+
+
+def test_the_queue_id_of_a_video_still_running_outlives_the_record_cap(monkeypatch):
+ caller = make_caller(account_id = "a")
+ running = video_queue.QueuedVideo(id = "vq_run", account_id = "a", caller = caller, body = {})
+ running.status, running.video_id = "submitted", "video-1"
+ video_queue._items["a:vq_run"] = running
+ video_queue._running["a"] = ("video-1", 0.0)
+ for n in range(video_queue.CAPACITY + 5):
+ done = video_queue.QueuedVideo(id = f"vq_{n}", account_id = "b", caller = caller, body = {})
+ done.status = "cancelled"
+ video_queue._items[f"b:vq_{n}"] = done
+ video_queue._evict()
+ assert video_queue.lookup("a", "vq_run") is running
+ assert len(video_queue._items) == video_queue.CAPACITY
+
+
+def test_a_second_video_never_overtakes_one_entering_the_queue(monkeypatch):
+ busy = httpx.Response(409, json = {"error": {"code": None, "message": video_queue.BUSY_MESSAGE}})
+ started = httpx.Response(200, json = {"id": "video-2", "status": "queued"})
+ posted = []
+
+ async def forward(caller, method, path, **kwargs):
+ posted.append(kwargs["json_body"]["prompt"])
+ if len(posted) == 1:
+ # The running video ends while the first, refused, is still on its way into the queue.
+ await asyncio.sleep(0.05)
+ return busy
+ return started
+
+ async def no_eta(item):
+ return 1, None
+
+ monkeypatch.setattr(video_queue, "forward", forward)
+ monkeypatch.setattr(video_queue, "_ensure_pump", lambda account_id: None)
+ monkeypatch.setattr(video_queue, "_position_eta", no_eta)
+ caller = make_caller(account_id = "a")
+
+ async def both():
+ first = asyncio.create_task(video_queue.post_or_queue(caller, {"prompt": "A"}))
+ await asyncio.sleep(0)
+ second = asyncio.create_task(video_queue.post_or_queue(caller, {"prompt": "B"}))
+ return await first, await second
+
+ first, second = asyncio.run(both())
+ assert (first.status, second.status) == ("queued", "queued")
+ assert posted == ["A"]
+ assert [item.body["prompt"] for item in video_queue._waiting["a"]] == ["A", "B"]
+
+
+def test_the_last_queued_video_is_followed_to_its_end(monkeypatch):
+ fake = OneVideoStudio()
+ with open_client(monkeypatch, fake) as http:
+ generate(http, "A")
+ b = generate(http, "B")
+ fake.finish()
+ wait_until(http, b["id"], lambda job: job["id"] == "video-2")
+ fake.finish()
+ deadline = time.monotonic() + 10.0
+ while video_queue._running and time.monotonic() < deadline:
+ time.sleep(0.02)
+ # Nothing waits on the finished clip any more, so its record can be dropped at the cap.
+ assert video_queue._running == {}
+ assert video_queue._ended(video_queue.lookup(*next(iter(video_queue._items)).split(":", 1)))
+
+
+def test_the_queue_has_a_cap_across_accounts():
+ for n in range(video_queue.CAPACITY):
+ caller = make_caller(account_id = f"acct-{n}")
+ video_queue._enqueue(caller, {"prompt": "x"}, None)
+ with pytest.raises(ToolError, match = "already queued"):
+ video_queue._enqueue(make_caller(account_id = "late"), {"prompt": "x"}, None)
+
+
+def test_a_failed_status_read_does_not_end_the_wait_on_a_running_video(monkeypatch):
+ reads = iter([None, "stall", {"status": "in_progress"}, {"status": "completed"}])
+
+ async def try_json(caller, path, **kwargs):
+ read = next(reads)
+ if read == "stall":
+ await asyncio.sleep(10)
+ return read
+
+ monkeypatch.setattr(video_queue, "try_json", try_json)
+ monkeypatch.setattr(video_queue, "POLL_S", 0)
+ monkeypatch.setattr(video_queue, "READ_S", 0.05)
+ video_queue._running["a"] = ("video-1", 0.0)
+ asyncio.run(video_queue._wait_for_running(make_caller(account_id = "a")))
+ # It waited through a failed read and a stalled one to the video's real end.
+ assert next(reads, "drained") == "drained" and "a" not in video_queue._running
+
+
+def test_a_stalled_eta_read_leaves_the_eta_unknown(monkeypatch):
+ async def stalled(caller, position):
+ await asyncio.sleep(10)
+
+ monkeypatch.setattr(video_queue, "_eta", stalled)
+ monkeypatch.setattr(video_queue, "READ_S", 0.05)
+ item = video_queue._enqueue(make_caller(account_id = "a"), {"prompt": "x"}, None)
+ assert asyncio.run(video_queue._position_eta(item)) == (1, None)