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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Family evidence from a Hub safetensors header (SDXL only); advisory, the load check stays final;
remote pipeline picks need no evidence (trusted repos); detect_family_for_pick is network-free;
prefetch_for_pick only for user requests."""
from __future__ import annotations
import threading
import time
from pathlib import Path
from typing import Any, Optional
_SINGLE_FILE_SUFFIXES = (".safetensors", ".sft")
# (repo id lowercased, filename) -> (monotonic time read, family name or None for a header that names no family).
# Only bridges a request's prefetch to the validation and load that follow it; a refresh REPLACES an entry (never
# clears it first, so an overlapping request keeps seeing the last good read), and an entry expires on its own.
_HEADER_VERDICTS: dict[tuple[str, str], tuple[float, Optional[str]]] = {}
_LOCK = threading.Lock()
_MAX_VERDICTS = 1024
_VERDICT_TTL_S = 600.0
def is_hub_id(repo_id: Optional[str]) -> bool:
"""True for a bare ``owner/name`` that is not a path on this machine."""
rid = (repo_id or "").strip()
if rid.count("/") != 1 or "\\" in rid or rid.startswith((".", "/", "~")):
return False
try:
return not Path(rid).expanduser().exists()
except (OSError, RuntimeError, ValueError):
return True
def _is_single_file(filename: Optional[str]) -> bool:
return bool(filename) and str(filename).lower().endswith(_SINGLE_FILE_SUFFIXES)
def _key(repo_id: str, filename: str) -> tuple[str, str]:
return repo_id.strip().lower(), str(filename).strip()
def _dit_family(info: Any) -> Optional[str]:
"""The whole-pipeline family (SDXL) a header classifies as, or None. A denoiser-only file (a bare
UNet with no text encoders or VAE) is not evidence: SDXL loads its single file through the WHOLE
pipeline's ``from_single_file``."""
from .diffusion_content import ROLE_DIT
from .diffusion_families import detect_family
if info.role != ROLE_DIT or not info.whole_pipeline or not info.family:
return None
fam = detect_family("", override = info.family)
return info.family if fam is not None and fam.single_file_is_pipeline else None
def _verdict(key: tuple[str, str]) -> tuple[bool, Optional[str]]:
"""``(known, family)`` for a remembered header read that has not expired."""
with _LOCK:
hit = _HEADER_VERDICTS.get(key)
if hit is None:
return False, None
if time.monotonic() - hit[0] > _VERDICT_TTL_S:
del _HEADER_VERDICTS[key]
return False, None
return True, hit[1]
def cached_family(repo_id: Optional[str], filename: Optional[str] = None) -> Optional[str]:
"""The family a Hub single-file header declares, from memory or disk only (None if unknown); a
prefetch read off the Hub outranks a cached copy, which may be an older revision."""
if not is_hub_id(repo_id) or not _is_single_file(filename):
return None
repo_id = str(repo_id).strip()
known, family = _verdict(_key(repo_id, str(filename)))
if known:
return family
from .diffusion_compat import _local_gguf_path
local = _local_gguf_path(repo_id, str(filename))
if not local:
return None
from .diffusion_content import inspect_checkpoint
return _dit_family(inspect_checkpoint(local))
def read_hub_checkpoint_family(
repo_id: str,
filename: str,
hf_token: Any,
revision: Optional[str] = None,
) -> Optional[str]:
"""Identify a bundled pipeline by its tensor header, independent of the repo and file names."""
from huggingface_hub import HfApi
from .diffusion_content import classify_tensors
from hub.utils.hf_tokens import normalize_token
token = normalize_token(hf_token)
meta = HfApi().parse_safetensors_file_metadata(
repo_id, filename, token = token, revision = revision
)
shapes = {name: list(info.shape) for name, info in meta.tensors.items()}
return _dit_family(classify_tensors(shapes, meta.metadata))
def prefetch_for_pick(
repo_id: Optional[str],
filename: Optional[str],
family_override: Optional[str],
hf_token: Any,
allow_network: bool = True,
) -> None:
"""Reads a picked single file's header off the Hub (range read, nothing cached) when name, path
and content gave no verdict; allow_network=False does nothing; hf_token passes through, False
stays anonymous; fails open."""
if (
not allow_network
or family_override
or not is_hub_id(repo_id)
or not _is_single_file(filename)
):
return
repo_id = str(repo_id).strip()
filename = str(filename)
try:
from .diffusion_families import _family_from_hub_evidence, detect_family_for_pick
# Skip only when the name, a local path or the content answered; an answer from Hub evidence is re-read.
if (
detect_family_for_pick(repo_id, filename, None) is not None
and _family_from_hub_evidence(repo_id, filename) is None
):
return
family = read_hub_checkpoint_family(repo_id, filename, hf_token)
except Exception: # noqa: BLE001 - evidence is best effort; validation and the load still decide
return
_remember(repo_id, filename, family)
def _remember(repo_id: str, filename: str, family: Optional[str]) -> None:
with _LOCK:
if len(_HEADER_VERDICTS) >= _MAX_VERDICTS:
_HEADER_VERDICTS.clear()
_HEADER_VERDICTS[_key(repo_id, filename)] = (time.monotonic(), family)
def hub_checkpoint_loads_as_sdxl(
repo_id: str,
filename: str,
hf_token: Any,
revision: Optional[str] = None,
) -> bool:
"""A whole-SDXL header AND the loader's own verdict, so name-vetoed variants (inpaint, edit) are not offered."""
from .diffusion_families import detect_family_for_pick
family = read_hub_checkpoint_family(repo_id, filename, hf_token, revision)
if family != "sdxl":
return False
_remember(repo_id, filename, family)
fam = detect_family_for_pick(repo_id, filename, None)
return fam is not None and fam.name == "sdxl"