Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""The --parallel aliases (default 4, 1..64) must stay a subset of the backend denylist."""
from __future__ import annotations
import contextlib
import json
import sys
from io import BytesIO
from pathlib import Path
import pytest
from typer.testing import CliRunner
_REPO_ROOT = Path(__file__).resolve().parents[2]
if str(_REPO_ROOT) not in sys.path:
sys.path.insert(0, str(_REPO_ROOT))
def _load_run_command():
"""Import studio without starting the server; backend imports are lazy inside run()."""
from unsloth_cli.commands import studio as _studio
return _studio
def test_parallel_option_is_registered():
"""The `--parallel` flag (with aliases) must be on the `run` command."""
studio_mod = _load_run_command()
import inspect
run_fn = studio_mod.run
sig = inspect.signature(run_fn)
assert "parallel" in sig.parameters, "missing `parallel` parameter on run()"
param = sig.parameters["parallel"]
opt = param.default
flags = set()
decls = getattr(opt, "param_decls", None) or []
for d in decls:
flags.add(d)
for required in ("--parallel", "--n-parallel", "-np"):
assert required in flags, f"flag {required!r} missing from --parallel option"
def test_context_length_alias_is_registered():
"""`--context-length` is an operator-facing alias for --max-seq-length."""
studio_mod = _load_run_command()
import inspect
sig = inspect.signature(studio_mod.run)
opt = sig.parameters["max_seq_length"].default
flags = set(getattr(opt, "param_decls", None) or [])
assert "--max-seq-length" in flags
assert "--context-length" in flags
def test_gpu_memory_mode_option_is_registered_with_auto_default():
"""The GPU placement policy is a first-class model option."""
studio_mod = _load_run_command()
import inspect
sig = inspect.signature(studio_mod.run)
opt = sig.parameters["gpu_memory_mode"].default
flags = set(getattr(opt, "param_decls", None) or [])
assert flags == {"--gpu-memory-mode"}
assert getattr(opt, "default", None) == "auto"
assert getattr(opt, "rich_help_panel", None) == "Model"
def test_speculative_options_are_registered():
studio_mod = _load_run_command()
import inspect
sig = inspect.signature(studio_mod.run)
spec_type = sig.parameters["speculative_type"].default
draft_n = sig.parameters["spec_draft_n_max"].default
assert set(getattr(spec_type, "param_decls", None) or []) == {"--speculative-type"}
assert getattr(spec_type, "default", "missing") is None
assert set(getattr(draft_n, "param_decls", None) or []) == {"--spec-draft-n-max"}
assert getattr(draft_n, "default", "missing") is None
assert getattr(draft_n, "min", None) == 1
assert getattr(draft_n, "max", None) == 16
def test_parallel_default_is_four():
"""Default must stay at 4 so plain `unsloth studio run` is unchanged."""
studio_mod = _load_run_command()
import inspect
sig = inspect.signature(studio_mod.run)
opt = sig.parameters["parallel"].default
default = getattr(opt, "default", None)
assert default == 4, f"default changed to {default}; would silently alter existing deployments"
def test_parallel_range_guards_are_set():
"""Range guards: 1 <= N <= 64. Outside this is a hard reject."""
studio_mod = _load_run_command()
import inspect
sig = inspect.signature(studio_mod.run)
opt = sig.parameters["parallel"].default
assert getattr(opt, "min", None) == 1, "min must be 1 (0 = no decode possible)"
assert getattr(opt, "max", None) == 64, "max must be 64 (KV split sanity cap)"
def test_parallel_help_describes_the_shared_kv_cache():
"""Multi-slot launches add --kv-unified; builds lacking it run one slot (load_model), never ctx/N."""
studio_mod = _load_run_command()
import inspect
sig = inspect.signature(studio_mod.run)
help_text = " ".join(sig.parameters["parallel"].default.help.split())
assert "--kv-unified" in help_text
assert "ctx/N" not in help_text
assert "fall back to one slot" in help_text
def test_typer_parallel_aliases_are_subset_of_backend_denylist():
"""Backend must deny every --parallel alias, or /load can smuggle it in via llama_extra_args."""
studio_mod = _load_run_command()
import inspect
import importlib.util
# Load llama_server_args.py directly to avoid the backend's full runtime chain.
lsa_path = (
Path(__file__).resolve().parents[2]
/ "studio"
/ "backend"
/ "core"
/ "inference"
/ "llama_server_args.py"
)
spec = importlib.util.spec_from_file_location("_lsa_for_subset_test", lsa_path)
lsa = importlib.util.module_from_spec(spec)
spec.loader.exec_module(lsa)
_DENYLIST_GROUPS = lsa._DENYLIST_GROUPS
parallel_group = next((g for g in _DENYLIST_GROUPS if "--parallel" in g), None)
assert parallel_group is not None, "denylist must include a --parallel group"
sig = inspect.signature(studio_mod.run)
opt = sig.parameters["parallel"].default
typer_aliases = set(getattr(opt, "param_decls", []) or [])
missing = typer_aliases - parallel_group
assert not missing, (
f"typer aliases {missing!r} are not in the backend denylist; "
f"add them to _DENYLIST_GROUPS to keep /load from desyncing "
f"llama_parallel_slots."
)
class _ExecCaptured(SystemExit):
def __init__(self, argv):
super().__init__(0)
self.argv = list(argv)
def _install_reexec_capture(monkeypatch, *, platform):
studio_mod = _load_run_command()
captured = []
monkeypatch.setattr(sys, "prefix", "/nonexistent/outer/venv")
fake_venv = Path("/fake/studio/venv/unsloth_studio")
host_is_windows = sys.platform == "win32"
fake_python = fake_venv / ("Scripts/python.exe" if host_is_windows else "bin/python")
fake_bin = fake_python.parent / ("unsloth.exe" if host_is_windows else "unsloth")
monkeypatch.setattr(studio_mod, "_studio_venv_python", lambda: fake_python)
real_is_file = Path.is_file
monkeypatch.setattr(
Path,
"is_file",
lambda self: True if str(self) == str(fake_bin) else real_is_file(self),
)
# resolve_tool_policy is imported lazily inside run(); patch the source.
from unsloth_cli import _tool_policy as _tp_mod
monkeypatch.setattr(
_tp_mod,
"resolve_tool_policy",
lambda host, flag, yes, silent: False if flag is None else bool(flag),
)
monkeypatch.setattr(sys, "platform", platform)
monkeypatch.setattr(
studio_mod,
"_studio_runtime_launch_guard",
lambda **_kwargs: contextlib.nullcontext(True),
)
def capture(kind, argv):
captured.append(
{
"kind": kind,
"argv": list(argv),
"start_api_key_marker": studio_mod.os.environ.get(
studio_mod._START_API_KEY_MARKER_ENV
),
}
)
def fake_execvp(file, argv):
capture("execvp", argv)
raise _ExecCaptured(argv)
class _FakePopen:
def __init__(self, argv, *a, **kw):
capture("popen", argv)
self._argv = argv
def wait(self):
raise _ExecCaptured(self._argv)
monkeypatch.setattr(studio_mod.os, "execvp", fake_execvp)
monkeypatch.setattr(studio_mod.subprocess, "Popen", _FakePopen)
return captured
def _invoke_run(
monkeypatch,
args,
*,
platform = "linux",
):
import typer as _typer
studio_mod = _load_run_command()
captured = _install_reexec_capture(monkeypatch, platform = platform)
app = _typer.Typer()
app.command(
context_settings = {
"allow_extra_args": True,
"ignore_unknown_options": True,
},
)(studio_mod.run)
result = CliRunner().invoke(app, args, catch_exceptions = True)
return result, captured
def _value_after(argv, flag):
for i, tok in enumerate(argv):
if tok == flag and i + 1 < len(argv):
return argv[i + 1]
return None
_BASE = ["--model", "unsloth/Qwen3-1.7B-GGUF"]
@pytest.mark.parametrize(
"flag,value",
[("--parallel", "8"), ("--n-parallel", "16"), ("-np", "32")],
)
def test_reexec_forwards_parallel_all_aliases(monkeypatch, flag, value):
"""Every alias the user can type must reach the re-exec'd child."""
result, captured = _invoke_run(monkeypatch, _BASE + [flag, value])
assert (
len(captured) == 1
), f"expected one launch via re-exec, got {captured}; output={result.output!r}"
argv = captured[0]["argv"]
assert (
_value_after(argv, "--parallel") == value
), f"{flag} {value} was dropped on re-exec; argv = {argv}"
@pytest.mark.parametrize("platform", ["linux", "darwin", "win32"])
def test_reexec_hands_off_start_api_key_marker_out_of_band(monkeypatch, platform):
"""A new child receives the marker while an old child sees no unknown flag."""
result, captured = _invoke_run(
monkeypatch,
_BASE + ["--start-api-key-marker"],
platform = platform,
)
assert len(captured) == 1, result.output
assert "--start-api-key-marker" not in captured[0]["argv"]
assert captured[0]["start_api_key_marker"] == "1"
def test_reexeced_child_consumes_start_api_key_marker_env(monkeypatch):
"""A supported child consumes the handoff before starting descendants."""
studio_mod = _load_run_command()
monkeypatch.setenv(studio_mod._START_API_KEY_MARKER_ENV, "1")
inherited = studio_mod._consume_start_api_key_marker_env()
assert inherited is True
assert studio_mod._START_API_KEY_MARKER_ENV not in studio_mod.os.environ
def test_in_venv_child_reports_bound_port_before_start_api_key(
monkeypatch, tmp_path, stub_tool_policy_state
):
import types
studio_mod = _load_run_command()
fake_venv = tmp_path / "studio" / "venv" / "unsloth_studio"
monkeypatch.setattr(sys, "prefix", str(fake_venv))
monkeypatch.setattr(studio_mod, "STUDIO_HOME", fake_venv.parent)
from unsloth_cli import _tool_policy as _tp_mod
monkeypatch.setattr(_tp_mod, "resolve_tool_policy", lambda host, flag, yes, silent: False)
class _App:
class state:
server_port = 8889
server_request_host = "127.0.0.1"
backend = types.ModuleType("studio.backend.run")
backend.run_server = lambda **_kwargs: _App()
backend._server = object()
backend._graceful_shutdown = lambda server: None
monkeypatch.setitem(sys.modules, "studio.backend.run", backend)
monkeypatch.setattr(studio_mod, "_RUN_MODULE", backend)
monkeypatch.setattr(studio_mod, "_wait_for_server", lambda port, **_kwargs: True)
monkeypatch.setattr(studio_mod, "_create_api_key_inprocess", lambda name: "sk-unsloth-test")
def stop_before_load(**_kwargs):
raise RuntimeError("stopped before load")
monkeypatch.setattr(studio_mod, "_load_model_via_http", stop_before_load)
import typer as _typer
app = _typer.Typer()
app.command(
context_settings = {
"allow_extra_args": True,
"ignore_unknown_options": True,
},
)(studio_mod.run)
result = CliRunner().invoke(
app,
_BASE + ["--port", "8888", "--start-api-key-marker"],
catch_exceptions = True,
)
assert "UNSLOTH_START_PORT: 8889\nUNSLOTH_START_API_KEY: sk-unsloth-test\n" in result.output
def test_run_default_sets_tool_call_env(monkeypatch):
"""Plain run enables healing and nudging via the inherited env, set before the re-exec."""
studio_mod = _load_run_command()
monkeypatch.delenv("UNSLOTH_DISABLE_TOOL_CALL_HEALING", raising = False)
monkeypatch.delenv("UNSLOTH_TOOL_CALL_NUDGE", raising = False)
_invoke_run(monkeypatch, _BASE)
assert studio_mod.os.environ["UNSLOTH_DISABLE_TOOL_CALL_HEALING"] == "0"
assert studio_mod.os.environ["UNSLOTH_TOOL_CALL_NUDGE"] == "1"
def test_run_disable_flags_set_tool_call_env(monkeypatch):
"""`--disable-tool-call-healing --disable-tool-call-nudging` flips both env vars."""
studio_mod = _load_run_command()
monkeypatch.delenv("UNSLOTH_DISABLE_TOOL_CALL_HEALING", raising = False)
monkeypatch.delenv("UNSLOTH_TOOL_CALL_NUDGE", raising = False)
_invoke_run(
monkeypatch,
_BASE + ["--disable-tool-call-healing", "--disable-tool-call-nudging"],
)
assert studio_mod.os.environ["UNSLOTH_DISABLE_TOOL_CALL_HEALING"] == "1"
assert studio_mod.os.environ["UNSLOTH_TOOL_CALL_NUDGE"] == "0"
@pytest.mark.parametrize("inherited", ["0", "false", "False", "no", ""])
def test_run_omitted_flag_respects_inherited_env(monkeypatch, inherited):
"""Omitted flag keeps a value the parent set (e.g. unsloth start) instead of resetting it."""
studio_mod = _load_run_command()
monkeypatch.setenv("UNSLOTH_TOOL_CALL_NUDGE", inherited)
monkeypatch.delenv("UNSLOTH_DISABLE_TOOL_CALL_HEALING", raising = False)
_invoke_run(monkeypatch, _BASE)
assert studio_mod.os.environ["UNSLOTH_TOOL_CALL_NUDGE"] == inherited
_SAMPLING_ENV_SUFFIXES = (
"TEMPERATURE",
"TOP_P",
"TOP_K",
"MIN_P",
"REPETITION_PENALTY",
"PRESENCE_PENALTY",
)
def test_run_sampling_flags_set_env(monkeypatch):
"""`--temperature`/`--top-k` write UNSLOTH_SAMPLING_* (a hard override the backend applies);
an omitted sampling flag leaves its env unset so the per-model recommendation stays."""
studio_mod = _load_run_command()
for _v in _SAMPLING_ENV_SUFFIXES:
monkeypatch.delenv(f"UNSLOTH_SAMPLING_{_v}", raising = False)
_invoke_run(monkeypatch, _BASE + ["--temperature", "0.3", "--top-k", "40"])
assert studio_mod.os.environ["UNSLOTH_SAMPLING_TEMPERATURE"] == "0.3"
assert studio_mod.os.environ["UNSLOTH_SAMPLING_TOP_K"] == "40"
assert "UNSLOTH_SAMPLING_TOP_P" not in studio_mod.os.environ
def test_run_no_sampling_flags_leaves_env_unset(monkeypatch):
"""Plain `unsloth run` writes no UNSLOTH_SAMPLING_*; the server keeps the recommendation."""
studio_mod = _load_run_command()
for _v in _SAMPLING_ENV_SUFFIXES:
monkeypatch.delenv(f"UNSLOTH_SAMPLING_{_v}", raising = False)
_invoke_run(monkeypatch, _BASE)
assert not any(k.startswith("UNSLOTH_SAMPLING_") for k in studio_mod.os.environ)
def test_run_rejects_out_of_range_sampling_flag(monkeypatch):
"""typer enforces the documented ranges before a value can reach the server."""
result, _captured = _invoke_run(monkeypatch, _BASE + ["--temperature", "9"])
assert result.exit_code != 0
@pytest.mark.parametrize("platform", ["linux", "darwin", "win32"])
def test_reexec_argv_is_consistent_across_platforms(monkeypatch, platform):
"""Linux/Darwin (execvp) and Windows (Popen) must build the same argv."""
result, captured = _invoke_run(monkeypatch, _BASE + ["--parallel", "12"], platform = platform)
assert len(captured) == 1
expected_kind = "popen" if platform == "win32" else "execvp"
assert (
captured[0]["kind"] == expected_kind
), f"{platform}: expected launcher {expected_kind}, got {captured[0]['kind']}"
assert _value_after(captured[0]["argv"], "--parallel") == "12"
def test_reexec_np_is_first_class_alias(monkeypatch):
"""`-np` must reach the child as --parallel <N>. Pre-PR Click
clustered `-np 8` as `-p 8` (port=8) + stray `-n`; also pin that
--port is no longer collateral damage."""
result, captured = _invoke_run(monkeypatch, _BASE + ["-np", "8"])
assert len(captured) == 1
argv = captured[0]["argv"]
assert (
_value_after(argv, "--parallel") == "8"
), f"-np 8 silently became 4 after re-exec; argv = {argv}"
assert _value_after(argv, "--port") == "8888", argv
def test_reexec_forwards_context_length_alias(monkeypatch):
"""Alias should normalize to the existing child --max-seq-length flag."""
result, captured = _invoke_run(monkeypatch, _BASE + ["--context-length", "8192"])
assert len(captured) == 1, result.output
argv = captured[0]["argv"]
assert _value_after(argv, "--max-seq-length") == "8192", argv
assert "--context-length" not in argv, argv
def test_reexec_forwards_manual_gpu_memory_mode(monkeypatch):
"""An explicit manual policy must survive the Unsloth venv re-exec."""
result, captured = _invoke_run(
monkeypatch,
_BASE + ["--gpu-memory-mode", "manual"],
)
assert len(captured) == 1, result.output
argv = captured[0]["argv"]
assert _value_after(argv, "--gpu-memory-mode") == "manual", argv
def test_reexec_omits_default_gpu_memory_mode(monkeypatch):
"""The default stays compatible with older Unsloth venv launchers."""
result, captured = _invoke_run(monkeypatch, _BASE)
assert len(captured) == 1, result.output
assert "--gpu-memory-mode" not in captured[0]["argv"]
def test_reexec_forwards_engine_parallelism_and_gpus(monkeypatch):
result, captured = _invoke_run(
monkeypatch,
["--model", "unsloth/Qwen3-8B", "--engine", "vllm"]
+ ["--engine-parallelism", "data", "--gpus", "0,2"],
)
assert len(captured) == 1, result.output
argv = captured[0]["argv"]
assert _value_after(argv, "--engine-parallelism") == "data", argv
assert _value_after(argv, "--gpus") == "0,2", argv
def test_reexec_omits_default_engine_parallelism_and_gpus(monkeypatch):
result, captured = _invoke_run(monkeypatch, _BASE)
assert len(captured) == 1, result.output
assert "--engine-parallelism" not in captured[0]["argv"]
assert "--gpus" not in captured[0]["argv"]
@pytest.mark.parametrize(
("extra", "message"),
[
(["--engine-parallelism", "data"], "--engine-parallelism applies only to --engine"),
(["--gpus", "0,x"], "--gpus takes comma-separated GPU indices"),
],
)
def test_bad_engine_parallelism_or_gpus_is_refused_before_reexec(monkeypatch, extra, message):
result, captured = _invoke_run(monkeypatch, _BASE + extra)
assert result.exit_code == 2 and not captured
assert message in result.output
def test_reexec_forwards_speculative_options(monkeypatch):
result, captured = _invoke_run(
monkeypatch,
_BASE + ["--speculative-type", "dspark", "--spec-draft-n-max", "3"],
)
assert len(captured) == 1, result.output
argv = captured[0]["argv"]
assert _value_after(argv, "--speculative-type") == "dspark", argv
assert _value_after(argv, "--spec-draft-n-max") == "3", argv
def test_reexec_forwards_dflash_speculative_type(monkeypatch):
"""Typer validates the option against SpeculativeType; a mode missing from it fails early."""
result, captured = _invoke_run(
monkeypatch,
_BASE + ["--speculative-type", "dflash"],
)
assert len(captured) == 1, result.output
assert _value_after(captured[0]["argv"], "--speculative-type") == "dflash"
def test_reexec_omits_unset_speculative_options(monkeypatch):
result, captured = _invoke_run(monkeypatch, _BASE)
assert len(captured) == 1, result.output
argv = captured[0]["argv"]
assert "--speculative-type" not in argv
assert "--spec-draft-n-max" not in argv
@pytest.mark.parametrize(
"args",
[
["--speculative-type", "invalid"],
["--spec-draft-n-max", "0"],
["--spec-draft-n-max", "17"],
],
)
def test_run_rejects_invalid_speculative_options(monkeypatch, args):
result, captured = _invoke_run(monkeypatch, _BASE + args)
assert result.exit_code != 0
assert captured == []
def test_run_rejects_invalid_gpu_memory_mode(monkeypatch):
result, captured = _invoke_run(
monkeypatch,
_BASE + ["--gpu-memory-mode", "invalid"],
)
assert result.exit_code != 0
assert captured == []
@pytest.mark.parametrize(
"mode,expected",
[
("auto", {"model_path": "owner/model-GGUF", "max_seq_length": 0, "load_in_4bit": True}),
(
"manual",
{
"model_path": "owner/model-GGUF",
"max_seq_length": 0,
"load_in_4bit": True,
"gpu_memory_mode": "manual",
"gpu_layers": -1,
},
),
],
)
def test_load_model_http_payload_for_gpu_memory_mode(monkeypatch, mode, expected):
"""Manual plus untouched layer and context settings matches the UI payload."""
studio_mod = _load_run_command()
captured = {}
def urlopen(request, timeout):
captured["request"] = request
captured["timeout"] = timeout
return BytesIO(b'{"model": "owner/model-GGUF"}')
monkeypatch.setattr(studio_mod, "_direct_urlopen", urlopen)
result = studio_mod._load_model_via_http(
port = 8888,
api_key = "sk-test",
model = "owner/model-GGUF",
gguf_variant = None,
max_seq_length = 0,
load_in_4bit = True,
gpu_memory_mode = mode,
request_host = "::1",
)
assert result == {"model": "owner/model-GGUF"}
assert json.loads(captured["request"].data) == expected
assert captured["request"].get_header("Authorization") == "Bearer sk-test"
assert captured["request"].full_url == "http://[::1]:8888/api/inference/load"
def test_health_poll_brackets_an_ipv6_request_host(monkeypatch):
studio_mod = _load_run_command()
urls = []
class _Healthy(BytesIO):
status = 200
def _urlopen(url, timeout):
urls.append((url, timeout))
return _Healthy()
monkeypatch.setattr(studio_mod, "_direct_urlopen", _urlopen)
assert studio_mod._wait_for_server(8888, timeout = 1, request_host = "::1") is True
assert urls == [("http://[::1]:8888/api/health", 2)]
def test_internal_request_urls_encode_an_ipv6_scope(monkeypatch):
studio_mod = _load_run_command()
urls = []
class _Healthy(BytesIO):
status = 200
def _urlopen(url, timeout):
urls.append(url)
return _Healthy()
monkeypatch.setattr(studio_mod, "_direct_urlopen", _urlopen)
assert studio_mod._wait_for_server(8888, timeout = 1, request_host = "fe80::1234%7") is True
assert urls == ["http://[fe80::1234%257]:8888/api/health"]
def test_process_local_http_opener_disables_proxies_and_redirects(monkeypatch):
studio_mod = _load_run_command()
handlers = []
opened = []
class _Opener:
def open(self, request, timeout):
opened.append((request, timeout))
return BytesIO(b"ok")
def _build_opener(*configured):
handlers.extend(configured)
return _Opener()
monkeypatch.setenv("HTTP_PROXY", "http://proxy.example:3128")
monkeypatch.setattr(studio_mod, "_direct_http_opener", None)
monkeypatch.setattr(studio_mod.urllib.request, "build_opener", _build_opener)
with studio_mod._direct_urlopen("http://192.0.2.24:8888/api/health", timeout = 2):
pass
proxy_handler = next(
handler
for handler in handlers
if isinstance(handler, studio_mod.urllib.request.ProxyHandler)
)
redirect_handler = next(
handler
for handler in handlers
if isinstance(handler, studio_mod.urllib.request.HTTPRedirectHandler)
)
assert proxy_handler.proxies == {}
assert opened == [("http://192.0.2.24:8888/api/health", 2)]
request = studio_mod.urllib.request.Request("http://192.0.2.24:8888/api/inference/load")
with pytest.raises(studio_mod.urllib.error.HTTPError, match = "refusing redirect"):
redirect_handler.redirect_request(
request,
None,
302,
"Found",
{},
"http://attacker.example/steal",
)
def test_load_model_http_payload_for_dspark(monkeypatch):
studio_mod = _load_run_command()
captured = {}
def urlopen(request, timeout):
captured["request"] = request
return BytesIO(b'{"model": "owner/model-GGUF"}')
monkeypatch.setattr(studio_mod, "_direct_urlopen", urlopen)
studio_mod._load_model_via_http(
port = 8888,
api_key = "sk-test",
model = "owner/model-GGUF",
gguf_variant = None,
max_seq_length = 8192,
load_in_4bit = True,
speculative_type = "dspark",
spec_draft_n_max = 3,
)
payload = json.loads(captured["request"].data)
assert payload["speculative_type"] == "dspark"
assert payload["spec_draft_n_max"] == 3
def test_load_model_http_fails_on_a_deferred_error(monkeypatch):
"""A slow load commits its 200 and pads the body, so a late failure arrives in-band and must
still raise the RuntimeError run reports, not a successful load."""
studio_mod = _load_run_command()
def urlopen(request, timeout):
return BytesIO(
b" "
+ json.dumps(
{"_deferred_error": {"status_code": 507, "detail": "CUDA out of memory"}}
).encode()
)
monkeypatch.setattr(studio_mod, "_direct_urlopen", urlopen)
with pytest.raises(RuntimeError) as excinfo:
studio_mod._load_model_via_http(
port = 8888,
api_key = "sk-test",
model = "owner/model-GGUF",
gguf_variant = None,
max_seq_length = 0,
load_in_4bit = True,
)
assert "HTTP 507" in str(excinfo.value)
assert "CUDA out of memory" in str(excinfo.value)
@pytest.mark.parametrize("body", [b"", b" ", b' {"status": "loa', b"{}"])
def test_load_model_http_rejects_a_truncated_padded_body(monkeypatch, body):
"""A 200 the load never finished under must fail like any other load failure."""
studio_mod = _load_run_command()
monkeypatch.setattr(studio_mod, "_direct_urlopen", lambda request, timeout: BytesIO(body))
with pytest.raises(RuntimeError) as excinfo:
studio_mod._load_model_via_http(
port = 8888,
api_key = "sk-test",
model = "owner/model-GGUF",
gguf_variant = None,
max_seq_length = 0,
load_in_4bit = True,
)
assert "did not report completion" in str(excinfo.value)
def test_reexec_mixed_parallel_with_passthrough(monkeypatch):
"""--parallel + llama-server pass-through flags must all reach the child."""
result, captured = _invoke_run(
monkeypatch,
# --top-k is a first-class sampling flag now; --seed / --temp still pass through.
_BASE + ["--parallel", "8", "--seed", "42", "--temp", "0.7"],
)
assert len(captured) == 1
argv = captured[0]["argv"]
assert _value_after(argv, "--parallel") == "8", argv
assert _value_after(argv, "--seed") == "42", argv
assert _value_after(argv, "--temp") == "0.7", argv
def test_context_length_banner_line_formats_ints():
studio_mod = _load_run_command()
assert studio_mod._format_context_length_line({"context_length": 4096}) == (
" Context length: 4096 tokens"
)
assert studio_mod._format_context_length_line({"context_length": "8192"}) == (
" Context length: 8192 tokens"
)
@pytest.mark.parametrize("value", [None, 0, -1, True, ""])
def test_context_length_banner_line_omits_unknown_values(value):
studio_mod = _load_run_command()
assert studio_mod._format_context_length_line({"context_length": value}) is None
@pytest.mark.parametrize(
"user_flag,expected_in_child",
[
("--load-in-4bit", "--load-in-4bit"),
("--no-load-in-4bit", "--no-load-in-4bit"),
(None, "--load-in-4bit"),
],
)
def test_reexec_forwards_load_in_4bit_in_both_directions(monkeypatch, user_flag, expected_in_child):
"""Re-exec must forward the chosen polarity or the typer default, so a default flip on one layer
cannot silently invert behaviour for users who never typed the flag."""
extras = [user_flag] if user_flag else []
result, captured = _invoke_run(monkeypatch, _BASE + extras)
assert len(captured) == 1
argv = captured[0]["argv"]
other_polarity = (
"--no-load-in-4bit" if expected_in_child == "--load-in-4bit" else "--load-in-4bit"
)
assert expected_in_child in argv, f"expected {expected_in_child} in child argv; got {argv}"
assert other_polarity not in argv, f"unexpected {other_polarity} in child argv; got {argv}"
class _RunServerCaptured(SystemExit):
def __init__(self, kwargs):
super().__init__(0)
self.kwargs = dict(kwargs)
def _types_module(name):
import types as _types
return _types.ModuleType(name)
def test_studio_default_rejects_parallel_when_subcommand_invoked():
"""`unsloth studio --parallel 8 run ...` would silently drop the 8
(typer doesn't forward parent options to subcommands). The
callback rejects with exit 2 and points at the subcommand flag."""
studio_mod = _load_run_command()
import typer as _typer
app = _typer.Typer()
app.add_typer(studio_mod.studio_app, name = "studio")
runner = CliRunner()
result = runner.invoke(app, ["studio", "--parallel", "8", "run", "--model", "X"])
assert result.exit_code == 2, (
f"expected exit 2 when --parallel is on studio group with a "
f"subcommand invoked; got {result.exit_code}; output={result.output!r}"
)
combined = (result.output or "") + (getattr(result, "stderr", "") or "")
assert "--parallel" in combined, combined
assert (
"run --parallel 8" in combined
), f"error message must show the corrected invocation; got: {combined}"
def test_studio_default_rejects_api_only_when_subcommand_invoked():
"""`unsloth studio --api-only run ...` would silently serve the UI (the
parent's --api-only never reaches run). The callback rejects with exit 2
and points at the subcommand flag."""
studio_mod = _load_run_command()
import typer as _typer
app = _typer.Typer()
app.add_typer(studio_mod.studio_app, name = "studio")
runner = CliRunner()
result = runner.invoke(app, ["studio", "--api-only", "run", "--model", "X"])
assert result.exit_code == 2, (
f"expected exit 2 when --api-only is on studio group with a "
f"subcommand invoked; got {result.exit_code}; output={result.output!r}"
)
combined = (result.output or "") + (getattr(result, "stderr", "") or "")
assert "--api-only" in combined, combined
assert (
"run --api-only" in combined
), f"error message must show the corrected invocation; got: {combined}"
def test_studio_default_default_parallel_with_subcommand_does_not_error():
"""Omitting --parallel on the group must not block subcommands; its default 1 is benign."""
studio_mod = _load_run_command()
import typer as _typer
app = _typer.Typer()
app.add_typer(studio_mod.studio_app, name = "studio")
runner = CliRunner()
result = runner.invoke(app, ["studio", "--help"])
assert result.exit_code == 0, result.output
def test_studio_default_exposes_parallel_option():
"""Plain `unsloth studio` exposes --parallel too so the API-only
path can raise concurrency without going through the denied
pass-through. Default stays at 1 (pre-PR); `run` keeps its 4."""
studio_mod = _load_run_command()
import inspect
sig = inspect.signature(studio_mod.studio_default)
assert (
"parallel" in sig.parameters
), "studio_default missing `parallel`; API-only path can't set llama_parallel_slots"
opt = sig.parameters["parallel"].default
decls = set(getattr(opt, "param_decls", []) or [])
assert "--parallel" in decls
assert "--n-parallel" in decls
assert (
getattr(opt, "default", None) == studio_mod._PARALLEL_DEFAULT_PLAIN
), "studio_default --parallel must use _PARALLEL_DEFAULT_PLAIN"
assert getattr(opt, "min", None) == 1
assert getattr(opt, "max", None) == 64
@pytest.mark.parametrize("value", [1, 4, 8, 64])
def test_in_venv_path_passes_parallel_to_run_server(
monkeypatch, tmp_path, value, stub_tool_policy_state
):
"""In-venv path must forward --parallel to
run_server(llama_parallel_slots=N), not the old hardcoded 4."""
studio_mod = _load_run_command()
# A real directory: the launch gate creates STUDIO_HOME and locks inside it.
fake_venv = tmp_path / "studio" / "venv" / "unsloth_studio"
monkeypatch.setattr(sys, "prefix", str(fake_venv))
# Pin STUDIO_HOME so sys.prefix.startswith() picks the in-venv branch.
monkeypatch.setattr(studio_mod, "STUDIO_HOME", fake_venv.parent)
from unsloth_cli import _tool_policy as _tp_mod
monkeypatch.setattr(
_tp_mod,
"resolve_tool_policy",
lambda host, flag, yes, silent: False if flag is None else bool(flag),
)
captured: dict = {}
def fake_run_server(**kwargs):
captured.update(kwargs)
raise _RunServerCaptured(kwargs)
fake_backend_run = sys.modules.setdefault(
"studio.backend.run", _types_module("studio.backend.run")
)
fake_backend_run.run_server = fake_run_server
fake_backend_run._resolve_external_ip = lambda: "127.0.0.1"
# run() loads the backend by file path; inject the mock as the cached run module.
monkeypatch.setattr(studio_mod, "_RUN_MODULE", fake_backend_run)
import typer as _typer
app = _typer.Typer()
app.command(
context_settings = {
"allow_extra_args": True,
"ignore_unknown_options": True,
},
)(studio_mod.run)
CliRunner().invoke(app, _BASE + ["--parallel", str(value)], catch_exceptions = True)
assert (
captured.get("llama_parallel_slots") == value
), f"run_server got llama_parallel_slots={captured.get('llama_parallel_slots')!r}, expected {value}"
def test_api_only_option_is_registered():
studio_mod = _load_run_command()
import inspect
opt = inspect.signature(studio_mod.run).parameters["api_only"].default
assert "--api-only" in set(getattr(opt, "param_decls", []) or [])
assert getattr(opt, "default", None) is False
@pytest.mark.parametrize(
"extra,present",
[
(["--api-only"], True),
([], False),
],
)
def test_reexec_forwards_api_only(monkeypatch, extra, present):
"""`--api-only` (and only when typed) must reach the re-exec'd child."""
result, captured = _invoke_run(monkeypatch, _BASE + extra)
assert len(captured) == 1, result.output
argv = captured[0]["argv"]
assert ("--api-only" in argv) is present, argv
def test_secure_api_only_is_refused_before_any_reexec(monkeypatch, tmp_path):
"""`--secure --api-only` used to re-exec; the pre-exposure gate now refuses
it, because api-only has no login page and the bootstrap deadline does not
apply, so the seeded password could never be changed."""
studio_mod = _load_run_command()
monkeypatch.setattr(studio_mod, "STUDIO_HOME", tmp_path)
result, captured = _invoke_run(monkeypatch, _BASE + ["--secure", "--api-only"])
assert captured == [], captured
assert result.exit_code != 0
combined = (result.output or "") + (getattr(result, "stderr", "") or "")
assert "default admin password was never changed" in combined.lower()
@pytest.mark.parametrize("extra,expected", [(["--api-only"], True), ([], False)])
def test_in_venv_path_passes_api_only_to_run_server(
monkeypatch, tmp_path, extra, expected, stub_tool_policy_state
):
"""In-venv path must forward --api-only to run_server(api_only=...)."""
studio_mod = _load_run_command()
# A real directory: the launch gate creates STUDIO_HOME and locks inside it.
fake_venv = tmp_path / "studio" / "venv" / "unsloth_studio"
monkeypatch.setattr(sys, "prefix", str(fake_venv))
monkeypatch.setattr(studio_mod, "STUDIO_HOME", fake_venv.parent)
from unsloth_cli import _tool_policy as _tp_mod
monkeypatch.setattr(
_tp_mod,
"resolve_tool_policy",
lambda host, flag, yes, silent: False if flag is None else bool(flag),
)
captured: dict = {}
def fake_run_server(**kwargs):
captured.update(kwargs)
raise _RunServerCaptured(kwargs)
fake_backend_run = sys.modules.setdefault(
"studio.backend.run", _types_module("studio.backend.run")
)
fake_backend_run.run_server = fake_run_server
fake_backend_run._resolve_external_ip = lambda: "127.0.0.1"
monkeypatch.setattr(studio_mod, "_RUN_MODULE", fake_backend_run)
import typer as _typer
app = _typer.Typer()
app.command(
context_settings = {
"allow_extra_args": True,
"ignore_unknown_options": True,
},
)(studio_mod.run)
CliRunner().invoke(app, _BASE + extra, catch_exceptions = True)
assert (
captured.get("api_only") is expected
), f"run_server got api_only={captured.get('api_only')!r}, expected {expected}"
assert (
captured.get("emit_tauri_port") is False
), f"run_server got emit_tauri_port={captured.get('emit_tauri_port')!r}, expected False"