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.

14.9 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

"""Every Hub repo an IMAGE load can fetch resolves to ``unsloth/*``.

Walks the family table (bases, named variants, prequant / TE checkpoints, sd-cli VAE and text encoders, train and
deploy bases), the frontend image catalog (every artifact row and the base each GGUF / bnb row takes its companions
from) and fails on any fetch id outside ``unsloth/*``. Fully offline: the cache probe is forced to "not cached", so the
answer is what a fresh install fetches, not what this host happens to hold.
"""

from __future__ import annotations

import re
from pathlib import Path

import pytest

from core.inference import diffusion_families as df
from core.inference.diffusion_families import (
    _FAMILIES,
    _UNGATED_MIRROR_PAIRS,
    canonical_base,
    detect_family,
    mirror_repo,
    prefer_ungated_mirror,
    sd_cpp_text_encoder_candidates,
    upstream_is_gated,
)

# Vendor repos an image load may still fetch because a licence clause forbids a mirror.
_LICENCE_BLOCKED: dict[str, str] = {
    # Tencent Hunyuan Community License: "Territory" means the worldwide territory, excluding the territory of the
    # European Union, United Kingdom and South Korea. A public Hub mirror cannot honour a territorial limit.
    "hunyuanvideo-community/hunyuanimage-2.1-diffusers": "territory-restricted licence",
}
# Bases fetched from upstream because no unsloth mirror of them is made.
_UNMIRRORED: dict[str, str] = {
    "lodestones/chroma1-hd": "Chroma",
    "circlestone-labs/anima-base-v1.0-diffusers": "Anima",
    # Native-layout release read by Studio's own loader; no unsloth mirror of it exists yet.
    "minimaxai/minimax-h3-image": "MiniMax-H3-Image",
}

# Third-party DENOISER artifacts the catalog still offers. Not a companion fetch and not licence-blocked: there is
# simply no unsloth GGUF of FLUX.1 Krea dev yet. Its companions already come from unsloth/FLUX.1-Krea-dev.
_THIRD_PARTY_DENOISER_ROWS: frozenset[str] = frozenset({"quantstack/flux.1-krea-dev-gguf"})

# Card tag of each quantised image repo: GGUF/bnb companions come from this repo, since no family
# table names the card-tag-only variants; the catalog test flags gaps.
_CARD_BASES: dict[str, str] = {
    "unsloth/Z-Image-Turbo-GGUF": "Tongyi-MAI/Z-Image-Turbo",
    "unsloth/Z-Image-Turbo-unsloth-bnb-4bit": "Tongyi-MAI/Z-Image-Turbo",
    "unsloth/Z-Image-GGUF": "Tongyi-MAI/Z-Image",
    "unsloth/Qwen-Image-2.1-GGUF": "Qwen/Qwen-Image-2.1",
    "unsloth/Qwen-Image-2.1-Turbo-GGUF": "Qwen/Qwen-Image-2.1-Turbo",
    "unsloth/Qwen-Image-2512-GGUF": "Qwen/Qwen-Image-2512",
    "unsloth/Qwen-Image-2512-unsloth-bnb-4bit": "Qwen/Qwen-Image-2512",
    "unsloth/Qwen-Image-GGUF": "Qwen/Qwen-Image",
    "unsloth/Qwen-Image-Edit-GGUF": "Qwen/Qwen-Image-Edit",
    "unsloth/Qwen-Image-Edit-2509-GGUF": "Qwen/Qwen-Image-Edit-2509",
    "unsloth/Qwen-Image-Edit-2511-GGUF": "Qwen/Qwen-Image-Edit-2511",
    "unsloth/Qwen-Image-Layered-GGUF": "Qwen/Qwen-Image-Layered",
    "unsloth/FLUX.1-schnell-GGUF": "black-forest-labs/FLUX.1-schnell",
    "unsloth/FLUX.1-dev-GGUF": "black-forest-labs/FLUX.1-dev",
    "QuantStack/FLUX.1-Krea-dev-GGUF": "black-forest-labs/FLUX.1-Krea-dev",
    "unsloth/FLUX.1-Kontext-dev-GGUF": "black-forest-labs/FLUX.1-Kontext-dev",
    "unsloth/FLUX.2-dev-GGUF": "black-forest-labs/FLUX.2-dev",
    "unsloth/FLUX.2-klein-4B-GGUF": "black-forest-labs/FLUX.2-klein-4B",
    "unsloth/FLUX.2-klein-9B-GGUF": "black-forest-labs/FLUX.2-klein-9B",
    "unsloth/FLUX.2-klein-base-4B-GGUF": "black-forest-labs/FLUX.2-klein-base-4B",
    "unsloth/FLUX.2-klein-base-9B-GGUF": "black-forest-labs/FLUX.2-klein-base-9B",
    "unsloth/flux-3-image-klein-GGUF": "black-forest-labs/flux-3-image-klein",
    "unsloth/flux-3-image-klein-base-GGUF": "black-forest-labs/flux-3-image-klein-base",
    "unsloth/MOSS-Image-SFT-GGUF": "OpenMOSS-Team/MOSS-Image-SFT",
    "unsloth/MOSS-Image-Base-GGUF": "OpenMOSS-Team/MOSS-Image-Base",
}

# No mirror repo: official diffusers folders live in the unsloth repo (-FP8 if any, else -GGUF).
_NEW_PAIRS = (
    ("Qwen/Qwen-Image-2.1-Turbo", "unsloth/Qwen-Image-2.1-Turbo-FP8"),
    ("Qwen/Qwen-Image-Edit", "unsloth/Qwen-Image-Edit-GGUF"),
    ("Qwen/Qwen-Image-Edit-2509", "unsloth/Qwen-Image-Edit-2509-GGUF"),
    ("Qwen/Qwen-Image-Layered", "unsloth/Qwen-Image-Layered-GGUF"),
    ("Tongyi-MAI/Z-Image", "unsloth/Z-Image-GGUF"),
    ("OpenMOSS-Team/MOSS-Image-SFT", "unsloth/MOSS-Image-SFT-FP8"),
    ("OpenMOSS-Team/MOSS-Image-Base", "unsloth/MOSS-Image-Base-FP8"),
)

# Repacks built by ComfyUI (or its unsloth/* copies). No image load may fetch from one, not even through the
# legacy-cache fallback.
_COMFY_MADE: frozenset[str] = frozenset(
    {
        "unsloth/flux-text-encoders",
        "unsloth/qwen-image-comfyui",
        "unsloth/flux.2-vae",
        "unsloth/flux.2-dev-comfyui",
        "unsloth/z-image-turbo-comfyui",
        "unsloth/flux.2-klein-9b-comfyui",
    }
)


def _is_comfy(repo: str) -> bool:
    r = repo.lower()
    return (
        r in _COMFY_MADE
        or r.startswith(("comfy-org/", "comfyanonymous/"))
        or "comfyui" in r
        or "comfy" in r.split("/")[0]
    )


@pytest.fixture(autouse = True)
def _fresh_install(monkeypatch):
    """Nothing is cached and the opt-out is off: the fetch id a fresh install uses."""
    monkeypatch.setattr(df, "_upstream_is_cached", lambda repo_id, files = None, **_k: False)
    monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)


def _fetch_id(repo: str) -> str:
    return prefer_ungated_mirror(repo)


def _allowed(repo: str) -> bool:
    if _is_comfy(repo):
        return False
    r = repo.lower()
    return r.startswith("unsloth/") or r in _LICENCE_BLOCKED or r in _UNMIRRORED


def _family_fetch_ids() -> list[tuple[str, str, str, str]]:
    """(family, role, table id, fetch id) for every repo the image family table can hand a fetch site."""
    rows: list[tuple[str, str, str, str]] = []

    def add(fam, role, repo):
        if repo:
            rows.append((fam.name, role, repo, _fetch_id(repo)))

    for fam in _FAMILIES:
        add(fam, "base_repo", fam.base_repo)
        for repo in fam.named_variant_bases:
            add(fam, "named_variant", repo)
        for _scheme, repo in fam.prequant_repos:
            add(fam, "prequant", repo)
        for base, _scheme, repo in fam.prequant_variant_repos:
            add(fam, "prequant_variant_base", base)
            add(fam, "prequant_variant", repo)
        for _scheme, _component, repo, *_built_as in fam.te_prequant_repos:
            add(fam, "te_prequant", repo)
        for repo in fam.train_base_repos:
            add(fam, "train_base", repo)
        add(fam, "deploy_base", fam.deploy_base_repo)
        for training, inference in fam.deploy_base_repos:
            add(fam, "deploy_base", training)
            add(fam, "deploy_base", inference)
        for base, _config in fam.mlx_model_config_by_base:
            add(fam, "mlx_base", base)
    return rows


def _sd_cpp_fetch_ids() -> list[tuple[str, str, str, str]]:
    """The sd-cli VAE and every text-encoder candidate, through the backend's own per-repo fetch map."""
    from core.inference.sd_cpp_backend import _fetch_repo_map

    rows: list[tuple[str, str, str, str]] = []
    for fam in _FAMILIES:
        specs = []
        if fam.sd_cpp_vae:
            specs.append((fam.sd_cpp_vae[0], fam.sd_cpp_vae[1], "vae"))
        specs.extend(sd_cpp_text_encoder_candidates(fam))
        fetch = _fetch_repo_map(specs, None)
        rows.extend((fam.name, f"sd_cpp:{kind}", repo, fetch[repo]) for repo, _f, kind in specs)
    return rows


def test_new_mirror_pairs_round_trip():
    for upstream, mirror in _NEW_PAIRS:
        assert (upstream, mirror) in _UNGATED_MIRROR_PAIRS
        assert mirror_repo(upstream) == mirror
        assert mirror_repo(upstream.lower()) == mirror
        assert canonical_base(mirror) == upstream
        # Ungated upstreams: the mirror only keeps the fetch in unsloth/*, it must not override a user's cache.
        assert not upstream_is_gated(upstream)
        assert _fetch_id(upstream) == mirror


def test_every_image_family_fetch_id_is_unsloth():
    bad = [row for row in _family_fetch_ids() if not _allowed(row[3])]
    assert not bad, "image family fetch ids outside unsloth/*:\n" + "\n".join(map(str, bad))


def test_every_sd_cpp_asset_fetch_id_is_unsloth():
    rows = _sd_cpp_fetch_ids()
    assert rows
    bad = [row for row in rows if not _allowed(row[3])]
    assert not bad, "sd-cli asset fetch ids outside unsloth/*:\n" + "\n".join(map(str, bad))


def test_moss_image_components_come_from_its_fp8_repos():
    fam = detect_family("OpenMOSS-Team/MOSS-Image-SFT")
    assert fam is not None and fam.name == "moss-image"
    assert fam.base_repo == "OpenMOSS-Team/MOSS-Image-SFT"
    for variant in ("SFT", "Base"):
        upstream, mirror = (
            f"OpenMOSS-Team/MOSS-Image-{variant}",
            f"unsloth/MOSS-Image-{variant}-FP8",
        )
        assert _fetch_id(upstream) == mirror
        assert df.mirror_hosts_artifacts(mirror)
    sd_cpp = {r[1]: r[3] for r in _sd_cpp_fetch_ids() if r[0] == "moss-image"}
    assert sd_cpp["sd_cpp:vae"] == "unsloth/MOSS-Image-SFT-FP8"
    assert fam.sd_cpp_tokenizer == ("unsloth/MOSS-Image-SFT-FP8", "tokenizer/tokenizer.json")


def test_layered_sd_cpp_vae_comes_from_the_mirror():
    """Layered's sd-cli VAE is read from its own base, so the base mirror is what keeps it inside unsloth/*."""
    fam = detect_family("", override = "qwen-image-layered")
    assert fam is not None and fam.sd_cpp_vae
    rows = [r for r in _sd_cpp_fetch_ids() if r[0] == "qwen-image-layered" and r[1] == "sd_cpp:vae"]
    assert rows and rows[0][3] == "unsloth/Qwen-Image-Layered-GGUF"


def _image_catalog() -> str:
    text = (
        Path(__file__).resolve().parents[2]
        / "frontend/src/features/model-picker/components/model-selector/model-catalog.ts"
    ).read_text(encoding = "utf-8")
    images = text.split("export const IMAGE_CATALOG", 1)[1].split("export const VIDEO_CATALOG", 1)[
        0
    ]
    # Comments name withdrawn repos (the old QuantStack HunyuanImage GGUF); only live code counts.
    return re.sub(r"^\s*//.*$", "", images, flags = re.M)


def _catalog_rows() -> list[tuple[str, str]]:
    images = _image_catalog()
    rows = []
    for helper in ("gguf", "bf16Pipeline", "bf16Mirror", "fp8Pipeline", "bnb4bit", "bf16Single"):
        rows.extend((helper, repo) for repo in re.findall(helper + r'\(\s*"([^"]+)"', images))
    rows.extend(("prequantRepo", repo) for repo in re.findall(r'prequantRepo:\s*"([^"]+)"', images))
    assert len(rows) > 20, rows
    return rows


def _catalog_fetch_id(helper: str, repo: str) -> str:
    # bf16Mirror rows already load the unsloth copy; the rest reach the backend by their own id.
    if helper == "bf16Mirror":
        return f"unsloth/{repo.split('/', 1)[1]}"
    return _fetch_id(repo)


def test_every_image_catalog_row_fetches_from_unsloth():
    bad = []
    for helper, repo in _catalog_rows():
        fetch = _catalog_fetch_id(helper, repo)
        if helper == "bf16Mirror":
            # The row's id is only usable if the backend maps it back to the upstream it copies.
            assert mirror_repo(repo) == fetch, repo
        if _allowed(fetch) or repo.lower() in _THIRD_PARTY_DENOISER_ROWS:
            continue
        bad.append((helper, repo, fetch))
    assert not bad, f"image catalog rows fetching outside unsloth/*: {bad}"


def test_every_quantised_catalog_row_takes_its_companions_from_unsloth():
    quantised = {repo for helper, repo in _catalog_rows() if helper in ("gguf", "bnb4bit")}
    unmapped = sorted(
        r for r in quantised if r not in _CARD_BASES and not r.lower().startswith("ideogram-ai/")
    )
    assert (
        not unmapped
    ), f"add the base_model card tag of these catalog rows to _CARD_BASES: {unmapped}"
    bad = []
    for repo, base in _CARD_BASES.items():
        fam = detect_family(repo)
        assert fam is not None, repo
        assert detect_family(base) is fam, (repo, base)
        fetch = _fetch_id(base)
        if not _allowed(fetch):
            bad.append((repo, base, fetch))
    assert not bad, f"companion bases fetched outside unsloth/*: {bad}"


def test_licence_allowlist_is_still_needed():
    """The allowlist cannot outlive its reason: each entry must still be a fetch id with no mirror."""
    ids = {row[2].lower() for row in _family_fetch_ids()} | {r.lower() for _h, r in _catalog_rows()}
    for repo in _LICENCE_BLOCKED:
        assert repo in ids, f"{repo} is no longer fetched; drop it from _LICENCE_BLOCKED"
        assert mirror_repo(repo) is None, f"{repo} is mirrored now; drop it from _LICENCE_BLOCKED"
    for repo in _UNMIRRORED:
        assert repo in ids, f"{repo} is no longer fetched; drop it from _UNMIRRORED"
        assert mirror_repo(repo) is None, f"{repo} is mirrored now; drop it from _UNMIRRORED"
    rows = {r.lower() for _h, r in _catalog_rows()}
    for repo in _THIRD_PARTY_DENOISER_ROWS:
        assert (
            repo in rows
        ), f"the catalog no longer offers {repo}; drop it from _THIRD_PARTY_DENOISER_ROWS"


def test_no_image_asset_names_a_comfy_repack():
    """Neither the tables nor the fetch map may name a ComfyUI-built file, and the legacy-cache fallback must not be
    able to turn an image asset back into one."""
    rows = _family_fetch_ids() + _sd_cpp_fetch_ids()
    bad = [r for r in rows if _is_comfy(r[2]) or _is_comfy(r[3])]
    assert not bad, bad
    image_assets = {r[2].lower() for r in rows} | {r[3].lower() for r in rows}
    for key, legacy in df._SD_CPP_LEGACY_SOURCES.items():
        assert key not in image_assets, (key, legacy)
        assert key not in _COMFY_MADE, key


def test_sd_cpp_text_encoders_are_unsloth_ggufs_or_official_files():
    """Every sd-cli text encoder is an unsloth GGUF or an official upstream file (through its unsloth mirror)."""
    for fam, role, repo, fetch in _sd_cpp_fetch_ids():
        if role == "sd_cpp:vae":
            continue
        assert fetch.lower().startswith("unsloth/") and not _is_comfy(fetch), (
            fam,
            role,
            repo,
            fetch,
        )


def test_every_sampling_grid_index_is_read_from_an_unsloth_repo(monkeypatch):
    """The native route reads a variant base's model_index.json for its sample_sigmas grid outside the asset table,
    so it needs its own walk: every base a grid family can name must resolve to an unsloth repo on a fresh install."""
    from core.inference import diffusion_families as families
    from core.inference import sd_cpp_backend as bk

    monkeypatch.setattr(families, "_upstream_is_cached", lambda *a, **k: False)
    bases = {
        b
        for fam in families._FAMILIES
        if fam.name in bk._SAMPLE_SIGMAS_FAMILIES
        for b in (fam.base_repo, *(getattr(fam, "named_variant_bases", ()) or ()))
        if b
    }
    assert bases
    for base in sorted(bases):
        assert bk._grid_fetch_repo(base, None).lower().startswith("unsloth/"), base