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.

17.2 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

"""An exported image LoRA dropped into a custom models folder shows up in the Images LoRA picker, and
never as a model in the model pickers."""

from __future__ import annotations

import asyncio
import json
import os
import struct

import pytest

from core.inference import diffusion_lora as dl
import storage.studio_db as studio_db

_MARK = {"kind": "diffusion-lora"}
_LORA_KEY = "unet.down.0.lora_A.weight"
_MODEL_KEY = "model.layers.0.self_attn.q_proj.weight"


def _safetensors(
    path,
    sidecar = None,
    key = _LORA_KEY,
):
    path.parent.mkdir(parents = True, exist_ok = True)
    header = json.dumps({key: {"dtype": "F32", "shape": [1], "data_offsets": [0, 4]}}).encode()
    path.write_bytes(struct.pack("<Q", len(header)) + header + b"\0\0\0\0")
    if sidecar is not None:
        path.with_suffix(".json").write_text(json.dumps(sidecar))
    return path


# The registered-folder table itself (normalisation, denylist) is covered elsewhere; macOS tmp_path
# lives under /private/var, which registration refuses, so the rows are faked here.
_FOLDERS: list = []


def register(folder):
    _FOLDERS.append({"path": str(folder)})


@pytest.fixture(autouse = True)
def _folders(monkeypatch):
    _FOLDERS.clear()
    monkeypatch.setattr(studio_db, "list_scan_folders", lambda: list(_FOLDERS))


@pytest.fixture
def catalog(tmp_path, monkeypatch):
    d = tmp_path / "loras"
    d.mkdir()
    monkeypatch.setattr(dl, "loras_dir", lambda: d)
    return d


def _local():
    return {e.id: e for e in dl.list_loras() if e.source == "local"}


def _by_path(path):
    return next(e for e in _local().values() if e.local_path == str(path))


def test_an_export_in_a_custom_folder_is_listed(catalog, tmp_path):
    (catalog / "mystyle.safetensors").write_bytes(b"w")
    (catalog / "mystyle.json").write_text(
        json.dumps({"family": "sdxl", "source": "studio-trained"})
    )
    folder = tmp_path / "my-models"
    dl.export_local_lora("mystyle", folder / "image-loras")
    (catalog / "mystyle.safetensors").unlink()
    (catalog / "mystyle.json").unlink()
    register(str(folder))

    entry = _by_path(folder / "image-loras" / "mystyle.safetensors")
    assert entry.display_name == "mystyle" and entry.id.startswith("mystyle-")
    assert entry.families == ("sdxl",) and entry.fine_tuned
    assert dl.resolve_one(entry.id, 1.0).path == entry.local_path


def test_unmarked_weights_in_a_custom_folder_are_ignored(catalog, tmp_path):
    folder = tmp_path / "my-models"
    _safetensors(folder / "model.safetensors", key = _MODEL_KEY)
    _safetensors(folder / "notes.safetensors", sidecar = {"family": "sdxl"}, key = _MODEL_KEY)
    register(str(folder))
    assert _local() == {}


def test_a_third_party_lora_without_a_sidecar_is_listed(catalog, tmp_path):
    folder = tmp_path / "my-models"
    lora = _safetensors(folder / "pixel-art" / "style.safetensors", key = "lora_unet_down.alpha")
    register(folder)
    entry = _by_path(lora)
    assert entry.display_name == "style" and entry.families == () and not entry.fine_tuned
    assert dl.resolve_one(entry.id, 1.0).path == str(lora)


@pytest.mark.parametrize(
    "drop",
    [
        "style.safetensors",
        "hub/style.safetensors",
        "hub/loras/style.safetensors",
        "loras/style.safetensors",
    ],
)
def test_a_lora_dropped_in_the_models_folder_is_listed(catalog, tmp_path, monkeypatch, drop):
    import utils.hf_cache_settings as settings

    home = tmp_path / "models"
    paths = type("Paths", (), {"cache_home": home, "hub_cache": home / "hub"})()
    monkeypatch.setattr(settings, "get_hf_cache_paths", lambda: paths)
    lora = _safetensors(home / drop)
    _safetensors(home / "hub" / "models--a--b" / "snapshots" / "c" / "deep.safetensors")
    assert [e.local_path for e in _local().values()] == [str(lora)]


@pytest.mark.parametrize("registered", ["ComfyUI", "ComfyUI/models"])
def test_loras_under_a_comfyui_folder_are_listed(catalog, tmp_path, registered):
    models = tmp_path / "ComfyUI" / "models"
    (models / "checkpoints").mkdir(parents = True)
    lora = _safetensors(models / "loras" / "flux" / "style.safetensors")
    register(tmp_path / registered)
    assert [e.local_path for e in _local().values()] == [str(lora)]


def test_loras_listed_in_extra_model_paths_yaml_are_listed(catalog, tmp_path, monkeypatch):
    from hub.storage import scan_folders

    monkeypatch.setattr(scan_folders, "_denied_path_prefixes", lambda: [])
    root = tmp_path / "ComfyUI"
    (root / "models" / "checkpoints").mkdir(parents = True)
    lora = _safetensors(tmp_path / "shared" / "Lora" / "style.safetensors")
    (root / "extra_model_paths.yaml").write_text(
        f"a111:\n  base_path: {tmp_path / 'shared'}\n  loras: Lora\n"
    )
    register(root)
    assert [e.local_path for e in _local().values()] == [str(lora)]


def test_a_chat_adapter_in_a_custom_folder_stays_out_of_the_picker(catalog, tmp_path):
    from hub.services.models.local_inventory import _scan_models_dir

    folder = tmp_path / "my-models"
    adapter = folder / "chat-lora"
    _safetensors(adapter / "adapter_model.safetensors")
    (adapter / "adapter_config.json").write_text(json.dumps({"peft_type": "LORA"}))
    register(folder)
    assert _local() == {}
    assert [row.display_name for row in _scan_models_dir(folder)] == ["chat-lora"]


def test_header_of_an_unchanged_lora_is_read_once(catalog, tmp_path, monkeypatch):
    from core.inference import diffusion_content

    folder = tmp_path / "my-models"
    lora = _safetensors(folder / "style.safetensors")
    register(folder)
    reads = []
    real = diffusion_content._read_safetensors_header
    monkeypatch.setattr(
        diffusion_content, "_read_safetensors_header", lambda p: reads.append(p) or real(p)
    )
    assert len(_local()) == len(_local()) == 1
    assert reads == [str(lora)]


def test_an_export_keeps_a_foreign_json_beside_an_identical_lora(catalog, tmp_path):
    _safetensors(catalog / "style.safetensors")
    dest = tmp_path / "out"
    _safetensors(dest / "style.safetensors", sidecar = {"note": "mine"})
    assert dl.export_local_lora("style", dest).name == "style-2.safetensors"
    assert json.loads((dest / "style.json").read_text()) == {"note": "mine"}


def test_custom_folder_ids_stay_stable_when_folders_change(catalog, tmp_path):
    (catalog / "style.safetensors").write_bytes(b"catalog")
    folders = [tmp_path / name for name in ("a", "b", "c")]
    for folder in folders:
        _safetensors(folder / "style.safetensors", sidecar = _MARK)
        register(str(folder))
    assert _local()["style"].local_path == str(catalog / "style.safetensors")
    ids = {str(f): _by_path(f / "style.safetensors").id for f in folders}
    assert len(set(ids.values())) == 3 and not _by_path(folders[2] / "style.safetensors").fine_tuned

    _FOLDERS.pop(0)
    for folder in folders[1:]:
        assert _by_path(folder / "style.safetensors").id == ids[str(folder)]
    assert ids[str(folders[0])] not in _local()


def test_the_catalog_registered_as_a_custom_folder_is_not_listed_twice(catalog, tmp_path):
    _safetensors(catalog / "style.safetensors", sidecar = _MARK)
    register(str(catalog))
    assert list(_local()) == ["style"]


@pytest.mark.parametrize("scanner", ["routes", "inventory"])
def test_marked_loras_are_not_listed_as_models(tmp_path, scanner):
    if scanner == "routes":
        from routes.models import _scan_models_dir
    else:
        from hub.services.models.local_inventory import _scan_models_dir

    folder = tmp_path / "image-loras"
    _safetensors(folder / "a.safetensors", sidecar = _MARK)
    _safetensors(folder / "b.safetensors", sidecar = {"source": "studio-trained"})
    assert _scan_models_dir(folder) == []
    assert _scan_models_dir(tmp_path) == []

    _safetensors(tmp_path / "plain" / "style.safetensors")
    assert _scan_models_dir(tmp_path) == []

    _safetensors(tmp_path / "checkpoint" / "model.safetensors", key = _MODEL_KEY)
    assert [row.display_name for row in _scan_models_dir(tmp_path)] == ["checkpoint"]


def test_the_picker_route_reports_fine_tuned(catalog):
    from routes.models import scan_diffusion_loras

    _safetensors(catalog / "trained.safetensors", sidecar = {"source": "studio-trained", **_MARK})
    _safetensors(catalog / "downloaded.safetensors")
    rows = asyncio.run(scan_diffusion_loras(family = None, current_subject = "subject"))["loras"]
    flags = {row["id"]: row["fine_tuned"] for row in rows if row["source"] == "local"}
    assert flags == {"trained": True, "downloaded": False}


@pytest.mark.parametrize("scanner", ["routes", "inventory"])
def test_a_marked_gguf_in_a_subfolder_is_not_a_model(tmp_path, scanner):
    if scanner == "routes":
        from routes.models import _scan_models_dir
    else:
        from hub.services.models.local_inventory import _scan_models_dir

    folder = tmp_path / "image-loras"
    folder.mkdir()
    (folder / "style.gguf").write_bytes(b"GGUF" + b"\0" * 60)
    (folder / "style.json").write_text(json.dumps(_MARK))
    assert _scan_models_dir(tmp_path) == []


def test_a_managed_account_only_sees_custom_folder_loras_it_may_access(
    catalog, tmp_path, monkeypatch
):
    from hub.services.models import account_access

    folder = tmp_path / "shared"
    _safetensors(folder / "style.safetensors", sidecar = _MARK)
    register(str(folder))
    monkeypatch.setattr(account_access, "managed_account", lambda: True)
    monkeypatch.setattr(account_access, "model_visible", lambda reference, **_: False)
    assert _local() == {}
    with pytest.raises(FileNotFoundError):
        dl.export_local_lora("style", tmp_path / "out")
    with pytest.raises(FileNotFoundError):
        dl.resolve_one("style", 1.0)


@pytest.mark.parametrize("scanner", ["routes", "inventory"])
def test_the_lmstudio_fallback_skips_marked_loras(tmp_path, scanner):
    if scanner == "routes":
        from routes.models import _scan_lmstudio_dir
    else:
        from hub.services.models.local_inventory import _scan_lmstudio_dir

    for gguf in (tmp_path / "image-loras" / "style.gguf", tmp_path / "loose.gguf"):
        gguf.parent.mkdir(parents = True, exist_ok = True)
        gguf.write_bytes(b"GGUF" + b"\0" * 60)
        gguf.with_suffix(".json").write_text(json.dumps(_MARK))
    (tmp_path / "real.gguf").write_bytes(b"GGUF" + b"\0" * 60)
    assert [row.display_name for row in _scan_lmstudio_dir(tmp_path)] == ["real"]


def test_stacked_loras_share_one_custom_folder_scan(catalog, tmp_path, monkeypatch):
    for name in ("a", "b", "c"):
        (catalog / f"{name}.safetensors").write_bytes(b"w")
    calls = []
    real = dl._scan_folder_roots
    monkeypatch.setattr(dl, "_scan_folder_roots", lambda: calls.append(1) or real())
    resolved = dl.resolve_specs([("a", 1.0), ("b", 0.5), ("c", 0.8)])
    assert [r.path for r in resolved] == [str(catalog / f"{n}.safetensors") for n in "abc"]
    assert len(calls) == 1


@pytest.mark.skipif(os.name == "nt", reason = "symlinks need a privilege on Windows")
def test_a_managed_account_cannot_reach_out_through_a_catalog_symlink(
    catalog, tmp_path, monkeypatch
):
    from hub.services.models import account_access

    secret = tmp_path / "elsewhere" / "secret.safetensors"
    _safetensors(secret, sidecar = _MARK)
    (catalog / "link.safetensors").symlink_to(secret)
    (catalog / "own.safetensors").write_bytes(b"w")
    monkeypatch.setattr(account_access, "managed_account", lambda: True)
    monkeypatch.setattr(
        account_access,
        "model_visible",
        lambda reference, **_: str(catalog) in os.path.realpath(reference),
    )
    assert list(_local()) == ["own"]
    with pytest.raises(FileNotFoundError):
        dl.export_local_lora("link", tmp_path / "out")


@pytest.mark.skipif(os.name == "nt", reason = "POSIX byte filenames")
def test_a_non_utf8_filename_does_not_break_the_scan(catalog, tmp_path):
    folder = tmp_path / "my-models"
    folder.mkdir()
    name = os.fsdecode(b"st\xffyle.safetensors")
    try:
        _safetensors(folder / name, sidecar = _MARK)
    except OSError:
        pytest.skip("this filesystem refuses non-UTF-8 names (APFS)")
    register(folder)
    assert [e.local_path for e in _local().values()] == [str(folder / name)]


def test_generation_rechecks_access_on_resolve(catalog, monkeypatch):
    from hub.services.models import account_access

    (catalog / "own.safetensors").write_bytes(b"w")
    catalog_snapshot = dl._catalog_by_id()
    monkeypatch.setattr(account_access, "managed_account", lambda: True)
    monkeypatch.setattr(account_access, "model_visible", lambda reference, **_: False)
    with pytest.raises(FileNotFoundError):
        dl.resolve_one("own", 1.0, catalog = catalog_snapshot)


def test_a_marked_gguf_beside_a_model_is_not_a_variant(tmp_path):
    from hub.services.models.common import _main_gguf_files

    (tmp_path / "config.json").write_text("{}")
    (tmp_path / "model-Q4_K_M.gguf").write_bytes(b"GGUF" + b"\0" * 60)
    (tmp_path / "style.gguf").write_bytes(b"GGUF" + b"\0" * 60)
    (tmp_path / "style.json").write_text(json.dumps(_MARK))
    assert [p.name for p in _main_gguf_files(tmp_path)] == ["model-Q4_K_M.gguf"]


def test_a_config_with_only_a_marked_safetensors_is_not_a_model(tmp_path):
    from hub.services.models.local_inventory import _scan_models_dir

    folder = tmp_path / "loras-with-config"
    folder.mkdir()
    (folder / "config.json").write_text("{}")
    _safetensors(folder / "style.safetensors", sidecar = _MARK)
    rows = _scan_models_dir(tmp_path)
    assert all(getattr(r, "model_format", None) != "safetensors" for r in rows)


def test_an_unreadable_entry_does_not_fail_the_catalog(catalog, tmp_path, monkeypatch):
    from pathlib import Path

    folder = tmp_path / "my-models"
    _safetensors(folder / "good.safetensors", sidecar = _MARK)
    _safetensors(folder / "locked.safetensors", sidecar = _MARK)
    register(folder)
    real_is_file = Path.is_file

    def is_file(self):
        if self.name == "locked.safetensors":
            raise PermissionError(13, "Permission denied")
        return real_is_file(self)

    monkeypatch.setattr(Path, "is_file", is_file)
    assert [e.display_name for e in _local().values()] == ["good"]


def test_an_unreadable_sibling_keeps_the_root_listed(catalog, tmp_path, monkeypatch):
    from pathlib import Path

    folder = tmp_path / "my-models"
    _safetensors(folder / "good.safetensors", sidecar = _MARK)
    (folder / "locked").mkdir()
    register(folder)
    real_is_dir = Path.is_dir

    def is_dir(self):
        if self.name == "locked":
            raise PermissionError(13, "Permission denied")
        return real_is_dir(self)

    monkeypatch.setattr(Path, "is_dir", is_dir)
    assert [e.display_name for e in _local().values()] == ["good"]


def test_an_export_of_a_listed_adapter_is_listed_once(catalog, tmp_path):
    meta = {"family": "sdxl", "source": "studio-trained", "created_at": 1.5, **_MARK}
    _safetensors(catalog / "mystyle.safetensors", sidecar = meta)
    folder = tmp_path / "my-models"
    out = dl.export_local_lora("mystyle", folder / "image-loras")
    register(folder)
    assert list(_local()) == ["mystyle"]
    copy = next(e for e in dl._scan_local() if e.copy_of)
    assert copy.copy_of == "mystyle" and copy.local_path == str(out)
    # Still resolvable, so a recipe saved with the copy's id keeps working.
    assert dl.resolve_one(copy.id, 1.0).path == str(out)
    # Account checks see the copy's own path, not its bare id.
    from types import SimpleNamespace
    from hub.services.models.account_access import media_adapter_references

    request = SimpleNamespace(loras = [SimpleNamespace(id = copy.id)], controlnet = None)
    assert media_adapter_references(request) == [str(out)]


def test_same_sized_adapters_without_metadata_are_not_collapsed(catalog, tmp_path):
    _safetensors(catalog / "a.safetensors")
    folder = tmp_path / "my-models"
    _safetensors(folder / "b.safetensors", sidecar = _MARK)
    register(folder)
    assert len(_local()) == 2


def test_a_different_training_run_with_the_same_name_is_not_a_copy(catalog, tmp_path):
    _safetensors(
        catalog / "style.safetensors", sidecar = {"source": "studio-trained", "created_at": 1.0}
    )
    folder = tmp_path / "my-models"
    _safetensors(
        folder / "style.safetensors",
        sidecar = {"source": "studio-trained", "created_at": 2.0, **_MARK},
    )
    register(folder)
    assert len(_local()) == 2


def test_a_same_layout_adapter_with_other_weights_is_not_a_copy(catalog, tmp_path):
    meta = {"family": "sdxl", "source": "studio-trained", "created_at": 1.5}
    (catalog / "style.safetensors").write_bytes(b"A" * 200_000)
    (catalog / "style.json").write_text(json.dumps(meta))
    folder = tmp_path / "my-models"
    folder.mkdir()
    (folder / "style.safetensors").write_bytes(b"A" * 100_000 + b"B" * 100_000)
    (folder / "style.json").write_text(json.dumps({**meta, **_MARK}))
    register(folder)
    assert len(_local()) == 2


def test_hand_written_metadata_never_collapses(catalog, tmp_path):
    (catalog / "style.safetensors").write_bytes(b"w" * 10)
    (catalog / "style.json").write_text(json.dumps({"family": "sdxl"}))
    folder = tmp_path / "my-models"
    folder.mkdir()
    (folder / "style.safetensors").write_bytes(b"w" * 10)
    (folder / "style.json").write_text(json.dumps({"family": "sdxl", **_MARK}))
    register(folder)
    assert len(_local()) == 2