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.

36.3 KB
Raw Blame
# 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"