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
"""DFlash sidecar discovery for a local GGUF model. DFlash is published as a ``dflash-`` prefixed sibling of the weights it drafts for, so discovery is a naming question first and a header question second. That order is deliberate: a caller with a directory lease (a native grant) hands in ``accept``, and that has to answer before anything is opened, because reading the header of a symlink pointing out of the lease is the very thing the lease exists to prevent, and no later rejection takes a read back."""
import logging
import os
from pathlib import Path
from typing import Callable, Optional
from utils.models.gguf_metadata import read_gguf_architecture
from utils.models.drafters.common import (
_drafter_launch_path,
_drafter_matches_weight,
_drafter_names_other_weight,
_drafter_split_is_complete,
_drafter_stem_rank,
_drafter_total_size,
)
from utils.models.drafters.preference import (
dflash_precision_rank,
dflash_preference_key,
dflash_repo_preference_key,
)
logger = logging.getLogger(__name__)
def is_dflash_architecture(path: str) -> bool:
"""Decided by header general.architecture = dflash, which no real weight declares; a dflash- filename can name a real weight, so downloads trust only the header."""
return (read_gguf_architecture(str(path)) or "").lower() == "dflash"
def detect_dflash_file(
path: str,
search_root: Optional[str] = None,
accept: Optional[Callable[[str], bool]] = None,
) -> Optional[str]:
"""Root level only, not dflash/ (a family name for real weights); header checked, since dflash-kquant.gguf names no family; a family-named sidecar ranks first."""
from utils.models.model_config import _local_gguf_load_path
def _rank(candidate: Path) -> tuple[int, int, int, int, str]:
# A sidecar naming THIS weight's family first, then any unpaired one, then precision, then total size so a split copy cannot outrank a smaller single file, then name for a stable order.
paired = _drafter_matches_weight(candidate.name, weight_name, kind = "dflash")
return (
0 if paired else 1,
_drafter_stem_rank(candidate.name, kind = "dflash") if paired else 0,
dflash_precision_rank(candidate.name),
_drafter_total_size(candidate),
candidate.name.lower(),
)
p = Path(path)
weight_name = p.name if p.suffix.lower() == ".gguf" else None
start_dir = p.parent if p.is_file() else p
# Not assets/: the sidecar names no family, so it is ambiguous in Hermes' shared pool.
dirs = [start_dir]
if search_root is not None:
dirs.append(Path(search_root))
candidates: list[Path] = []
other_weights: list[str] = []
seen: set[Path] = set()
# dict.fromkeys: search_root is the weight's own parent for a flat layout, and scanning it twice doubles the directory reads for nothing.
for root in dict.fromkeys(dirs):
try:
entries = list(root.iterdir())
except OSError:
continue
for candidate in entries:
lower = candidate.name.lower()
if not lower.endswith(".gguf"):
continue
# Prefix form only: the shared predicates (_drafter_path_kind / is_mtp_drafter_path) know DFlash by the dflash- prefix, so accepting <model>-dflash.gguf would make one file both a drafter and a selectable Q8_0 main model (#7811). No published DFlash sidecar uses the suffix form; the shipped one is dflash-kquant.gguf.
if not lower.startswith("dflash-"):
# Every other GGUF in the folder is a weight some sidecar could be naming. Recorded so a sidecar belonging to a NEIGHBOUR can be told apart from one naming no family at all (below).
other_weights.append(candidate.name)
continue
try:
# Collapse a split copy to shard 1 before ranking.
launch = _local_gguf_load_path(candidate)
# is_file() follows the link, so this also drops a dangling snapshot symlink and a directory named like a sidecar, which --model-draft cannot open and which fails the whole load. detect_dspark_file guards the same way.
if not (launch.is_file() and _drafter_split_is_complete(launch)):
continue
resolved = launch.resolve()
except OSError:
continue
if resolved in seen:
continue
seen.add(resolved)
candidates.append(launch)
# A sidecar naming a NEIGHBOUR weight's family is that neighbour's drafter: ranking alone floated the foreign one to the top, so loading model B beside dflash-model-A-Q8_0.gguf and dflash-kquant.gguf launched model A's drafter for model B, and both carry a real dflash header so the architecture check cannot catch it. _drafter_names_other_weight decides against the weights actually present and is shared with the remote paths through dflash_repo_preference_key.
if weight_name is not None and other_weights:
kept: list[Path] = []
for candidate in candidates:
if _drafter_names_other_weight(candidate.name, weight_name, other_weights):
logger.info(
"detect_dflash_file: dropped %s (names another weight in this folder)",
candidate.name,
)
continue
kept.append(candidate)
candidates = kept
for candidate in sorted(candidates, key = _rank):
# Resolve and validate before opening anything: a dflash-*.gguf reached through a native grant can be a symlink outside the lease, and reading the header first cannot be undone.
try:
launch = _drafter_launch_path(candidate)
except OSError:
continue
if accept is not None and not accept(launch):
logger.info(
"detect_dflash_file: dropped %s (outside the granted directory)",
candidate.name,
)
continue
if not is_dflash_architecture(launch):
logger.info(
"detect_dflash_file: dropped %s (architecture %r is not dflash)",
candidate.name,
# Re-read only on the reject path, and header reads are cached by (path, mtime, size), so naming the offending architecture in the log costs nothing.
read_gguf_architecture(launch),
)
continue
logger.info("Detected DFlash drafter: %s", launch)
return launch
return None