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.

6.9 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.

import os
from types import SimpleNamespace

import huggingface_hub
import pytest

import unsloth.save as save_mod


class _RecordingApi:
    calls = []

    def __init__(self, *args, **kwargs):
        pass

    def __getattr__(self, name):
        def record(*args, **kwargs):
            if name == "create_commit":
                readme = next(op for op in kwargs["operations"] if op.path_in_repo == "README.md")
                kwargs["readme"] = readme.path_or_fileobj.decode("utf-8")
            _RecordingApi.calls.append((name, kwargs))
            if name == "create_commit" and kwargs.get("create_pr"):
                return SimpleNamespace(pr_url = "https://huggingface.co/u/my-model/discussions/1")
            return SimpleNamespace(pr_url = None)

        return record


def _fake_convert(**kwargs):
    directory = kwargs["save_directory"]
    os.makedirs(directory, exist_ok = True)
    stem = os.path.basename(directory)
    files = []
    for suffix in ("Q8_0.gguf", "BF16-mmproj.gguf"):
        path = os.path.join(directory, f"{stem}.{suffix}")
        open(path, "wb").write(b"GGUF")
        files.append(path)
    open(os.path.join(directory, "config.json"), "w").write("{}")
    modelfile = os.path.join(directory, "Modelfile")
    open(modelfile, "w").write("FROM x")
    return {
        "gguf_files": files,
        "modelfile_location": modelfile,
        "want_full_precision": False,
        "is_vlm": True,
        "fix_bos_token": False,
        "save_directory": directory,
    }


@pytest.fixture
def push(monkeypatch):
    _RecordingApi.calls = []
    monkeypatch.setattr(huggingface_hub, "HfApi", _RecordingApi)
    monkeypatch.setattr(save_mod, "unsloth_save_pretrained_gguf", _fake_convert)

    def run(**kwargs):
        save_mod.unsloth_push_to_hub_gguf(object(), "u/my-model", tokenizer = object(), **kwargs)
        return _RecordingApi.calls

    return run


EXPECTED_PATHS = {
    "my-model.Q8_0.gguf",
    "my-model.BF16-mmproj.gguf",
    "config.json",
    "Modelfile",
    "README.md",
}


@pytest.mark.parametrize(
    "kwargs",
    [{}, {"create_pr": True}, {"revision": "new-branch"}, {"revision": "refs/pr/3"}],
)
def test_all_files_go_in_one_commit(push, kwargs):
    calls = push(**kwargs)
    names = [name for name, _ in calls]
    assert "upload_file" not in names
    assert names.count("create_commit") == 1
    commit = next(kw for name, kw in calls if name == "create_commit")
    assert {op.path_in_repo for op in commit["operations"]} == EXPECTED_PATHS
    assert commit["create_pr"] == kwargs.get("create_pr", False)
    assert commit["revision"] == kwargs.get("revision")


def test_new_revision_is_created_before_the_commit(push):
    names = [name for name, _ in push(revision = "new-branch")]
    assert names.index("create_branch") < names.index("create_commit")
    branch = next(kw for name, kw in _RecordingApi.calls if name == "create_branch")
    assert branch["branch"] == "new-branch" and branch["exist_ok"] is True


@pytest.mark.parametrize("kwargs", [{}, {"create_pr": True}, {"revision": "refs/pr/3"}])
def test_no_branch_is_created_without_a_new_revision(push, kwargs):
    assert "create_branch" not in [name for name, _ in push(**kwargs)]


@pytest.mark.parametrize(
    "revision, expected",
    [("exp/q4", "/tree/exp%2Fq4"), ("v2", "/tree/v2"), ("refs/pr/3", "/discussions/3")],
)
def test_printed_destination_encodes_the_branch(push, capsys, revision, expected):
    push(revision = revision)
    assert f"https://huggingface.co/u/my-model{expected}\n" in capsys.readouterr().out


@pytest.mark.parametrize("datasets", [["org/data", "other"], "org/data"])
def test_datasets_go_in_the_same_commit(push, monkeypatch, datasets):
    def fail(*args, **kwargs):
        raise AssertionError("datasets must not be written in a separate commit")

    monkeypatch.setattr(huggingface_hub, "metadata_update", fail)
    calls = push(create_pr = True, datasets = datasets)
    readme = next(kw for name, kw in calls if name == "create_commit")["readme"]
    card = huggingface_hub.ModelCard(readme)
    expected = [datasets] if isinstance(datasets, str) else datasets
    assert card.data.datasets == expected
    assert "gguf" in card.data.tags


def test_readme_is_not_written_into_the_save_directory(push, tmp_path, monkeypatch):
    """For a non-PEFT model the returned save directory is the user's own checkpoint."""
    checkpoint = tmp_path / "checkpoint"
    checkpoint.mkdir()
    (checkpoint / "README.md").write_text("my model card")

    def _convert_reusing_checkpoint(**kwargs):
        result = _fake_convert(**kwargs)
        result["save_directory"] = str(checkpoint)
        return result

    monkeypatch.setattr(save_mod, "unsloth_save_pretrained_gguf", _convert_reusing_checkpoint)
    calls = push()
    commit = next(kw for name, kw in calls if name == "create_commit")
    assert "Unsloth" in commit["readme"]
    assert (checkpoint / "README.md").read_text() == "my model card"


@pytest.mark.parametrize("tags", [["my-tag", "second"], "my-tag"])
def test_tags_go_in_the_readme_card(push, tags):
    """HfApi has no add_tags, so tags only reach the Hub through the README card."""
    calls = push(create_pr = True, tags = tags)
    assert "add_tags" not in [name for name, _ in calls]
    readme = next(kw for name, kw in calls if name == "create_commit")["readme"]
    card_tags = huggingface_hub.ModelCard(readme).data.tags
    assert set([tags] if isinstance(tags, str) else tags) <= set(card_tags)
    assert {"gguf", "llama-cpp", "unsloth"} <= set(card_tags)


def test_tags_argument_is_not_modified(push):
    tags = ["my-tag"]
    push(tags = tags)
    assert tags == ["my-tag"]


@pytest.mark.parametrize("tags", [None, ["my-tag", "gguf"], "my-tag"])
def test_sentence_transformer_tags_go_in_the_readme_card(monkeypatch, tags):
    st_mod = pytest.importorskip("unsloth.models.sentence_transformer")
    _RecordingApi.calls = []
    readmes = []

    def upload_file(self, **kwargs):
        if kwargs["path_in_repo"] == "README.md":
            readmes.append(open(kwargs["path_or_fileobj"], encoding = "utf-8").read())

    def fake_convert(self, save_directory, **kwargs):
        return {**_fake_convert(save_directory = save_directory), "modelfile_location": None}

    monkeypatch.setattr(_RecordingApi, "upload_file", upload_file, raising = False)
    monkeypatch.setattr(st_mod, "HfApi", _RecordingApi)
    monkeypatch.setattr(st_mod, "_save_pretrained_gguf", fake_convert)
    st_mod._push_to_hub_gguf(object(), "u/my-model", token = "x", tags = tags)

    assert "add_tags" not in [name for name, _ in _RecordingApi.calls]
    card_tags = huggingface_hub.ModelCard(readmes[0]).data.tags
    expected = {"gguf", "llama-cpp", "unsloth", "sentence-transformers", "vision-language-model"}
    expected |= {tags} if isinstance(tags, str) else set(tags or [])
    assert expected <= set(card_tags)
    assert len(card_tags) == len(set(card_tags))