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.

16.6 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

from __future__ import annotations

import json
import os
import subprocess
import sys
import threading
import time
from pathlib import Path

import pytest

_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
if _BACKEND_DIR not in sys.path:
    sys.path.insert(0, _BACKEND_DIR)

from hub.services.models.common import _local_model_info
from utils import hf_cache_settings
from utils import native_path_leases


@pytest.fixture()
def settings_store(monkeypatch, tmp_path):
    store = {}
    monkeypatch.setattr(hf_cache_settings, "_EXPLICIT_CACHE_ENV", {})
    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
    monkeypatch.setattr(
        "storage.studio_db.get_app_setting",
        lambda key, fallback = None: store.get(key, fallback),
    )
    monkeypatch.setattr(
        "storage.studio_db.upsert_app_settings",
        lambda values: store.update(values) or values,
    )
    return store


def test_studio_cache_switch_is_live_and_keeps_history(settings_store, tmp_path):
    first = tmp_path / "external-a" / "huggingface"
    second = tmp_path / "external-b" / "huggingface"
    first.parent.mkdir()
    second.parent.mkdir()

    selected = hf_cache_settings.set_hf_cache_home(str(first))
    assert selected.hub_cache == first / "hub"
    assert selected.xet_cache == first / "xet"
    assert selected.child_env({}) == {
        "HF_HUB_CACHE": str(first / "hub"),
        "HF_XET_CACHE": str(first / "xet"),
    }

    hf_cache_settings.set_hf_cache_home(str(second))
    assert settings_store[hf_cache_settings.CACHE_HISTORY_SETTING_KEY] == [str(first)]
    assert first / "hub" in hf_cache_settings.known_hf_hub_caches()

    reset = hf_cache_settings.set_hf_cache_home(None)
    assert reset.source == "default"
    assert second in hf_cache_settings.known_hf_cache_homes()


def test_environment_cache_is_read_only(monkeypatch, tmp_path):
    custom = tmp_path / "managed"
    monkeypatch.setattr(
        hf_cache_settings,
        "_EXPLICIT_CACHE_ENV",
        {"HF_HOME": str(custom)},
    )
    paths = hf_cache_settings.get_hf_cache_paths()
    assert paths.source == "environment"
    assert paths.editable is False
    assert paths.hub_cache == custom / "hub"
    with pytest.raises(RuntimeError, match = "environment variable"):
        hf_cache_settings.set_hf_cache_home(str(tmp_path / "other"))


def test_explicit_hub_cache_is_the_displayed_location(monkeypatch, tmp_path):
    custom_hub = tmp_path / "models-cache"
    custom_hub.mkdir()
    monkeypatch.setattr(
        hf_cache_settings,
        "_EXPLICIT_CACHE_ENV",
        {"HF_HUB_CACHE": str(custom_hub)},
    )

    paths = hf_cache_settings.get_hf_cache_paths()
    status = hf_cache_settings.cache_status(paths)

    assert paths.cache_home == custom_hub
    assert paths.hub_cache == custom_hub
    assert status["cache_home"] == str(custom_hub)
    assert status["available"] is True
    assert custom_hub / "hub" not in hf_cache_settings.known_hf_hub_caches()


def test_explicit_hub_cache_display_wins_over_hf_home(monkeypatch, tmp_path):
    hf_home = tmp_path / "hf-home"
    custom_hub = tmp_path / "other-disk" / "models-cache"
    hf_home.mkdir()
    custom_hub.mkdir(parents = True)
    monkeypatch.setattr(
        hf_cache_settings,
        "_EXPLICIT_CACHE_ENV",
        {"HF_HOME": str(hf_home), "HF_HUB_CACHE": str(custom_hub)},
    )

    paths = hf_cache_settings.get_hf_cache_paths()

    assert paths.cache_home == custom_hub
    assert paths.hub_cache == custom_hub
    assert paths.xet_cache == hf_home / "xet"
    assert custom_hub / "hub" not in hf_cache_settings.known_hf_hub_caches()
    assert hf_home / "hub" in hf_cache_settings.known_hf_hub_caches()


def test_xet_only_override_keeps_model_cache_editable(settings_store, monkeypatch, tmp_path):
    xet_cache = tmp_path / "chunks"
    stored = tmp_path / "stored-cache"
    settings_store[hf_cache_settings.CACHE_HOME_SETTING_KEY] = str(stored)
    monkeypatch.setattr(
        hf_cache_settings,
        "_EXPLICIT_CACHE_ENV",
        {"HF_XET_CACHE": str(xet_cache)},
    )

    paths = hf_cache_settings.get_hf_cache_paths()

    assert paths.cache_home == stored
    assert paths.hub_cache == stored / "hub"
    assert paths.xet_cache == xet_cache
    assert paths.editable is True

    selected = tmp_path / "selected-cache"
    selected.parent.mkdir(exist_ok = True)
    updated = hf_cache_settings.set_hf_cache_home(str(selected))
    assert updated.hub_cache == selected / "hub"
    assert updated.xet_cache == xet_cache


def test_worker_environment_is_applied_before_import(monkeypatch, tmp_path):
    hub = str(tmp_path / "hub")
    xet = str(tmp_path / "xet")
    observed = {}

    class Module:
        @staticmethod
        def run():
            return os.environ["HF_HUB_CACHE"], os.environ["HF_XET_CACHE"]

    def fake_import(name):
        observed["name"] = name
        observed["hub"] = os.environ.get("HF_HUB_CACHE")
        return Module

    monkeypatch.setattr(native_path_leases.importlib, "import_module", fake_import)
    result = native_path_leases.run_without_native_path_secret(
        "fake.worker",
        "run",
        {"HF_HUB_CACHE": hub, "HF_XET_CACHE": xet},
    )
    assert observed == {"name": "fake.worker", "hub": hub}
    assert result == (hub, xet)


def test_spawn_environment_is_applied_then_restored(monkeypatch, tmp_path):
    hub = str(tmp_path / "hub")
    xet = str(tmp_path / "xet")
    monkeypatch.setenv("HF_HUB_CACHE", "parent-hub")
    monkeypatch.delenv("HF_XET_CACHE", raising = False)

    with hf_cache_settings.child_environment_for_spawn({"HF_HUB_CACHE": hub, "HF_XET_CACHE": xet}):
        assert os.environ["HF_HUB_CACHE"] == hub
        assert os.environ["HF_XET_CACHE"] == xet

    assert os.environ["HF_HUB_CACHE"] == "parent-hub"
    assert "HF_XET_CACHE" not in os.environ


def test_spawn_environment_supports_nested_contexts(monkeypatch):
    monkeypatch.setenv("HF_HUB_CACHE", "parent")

    with hf_cache_settings.child_environment_for_spawn({"HF_HUB_CACHE": "outer"}):
        assert os.environ["HF_HUB_CACHE"] == "outer"
        with hf_cache_settings.child_environment_for_spawn({"HF_HUB_CACHE": "inner"}):
            assert os.environ["HF_HUB_CACHE"] == "inner"
        assert os.environ["HF_HUB_CACHE"] == "outer"

    assert os.environ["HF_HUB_CACHE"] == "parent"


def test_spawn_environment_serializes_threads(monkeypatch):
    monkeypatch.setenv("HF_HUB_CACHE", "parent")
    first_entered = threading.Event()
    release_first = threading.Event()
    observations: list[tuple[str, str]] = []

    def first():
        with hf_cache_settings.child_environment_for_spawn({"HF_HUB_CACHE": "first"}):
            observations.append(("first", os.environ["HF_HUB_CACHE"]))
            first_entered.set()
            assert release_first.wait(timeout = 2)

    def second():
        assert first_entered.wait(timeout = 2)
        with hf_cache_settings.child_environment_for_spawn({"HF_HUB_CACHE": "second"}):
            observations.append(("second", os.environ["HF_HUB_CACHE"]))

    first_thread = threading.Thread(target = first)
    second_thread = threading.Thread(target = second)
    first_thread.start()
    second_thread.start()
    assert first_entered.wait(timeout = 2)
    time.sleep(0.02)
    assert observations == [("first", "first")]
    release_first.set()
    first_thread.join(timeout = 2)
    second_thread.join(timeout = 2)

    assert observations == [("first", "first"), ("second", "second")]
    assert os.environ["HF_HUB_CACHE"] == "parent"


def test_cache_switch_invalidates_inventory(settings_store, tmp_path, monkeypatch):
    invalidations = []
    monkeypatch.setattr(
        "hub.utils.inventory_scan.invalidate_hf_cache_scans",
        lambda: invalidations.append(True),
    )
    selected = tmp_path / "external" / "huggingface"
    selected.parent.mkdir()

    hf_cache_settings.set_hf_cache_home(str(selected))

    assert invalidations == [True]


def test_cache_validation_write_tests_hub_and_xet(settings_store, tmp_path, monkeypatch):
    selected = tmp_path / "external" / "huggingface"
    selected.parent.mkdir()
    tested = []
    real_named_temporary_file = hf_cache_settings.tempfile.NamedTemporaryFile

    def recording_write_test(*args, **kwargs):
        tested.append(Path(kwargs["dir"]))
        return real_named_temporary_file(*args, **kwargs)

    monkeypatch.setattr(
        hf_cache_settings.tempfile,
        "NamedTemporaryFile",
        recording_write_test,
    )

    hf_cache_settings.set_hf_cache_home(str(selected))

    assert tested == [selected / "hub", selected / "xet"]


def test_cache_validation_rejects_unwritable_child(settings_store, tmp_path, monkeypatch):
    selected = tmp_path / "external" / "huggingface"
    selected.parent.mkdir()

    def reject_hub(*args, **kwargs):
        if Path(kwargs["dir"]).name == "hub":
            raise PermissionError("read-only")
        raise AssertionError("xet should not be tested after hub fails")

    monkeypatch.setattr(hf_cache_settings.tempfile, "NamedTemporaryFile", reject_hub)

    with pytest.raises(ValueError, match = "permission"):
        hf_cache_settings.set_hf_cache_home(str(selected))


def test_inactive_cache_model_loads_from_snapshot_path(tmp_path):
    snapshot = tmp_path / "snapshots" / "revision"
    snapshot.mkdir(parents = True)
    row = _local_model_info(
        scan_path = snapshot,
        load_path = snapshot,
        source = "hf_cache",
        model_format = "safetensors",
        model_id = "org/model",
        active_cache = False,
    )
    assert row.model_id == "org/model"
    assert row.active_cache is False
    assert row.load_id == str(snapshot)


def test_diffusion_cache_root_follows_a_live_switch(settings_store, tmp_path):
    # The diffusion backends must not use hub's import-time HF_HUB_CACHE constant, which goes stale.
    import core.inference.diffusion as diffusion

    moved = tmp_path / "external-c" / "huggingface"
    # Bypass set_hf_cache_home: its folder validation rejects the pytest tmp root on macOS.
    settings_store[hf_cache_settings.CACHE_HOME_SETTING_KEY] = str(moved)

    assert diffusion.hub_cache_dir() == str(moved / "hub")
    assert diffusion.DiffusionBackend._hub_cache_repo_dir("org/model") == (
        moved / "hub" / "models--org--model"
    )


def test_diffusion_loader_calls_pin_the_cache_dir():
    for rel in ("core/inference/diffusion.py", "core/inference/video.py"):
        source = (Path(_BACKEND_DIR) / rel).read_text(encoding = "utf-8")
        for call in ("from_pretrained(", "from_single_file("):
            for index, line in enumerate(source.splitlines(), start = 1):
                if not line.strip().startswith(("pipe = ", "transformer = ", "cn_model = ")):
                    continue
                if call not in line:
                    continue
                window = "\n".join(source.splitlines()[index - 1 : index + 8])
                assert (
                    "cache_dir" in window or "kwargs" in window
                ), f"{rel}:{index} calls {call} without a pinned cache_dir"


# Skipping the DB read avoids creating studio.db for `unsloth train`; runs in a subprocess
# because the skip needs storage.studio_db out of sys.modules.
_GUARD_PROBE = """
import json, os, sys

sys.path.insert(0, os.environ["FAKE_STORAGE"])
sys.path.insert(1, os.environ["BACKEND_DIR"])
from utils import hf_cache_settings

assert "storage.studio_db" not in sys.modules, "the probe must exercise the skip"
stored = hf_cache_settings._stored_cache_home()
print(json.dumps({"stored": None if stored is None else str(stored)}))
"""

_FAKE_STUDIO_DB = """
import os
from pathlib import Path


def get_app_setting(key, fallback = None):
    Path(os.environ["READ_WITNESS"]).write_text("read", encoding = "utf-8")
    if key == "hugging_face_cache_home":
        return os.environ["STORED_CACHE_HOME"]
    return fallback
"""


def _run_guard_probe(
    tmp_path,
    studio_home: Path,
    stored: Path,
    *,
    probe: str | None = None,
    extra_env: dict[str, str] | None = None,
) -> tuple[str | None, bool]:
    """Return (_stored_cache_home() answer, whether the database was read)."""
    fake = tmp_path / "fake_storage"
    (fake / "storage").mkdir(parents = True, exist_ok = True)
    (fake / "storage" / "__init__.py").write_text("", encoding = "utf-8")
    (fake / "storage" / "studio_db.py").write_text(_FAKE_STUDIO_DB, encoding = "utf-8")
    witness = tmp_path / "read_witness"
    witness.unlink(missing_ok = True)

    environment = dict(os.environ)
    environment.update(
        BACKEND_DIR = _BACKEND_DIR,
        FAKE_STORAGE = str(fake),
        READ_WITNESS = str(witness),
        STORED_CACHE_HOME = str(stored),
        UNSLOTH_STUDIO_HOME = str(studio_home),
        PYTHONPATH = "",
    )
    environment.update(extra_env or {})
    for key in ("HF_HOME", "HF_HUB_CACHE", "HUGGINGFACE_HUB_CACHE", "HF_XET_CACHE"):
        environment.pop(key, None)
    result = subprocess.run(
        [sys.executable, "-c", probe if probe is not None else _GUARD_PROBE],
        capture_output = True,
        text = True,
        env = environment,
        timeout = 120,
    )
    assert result.returncode == 0, result.stderr
    return json.loads(result.stdout.strip().splitlines()[-1])["stored"], witness.exists()


def test_absent_studio_db_skips_the_database_read(tmp_path):
    studio_home = tmp_path / "root" / "studio"
    studio_home.mkdir(parents = True)

    answer, was_read = _run_guard_probe(tmp_path, studio_home, tmp_path / "chosen")

    assert answer is None
    assert not was_read, "an absent database must not be opened"


@pytest.mark.parametrize("fixture", ["not_a_directory", "symlink_loop", "unreadable_parent"])
def test_uninspectable_studio_db_keeps_the_stored_cache_home(tmp_path, fixture):
    # Path.exists reports ENOTDIR/ELOOP (and EACCES from 3.14) as absence; that must not count.
    chosen = tmp_path / "chosen"
    studio_home = tmp_path / "root" / "studio"
    if fixture == "not_a_directory":
        studio_home.parent.mkdir(parents = True)
        studio_home.write_text("", encoding = "utf-8")
    elif fixture == "symlink_loop":
        studio_home.parent.mkdir(parents = True)
        studio_home.symlink_to(studio_home)
    else:
        studio_home.mkdir(parents = True)
        (studio_home / "studio.db").write_bytes(b"")
        os.chmod(studio_home, 0o000)

    try:
        answer, was_read = _run_guard_probe(tmp_path, studio_home, chosen)
    finally:
        if fixture == "unreadable_parent":
            os.chmod(studio_home, 0o755)

    assert was_read, "a database we could not inspect must still be read"
    assert answer == str(chosen)


_WINDOWS_SHAPED_GUARD_PROBE = """
import errno, json, os, sys

# Windows reports a path whose PARENT is a file as ERROR_PATH_NOT_FOUND, which Python raises as
# FileNotFoundError; POSIX raises NotADirectoryError. Reproduce the error shape, since the Linux
# runners cannot produce it, and do it before hf_cache_settings is imported.
_NOT_A_DIR = os.environ["NOT_A_DIRECTORY"]
_real_stat = os.stat


def _stat(path, *args, **kwargs):
    text = os.fspath(path)
    if text != _NOT_A_DIR and text.startswith(_NOT_A_DIR + os.sep):
        raise FileNotFoundError(errno.ENOENT, "The system cannot find the path specified", text)
    return _real_stat(path, *args, **kwargs)


os.stat = _stat
sys.path.insert(0, os.environ["FAKE_STORAGE"])
sys.path.insert(1, os.environ["BACKEND_DIR"])
from utils import hf_cache_settings

assert "storage.studio_db" not in sys.modules, "the probe must exercise the skip"
stored = hf_cache_settings._stored_cache_home()
print(json.dumps({"stored": None if stored is None else str(stored)}))
"""


def test_a_studio_home_that_is_a_file_still_reads_the_database_on_windows(tmp_path):
    """On Windows a file-as-directory is FileNotFoundError, which must not discard the chosen home."""
    studio_home = tmp_path / "root" / "studio"
    studio_home.parent.mkdir(parents = True)
    studio_home.write_text("", encoding = "utf-8")
    chosen = tmp_path / "chosen"

    answer, was_read = _run_guard_probe(
        tmp_path,
        studio_home,
        chosen,
        probe = _WINDOWS_SHAPED_GUARD_PROBE,
        extra_env = {"NOT_A_DIRECTORY": str(studio_home)},
    )

    assert was_read, "a studio home we could not inspect was read as no database"
    assert answer == str(chosen)


def test_a_studio_home_that_does_not_exist_still_skips_the_database_read(tmp_path):
    """A missing studio/ directory must still skip the read, or the 250 KB database gets built."""
    studio_home = tmp_path / "never-created" / "studio"

    answer, was_read = _run_guard_probe(tmp_path, studio_home, tmp_path / "chosen")

    assert answer is None
    assert not was_read, "an absent studio home must not open a database"