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.

21.5 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

"""Image PNGs in workspace_root()/images; recipe in an unsloth JSON text chunk (source of truth)"""

from __future__ import annotations

import base64
import errno
import functools
import json
import os
import re
import sys
import threading
import uuid
from collections import OrderedDict
from collections.abc import Callable, Iterable, Iterator
from pathlib import Path
from typing import Any, Optional

from core.inference import gallery_flags, png_encode
from loggers import get_logger
from utils.account_context import is_owner_context
from utils.paths import ensure_account_dir, studio_root
from utils.paths.relocations import location_dir
from utils.paths.storage_roots import account_path

logger = get_logger(__name__)

# PNG text-chunk key holding our structured recipe JSON.
_META_KEY = "unsloth"
# Absent on PNGs written before it existed.
RECIPE_SCHEMA_VERSION = 1
# Image ids are file stems; restrict to safe chars so a crafted id can't escape the directory.
_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")


def gallery_dir() -> Path:
    if is_owner_context():
        return location_dir("images", studio_root() / "images")
    return ensure_account_dir(account_path("images"))


_IMG2IMG_WORKFLOWS = ("img2img", "inpaint", "outpaint", "edit", "upscale")


def _params_text(meta: dict[str, Any]) -> str:
    """Automatic1111-style ``parameters`` string for cross-tool interop."""
    from core.inference.diffusion_hires import infotext_fields as hires_infotext, infotext_meta

    grid = meta.get("xy_grid") or {}
    if grid.get("cell_width") and grid.get("cell_height"):
        # An X/Y grid's recipe is its first cell's: A1111 writes the cell size, not the grid's pixels.
        meta = {**meta, "width": grid["cell_width"], "height": grid["cell_height"]}
    # A Hires fix image is written the way A1111 writes one: Size is the base pass, Hires upscale the factor.
    meta = infotext_meta(meta)
    # The enhanced prompt the model encoded; other tools reproduce the image from this line.
    lines = [str(meta.get("enhanced_prompt") or meta.get("prompt", ""))]
    negative = meta.get("negative_prompt")
    if negative:
        lines.append(f"Negative prompt: {negative}")
    from core.inference.diffusion_sampler import sampler_label, schedule_label

    if meta.get("model_kind") == "connection":
        lines.append(
            f"Size: {meta.get('width')}x{meta.get('height')}, Model: {meta.get('model', '')}"
        )
        return "\n".join(lines)
    sampler = sampler_label(meta.get("sampler"))
    schedule = schedule_label(meta.get("schedule_type"))
    fields = (
        f"Steps: {meta.get('steps')}, "
        + (f"Sampler: {sampler}, " if sampler else "")
        + (f"Schedule type: {schedule}, " if schedule else "")
        + f"CFG scale: {meta.get('guidance')}, "
        f"Seed: {meta.get('seed')}, Size: {meta.get('width')}x{meta.get('height')}, "
        f"Model: {meta.get('model', '')}"
    )
    # webui infotext names (processing.create_infotext).
    if meta.get("variation_strength"):
        fields += (
            f", Variation seed: {meta.get('variation_seed')}, "
            f"Variation seed strength: {meta['variation_strength']}"
        )
    if meta.get("clip_skip"):
        fields += f", Clip skip: {meta['clip_skip']}"
    if meta.get("cfg_rescale"):
        fields += f", CFG rescale: {meta['cfg_rescale']}"
    # webui opts.emphasis infotext: a prompt run with weighting off replays literally there too.
    if meta.get("prompt_weighting") is False:
        fields += ", Emphasis: None"
    if meta.get("workflow") in _IMG2IMG_WORKFLOWS and meta.get("strength") is not None:
        fields += f", Denoising strength: {meta['strength']}"
    # A1111 inpaint keys (modules/processing.py), only when this inpaint applied them.
    if meta.get("mask_blur"):
        fields += f", Mask blur: {meta['mask_blur']}"
    if meta.get("inpaint_only_masked"):
        fields += ", Inpaint area: Only masked"
        if meta.get("inpaint_padding") is not None:
            fields += f", Masked area padding: {meta['inpaint_padding']}"
    fields += hires_infotext(meta)
    # Static flow shift, read back by the paste parser; base / max shift stay in the recipe chunk only.
    if meta.get("shift") is not None:
        fields += f", Shift: {meta['shift']}"
    # ADetailer's own keys (adetailer/args.py), so a paste into Studio or a webui with ADetailer restores the pass.
    if meta.get("detailer"):
        from core.inference.diffusion_detailer import infotext_fields
        fields += infotext_fields(meta["detailer"])
    if meta.get("generator"):
        fields += f", Version: {meta['generator']}"
    lines.append(fields)
    return "\n".join(lines)


# Pillow's default zlib level 6 costs ~0.4 s per 1024x1024 PNG on the request path; level 1 ~0.1 s, ~10% larger, lossless.
PNG_COMPRESS_LEVEL_ENV = "UNSLOTH_IMAGE_PNG_COMPRESS_LEVEL"
_DEFAULT_PNG_COMPRESS_LEVEL = 1


def png_compress_level() -> int:
    raw = os.environ.get(PNG_COMPRESS_LEVEL_ENV, "").strip()
    try:
        level = int(raw)
    except ValueError:
        return _DEFAULT_PNG_COMPRESS_LEVEL
    return level if 0 <= level <= 9 else _DEFAULT_PNG_COMPRESS_LEVEL


def _png_bytes(image: Any, meta: dict[str, Any]) -> bytes:
    import io

    from PIL.PngImagePlugin import PngInfo

    info = PngInfo()
    info.add_text(_META_KEY, json.dumps(meta))
    info.add_text("parameters", _params_text(meta))
    data = png_encode.encode(image, pnginfo = info, compress_level = png_compress_level())
    if data is not None:
        return data
    buf = io.BytesIO()
    image.save(buf, format = "PNG", pnginfo = info, compress_level = png_compress_level())
    return buf.getvalue()


@functools.lru_cache(maxsize = 1)
def _generator() -> str:
    try:
        from utils.studio_version import get_studio_version
        return f"Unsloth {get_studio_version()}"
    except Exception:
        return "Unsloth"


def _engine() -> Optional[str]:
    # Read only when a generation already loaded the router: diffusers and the native engine draw
    # different pixels from the same seed, so a replay needs to know which one ran.
    router = sys.modules.get("core.inference.diffusion_engine_router")
    try:
        return router.active_engine_name() if router is not None else None
    except Exception:
        return None


def _recipe(meta: dict[str, Any]) -> dict[str, Any]:
    return {
        # A Connection run never touched the local engine.
        "engine": None if meta.get("model_kind") == "connection" else _engine(),
        "generator": _generator(),
        **meta,
        "schema_version": RECIPE_SCHEMA_VERSION,
    }


def save(image: Any, meta: dict[str, Any]) -> dict[str, Any]:
    """Persist a PIL image with its recipe embedded; return the gallery record."""
    image_id = uuid.uuid4().hex
    meta = _recipe(meta)
    # Encoded before the folder lookup so a mid-encode Settings move cannot misfile the image.
    data = _encoded_ahead(image, meta)
    if data is None:
        data = _png_bytes(image, meta)
    return _publish(image_id, meta, data)


# Pillow releases the GIL while it filters and deflates, so a batch's PNGs encode side by side.
_MAX_ENCODE_WORKERS = 8
_ahead = threading.local()


def _encoded_ahead(image: Any, meta: dict[str, Any]) -> Optional[bytes]:
    """The PNG ``save_many`` already encoded from this image and this exact recipe, else None."""
    pending = getattr(_ahead, "pending", None)
    entry = pending.pop(id(image), None) if pending else None
    if entry is None or entry[0] is not image or list(entry[1].items()) != list(meta.items()):
        return None
    return entry[2].result()


def save_many(items: Iterable[tuple[Any, dict[str, Any]]]) -> Iterator[dict[str, Any]]:
    """Saves each item in order with PNGs encoded concurrently up front; results match a plain save loop."""
    items = list(items)
    cpus = getattr(os, "process_cpu_count", os.cpu_count)() or 1
    workers = min(len(items), cpus, _MAX_ENCODE_WORKERS)
    # One image object twice would be loaded by two threads at once.
    if workers < 2 or len({id(image) for image, _ in items}) < len(items):
        for image, meta in items:
            yield save(image, meta)
        return
    from concurrent.futures import ThreadPoolExecutor

    with ThreadPoolExecutor(max_workers = workers, thread_name_prefix = "gallery-png") as pool:
        pending = {}
        for image, meta in items:
            recipe = _recipe(meta)
            pending[id(image)] = (image, recipe, pool.submit(_png_bytes, image, recipe))
        futures = [entry[2] for entry in pending.values()]
        _ahead.pending = pending
        # The gallery sorts by mtime and back-to-back writes can tie (Windows ~15.6 ms tick): keep each strictly newer.
        _ahead.floor_ns = None
        try:
            for image, meta in items:
                yield save(image, meta)
        finally:
            if getattr(_ahead, "pending", None) is pending:
                _ahead.pending = None
                _ahead.floor_ns = None
            for future in futures:
                future.cancel()


def _publish(image_id: str, meta: dict[str, Any], data: bytes) -> dict[str, Any]:
    directory = gallery_dir()
    final_path = directory / f"{image_id}.png"
    # Dotted temp (skipped by the *.png glob) then atomic rename: no truncated PNG in the listing.
    tmp_path = directory / f".{image_id}.png.tmp"
    try:
        tmp_path.write_bytes(data)
        os.replace(tmp_path, final_path)
    except BaseException:
        try:
            tmp_path.unlink(missing_ok = True)
        except OSError:
            pass
        raise
    if getattr(_ahead, "pending", None) is not None:
        _keep_after_previous(final_path)
    return _record(image_id, meta, directory = directory)


def _keep_after_previous(path: Path) -> None:
    """In a ``save_many`` batch, move ``path``'s mtime 1 us past the previous image's when it is not already later."""
    try:
        stat = path.stat()
        mtime_ns = stat.st_mtime_ns
        floor = getattr(_ahead, "floor_ns", None)
        if floor is not None and mtime_ns <= floor:
            mtime_ns = floor + 1000
            os.utime(path, ns = (stat.st_atime_ns, mtime_ns))
        _ahead.floor_ns = mtime_ns
    except OSError:
        pass


def _record(
    image_id: str,
    meta: dict[str, Any],
    flags: Optional[dict[str, dict[str, Any]]] = None,
    *,
    directory: Optional[Path] = None,
    mtime: Optional[float] = None,
) -> dict[str, Any]:
    if directory is None:
        directory = gallery_dir()
    # flags are library state, not recipe: they come from the sidecar store, never the PNG chunk
    if flags is None:
        flags = gallery_flags.read(directory)
    if mtime is None:
        mtime = _mtime(directory / f"{image_id}.png")
    return {
        **meta,
        "id": image_id,
        "url": f"/api/inference/images/gallery/{image_id}/file",
        **gallery_flags.flags_for(flags, image_id),
        # The server's own sort key, so a client re-sort agrees with it (created_at can differ).
        "order_at": gallery_flags.order_rank(flags, image_id, mtime),
    }


def image_path(image_id: str) -> Optional[Path]:
    """Resolve an id to its on-disk PNG, or None if missing / unsafe."""
    if not _ID_RE.match(image_id):
        return None
    directory = gallery_dir()
    path = directory / f"{image_id}.png"
    try:
        path.resolve().relative_to(directory.resolve())
    except ValueError:
        return None
    return path if path.is_file() else None


def image_b64(image_id: str) -> Optional[str]:
    path = image_path(image_id)
    if path is None:
        return None
    return base64.b64encode(path.read_bytes()).decode("ascii")


# A PNG missing any required key is skipped as foreign so it cannot 500 the listing.
_REQUIRED_META = ("prompt", "width", "height", "steps", "guidance", "seed", "created_at")


def _parse_meta(raw: Any) -> Optional[dict[str, Any]]:
    if not raw:
        return None
    try:
        meta = json.loads(raw)
    except (ValueError, TypeError):
        return None
    if not isinstance(meta, dict) or any(k not in meta for k in _REQUIRED_META):
        return None
    return meta


def _read_chunk(path: Path, *, strict_io: bool = False) -> tuple[Any, bool]:
    """(raw recipe chunk or None, whether a retry could read something else)."""
    from PIL import Image
    try:
        with Image.open(path) as im:
            # The chunk is written before IDAT; im.text would decode every pixel to find later chunks.
            return im.info.get(_META_KEY) or im.text.get(_META_KEY), False  # type: ignore[attr-defined]
    except OSError as exc:
        if strict_io and exc.errno not in (None, errno.ENOENT):
            raise
        return None, True
    except MemoryError:
        return None, True
    except Exception:
        return None, False


def _read_meta(path: Path, *, strict_io: bool = False) -> Optional[dict[str, Any]]:
    return _parse_meta(_read_chunk(path, strict_io = strict_io)[0])


_CHUNK_CACHE_MAX = 8192
_CHUNK_CACHE_ITEM_MAX = 64 * 1024
_CHUNK_CACHE_BYTES = 32 * 1024 * 1024
_chunk_cache: OrderedDict[str, tuple[tuple, Any, int]] = OrderedDict()
_chunk_cache_bytes = 0
_chunk_cache_lock = threading.Lock()


def _listed_meta(path: Path, info: Optional[os.stat_result]) -> Optional[dict[str, Any]]:
    """``_read_meta(path)``, reparsed only once the file changed since ``info`` (stat taken before)."""
    if info is None:
        return _read_meta(path)
    # A write moves mtime or ctime and a replace the inode, so a key that agrees means the same bytes.
    key = (info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns, info.st_ctime_ns)
    name = str(path)
    with _chunk_cache_lock:
        hit = _chunk_cache.get(name)
        if hit is not None and hit[0] == key:
            _chunk_cache.move_to_end(name)
            return _parse_meta(hit[1])
    raw, transient = _read_chunk(path)
    size = len(raw) if isinstance(raw, (str, bytes)) else 0
    if transient or size > _CHUNK_CACHE_ITEM_MAX:
        return _parse_meta(raw)
    global _chunk_cache_bytes
    with _chunk_cache_lock:
        old = _chunk_cache.pop(name, None)
        _chunk_cache[name] = (key, raw, size)
        _chunk_cache_bytes += size - (old[2] if old else 0)
        while len(_chunk_cache) > _CHUNK_CACHE_MAX or _chunk_cache_bytes > _CHUNK_CACHE_BYTES:
            _chunk_cache_bytes -= _chunk_cache.popitem(last = False)[1][2]
    return _parse_meta(raw)


def owned_image_path(image_id: str) -> Optional[Path]:
    """Returns None unless the PNG is Unsloth-owned, so a guessed id cannot stream a hand-dropped file."""
    path = image_path(image_id)
    if path is None or _read_meta(path) is None:
        return None
    return path


def thumbnail(path: Path, size: int) -> bytes:
    """Return a WebP thumbnail with its longest side at most ``size`` pixels."""
    import io

    from PIL import Image

    with Image.open(path) as im:
        im.thumbnail((size, size), Image.LANCZOS)
        if im.mode not in ("RGB", "RGBA"):
            im = im.convert("RGBA" if "A" in im.getbands() or "transparency" in im.info else "RGB")
        buf = io.BytesIO()
        im.save(buf, format = "WEBP", quality = 85, method = 4)
    return buf.getvalue()


def _mtime(path: Path) -> float:
    try:
        return path.stat().st_mtime
    except OSError:
        return 0.0


def list_images(
    limit: Optional[int] = None,
    offset: int = 0,
    *,
    valid: Optional[Callable[[dict[str, Any]], bool]] = None,
    archived: bool = False,
) -> list[dict[str, Any]]:
    """Pinned first, then mtime; archived selects a shelf, never widens; valid filter runs before paging."""
    try:
        directory = gallery_dir()
        paths = list(directory.glob("*.png"))
    except OSError:
        return []
    flags = gallery_flags.read(directory)
    # Shelf split and pin sort use file stems before any recipe read, keeping the early break intact.
    paths = [p for p in paths if gallery_flags.is_archived(flags, p.stem) == archived]
    # The sort's stat keys the recipe read, so it must precede it.
    stats: dict[Path, os.stat_result] = {}

    def mtime(path: Path) -> float:
        try:
            stats[path] = info = path.stat()
        except OSError:
            return 0.0
        return info.st_mtime

    paths.sort(
        key = lambda p: (
            gallery_flags.pin_rank(flags, p.stem),
            gallery_flags.order_rank(flags, p.stem, mtime(p)),
        ),
        reverse = True,
    )
    # Page over readable records, not raw files, or has_more is wrong. Deep scroll is O(offset).
    want = None if limit is None else offset + limit
    records = []
    for path in paths:
        info = stats.get(path)
        meta = _listed_meta(path, info)
        if meta is None:
            continue
        record = _record(
            path.stem,
            meta,
            flags,
            directory = directory,
            mtime = None if info is None else info.st_mtime,
        )
        if valid is not None and not valid(record):
            continue
        records.append(record)
        if want is not None and len(records) >= want:
            break
    return records[offset:] if limit is None else records[offset : offset + limit]


def set_flags(
    image_id: str,
    *,
    pinned: Optional[bool] = None,
    archived: Optional[bool] = None,
) -> Optional[dict[str, Any]]:
    """Returns None unless the id is Unsloth-owned, so a hand-dropped foreign PNG cannot become
    flaggable."""
    # Check and write under one lock so a concurrent clear cannot delete the file between them.
    with gallery_flags.exclusive(gallery_dir()):
        path = owned_image_path(image_id)
        if path is None:
            return None
        gallery_flags.set_flags_locked(gallery_dir(), image_id, pinned = pinned, archived = archived)
        meta = _read_meta(path)
    if meta is None:  # raced a delete between the guard and the read
        return None
    return _record(image_id, meta)


def move(image_id: str, after_id: Optional[str]) -> Optional[dict[str, Any]]:
    """Moves an owned, active image after after_id (None = front) and returns its record, or None if
    the id is not owned and active; KeyError if after_id is not on the shelf."""
    with gallery_flags.exclusive(gallery_dir()):
        path = owned_image_path(image_id)
        if path is None:
            return None
        flags = gallery_flags.read(gallery_dir())
        if gallery_flags.is_archived(flags, image_id):
            return None
        # Full shelf in listing order, so neighbours past the client's loaded window are known.
        try:
            paths = [
                p
                for p in gallery_dir().glob("*.png")
                if not gallery_flags.is_archived(flags, p.stem)
            ]
        except OSError:
            paths = []
        keyed = [(p.stem, _mtime(p)) for p in paths]
        keyed.sort(
            key = lambda pair: (
                gallery_flags.pin_rank(flags, pair[0]),
                gallery_flags.order_rank(flags, pair[0], pair[1]),
            ),
            reverse = True,
        )
        gallery_flags.place_locked(gallery_dir(), image_id, keyed, after_id = after_id)
        meta = _read_meta(path)
    if meta is None:  # raced a delete between the guard and the read
        return None
    return _record(image_id, meta)


def delete(image_id: str) -> bool:
    path = image_path(image_id)
    # a hand-dropped foreign PNG is invisible to list_images, so a guessed id must not destroy it
    if path is None or _read_meta(path, strict_io = True) is None:
        if _ID_RE.fullmatch(image_id):
            # Only prune absent files, preserving foreign files and symlinks.
            try:
                (gallery_dir() / f"{image_id}.png").lstat()
            except FileNotFoundError:
                gallery_flags.forget(gallery_dir(), [image_id])
        return False
    removed = True
    try:
        path.unlink()
    except FileNotFoundError:
        removed = False
    except OSError as exc:
        logger.warning("image_gallery.delete_failed: %s", exc)
        # Propagate I/O failures instead of reporting a missing image.
        raise
    # drop the flags with the file, so the id cannot hand out a stale pin and the store cannot grow forever
    gallery_flags.forget(gallery_dir(), [image_id])
    return removed


def clear(include_archived: bool = False) -> int:
    """Owned PNGs only; archived spared unless include_archived; fails closed if flags unreadable."""
    removed = 0
    directory = gallery_dir()
    # Hold the flag lock across read-then-delete, or an archive landing mid-loop gets deleted.
    with gallery_flags.exclusive(directory):
        # read flags BEFORE listing: nothing is unlinked if the store turns out to be untrusted
        flags = {} if include_archived else gallery_flags.read_trusted(directory)
        try:
            paths = list(directory.glob("*.png"))
        except OSError:
            return 0
        cleared: list[str] = []
        for path in paths:
            if _read_meta(path) is None:
                continue
            if not include_archived and gallery_flags.is_archived(flags, path.stem):
                continue
            try:
                path.unlink()
                removed += 1
                cleared.append(path.stem)
            except OSError:
                continue
        # Every owned image is gone, so replace the untrusted store or later clears keep refusing.
        if include_archived and not gallery_flags.is_trusted(directory):
            gallery_flags.reset_locked(directory)
        else:
            gallery_flags.forget_locked(directory, cleared)
    return removed