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
"""A wheel missing studio reports null silently, and a payload change blocks desktop launch."""
import importlib.util
import json
import os
import pathlib
import re
import subprocess
import sys
import time
import typing
from pathlib import Path
import pytest
PACKAGE_ROOT = Path(__file__).resolve().parents[3]
MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
SPEC = importlib.util.spec_from_file_location("studio_install_llama_prebuilt", MODULE_PATH)
assert SPEC is not None and SPEC.loader is not None
ILP = importlib.util.module_from_spec(SPEC)
sys.modules[SPEC.name] = ILP
SPEC.loader.exec_module(ILP)
MANAGED_RS = PACKAGE_ROOT / "studio" / "src-tauri" / "src" / "preflight" / "managed.rs"
# Spelled out rather than derived from the command's dict, which could not notice a dropped key.
PRE_PR_KEYS: dict[str, type | tuple[type, ...]] = {
"desktop_protocol_version": int,
"desktop_manageability_version": int,
"supports_provision_desktop_auth": bool,
"supports_api_only": bool,
"supports_desktop_backend_ownership": bool,
"studio_install_ok": bool,
"studio_install_reason": str,
"version": str,
}
NEW_KEYS = ("llama_runtime_ok", "llama_runtime_reason")
# Bumping either tells older desktops the protocol changed; additive keys must not.
EXPECTED_PROTOCOL_VERSION = 1
EXPECTED_MANAGEABILITY_VERSION = 2
def _venv_python() -> Path | None:
"""The interpreter of the prepared venv, or None when it was never built."""
override = os.environ.get("UNSLOTH_DESKTOP_CAP_VENV")
root = (
Path(override).expanduser()
if override
else Path(os.environ.get("UNSLOTH_WORKSPACE") or PACKAGE_ROOT.parent)
/ "temp"
/ "venv_desktop_cap"
)
for candidate in (root / "bin" / "python", root / "Scripts" / "python.exe"):
if candidate.is_file():
return candidate
return None
VENV_PYTHON = _venv_python()
NEEDS_VENV = pytest.mark.skipif(
VENV_PYTHON is None,
reason = "no prepared venv with the CLI installed; see this module's docstring",
)
def _console_script() -> Path:
assert VENV_PYTHON is not None
name = "unsloth.exe" if os.name == "nt" else "unsloth"
return VENV_PYTHON.parent / name
def _capabilities(
install_dir: Path,
tmp_path: Path,
*,
json_output: bool = True,
):
"""Runs the installed CLI outside the checkout, with Studio and llama.cpp paths pointed at fixtures."""
env = dict(os.environ)
env["UNSLOTH_LLAMA_CPP_PATH"] = str(install_dir)
env["UNSLOTH_STUDIO_HOME"] = str(tmp_path / "studio_home")
# cwd matters: from the checkout `studio` would resolve to the source tree, not site-packages.
args = [str(_console_script()), "studio", "desktop-capabilities"]
if json_output:
args.append("--json")
result = subprocess.run(
args,
cwd = str(tmp_path),
env = env,
capture_output = True,
text = True,
timeout = 120,
)
return result.returncode, result.stdout
def _shared_health_groups() -> list[list[str]]:
"""Runtime file groups every install kind on this platform shares, read from the health tables."""
host = ILP.platform_only_host()
prefix = "windows-" if host.is_windows else "macos-" if host.is_macos else "linux-"
kinds = sorted(k for k in ILP.INSTALL_KIND_BACKENDS if k.startswith(prefix))
assert kinds, f"no install kinds for {prefix!r}"
shared = set.intersection(
*(
{
tuple(group)
for group in ILP.runtime_payload_health_groups(
kind,
source_label = None,
runtime_name = None,
tag = "b10830",
)
}
for kind in kinds
)
)
assert shared, "the shared payload must not be empty, or 'complete' means nothing"
return [list(group) for group in sorted(shared)]
def _complete_tree(root: Path) -> Path:
"""Empty files suffice: installed_runtime_health only looks and never executes."""
host = ILP.platform_only_host()
runtime_dir = ILP.install_runtime_dir(root, host)
runtime_dir.mkdir(parents = True, exist_ok = True)
(root / "UNSLOTH_PREBUILT_INFO.json").write_text(
json.dumps({"release_tag": "b10830-mix-d5c17a0", "tag": "b10830"}) + "\n",
encoding = "utf-8",
)
for group in _shared_health_groups():
(runtime_dir / group[0].replace("*", "")).write_text("x", encoding = "utf-8")
ext = ".exe" if host.is_windows else ""
for name in ("server", "quantize"):
(runtime_dir / f"llama-{name}{ext}").write_text("x", encoding = "utf-8")
return runtime_dir
def _assert_pre_pr_payload_intact(payload: dict) -> None:
"""Every key an older desktop already reads, still present and still its old type."""
for key, expected in PRE_PR_KEYS.items():
assert key in payload, f"{key} disappeared from the capability payload"
# bool subclasses int, so an int field must not accept a bool.
if expected is int:
assert isinstance(payload[key], int) and not isinstance(
payload[key], bool
), f"{key} is {payload[key]!r}, not an int"
else:
assert isinstance(payload[key], expected), f"{key} is {payload[key]!r}"
assert payload["desktop_protocol_version"] == EXPECTED_PROTOCOL_VERSION
assert payload["desktop_manageability_version"] == EXPECTED_MANAGEABILITY_VERSION
@NEEDS_VENV
def test_studio_is_importable_from_an_installed_wheel():
"""The whole feature hangs off this import succeeding outside a source checkout.
``desktop_capabilities`` swallows every probe exception, so a ``studio`` package
missing from the wheel would report null for every user with no error. Run from a cwd
that is not the checkout, or the tree beside the tests answers instead.
"""
assert VENV_PYTHON is not None
probe = (
"import studio.install_llama_prebuilt as m; "
"print(m.__file__); print(callable(m.installed_runtime_health))"
)
result = subprocess.run(
[str(VENV_PYTHON), "-c", probe],
cwd = str(VENV_PYTHON.parent),
capture_output = True,
text = True,
timeout = 120,
)
assert result.returncode == 0, result.stderr
module_file, callable_flag = result.stdout.strip().splitlines()
assert callable_flag == "True"
assert (
"site-packages" in module_file
), f"resolved to {module_file}, not the installed package; the checkout shadowed it"
@NEEDS_VENV
def test_nothing_installed_reports_null_rather_than_false(tmp_path):
"""The desktop repairs on an explicit false, so NotInstalled must not report one."""
empty = tmp_path / "empty"
empty.mkdir()
rc, out = _capabilities(empty, tmp_path)
assert rc == 0
payload = json.loads(out)
assert payload["llama_runtime_ok"] is None
assert payload["llama_runtime_reason"] == ""
_assert_pre_pr_payload_intact(payload)
@NEEDS_VENV
def test_a_complete_tree_reports_true_with_an_empty_reason(tmp_path):
root = tmp_path / "llama.cpp"
_complete_tree(root)
rc, out = _capabilities(root, tmp_path)
assert rc == 0
payload = json.loads(out)
assert payload["llama_runtime_ok"] is True
assert payload["llama_runtime_reason"] == ""
_assert_pre_pr_payload_intact(payload)
@NEEDS_VENV
def test_a_quarantined_library_reports_false_with_a_reason(tmp_path):
"""The shape antivirus leaves behind; the reason string is what the desktop shows."""
root = tmp_path / "llama.cpp"
runtime_dir = _complete_tree(root)
victim = sorted(
path
for path in runtime_dir.iterdir()
if not path.name.startswith("llama-server") and not path.name.startswith("llama-quantize")
)[0]
victim.unlink()
rc, out = _capabilities(root, tmp_path)
assert rc == 0
payload = json.loads(out)
assert payload["llama_runtime_ok"] is False
assert payload["llama_runtime_reason"], "a false verdict with no reason tells nobody anything"
_assert_pre_pr_payload_intact(payload)
@NEEDS_VENV
def test_a_missing_llama_server_reports_binaries_missing(tmp_path):
"""The payload groups name libraries only, so on Linux and macOS a quarantined
llama-server would otherwise read as a complete install."""
root = tmp_path / "llama.cpp"
runtime_dir = _complete_tree(root)
ext = ".exe" if ILP.platform_only_host().is_windows else ""
(runtime_dir / f"llama-server{ext}").unlink()
rc, out = _capabilities(root, tmp_path)
assert rc == 0
payload = json.loads(out)
assert payload["llama_runtime_ok"] is False
assert payload["llama_runtime_reason"] == "llama_runtime_binaries_missing"
_assert_pre_pr_payload_intact(payload)
@NEEDS_VENV
def test_the_human_readable_form_still_prints_every_key(tmp_path):
"""The desktop reads --json; a support request pastes the bare form, same dict."""
root = tmp_path / "llama.cpp"
_complete_tree(root)
rc, out = _capabilities(root, tmp_path, json_output = False)
assert rc == 0
printed = {line.split(":", 1)[0] for line in out.splitlines() if ":" in line}
for key in (*PRE_PR_KEYS, *NEW_KEYS):
assert key in printed
@NEEDS_VENV
def test_the_probe_stays_off_the_critical_path_budget(tmp_path):
"""The command runs at every launch under a desktop timeout; the loose half-second bound on
import plus call catches a network or GPU probe, not CI jitter."""
assert VENV_PYTHON is not None
root = tmp_path / "llama.cpp"
_complete_tree(root)
script = (
"import json, time\n"
"import unsloth_cli.commands.studio\n"
"t0 = time.perf_counter()\n"
"from studio.install_llama_prebuilt import installed_runtime_health\n"
"t1 = time.perf_counter()\n"
"health = installed_runtime_health()\n"
"t2 = time.perf_counter()\n"
"print(json.dumps({'import': t1 - t0, 'call': t2 - t1, 'health': health}))\n"
)
env = dict(os.environ)
env["UNSLOTH_LLAMA_CPP_PATH"] = str(root)
env["UNSLOTH_STUDIO_HOME"] = str(tmp_path / "studio_home")
started = time.perf_counter()
result = subprocess.run(
[str(VENV_PYTHON), "-c", script],
cwd = str(tmp_path),
env = env,
capture_output = True,
text = True,
timeout = 120,
)
assert result.returncode == 0, result.stderr
measured = json.loads(result.stdout)
assert measured["health"] == [True, ""]
total = measured["import"] + measured["call"]
assert total < 0.5, f"the probe added {total:.3f}s to every launch"
assert time.perf_counter() - started < 120
@NEEDS_VENV
def test_an_unimportable_probe_leaves_the_verdict_null(tmp_path):
"""The ``except Exception`` arm, exercised rather than read.
A denied tree, a corrupt marker or a missing ``studio`` package must all land on null
with the rest of the payload unchanged. ImportError is the one that would hit every
user at once, so it is the one simulated: a meta_path hook refusing the module while a
complete tree, which would otherwise answer true, sits on disk.
"""
assert VENV_PYTHON is not None
root = tmp_path / "llama.cpp"
_complete_tree(root)
driver = tmp_path / "blocked.py"
driver.write_text(
"import sys\n"
"class _Blocker:\n"
" def find_spec(self, name, path = None, target = None):\n"
" if name == 'studio.install_llama_prebuilt':\n"
" raise ImportError('simulated: studio not shipped')\n"
" return None\n"
"sys.meta_path.insert(0, _Blocker())\n"
"from unsloth_cli import app\n"
"sys.argv = ['unsloth', 'studio', 'desktop-capabilities', '--json']\n"
"app()\n",
encoding = "utf-8",
)
env = dict(os.environ)
env["UNSLOTH_LLAMA_CPP_PATH"] = str(root)
env["UNSLOTH_STUDIO_HOME"] = str(tmp_path / "studio_home")
result = subprocess.run(
[str(VENV_PYTHON), str(driver)],
cwd = str(tmp_path),
env = env,
capture_output = True,
text = True,
timeout = 120,
)
assert result.returncode == 0, result.stderr
payload = json.loads(result.stdout)
assert payload["llama_runtime_ok"] is None
assert payload["llama_runtime_reason"] == ""
_assert_pre_pr_payload_intact(payload)
def test_the_command_emits_exactly_the_pre_pr_keys_plus_the_two_new_ones():
"""Read off the source so it holds without the venv: a key added without a matching Option<T> in
managed.rs is invisible to the desktop, and a removed key breaks it."""
source = (PACKAGE_ROOT / "unsloth_cli" / "commands" / "studio.py").read_text(encoding = "utf-8")
body = source.split("def desktop_capabilities(", 1)[1]
body = body.split("if json_output:", 1)[0]
emitted = set(re.findall(r'^\s+"([a-z_]+)":', body, flags = re.MULTILINE))
emitted |= set(re.findall(r'payload\["([a-z_]+)"\]', body))
assert emitted == set(PRE_PR_KEYS) | set(NEW_KEYS), sorted(emitted)
@NEEDS_VENV
def test_dropping_the_new_keys_yields_the_pre_pr_payload(tmp_path):
"""Additive, proven by subtraction: without the two new keys the payload is what the pre-PR
desktop accepts; neither version constant may move or the CLI reads as stale."""
root = tmp_path / "llama.cpp"
_complete_tree(root)
rc, out = _capabilities(root, tmp_path)
assert rc == 0
payload = json.loads(out)
stripped = {key: value for key, value in payload.items() if key not in NEW_KEYS}
assert set(stripped) == set(PRE_PR_KEYS)
_assert_pre_pr_payload_intact(stripped)
def test_the_desktop_reads_every_emitted_key_as_optional():
"""A desktop must survive a pre-PR CLI sending neither new key: serde maps an absent field to
None and managed.rs only flags Some(false), so every field must stay an Option."""
source = MANAGED_RS.read_text(encoding = "utf-8")
struct_body = source.split("struct DesktopCapability {", 1)[1].split("\n}", 1)[0]
fields = dict(re.findall(r"^\s+([a-z_]+):\s*(.+),$", struct_body, flags = re.MULTILINE))
for key in (*PRE_PR_KEYS, *NEW_KEYS):
assert key in fields, f"the desktop struct has no field for {key}"
assert fields[key].startswith(
"Option<"
), f"{key} is {fields[key]}, so a CLI that omits it fails the whole parse"
def test_unknown_keys_do_not_break_the_desktop_parse():
"""Keeps the desktop parse tolerant: the capability struct must never gain deny_unknown_fields."""
source = MANAGED_RS.read_text(encoding = "utf-8")
assert "deny_unknown_fields" not in source
prologue = source.split("struct DesktopCapability {", 1)[0]
assert "deny_unknown_fields" not in prologue.rsplit("#[derive", 1)[-1]
def test_unknown_keys_do_not_break_the_cli_side_consumer():
"""The CI probe reads named keys only, so extra keys in the payload must stay inert."""
probe = PACKAGE_ROOT / ".github" / "scripts" / "interrupted_install_probe.py"
if not probe.is_file():
pytest.skip("CI probe script not present in this tree")
source = probe.read_text(encoding = "utf-8")
assert 'parsed.get("studio_install_ok")' in source
assert not re.search(r"set\(parsed", source)
payload = {key: ("" if kind is str else kind()) for key, kind in PRE_PR_KEYS.items()}
payload["studio_install_ok"] = True
payload.update({key: None for key in NEW_KEYS})
payload["some_future_key"] = {"nested": [1, 2, 3]}
payload["another_future_key"] = "ignored"
parsed = json.loads(json.dumps(payload))
assert isinstance(parsed, dict)
value = parsed.get("studio_install_ok")
assert isinstance(value, bool) and value is True
def test_the_managed_probe_is_skipped_when_a_custom_runtime_is_active(monkeypatch):
"""Skip the managed probe under a user's own runtime; the backend would never open that tree."""
active = _active_helper()
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
assert active() is True
pinned = pathlib.Path(__file__).resolve().parents[3] / "studio" / "install_llama_prebuilt.py"
monkeypatch.setenv("LLAMA_SERVER_PATH", str(pinned))
assert active() is False
monkeypatch.setenv("LLAMA_SERVER_PATH", " ")
assert active() is True
def test_the_managed_runtime_path_override_is_not_treated_as_a_custom_runtime(monkeypatch):
"""UNSLOTH_LLAMA_CPP_PATH moves the managed root itself, so default_managed_llama_dir
already grades exactly the tree that variable names. Skipping on it would drop the
coverage for every user who relocated their install."""
active = _active_helper()
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", "/opt/relocated/llama.cpp")
assert active() is True
def _helper_namespace(studio_home = None):
"""Reads the helper block from the CLI source, since importing the module pulls in typer."""
text = (
pathlib.Path(__file__).resolve().parents[3] / "unsloth_cli" / "commands" / "studio.py"
).read_text(encoding = "utf-8")
start = text.index("def _managed_llama_runtime_is_the_active_one")
end = text.index('@studio_app.command("desktop-capabilities"', start)
master_start = text.index("def _master_root_llama_dir")
master_end = text.index("def _ensure_studio_env_exported", master_start)
namespace = {
"os": __import__("os"),
"sys": __import__("sys"),
"Optional": typing.Optional,
"Path": pathlib.Path,
"_PACKAGE_ROOT": pathlib.Path(__file__).resolve().parents[3],
"STUDIO_HOME": pathlib.Path(studio_home)
if studio_home is not None
else pathlib.Path.home() / ".unsloth" / "studio",
"_STUDIO_HOME_IS_CUSTOM": studio_home is not None,
}
exec(compile(text[master_start:master_end], "<helper>", "exec"), namespace)
exec(compile(text[start:end], "<helper>", "exec"), namespace)
return namespace
def _active_helper():
return _helper_namespace()["_managed_llama_runtime_is_the_active_one"]
def test_an_inferred_studio_root_is_graded_not_the_legacy_tree(tmp_path, monkeypatch):
"""Grade the studio root inferred from sys.prefix; the desktop scrubs STUDIO_HOME before spawning."""
for name in (
"LLAMA_SERVER_PATH",
"UNSLOTH_LLAMA_CPP_PATH",
"UNSLOTH_STUDIO_HOME",
"STUDIO_HOME",
"UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH",
):
monkeypatch.delenv(name, raising = False)
root = tmp_path / "custom-studio"
graded = _helper_namespace(root)["_llama_runtime_to_grade"]()
assert graded == root / "llama.cpp"
assert "UNSLOTH_STUDIO_HOME" not in os.environ
def test_a_legacy_install_still_grades_the_legacy_tree(tmp_path, monkeypatch):
"""The other direction: nothing was inferred, so nothing is exported and the answer is
the tree every ordinary install has."""
for name in (
"LLAMA_SERVER_PATH",
"UNSLOTH_LLAMA_CPP_PATH",
"UNSLOTH_STUDIO_HOME",
"STUDIO_HOME",
"UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH",
):
monkeypatch.delenv(name, raising = False)
graded = _helper_namespace()["_llama_runtime_to_grade"]()
assert graded == pathlib.Path.home() / ".unsloth" / "llama.cpp"
def test_an_explicit_studio_home_is_left_alone(tmp_path, monkeypatch):
"""An ambient UNSLOTH_STUDIO_HOME is the user's, not an inference, and it must survive
the call unchanged rather than being replaced by the inferred root."""
for name in (
"LLAMA_SERVER_PATH",
"UNSLOTH_LLAMA_CPP_PATH",
"UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH",
"STUDIO_HOME",
):
monkeypatch.delenv(name, raising = False)
theirs = tmp_path / "theirs"
monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(theirs))
graded = _helper_namespace(tmp_path / "inferred")["_llama_runtime_to_grade"]()
assert graded == theirs / "llama.cpp"
assert os.environ["UNSLOTH_STUDIO_HOME"] == str(theirs)
def test_a_deleted_llama_server_path_does_not_suppress_the_managed_verdict(tmp_path, monkeypatch):
"""A deleted LLAMA_SERVER_PATH falls through to the managed tree, which must still be graded."""
active = _active_helper()
monkeypatch.setenv("LLAMA_SERVER_PATH", str(tmp_path / "gone" / "llama-server"))
assert active() is True
present = tmp_path / "llama-server"
present.write_text("", encoding = "utf-8")
monkeypatch.setenv("LLAMA_SERVER_PATH", str(present))
assert active() is False
def test_a_dangling_symlink_pin_falls_through_like_any_absent_pin(tmp_path, monkeypatch):
"""A dangling symlink pin is absent, so the finder falls through and the managed tree is graded."""
if os.name == "nt":
pytest.skip("POSIX symlink semantics")
active = _active_helper()
link = tmp_path / "pinned"
os.symlink(tmp_path / "never-existed", link)
assert os.path.lexists(link) and not link.is_file()
monkeypatch.setenv("LLAMA_SERVER_PATH", str(link))
assert active() is True
(tmp_path / "never-existed").write_text("", encoding = "utf-8")
assert active() is False
def test_a_user_set_runtime_override_is_not_ours_to_repair(tmp_path, monkeypatch):
"""A user's UNSLOTH_LLAMA_CPP_PATH override is not graded, since setup cannot repair that tree."""
active = _active_helper()
override = tmp_path / "relocated" / "llama.cpp"
server = (
override / "build" / "bin" / ("llama-server.exe" if os.name == "nt" else "llama-server")
)
server.parent.mkdir(parents = True)
server.write_text("x", encoding = "utf-8")
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(override))
_stub_stored_selection(monkeypatch, "/home/someone/older-build")
assert active() is False
_stub_stored_selection(monkeypatch, None)
assert active() is False
monkeypatch.setenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", "1")
assert active() is True
_stub_stored_selection(monkeypatch, "/home/someone/older-build")
assert active() is False
def test_the_cli_s_own_inferred_override_is_not_mistaken_for_a_user_pin(tmp_path, monkeypatch):
"""A CLI-inferred UNSLOTH_LLAMA_CPP_PATH is not a user pin, and the backend walks past it."""
active = _active_helper()
studio_home = tmp_path / "custom-studio"
managed = studio_home / "llama.cpp"
server = managed / "build" / "bin" / ("llama-server.exe" if os.name == "nt" else "llama-server")
server.parent.mkdir(parents = True)
server.write_text("", encoding = "utf-8")
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio_home))
monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(managed))
_stub_stored_selection(monkeypatch, "/home/someone/older-build")
assert active() is False, (
"the CLI's own inferred override names the managed tree, so the finder skips "
"it and the stored folder is what the backend opens"
)
elsewhere = tmp_path / "hand-built" / "llama.cpp"
pinned = (
elsewhere / "build" / "bin" / ("llama-server.exe" if os.name == "nt" else "llama-server")
)
pinned.parent.mkdir(parents = True)
pinned.write_text("x", encoding = "utf-8")
monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(elsewhere))
assert active() is False
_stub_stored_selection(monkeypatch, None)
assert active() is False
monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(managed))
assert active() is True
def test_a_master_root_grades_the_runtime_beside_studio_not_the_one_under_it(tmp_path, monkeypatch):
"""A master root grades llama.cpp beside studio/, not under it, to match the installer's export."""
active = _active_helper()
master = tmp_path / "portable"
managed = master / "llama.cpp"
server = managed / "build" / "bin" / ("llama-server.exe" if os.name == "nt" else "llama-server")
server.parent.mkdir(parents = True)
server.write_text("", encoding = "utf-8")
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
monkeypatch.setenv("UNSLOTH_HOME", str(master))
monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(master / "studio"))
monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(managed))
_stub_stored_selection(monkeypatch, None)
assert (
active() is True
), "the exported <master>/llama.cpp is the tree this install owns, so it is graded"
elsewhere = tmp_path / "hand-built" / "llama.cpp"
pinned = (
elsewhere / "build" / "bin" / ("llama-server.exe" if os.name == "nt" else "llama-server")
)
pinned.parent.mkdir(parents = True)
pinned.write_text("x", encoding = "utf-8")
monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(elsewhere))
assert active() is False
def test_the_master_root_rule_is_the_one_the_export_writes(tmp_path, monkeypatch):
"""One rule, not two that can drift: the value graded has to be the value exported."""
namespace = _helper_namespace()
master_dir = namespace["_master_root_llama_dir"]
monkeypatch.delenv("UNSLOTH_HOME", raising = False)
assert master_dir() is None, "no master root means the studio home decides, as before"
master = tmp_path / "portable"
monkeypatch.setenv("UNSLOTH_HOME", str(master))
assert master_dir() == master.resolve() / "llama.cpp"
monkeypatch.setenv("UNSLOTH_HOME", " ")
assert master_dir() is None
def test_an_override_that_holds_no_server_does_not_outrank_the_stored_folder(tmp_path, monkeypatch):
"""An override with no server yields to the stored folder, since the backend never loads it."""
active = _active_helper()
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(tmp_path / "never-installed"))
_stub_stored_selection(monkeypatch, "/home/someone/older-build")
assert active() is False, "the finder walks past an empty override to the stored folder"
_stub_stored_selection(monkeypatch, None)
assert active() is True
@pytest.mark.skipif(os.name == "nt", reason = "POSIX ~name expansion")
def test_an_override_naming_no_account_answers_instead_of_raising(tmp_path, monkeypatch):
"""Codex 3962938521, P2. Path.expanduser raises RuntimeError for a "~name" that resolves
to no account, which an override left in a service unit or a .env after a rename does, and
this doctor's whole job is to answer. Every other reader of the variable goes through
expanded_user_path, which hands an unresolvable name back unchanged, so the override then
reaches the search as an ordinary path, finds nothing, and the documented order continues."""
active = _active_helper()
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", "~no-such-account-9d3f/llama.cpp")
with pytest.raises(RuntimeError):
pathlib.Path("~no-such-account-9d3f/llama.cpp").expanduser()
_stub_stored_selection(monkeypatch, None)
assert active() is True, "an unexpandable override holds no server, so the search walks on"
def _stub_stored_selection(monkeypatch, selected):
"""The helper imports by name, so parent packages must be in sys.modules or real ones get pulled in."""
import types
for name in ("studio", "studio.backend", "studio.backend.utils"):
module = types.ModuleType(name)
module.__path__ = []
monkeypatch.setitem(sys.modules, name, module)
settings = types.ModuleType("studio.backend.utils.llama_cpp_path_settings")
settings.get_stored_custom_llama_cpp_path = lambda: selected
settings.llama_server_candidates = _real_llama_server_candidates
# The real reader: without it the guarded import failed and tests graded the fallback.
settings.expanded_user_path = lambda value: pathlib.Path(os.path.expanduser(str(value)))
monkeypatch.setitem(sys.modules, "studio.backend.utils.llama_cpp_path_settings", settings)
prebuilt = types.ModuleType("studio.install_llama_prebuilt")
prebuilt.default_managed_llama_dir = _managed_dir_rule
monkeypatch.setitem(sys.modules, "studio.install_llama_prebuilt", prebuilt)
def _managed_dir_rule():
"""Mirrors default_managed_llama_dir: override, then the custom studio home, then legacy root."""
override = (os.environ.get("UNSLOTH_LLAMA_CPP_PATH") or "").strip()
if override:
return pathlib.Path(override).expanduser()
home = (os.environ.get("UNSLOTH_STUDIO_HOME") or os.environ.get("STUDIO_HOME") or "").strip()
if home:
root = pathlib.Path(home).expanduser()
if root != pathlib.Path.home() / ".unsloth" / "studio":
return root / "llama.cpp"
return pathlib.Path.home() / ".unsloth" / "llama.cpp"
def _real_llama_server_candidates(directory):
"""The shipped layouts, read off llama_cpp_path_settings rather than retyped."""
root = pathlib.Path(directory)
name = "llama-server.exe" if sys.platform == "win32" else "llama-server"
candidates = [root / name, root / "build" / "bin" / name]
if sys.platform == "win32":
candidates.append(root / "build" / "bin" / "Release" / name)
return tuple(candidates)
def test_a_skipped_runtime_verdict_says_so_in_its_reason(monkeypatch):
"""A skipped verdict must name the skip in its reason, so the desktop does not cache it."""
source = (
pathlib.Path(__file__).resolve().parents[3] / "unsloth_cli" / "commands" / "studio.py"
).read_text(encoding = "utf-8")
body = source.split("def desktop_capabilities(", 1)[1].split("if json_output:", 1)[0]
assert 'payload["llama_runtime_reason"] = "llama_runtime_not_managed"' in body
assert 'payload["llama_runtime_reason"] = "llama_runtime_probe_failed"' in body
managed_rs = MANAGED_RS.read_text(encoding = "utf-8")
for reason in ("llama_runtime_not_managed", "llama_runtime_probe_failed"):
assert reason in managed_rs, "the desktop must know the reason the CLI emits"
def test_the_stored_settings_lookup_can_reach_its_own_database_module(monkeypatch):
"""The stored-folder lookup silently reads as absent unless studio/backend is on sys.path."""
import subprocess
import sys as _sys
root = pathlib.Path(__file__).resolve().parents[3]
without = subprocess.run(
[_sys.executable, "-c", "import storage.studio_db"],
cwd = root,
capture_output = True,
text = True,
)
assert without.returncode != 0, "storage must not already be importable from the repo root"
assert "No module named 'storage'" in without.stderr
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
_active_helper()()
assert str(root / "studio" / "backend") in _sys.path, (
"the helper must put the backend on the path itself, or the settings lookup "
"silently answers None and the skip never happens"
)
@pytest.mark.skipif(os.name == "nt", reason = "POSIX ~ expansion")
def test_the_finder_expands_the_override_the_way_every_other_reader_does(tmp_path, monkeypatch):
"""Codex 3960401528, P1. ``default_managed_llama_dir``, ``get_stored_custom_llama_cpp_path``
and the desktop's own pinning all expand UNSLOTH_LLAMA_CPP_PATH; the finder's
``Path(custom_llama_cpp)`` was the one literal read. A "~/llama.cpp" written into a
service unit, a .env or the Windows environment dialog reaches the process unexpanded, so
the finder searched a folder named ~ beside the working directory, walked past it and
loaded a different runtime than the probe graded and the desktop fingerprinted.
Driven against the real finder rather than read off the source: importing it costs about
a third of a second."""
backend_dir = PACKAGE_ROOT / "studio" / "backend"
if str(backend_dir) not in sys.path:
sys.path.insert(0, str(backend_dir))
from core.inference.llama_cpp import LlamaCppBackend
home = tmp_path / "home"
build = home / "llama.cpp" / "build" / "bin"
build.mkdir(parents = True)
server = build / "llama-server"
server.write_text("", encoding = "utf-8")
os.chmod(server, 0o755)
monkeypatch.setenv("HOME", str(home))
monkeypatch.setenv("USERPROFILE", str(home))
monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", "~/llama.cpp")
monkeypatch.chdir(tmp_path)
assert LlamaCppBackend._find_llama_server_binary() == str(server)