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.

25.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

import asyncio
import os
from dataclasses import dataclass
from datetime import datetime
from pathlib import Path
from typing import List, Optional

NON_CHAT_TASKS = frozenset(
    {
        "automatic-speech-recognition",
        "text-to-image",
        "text-to-video",
        "text-to-speech",
        "image-diffusion-unsupported",
    }
)
LOCAL_SOURCES = frozenset({"models_dir", "lmstudio", "custom"})


@dataclass
class ModelEntry:
    group: str
    name: str
    detail: str
    model: str


def _run_title(run: dict) -> str:
    for key in ("display_name", "project_name", "model_name"):
        value = (run.get(key) or "").strip()
        if value:
            return value.split("/")[-1]
    return ""


def _folder_title(folder: str) -> str:
    name = folder.removeprefix("unsloth_")
    stem, _, suffix = name.rpartition("_")
    return stem if stem and suffix.isdigit() else name


def _short_date(value) -> str:
    try:
        if isinstance(value, (int, float)):
            dt = datetime.fromtimestamp(value)
        else:
            dt = datetime.fromisoformat(str(value)).astimezone()
        return dt.strftime("%b %d").replace(" 0", " ")
    except Exception:
        return ""


def _dataset_title(dataset: Optional[str]) -> str:
    if not dataset:
        return ""
    base = os.path.basename(dataset.rstrip("/"))
    head, sep, tail = base.partition("_")
    if sep and len(head) == 32 and all(c in "0123456789abcdef" for c in head):
        base = tail
    return base.removesuffix(".jsonl").removesuffix(".json").removesuffix(".csv")


def _run_detail(model_type: str, path: str, run: Optional[dict]) -> str:
    parts = [] if model_type == "lora" else [model_type]
    if run:
        parts.append(_dataset_title(run.get("dataset_name")))
        if run.get("final_step"):
            parts.append(f"{run['final_step']} steps")
        parts.append(_short_date(run.get("started_at")))
    else:
        try:
            parts.append(_short_date(Path(path).stat().st_mtime))
        except OSError:
            pass
    return " · ".join(p for p in parts if p)


def _runs_by_output_dir() -> dict:
    try:
        from storage.studio_db import list_runs
        runs = list_runs(limit = 1000)["runs"]
    except Exception:
        return {}
    by_dir = {}
    for run in sorted(runs, key = lambda r: r.get("started_at") or ""):
        if run.get("output_dir"):
            by_dir[os.path.normpath(run["output_dir"])] = run
    return by_dir


def _path_can_chat(path: str, base_model: Optional[str] = None) -> Optional[bool]:
    """``False`` only for a locally identifiable non-chat checkpoint, else ``None``."""
    try:
        from hub.services.models.common import _local_path_can_chat
    except ImportError:
        return None
    return _local_path_can_chat(path, base_model)


def _gguf_export_task(
    path: str,
    name: str,
    base_model: Optional[str] = None,
) -> Optional[str]:
    try:
        from hub.services.models.catalog_classification import _gguf_path_task
    except ImportError:
        return None
    return _gguf_path_task(path, (name, base_model))


def trained_entries() -> List[ModelEntry]:
    from utils.models import scan_trained_models

    runs = _runs_by_output_dir()
    entries = []
    for folder, path, model_type in scan_trained_models():
        run = runs.get(os.path.normpath(path))
        base = run.get("model_name") if run and model_type == "lora" else None
        if _path_can_chat(path, base) is False:
            continue
        name = (_run_title(run) if run else "") or _folder_title(folder)
        entries.append(ModelEntry("Fine-tunes", name, _run_detail(model_type, path, run), path))
    return entries


def exported_entries() -> List[ModelEntry]:
    from utils.models import scan_exported_models

    entries = []
    for name, path, export_type, base in scan_exported_models():
        if _path_can_chat(path, base if export_type == "lora" else None) is False:
            continue
        if export_type == "gguf" and _gguf_export_task(path, name, base) in NON_CHAT_TASKS:
            continue
        if export_type == "gguf":
            # Drop only when positively unloadable: a falsy result also means "could not tell".
            load_id = _preferred_complete_gguf(path)
            if not load_id and not _local_dir_holds_a_payload(Path(path)):
                continue
        else:
            load_id = None
            # scan_exported_models calls a dir "lora" on adapter_config.json alone; require weights.
            if not _local_dir_holds_a_payload(Path(path)):
                continue
        entries.append(ModelEntry("Fine-tunes", name, export_type, load_id or path))
    return entries


def _pinned_snapshot(repo_path: Path, load_id: Optional[str]) -> Optional[Path]:
    """Snapshot a pinned row opens when load_id names one in this repo; a pin beats refs/main, which
    would resolve to a revision this row never loads."""
    if not load_id:
        return None
    try:
        candidate = Path(load_id)
        snapshots = (repo_path / "snapshots").resolve(strict = False)
        for path in (candidate, *candidate.parents):
            if path.parent.resolve(strict = False) == snapshots and path.is_dir():
                return path
    except (OSError, ValueError):
        return None
    return None


def _reachable_snapshots(repo_path: Path, load_id: Optional[str] = None) -> List[Path]:
    """Snapshots a load through this row can open: the pinned one if pinned, else refs/main alone,
    since other revisions' quants are unreachable; commit- or tag-pinned rows with no refs/main
    describe every snapshot."""
    snapshots = repo_path / "snapshots"
    try:
        available = sorted(path for path in snapshots.iterdir() if path.is_dir())
    except OSError:
        return []
    pinned = _pinned_snapshot(repo_path, load_id)
    if pinned is not None:
        # Not re-checked against `available`: under a symlinked cache root the two spellings differ.
        return [pinned]
    try:
        # ValueError too: an undecodable ref raises UnicodeDecodeError, not OSError.
        ref = (repo_path / "refs" / "main").read_text(encoding = "utf-8").strip()
    except (OSError, ValueError):
        ref = ""
    if ref:
        by_ref = snapshots / ref
        if by_ref in available:
            return [by_ref]
    return available


def _complete_quants(snapshot: Path) -> Optional[set]:
    """The quant keys under *snapshot* a load can resolve, or None if unknown.

    ``_preferred_complete_gguf`` narrows to this same set, so a label outside it names a
    quant selecting the row can never reach.
    """
    try:
        from hub.utils.inventory_scan import complete_snapshot_variants
        complete = complete_snapshot_variants(str(snapshot))
    except Exception:
        return None
    # Empty means the check could not tell, not that nothing loads.
    return set(complete) or None


def _quant_labels(
    repo_id: str,
    repo_path: str,
    load_id: Optional[str] = None,
) -> str:
    """The quants this cached GGUF repo offers, spelled the way Unsloth spells them.

    Through ``list_local_gguf_variants``, which is what ``_preferred_complete_gguf`` picks the
    load target with, so the label and the target cannot disagree. Globbing
    ``snapshots/*/*.gguf`` missed a per-quant subdirectory, gave a split quant one label per
    shard, and matched ``.GGUF`` only on Windows, where fnmatch normcases; the lister recurses,
    groups shard families, and tests the suffix case-insensitively.

    Scoped to the snapshot this row loads from and narrowed to the quants that snapshot can
    actually serve, so the detail never advertises a variant selecting the row cannot reach.

    Fails open to no detail, like every backend import here: a raise would leave ``_safe`` to
    swallow the whole cached source and every Downloaded row with it.
    """
    try:
        from hub.utils.gguf import list_local_gguf_variants
    except ImportError:
        return ""

    stem = repo_id.split("/")[-1].removesuffix("-GGUF").lower()
    quants = []
    for snapshot in _reachable_snapshots(Path(repo_path), load_id):
        try:
            variants, _ = list_local_gguf_variants(str(snapshot))
        except Exception:
            continue
        complete = _complete_quants(snapshot)
        for variant in variants:
            if complete is not None and variant.quant not in complete:
                continue
            label = variant.display_label or variant.quant
            if label.lower().startswith(stem + "-"):
                label = label[len(stem) + 1 :]
            if label and label not in quants:
                quants.append(label)
    return ", ".join(quants)


def _local_payload_is_torn(path: Path) -> bool:
    """Whether *path*'s own contents prove it cannot serve a load.

    Named apart from ``routes.models._snapshot_payload_is_torn``, which shares the rule but
    not the error policy: this one fails open, because ``_safe`` turns a raise here into an
    empty source rather than one dropped row.

    The shared rule the cache rows already use: a zero-byte weight, or a shard set naming a
    total it does not have, is not a payload. Fails open so an unreadable dir is not hidden.
    """
    try:
        from hub.utils.inventory_scan import _snapshot_cannot_serve_its_payload
    except ImportError:
        return False
    try:
        return bool(_snapshot_cannot_serve_its_payload(path))
    except (OSError, RuntimeError, ValueError):
        return False


def _gguf_file_is_loadable(path: Path) -> bool:
    """Whether a single-file GGUF can be read: non-empty, and whole if it names a shard total.

    ``_snapshot_cannot_serve_its_payload`` judges a directory; a scan row can name the ``.gguf``
    itself, and its folder may hold unrelated quants, so the file is judged on its own family.
    """
    try:
        if path.stat().st_size <= 0:
            return False
    except OSError:
        return True
    try:
        from hub.utils.inventory_scan import _GGUF_SPLIT_RE
    except ImportError:
        return True
    split = _GGUF_SPLIT_RE.search(path.name)
    if split is None:
        return True
    total = int(split.group(2))
    prefix = path.name[: split.start()]
    if int(split.group(1)) <= 0 or total <= 0 or int(split.group(1)) > total:
        return False
    present = set()
    try:
        for sibling in path.parent.iterdir():
            match = _GGUF_SPLIT_RE.search(sibling.name)
            if (
                match is None
                or sibling.name[: match.start()] != prefix
                or int(match.group(2)) != total
                or not sibling.is_file()
                or sibling.stat().st_size <= 0
            ):
                continue
            present.add(int(match.group(1)))
    except OSError:
        return True
    return present >= set(range(1, total + 1))


def _is_gguf_file(path: str) -> bool:
    try:
        return path.lower().endswith(".gguf") and Path(path).is_file()
    except OSError:
        return False


def _is_loose_gguf_companion(path: str) -> bool:
    """Whether a scan row names a GGUF SIDECAR rather than a model.

    ``_scan_models_dir`` screens mmproj, MTP drafter and imatrix files when it decides a
    directory is a model, and ``_local_dir_holds_a_payload`` requires a main GGUF inside one,
    but a loose ``.gguf`` child is listed on its extension alone. Resolving through the folder
    used to hide that by rewriting the sidecar row onto the real model; loading the file the row
    names offers a projector the loader refuses, so apply the same rule the directories get.
    """
    if not _is_gguf_file(path):
        return False
    try:
        from hub.services.models.common import _is_main_gguf_filename
    except ImportError:
        return False
    return not _is_main_gguf_filename(Path(path).name)


def _gguf_file_as_the_loader_opens_it(path: str) -> str:
    """Shard 1 for a split family as the loader reads it, not restated: the loader's
    _GGUF_SPLIT_FILE_RE takes exactly five digits, the scan's _GGUF_SPLIT_RE three or more; a
    local rule would rewrite model-002-of-003.gguf onto a sibling."""
    try:
        from utils.models.model_config import _local_gguf_load_path
    except ImportError:
        return path
    try:
        resolved = _local_gguf_load_path(Path(path))
        return path if resolved.samefile(path) else str(resolved)
    except OSError:
        return path


def _gguf_load_target(target: str) -> str:
    """A .gguf row loads its own file, not a folder's best quant across unrelated GGUFs (issue
    10352); shards collapse to the file the loader opens; a folder takes the largest, often an
    F16 that risks OOM."""
    if _is_gguf_file(target):
        return _gguf_file_as_the_loader_opens_it(target)
    return _preferred_complete_gguf(target) or target


def _preferred_complete_gguf(path: str) -> Optional[str]:
    model_path = Path(path)
    try:
        root = model_path.parent if model_path.is_file() else model_path
        if not root.is_dir():
            return None
        from hub.utils.gguf import list_local_gguf_variants, pick_best_gguf
        from hub.utils.inventory_scan import complete_snapshot_variants

        variants, _ = list_local_gguf_variants(str(root))
        complete = complete_snapshot_variants(str(root))
        ready = [variant for variant in variants if variant.quant in complete]
        root_variants = [variant for variant in ready if "/" not in variant.quant]
        best = pick_best_gguf([variant.filename for variant in root_variants or ready])
        candidate = root / best if best else None
        return str(candidate) if candidate is not None and candidate.is_file() else None
    except Exception:
        return None


def _cached_gguf_load_id(row: dict) -> str:
    """Concrete local GGUF for a cached row, else the identifier it came with; an active-cache bare
    repo id reaches detect_gguf_model_remote, whose permanent GatedRepoError returns None without
    the local-cache fallback, so a downloaded gated GGUF reads as non-GGUF."""
    load_id = row.get("load_id") or row["repo_id"]
    resolved = _preferred_complete_gguf(load_id)
    if resolved:
        return resolved
    # The bare repo id is not a path, so resolve through the snapshot the row was built from.
    cache_path = row.get("cache_path")
    if cache_path:
        try:
            from hub.utils.inventory_scan import default_ref_snapshot
            snapshot = default_ref_snapshot(Path(cache_path))
        except Exception:
            snapshot = None
        if snapshot is None:
            snapshots = sorted(Path(cache_path).glob("snapshots/*"))
            snapshot = snapshots[-1] if snapshots else None
        if snapshot is not None:
            resolved = _preferred_complete_gguf(str(snapshot))
            if resolved:
                return resolved
    return load_id


def _cached_catalog_rows() -> tuple[list[dict], list[dict]]:
    from hub.services.models.cache_inventory import (
        _scan_cached_gguf,
        _scan_cached_models,
        all_hf_cache_scans,
    )
    from utils.hf_cache_settings import get_hf_cache_paths

    scans = all_hf_cache_scans()
    active_hub_cache = get_hf_cache_paths().hub_cache

    def newest_first(rows):
        return sorted(
            rows,
            key = lambda row: (-(row.get("last_modified") or 0.0), row["repo_id"].lower()),
        )

    gguf_rows = _scan_cached_gguf(cache_scans = scans, active_hub_cache = active_hub_cache)
    model_rows = _scan_cached_models(cache_scans = scans, active_hub_cache = active_hub_cache)
    return newest_first(gguf_rows), newest_first(model_rows)


def cached_entries() -> List[ModelEntry]:
    gguf_rows, model_rows = _cached_catalog_rows()
    entries = []
    for row in gguf_rows:
        if (
            row.get("partial")
            or row.get("task") in NON_CHAT_TASKS
            or row.get("capabilities", {}).get("can_chat") is False
        ):
            continue
        entries.append(
            ModelEntry(
                "Downloaded",
                row["repo_id"],
                _quant_labels(row["repo_id"], row["cache_path"], row.get("load_id")),
                _cached_gguf_load_id(row),
            )
        )
    for row in model_rows:
        if row.get("partial") or row.get("companion") or row.get("task") in NON_CHAT_TASKS:
            continue
        # A cached embedding/CLIP repo has task None like any chat repo; can_chat is the gate.
        if row.get("capabilities", {}).get("can_chat") is False:
            continue
        # A diffusion repo carries no task and no root config, so neither gate catches it.
        if row.get("diffusers"):
            continue
        entries.append(ModelEntry("Downloaded", row["repo_id"], "", _cached_model_load_id(row)))
    return entries


def _cached_model_load_id(row: dict) -> str:
    """Load target for a cached non-GGUF row; a local snapshot for adapters.

    An ACTIVE-cache adapter carries the bare repo id, and a LoRA resolved by id takes the
    remote branch of get_base_model_from_lora_identifier, which downloads adapter_config.json
    with no local_files_only. For a cached gated adapter with no token that fails and the base
    is never read, so a row advertised as local yields no model configuration. A snapshot path
    makes is_local_path true and takes the local reader instead.

    Only adapters, deliberately: pinning an ordinary cached repo would freeze a live repo the
    inventory chose not to pin.
    """
    load_id = row.get("load_id") or row["repo_id"]
    if row.get("model_format") != "adapter" or os.path.isabs(str(load_id)):
        return load_id
    cache_path = row.get("cache_path")
    if not cache_path:
        return load_id
    try:
        from hub.utils.inventory_scan import default_ref_snapshot
        snapshot = default_ref_snapshot(Path(cache_path))
    except Exception:
        snapshot = None
    if snapshot is None:
        snapshots = sorted(Path(cache_path).glob("snapshots/*"))
        snapshot = snapshots[-1] if snapshots else None
    return str(snapshot) if snapshot is not None else load_id


def _local_dir_holds_a_payload(path: Path) -> bool:
    """Whether a scanned local directory holds something a load can actually read.

    ``_scan_models_dir`` lists a child on a config alone, so a weights-less config dir
    arrives with ``partial`` False and the picker would offer a folder that fails on
    selection. Anything that is not a readable directory fails open: a single-file GGUF
    is a file, not a dir.
    """
    try:
        is_dir = path.is_dir()
    except OSError:
        return True
    if not is_dir:
        # A scan row can name the .gguf file itself; anything else still fails open.
        return _gguf_file_is_loadable(path) if path.suffix.lower() == ".gguf" else True
    from hub.services.models.common import (
        _is_diffusers_pipeline_dir,
        _is_main_gguf_filename,
        _is_model_directory,
    )
    from utils.paths.path_utils import is_appledouble_metadata

    # A pipeline keeps its weights in component subdirs; the torn test would reject every one.
    if _is_diffusers_pipeline_dir(path):
        return True
    if _local_payload_is_torn(path):
        return False
    # iterdir, not glob("*.gguf"): the glob is case-sensitive on Linux and macOS.
    try:
        children = list(path.iterdir())
    except OSError:
        return True
    return any(
        _is_main_gguf_filename(file.name) and not is_appledouble_metadata(file) for file in children
    ) or _is_model_directory(path)


def _local_is_a_diffusers_pipeline(model) -> bool:
    """Diffusers pipelines never answer chat; an unrecognised one passes both can_chat gates with no
    task or root config, so the local check mirrors the cached diffusers flag."""
    from hub.services.models.catalog_classification import _local_is_diffusers
    return bool(_local_is_diffusers(model))


def _local_model_task(model) -> Optional[str]:
    from hub.services.models.catalog_classification import _local_model_task as classify
    return classify(model)


def _local_model_can_chat(model) -> Optional[bool]:
    from hub.services.models.catalog_classification import _local_model_can_chat as classify
    return classify(model)


def _local_catalog_rows():
    from hub.services.models.local_inventory import list_local_models_response
    response = asyncio.run(list_local_models_response(str(Path("./models").resolve())))
    return response.models


def _registered_custom_hf_cache(model) -> bool:
    if model.source != "hf_cache":
        return False
    try:
        from hub.storage.scan_folders import list_scan_folders
        from hub.utils.hf_cache_state import hf_cache_roots
        from hub.utils.paths import path_is_same_or_child

        model_path = Path(model.path)
        repo_dir = next(
            (
                path
                for path in (model_path, *model_path.parents)
                if path.name.startswith("models--")
            ),
            None,
        )
        if repo_dir is None:
            return False
        cache_root = repo_dir.parent

        def same_path(left: Path, right: Path) -> bool:
            return path_is_same_or_child(left, right) and path_is_same_or_child(right, left)

        if any(same_path(cache_root, root) for root in hf_cache_roots()):
            return False
        return any(
            same_path(cache_root, Path(folder["path"]).expanduser())
            for folder in list_scan_folders()
            if folder.get("path")
        )
    except Exception:
        return False


def local_folder_entries() -> List[ModelEntry]:
    entries = []
    for model in _local_catalog_rows():
        if (
            model.source not in LOCAL_SOURCES and not _registered_custom_hf_cache(model)
        ) or model.partial:
            continue
        is_gguf = model.model_format == "gguf" or model.path.lower().endswith(".gguf")
        # No format gate: _dir_model_format yields only gguf or None, so a safetensors literal would drop every non-GGUF model.
        if _local_model_task(model) in NON_CHAT_TASKS:
            continue
        # No format gate, so embedding and CLIP exports get through; only this stops them.
        if _local_model_can_chat(model) is False:
            continue
        if not _local_dir_holds_a_payload(Path(model.path)):
            continue
        if _is_loose_gguf_companion(model.path):
            continue
        if _local_is_a_diffusers_pipeline(model):
            continue
        target = model.load_id or model.id
        if is_gguf:
            target = _gguf_load_target(target)
        entries.append(
            ModelEntry(
                "Downloaded",
                model.display_name,
                "gguf" if is_gguf else "",
                target,
            )
        )
    return entries


def _safe(fn) -> List[ModelEntry]:
    """Run one source, and never let it take the other three down with it.

    Fails open, since a picker missing one group beats a traceback where a model list should
    be, but not SILENTLY: a source is every downloaded model or every fine-tune, so swallowing
    the reason turns "my HF cache is unreadable" into an empty list. UNSLOTH_DEBUG re-raises.
    """
    try:
        return fn()
    except Exception as error:
        # Same truthy set the rest of the tree uses (utils.utils, utils.transformers_version).
        if os.environ.get("UNSLOTH_DEBUG", "").strip().lower() in ("1", "true", "yes", "on"):
            raise
        # Not at module scope: this module must pull in nothing beyond the inventory layer (test_catalog_inventory_works_without_fastapi_or_routes).
        import typer

        typer.echo(
            f"Could not read one model source ({fn.__name__}): {type(error).__name__}: {error}. "
            f"Set UNSLOTH_DEBUG=1 for the traceback.",
            err = True,
        )
        return []


def _shorten_names(entries: List[ModelEntry]) -> None:
    # Count every visible label: an unprefixed fine-tune can collide once prefixes are shortened.
    counts = {}
    for entry in entries:
        short = entry.name.split("/")[-1].lower()
        counts[short] = counts.get(short, 0) + 1
    for entry in entries:
        if "/" not in entry.name:
            continue
        short = entry.name.split("/")[-1]
        if counts[short.lower()] == 1:
            entry.name = short


def _dedup_key(model: str):
    """Identity of a load target, for collapsing the same model reached by two sources.

    For anything that exists on disk the filesystem is ASKED rather than guessed: two paths
    are the same model when they are the same inode. That is the only rule that holds across
    the three cases that actually differ, and no platform test gets all three right --
    ``/models/Foo`` and ``/models/foo`` are two models on ext4, one model on NTFS, and one
    model on a stock case-insensitive APFS volume, where ``os.path.normcase`` is identity and
    would wrongly have shown the user the same model twice. It also collapses a path reached
    once directly and once through a symlink, which the old key could not see at all.

    Falling back on a string is only for what cannot be stat'd: a bare repo id, or a path that
    has gone away since the scan. A repo id keeps the case-insensitive treatment, since the Hub
    resolves ``Unsloth/Qwen3`` and ``unsloth/qwen3`` to one repo and the cache folds them into
    one directory; a vanished path uses ``normcase``, which at worst leaves two rows for a model
    that is not loadable from either of them.
    """
    try:
        stat = os.stat(model)
        return (stat.st_dev, stat.st_ino)
    except (OSError, ValueError):
        return os.path.normcase(model) if os.path.isabs(model) else model.lower()


def list_chat_models() -> List[ModelEntry]:
    entries = []
    for fn in (trained_entries, exported_entries, cached_entries, local_folder_entries):
        entries.extend(_safe(fn))
    seen = set()
    unique = []
    for entry in entries:
        key = _dedup_key(entry.model)
        if key in seen:
            continue
        seen.add(key)
        unique.append(entry)
    _shorten_names(unique)
    return unique