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.7 KB
Raw Blame
"""The converter pin is scoped to the conversion via internal_scripts_dir_pin, never left set."""

from __future__ import annotations

import ast
import contextlib
import os
import sys
import threading
import types
from pathlib import Path


SOURCE_PATH = (
    Path(__file__).resolve().parents[2] / "studio" / "backend" / "core" / "export" / "export.py"
)
SRC = SOURCE_PATH.read_text(encoding = "utf-8")
TREE = ast.parse(SRC)
SCRIPTS_DIR = "UNSLOTH_LLAMA_CPP_SCRIPTS_DIR"
CONVERTER_TAG = "UNSLOTH_LLAMA_CPP_CONVERTER_TAG"
PIN_HELPER = "_llama_cpp_scripts_pin"


def _module_level_assignments(tree: ast.Module):
    for node in tree.body:
        if isinstance(node, ast.Assign):
            for target in node.targets:
                if isinstance(target, ast.Name):
                    yield target.id, node.value


def _pin_helper_node(tree: ast.AST):
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef) and node.name == PIN_HELPER:
            return node
    return None


def _find_pin_try(tree: ast.AST):
    for node in ast.walk(tree):
        if not isinstance(node, ast.Try):
            continue
        for stmt in node.body:
            if (
                isinstance(stmt, ast.ImportFrom)
                and stmt.module == "unsloth_zoo.llama_cpp"
                and any(alias.name == "_resolve_local_convert_script" for alias in stmt.names)
            ):
                return node
    return None


# Anything still catching ImportError counts, so widening the handler does not break this.
_CATCHES_IMPORT_ERROR = ("ImportError", "Exception", "BaseException")


def _catches_import_error(handler: ast.ExceptHandler) -> bool:
    if handler.type is None:
        return True
    names = handler.type.elts if isinstance(handler.type, ast.Tuple) else [handler.type]
    return any(isinstance(n, ast.Name) and n.id in _CATCHES_IMPORT_ERROR for n in names)


# A half-built unsloth_zoo raises RuntimeError or AttributeError, not only ImportError.
_CATCHES_EVERYTHING = ("Exception", "BaseException")


def _covers_half_built_zoo(handler: ast.ExceptHandler) -> bool:
    if handler.type is None:
        return True
    names = handler.type.elts if isinstance(handler.type, ast.Tuple) else [handler.type]
    caught = {n.id for n in names if isinstance(n, ast.Name)}
    return bool(caught & set(_CATCHES_EVERYTHING)) or {"RuntimeError", "AttributeError"} <= caught


def _load_pin_helper(*, is_mlx = False, logger = None):
    """The real helper, executed on its own so these cases run the shipped code."""
    node = _pin_helper_node(TREE)
    assert node is not None, f"expected a {PIN_HELPER} helper in export.py"
    namespace = {
        "os": os,
        "contextlib": contextlib,
        "logger": logger
        if logger is not None
        else types.SimpleNamespace(warning = lambda *args, **kwargs: None),
        "_LLAMA_CPP_SCRIPTS_WARNING_EMITTED": False,
        "_IS_MLX": is_mlx,
    }
    exec(
        compile(ast.Module(body = [node], type_ignores = []), str(SOURCE_PATH), "exec"),
        namespace,
    )
    return namespace[PIN_HELPER], namespace


def _install_fake_zoo(
    monkeypatch,
    *,
    default_dir = "/fake/llama.cpp",
    resolver = True,
    internal_pin = True,
    incomplete = False,
):
    """A stand-in unsloth_zoo.llama_cpp whose pin is as non-reentrant as the real one."""
    calls = {"internal": []}
    fake = types.ModuleType("unsloth_zoo.llama_cpp")
    if default_dir is not None:
        fake.LLAMA_CPP_DEFAULT_DIR = default_dir
    if resolver:
        fake._resolve_local_convert_script = lambda *args, **kwargs: None
    fake._converter_dir_is_incomplete = lambda folder: incomplete
    held = threading.Lock()

    @contextlib.contextmanager
    def _internal_scripts_dir_pin(folder):
        if not held.acquire(blocking = False):
            raise RuntimeError("internal_scripts_dir_pin re-entered: the real one deadlocks here")
        calls["internal"].append(folder)
        existing = os.environ.get(SCRIPTS_DIR)
        if existing is None:
            os.environ[SCRIPTS_DIR] = folder
        try:
            yield
        finally:
            if existing is None:
                os.environ.pop(SCRIPTS_DIR, None)
            else:
                os.environ[SCRIPTS_DIR] = existing
            held.release()

    if internal_pin:
        fake.internal_scripts_dir_pin = _internal_scripts_dir_pin
    package = types.ModuleType("unsloth_zoo")
    monkeypatch.setitem(sys.modules, "unsloth_zoo", package)
    monkeypatch.setitem(sys.modules, "unsloth_zoo.llama_cpp", fake)
    monkeypatch.delenv(SCRIPTS_DIR, raising = False)
    monkeypatch.delenv(CONVERTER_TAG, raising = False)
    return fake, calls


def test_warning_flag_defined_at_module_scope():
    flags = {
        name: value
        for name, value in _module_level_assignments(TREE)
        if name == "_LLAMA_CPP_SCRIPTS_WARNING_EMITTED"
    }
    assert flags, "expected module-level _LLAMA_CPP_SCRIPTS_WARNING_EMITTED flag"
    init = flags["_LLAMA_CPP_SCRIPTS_WARNING_EMITTED"]
    assert isinstance(init, ast.Constant) and init.value is False


def test_constant_and_resolver_imported_in_same_try():
    try_node = _find_pin_try(TREE)
    assert try_node is not None
    imported = []
    for stmt in try_node.body:
        if isinstance(stmt, ast.ImportFrom) and stmt.module == "unsloth_zoo.llama_cpp":
            imported.extend(alias.name for alias in stmt.names)
    assert "LLAMA_CPP_DEFAULT_DIR" in imported
    assert "_resolve_local_convert_script" in imported


def test_the_pin_is_never_left_in_the_environment():
    """No setdefault, and every direct write is answered by a pop in a finally. The
    setdefault this replaced is what made the converter tag inert and turned
    UNSLOTH_CONVERTER_SCAN_STRICT into a warning for every Studio export."""
    setdefaults = []
    for node in ast.walk(TREE):
        if (
            isinstance(node, ast.Call)
            and isinstance(node.func, ast.Attribute)
            and node.func.attr == "setdefault"
            and isinstance(node.func.value, ast.Attribute)
            and node.func.value.attr == "environ"
            and node.args
            and isinstance(node.args[0], ast.Constant)
            and node.args[0].value == SCRIPTS_DIR
        ):
            setdefaults.append(node)
    assert not setdefaults, "the scripts pin must not be left in the environment"

    helper = _pin_helper_node(TREE)
    assert helper is not None
    writes = [
        node
        for node in ast.walk(helper)
        if isinstance(node, ast.Subscript)
        and isinstance(node.ctx, ast.Store)
        and isinstance(node.value, ast.Attribute)
        and node.value.attr == "environ"
    ]
    pops = [
        node
        for node in ast.walk(helper)
        if isinstance(node, ast.Call)
        and isinstance(node.func, ast.Attribute)
        and node.func.attr == "pop"
        and isinstance(node.func.value, ast.Attribute)
        and node.func.value.attr == "environ"
    ]
    assert len(writes) <= len(pops), "a direct write to os.environ needs an unwind"


def test_pin_prefers_the_internal_helper():
    """unsloth_zoo exempts a user pin from the strict converter scan, so Studio's own routing must
    be marked internal or the exemption goes to an unreviewed converter."""
    helper = _pin_helper_node(TREE)
    assert helper is not None
    imported = [
        alias.name
        for node in ast.walk(helper)
        if isinstance(node, ast.ImportFrom) and node.module == "unsloth_zoo.llama_cpp"
        for alias in node.names
    ]
    assert "internal_scripts_dir_pin" in imported
    used = [
        item
        for node in ast.walk(helper)
        if isinstance(node, ast.With)
        for item in node.items
        if isinstance(item.context_expr, ast.Call)
        and isinstance(item.context_expr.func, ast.Name)
        and item.context_expr.func.id == "internal_scripts_dir_pin"
    ]
    assert used, "internal_scripts_dir_pin must be entered, not just imported"


def test_warning_handler_gated_on_module_flag():
    try_node = _find_pin_try(TREE)
    assert try_node is not None
    handlers = [h for h in try_node.handlers if _catches_import_error(h)]
    assert handlers
    # A revert to ImportError alone would still satisfy _catches_import_error above.
    covering = [h for h in handlers if _covers_half_built_zoo(h)]
    assert (
        covering
    ), "the scripts pin must fall back on a half-built unsloth_zoo, not just a missing one"
    handler = covering[0]
    flag_reads = []
    flag_writes = []
    warning_calls = []
    for node in ast.walk(ast.Module(body = handler.body, type_ignores = [])):
        if isinstance(node, ast.Name) and node.id == "_LLAMA_CPP_SCRIPTS_WARNING_EMITTED":
            if isinstance(node.ctx, ast.Load):
                flag_reads.append(node)
            elif isinstance(node.ctx, ast.Store):
                flag_writes.append(node)
        elif (
            isinstance(node, ast.Call)
            and isinstance(node.func, ast.Attribute)
            and node.func.attr == "warning"
        ):
            warning_calls.append(node)
    assert flag_reads
    assert flag_writes
    assert warning_calls
    msg = ast.dump(warning_calls[0])
    assert SCRIPTS_DIR in msg
    assert "unsloth_zoo" in msg


def test_default_dir_is_string():
    from unsloth_zoo.llama_cpp import LLAMA_CPP_DEFAULT_DIR
    assert isinstance(LLAMA_CPP_DEFAULT_DIR, str)


def test_pin_is_in_force_only_while_converting(monkeypatch):
    fake, calls = _install_fake_zoo(monkeypatch)
    pin, _ns = _load_pin_helper()

    with pin():
        assert os.environ[SCRIPTS_DIR] == fake.LLAMA_CPP_DEFAULT_DIR
    assert SCRIPTS_DIR not in os.environ
    assert calls["internal"] == [fake.LLAMA_CPP_DEFAULT_DIR]


def test_pin_preserves_an_explicit_user_override(monkeypatch):
    _fake, _calls = _install_fake_zoo(monkeypatch)
    monkeypatch.setenv(SCRIPTS_DIR, "/explicit/override")
    pin, _ns = _load_pin_helper()

    with pin():
        assert os.environ[SCRIPTS_DIR] == "/explicit/override"
    assert os.environ[SCRIPTS_DIR] == "/explicit/override"


def test_converter_tag_is_not_overridden(monkeypatch):
    """UNSLOTH_LLAMA_CPP_SCRIPTS_DIR outranks the tag, so pinning while a tag is set is
    what made the tag do nothing."""
    _fake, calls = _install_fake_zoo(monkeypatch)
    monkeypatch.setenv(CONVERTER_TAG, "b9999")
    pin, _ns = _load_pin_helper()

    with pin():
        assert SCRIPTS_DIR not in os.environ
    assert calls["internal"] == []


def test_incomplete_install_is_not_pinned(monkeypatch):
    _fake, calls = _install_fake_zoo(monkeypatch, incomplete = True)
    pin, _ns = _load_pin_helper()

    with pin():
        assert SCRIPTS_DIR not in os.environ
    assert calls["internal"] == []


def test_mlx_does_not_nest_the_pin(monkeypatch):
    """unsloth_zoo's MLX save path pins the converter itself and its pin holds a plain
    threading.Lock across the conversion, so a second entry hangs the export."""
    fake, calls = _install_fake_zoo(monkeypatch)
    pin, _ns = _load_pin_helper(is_mlx = True)

    with pin():
        with fake.internal_scripts_dir_pin(fake.LLAMA_CPP_DEFAULT_DIR):
            pass
    assert calls["internal"] == [fake.LLAMA_CPP_DEFAULT_DIR]
    assert SCRIPTS_DIR not in os.environ


def test_older_zoo_without_the_internal_helper_still_unwinds(monkeypatch):
    fake, _calls = _install_fake_zoo(monkeypatch, internal_pin = False)
    pin, _ns = _load_pin_helper()

    with pin():
        assert os.environ[SCRIPTS_DIR] == fake.LLAMA_CPP_DEFAULT_DIR
    assert SCRIPTS_DIR not in os.environ


def test_warning_fires_at_most_once_across_calls(monkeypatch):
    """A zoo with no local-script resolver: warn once, keep exporting."""
    _fake, _calls = _install_fake_zoo(monkeypatch, resolver = False)
    emits = []
    logger = types.SimpleNamespace(warning = lambda message, *a, **k: emits.append(message))
    pin, _ns = _load_pin_helper(logger = logger)

    for _ in range(3):
        with pin():
            pass
    assert len(emits) == 1
    assert SCRIPTS_DIR in emits[0]
    assert SCRIPTS_DIR not in os.environ


def test_missing_default_dir_degrades_to_warning(monkeypatch):
    _fake, _calls = _install_fake_zoo(monkeypatch, default_dir = None)
    emits = []
    logger = types.SimpleNamespace(warning = lambda message, *a, **k: emits.append(message))
    pin, _ns = _load_pin_helper(logger = logger)

    with pin():
        assert SCRIPTS_DIR not in os.environ
    assert len(emits) == 1
    assert SCRIPTS_DIR not in os.environ


def test_no_warning_when_both_symbols_present(monkeypatch):
    fake, _calls = _install_fake_zoo(monkeypatch)
    emits = []
    logger = types.SimpleNamespace(warning = lambda message, *a, **k: emits.append(message))
    pin, _ns = _load_pin_helper(logger = logger)

    with pin():
        assert os.environ.get(SCRIPTS_DIR) == fake.LLAMA_CPP_DEFAULT_DIR
    assert emits == []