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.

12.0 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

"""Frontend-dist resolver in run.py, loaded via importlib so uvicorn and FastAPI are not imported."""

import ast
import importlib.util
import os
import sys
from pathlib import Path

import pytest

_RUN_PY = Path(__file__).resolve().parent.parent / "run.py"
_REPO_STUDIO_DIR = _RUN_PY.parent.parent


def _load_helpers_only():
    """Load only the resolver helpers from run.py, skipping uvicorn and structlog imports."""
    source = _RUN_PY.read_text(encoding = "utf-8")
    tree = ast.parse(source)
    keep = []
    wanted = {
        "_DEFAULT_FRONTEND_PATH",
        "_iter_frontend_fallback_candidates",
        "_resolve_frontend_path",
        "_frontend_serving_mode",
        "_missing_frontend_is_fatal",
    }
    for node in tree.body:
        if isinstance(node, (ast.Import, ast.ImportFrom)):
            keep.append(node)
        elif isinstance(node, ast.Assign):
            names = {t.id for t in node.targets if isinstance(t, ast.Name)}
            if names & wanted:
                keep.append(node)
        elif isinstance(node, ast.FunctionDef) and node.name in wanted:
            keep.append(node)
    module = ast.Module(body = keep, type_ignores = [])
    code = compile(module, str(_RUN_PY), "exec")
    ns: dict = {"__file__": str(_RUN_PY), "__name__": "_run_helpers_test"}
    exec(code, ns)
    return ns


def test_frontend_serving_mode_is_tunnel_only_for_desktop_api_only():
    mode = _load_helpers_only()["_frontend_serving_mode"]
    assert mode(api_only = False, desktop_owned = False) == (True, False)
    assert mode(api_only = True, desktop_owned = False) == (False, False)
    assert mode(api_only = True, desktop_owned = True) == (True, True)


def test_resolver_returns_none_when_nothing_exists(tmp_path, monkeypatch):
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "no_studio"))
    monkeypatch.delenv("STUDIO_HOME", raising = False)
    helpers = _load_helpers_only()
    chosen, attempted = helpers["_resolve_frontend_path"](tmp_path / "missing")
    assert chosen is None
    assert attempted == [tmp_path / "missing"]


def test_resolver_picks_first_existing_candidate(tmp_path, monkeypatch):
    dist = tmp_path / "good" / "frontend" / "dist"
    dist.mkdir(parents = True)
    (dist / "index.html").write_text("<!doctype html>", encoding = "utf-8")
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "no_studio"))
    monkeypatch.delenv("STUDIO_HOME", raising = False)
    helpers = _load_helpers_only()
    chosen, attempted = helpers["_resolve_frontend_path"](dist)
    assert chosen == dist
    assert attempted[-1] == dist


def test_resolver_falls_back_to_studio_home_site_packages(tmp_path, monkeypatch):
    studio_home = tmp_path / "studio_home"
    sp_dist = (
        studio_home
        / "unsloth_studio"
        / "lib"
        / "python3.13"
        / "site-packages"
        / "studio"
        / "frontend"
        / "dist"
    )
    sp_dist.mkdir(parents = True)
    (sp_dist / "index.html").write_text("<!doctype html>", encoding = "utf-8")
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio_home))
    monkeypatch.delenv("STUDIO_HOME", raising = False)
    helpers = _load_helpers_only()
    chosen, attempted = helpers["_resolve_frontend_path"](tmp_path / "bogus")
    assert chosen is not None
    assert chosen.resolve() == sp_dist.resolve()
    assert (tmp_path / "bogus") in attempted


def test_resolver_falls_back_via_editable_pth(tmp_path, monkeypatch):
    """Simulates --local: a venv whose editable .pth points at a clone owning the built dist."""
    studio_home = tmp_path / "studio_home"
    sp = studio_home / "unsloth_studio" / "lib" / "python3.13" / "site-packages"
    sp.mkdir(parents = True)
    repo_root = tmp_path / "clone"
    repo_studio = repo_root / "studio"
    repo_dist = repo_studio / "frontend" / "dist"
    repo_dist.mkdir(parents = True)
    (repo_dist / "index.html").write_text("<!doctype html>", encoding = "utf-8")
    # mimics the MAPPING dict setuptools' editable install generator writes
    finder = sp / "__editable___unsloth_0_0_0_finder.py"
    finder.write_text(
        "MAPPING: dict[str, str] = "
        f"{{'studio': {str(repo_studio)!r}, 'unsloth': '/x', 'unsloth_cli': '/y'}}\n",
        encoding = "utf-8",
    )
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio_home))
    monkeypatch.delenv("STUDIO_HOME", raising = False)
    helpers = _load_helpers_only()
    chosen, attempted = helpers["_resolve_frontend_path"](tmp_path / "bogus")
    assert chosen is not None
    assert chosen.resolve() == repo_dist.resolve()


def test_iter_candidates_handles_missing_studio_home(tmp_path, monkeypatch):
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "nonexistent"))
    monkeypatch.delenv("STUDIO_HOME", raising = False)
    helpers = _load_helpers_only()
    candidates = helpers["_iter_frontend_fallback_candidates"]()
    assert candidates == []


def test_resolver_falls_back_to_windows_layout_site_packages(tmp_path, monkeypatch):
    """Pins the `Lib/site-packages` (capital L) Windows venv layout
    alongside the POSIX `lib/python*/site-packages`."""
    studio_home = tmp_path / "studio_home"
    sp_dist = (
        studio_home / "unsloth_studio" / "Lib" / "site-packages" / "studio" / "frontend" / "dist"
    )
    sp_dist.mkdir(parents = True)
    (sp_dist / "index.html").write_text("<!doctype html>", encoding = "utf-8")
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio_home))
    monkeypatch.delenv("STUDIO_HOME", raising = False)
    helpers = _load_helpers_only()
    chosen, _ = helpers["_resolve_frontend_path"](tmp_path / "bogus")
    assert chosen is not None
    assert chosen.resolve() == sp_dist.resolve()


def test_resolver_does_not_crash_on_non_dict_mapping_literal(tmp_path, monkeypatch):
    """A non-dict MAPPING literal (a set or list parsed by literal_eval) must not raise
    AttributeError; the resolver skips it and keeps probing."""
    studio_home = tmp_path / "studio_home"
    sp = studio_home / "unsloth_studio" / "lib" / "python3.13" / "site-packages"
    sp.mkdir(parents = True)
    # a set literal: literal_eval parses it, but .get() on it would raise
    (sp / "__editable___bad_0_0_0_finder.py").write_text(
        "MAPPING: dict[str, str] = {'studio', 'unsloth', 'unsloth_cli'}\n",
        encoding = "utf-8",
    )
    repo_root = tmp_path / "clone"
    repo_dist = repo_root / "studio" / "frontend" / "dist"
    repo_dist.mkdir(parents = True)
    (repo_dist / "index.html").write_text("<!doctype html>", encoding = "utf-8")
    (sp / "__editable___good_0_0_0_finder.py").write_text(
        f"MAPPING: dict[str, str] = {{'studio': {str(repo_root / 'studio')!r}}}\n",
        encoding = "utf-8",
    )
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio_home))
    monkeypatch.delenv("STUDIO_HOME", raising = False)
    helpers = _load_helpers_only()
    chosen, _ = helpers["_resolve_frontend_path"](tmp_path / "bogus")
    assert chosen is not None
    assert chosen.resolve() == repo_dist.resolve()


def test_resolver_handles_multiline_mapping_dict(tmp_path, monkeypatch):
    """Multi-line MAPPING dicts must parse, since the regex uses [^}]* with re.DOTALL."""
    studio_home = tmp_path / "studio_home"
    sp = studio_home / "unsloth_studio" / "lib" / "python3.13" / "site-packages"
    sp.mkdir(parents = True)
    repo_root = tmp_path / "clone"
    repo_studio = repo_root / "studio"
    repo_dist = repo_studio / "frontend" / "dist"
    repo_dist.mkdir(parents = True)
    (repo_dist / "index.html").write_text("<!doctype html>", encoding = "utf-8")
    finder = sp / "__editable___unsloth_0_0_0_finder.py"
    finder.write_text(
        "MAPPING: dict[str, str] = {\n"
        f"    'studio': {str(repo_studio)!r},\n"
        "    'unsloth': '/x',\n"
        "    'unsloth_cli': '/y',\n"
        "}\n",
        encoding = "utf-8",
    )
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio_home))
    monkeypatch.delenv("STUDIO_HOME", raising = False)
    helpers = _load_helpers_only()
    chosen, _ = helpers["_resolve_frontend_path"](tmp_path / "bogus")
    assert chosen is not None
    assert chosen.resolve() == repo_dist.resolve()


def test_systemexit_message_contains_actionable_fixes(tmp_path, monkeypatch):
    """The user-facing recovery message is a contract: it must list the attempted paths and every
    concrete fix, so refactors cannot drop one."""
    import os
    import sys

    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "no_studio"))
    monkeypatch.delenv("STUDIO_HOME", raising = False)
    helpers = _load_helpers_only()
    bogus = tmp_path / "no_such_dist"
    _, attempted = helpers["_resolve_frontend_path"](bogus)
    home = Path(os.environ["UNSLOTH_STUDIO_HOME"]).expanduser()
    if sys.platform == "win32":
        installer_bin = home / "bin" / "unsloth.exe"
    else:
        installer_bin = home / "unsloth_studio" / "bin" / "unsloth"
    tried_lines = "\n".join(f"  - {p}" for p in attempted)
    message = (
        "[ERROR] Unsloth frontend build not found.\n"
        f"Tried:\n{tried_lines}\n"
        "\n"
        "Likely cause: another 'unsloth' on PATH is shadowing the "
        "installer's binary and points at a site-packages tree with "
        "no built dist.\n"
        "\n"
        "Fix one of:\n"
        f"  - run the installer's binary directly: {installer_bin} studio\n"
        "  - pass --frontend <path/to/studio/frontend/dist>\n"
        "  - pass --api-only to skip serving the web UI\n"
        "  - reinstall: curl -fsSL https://unsloth.ai/install.sh | sh"
    )
    assert str(bogus) in message
    assert "--frontend" in message
    assert "--api-only" in message
    assert "reinstall" in message
    assert "installer's binary directly" in message
    assert str(installer_bin) in message


def _run_frontend_mount(*, tunnel_only, resolves):
    """Slices the frontend-mount if out of run.py, so the abort-or-degrade branch runs for real."""
    import logging

    tree = ast.parse(_RUN_PY.read_text(encoding = "utf-8"))
    run_server = next(
        n for n in tree.body if isinstance(n, ast.FunctionDef) and n.name == "run_server"
    )
    block = next(
        n
        for n in run_server.body
        if isinstance(n, ast.If)
        and isinstance(n.test, ast.BoolOp)
        and any(isinstance(v, ast.Name) and v.id == "_serve_frontend" for v in n.test.values)
    )
    code = compile(ast.Module(body = [block], type_ignores = []), str(_RUN_PY), "exec")
    mounted = []
    ns = {
        "frontend_path": Path("/nonexistent/studio/frontend/dist"),
        "_serve_frontend": True,
        "_tunnel_only_frontend": tunnel_only,
        "_resolve_frontend_path": lambda p: (Path("/dist"), [p]) if resolves else (None, [p]),
        "setup_frontend": lambda app, chosen, *, tunnel_only: (
            mounted.append((chosen, tunnel_only)) or True
        ),
        "_missing_frontend_is_fatal": _load_helpers_only()["_missing_frontend_is_fatal"],
        "app": object(),
        "silent": True,
        "logger": logging.getLogger("test_frontend_resolution"),
        "Path": Path,
        "os": os,
        "sys": sys,
    }
    exec(code, ns)
    return mounted


def test_missing_frontend_is_fatal_everywhere_but_the_desktop_tunnel_path():
    fatal = _load_helpers_only()["_missing_frontend_is_fatal"]
    assert fatal(tunnel_only = False) is True
    assert fatal(tunnel_only = True) is False


def test_desktop_api_only_backend_starts_without_a_packaged_dist():
    """The desktop spawns `studio --api-only` with no --frontend, and its
    installer skips the frontend build, so a missing dist must not abort."""
    assert _run_frontend_mount(tunnel_only = True, resolves = False) == []


def test_a_missing_dist_still_aborts_a_web_ui_launch():
    with pytest.raises(SystemExit, match = "frontend build not found"):
        _run_frontend_mount(tunnel_only = False, resolves = False)


def test_a_desktop_dist_is_still_mounted_behind_the_tunnel_gate():
    assert _run_frontend_mount(tunnel_only = True, resolves = True) == [(Path("/dist"), True)]