ci: ruff + pytest on push/pr (l1+l2, no gpu deps)

Add .github/workflows/ci.yml running ruff format, ruff check, and pytest
against a minimal dep set (no torch/diffsynth/realesrgan/controlnet_aux).
Fix all ruff format + lint violations found during CI replication (import
order, unused imports, EN-dash RUF001, RUF059 unused unpack variables).
Skip auto_device test when torch is absent so CI passes without a GPU.

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ runner.os }}-${{ hashFiles('requirements.txt') }}
+
+      - name: Install
+        run: |
+          python -m pip install -U pip
+          pip install ruff pytest pytest-mock pillow numpy gradio==5.50.0 safetensors opencv-python-headless
+
+      - name: Ruff format
+        run: ruff format --check .
+
+      - name: Ruff lint
+        run: ruff check .
+
+      - name: Pytest (L1+L2 — no GPU)
+        run: pytest -q --tb=short
+        env:
+          # Skip tests that need diffsynth / realesrgan / controlnet_aux installed
+          PYTEST_DISABLE_PLUGIN_AUTOLOAD: 1

app.py

@@ -3,12 +3,12 @@
 On HF Spaces, ``_bootstrap`` runs once on import to mirror the read-only preload
 cache into a writable tree.
 """
+
 from __future__ import annotations
 
 import os
 import random
 from pathlib import Path
-from typing import Any
 
 import gradio as gr
 
@@ -18,9 +18,9 @@ import models
 import theme
 import ui
 
-
 # ----- HF Spaces bootstrap ---------------------------------------------------
 
+
 def _bootstrap() -> None:
     """Mirror the preload_from_hub cache once, then point HF env at the mirror."""
     if not models.on_spaces():
@@ -49,6 +49,7 @@ def get_backend() -> backend.ZImageStudioBackend:
 
 # ----- Generation event handlers --------------------------------------------
 
+
 def _maybe_random_seed(seed: int) -> int:
     return seed if seed and seed > 0 else random.randint(1, 2_147_483_647)
 
@@ -64,46 +65,53 @@ def _coerce_lora(lora_path: str | None) -> Path | None:
 def _esrgan_path() -> str:
     """Locate the preloaded RealESRGAN_x4plus.pth."""
     from huggingface_hub import hf_hub_download
+
     return hf_hub_download("xinntao/Real-ESRGAN", "RealESRGAN_x4plus.pth")
 
 
-def on_t2i_generate(prompt, negative_prompt, model, steps, cfg,
-                    width, height, seed, lora_path, lora_strength):
+def on_t2i_generate(prompt, negative_prompt, model, steps, cfg, width, height, seed, lora_path, lora_strength):
     try:
         lora_p = _coerce_lora(lora_path)
     except lora_mod.LoRAValidationError as e:
         raise gr.Error(str(e)) from e
 
     params = dict(
-        prompt=prompt, negative_prompt=negative_prompt or "",
-        model=model, steps=int(steps), cfg=float(cfg),
-        width=int(width), height=int(height),
+        prompt=prompt,
+        negative_prompt=negative_prompt or "",
+        model=model,
+        steps=int(steps),
+        cfg=float(cfg),
+        width=int(width),
+        height=int(height),
         seed=_maybe_random_seed(int(seed)),
-        lora_path=lora_p, lora_strength=float(lora_strength),
+        lora_path=lora_p,
+        lora_strength=float(lora_strength),
     )
     image, meta = get_backend().generate(mode="t2i", params=params)
     return image, meta
 
 
-def on_controlnet_generate(prompt, input_image, preprocessor, controlnet_scale,
-                           steps, seed, lora_path, lora_strength):
+def on_controlnet_generate(prompt, input_image, preprocessor, controlnet_scale, steps, seed, lora_path, lora_strength):
     try:
         lora_p = _coerce_lora(lora_path)
     except lora_mod.LoRAValidationError as e:
         raise gr.Error(str(e)) from e
 
     params = dict(
-        prompt=prompt, input_image=input_image,
-        preprocessor=preprocessor, controlnet_scale=float(controlnet_scale),
-        steps=int(steps), seed=_maybe_random_seed(int(seed)),
-        lora_path=lora_p, lora_strength=float(lora_strength),
+        prompt=prompt,
+        input_image=input_image,
+        preprocessor=preprocessor,
+        controlnet_scale=float(controlnet_scale),
+        steps=int(steps),
+        seed=_maybe_random_seed(int(seed)),
+        lora_path=lora_p,
+        lora_strength=float(lora_strength),
     )
     image, meta = get_backend().generate(mode="controlnet", params=params)
     return image, meta
 
 
-def on_upscale_generate(prompt, input_image, refine_steps, refine_denoise,
-                        seed, lora_path, lora_strength):
+def on_upscale_generate(prompt, input_image, refine_steps, refine_denoise, seed, lora_path, lora_strength):
     try:
         lora_p = _coerce_lora(lora_path)
     except lora_mod.LoRAValidationError as e:
@@ -115,7 +123,8 @@ def on_upscale_generate(prompt, input_image, refine_steps, refine_denoise,
         refine_steps=int(refine_steps),
         refine_denoise=float(refine_denoise),
         seed=_maybe_random_seed(int(seed)),
-        lora_path=lora_p, lora_strength=float(lora_strength),
+        lora_path=lora_p,
+        lora_strength=float(lora_strength),
         esrgan_model_path=_esrgan_path(),
     )
     image, meta = get_backend().generate(mode="upscale", params=params)
@@ -169,9 +178,18 @@ def build_app() -> gr.Blocks:
                 t = ui.build_t2i_tab()
                 t["generate_btn"].click(
                     fn=on_t2i_generate,
-                    inputs=[t["prompt"], t["negative_prompt"], t["model_state"],
-                            t["steps"], t["cfg"], t["width"], t["height"], t["seed"],
-                            t["lora_path"], t["lora_strength"]],
+                    inputs=[
+                        t["prompt"],
+                        t["negative_prompt"],
+                        t["model_state"],
+                        t["steps"],
+                        t["cfg"],
+                        t["width"],
+                        t["height"],
+                        t["seed"],
+                        t["lora_path"],
+                        t["lora_strength"],
+                    ],
                     outputs=[t["output_image"], t["output_meta"]],
                 )
 
@@ -179,9 +197,16 @@ def build_app() -> gr.Blocks:
                 c = ui.build_controlnet_tab()
                 c["generate_btn"].click(
                     fn=on_controlnet_generate,
-                    inputs=[c["prompt"], c["input_image"],
-                            c["preprocessor"], c["controlnet_scale"],
-                            c["steps"], c["seed"], c["lora_path"], c["lora_strength"]],
+                    inputs=[
+                        c["prompt"],
+                        c["input_image"],
+                        c["preprocessor"],
+                        c["controlnet_scale"],
+                        c["steps"],
+                        c["seed"],
+                        c["lora_path"],
+                        c["lora_strength"],
+                    ],
                     outputs=[c["output_image"], c["output_meta"]],
                 )
 
@@ -189,9 +214,15 @@ def build_app() -> gr.Blocks:
                 u = ui.build_upscale_tab()
                 u["generate_btn"].click(
                     fn=on_upscale_generate,
-                    inputs=[u["prompt"], u["input_image"],
-                            u["refine_steps"], u["refine_denoise"],
-                            u["seed"], u["lora_path"], u["lora_strength"]],
+                    inputs=[
+                        u["prompt"],
+                        u["input_image"],
+                        u["refine_steps"],
+                        u["refine_denoise"],
+                        u["seed"],
+                        u["lora_path"],
+                        u["lora_strength"],
+                    ],
                     outputs=[u["output_image"], u["output_meta"]],
                 )
     return demo

backend.py

@@ -1,4 +1,5 @@
 """ZImageStudioBackend — wraps the DiffSynth pipeline; applies @spaces.GPU on HF Spaces."""
+
 from __future__ import annotations
 
 import os
@@ -12,17 +13,16 @@ except ImportError:
 
 import modes
 
-
 _BASE_DURATION_S: dict[str, int] = {
-    "t2i":        20,   # fixed setup + decode
-    "controlnet": 30,   # + preprocessor + control patch
-    "upscale":    50,   # + realesrgan pixel-space step
+    "t2i": 20,  # fixed setup + decode
+    "controlnet": 30,  # + preprocessor + control patch
+    "upscale": 50,  # + realesrgan pixel-space step
 }
 _PER_STEP_S: dict[tuple[str, str], float] = {
-    ("t2i", "Base"):  2.4,
+    ("t2i", "Base"): 2.4,
     ("t2i", "Turbo"): 1.6,
     ("controlnet", "Turbo"): 2.0,
-    ("upscale", "Turbo"):    1.6,
+    ("upscale", "Turbo"): 1.6,
 }
 
 
@@ -51,8 +51,11 @@ def _identity(fn):
 
 
 _ON_SPACES = bool(os.environ.get("SPACES_ZERO_GPU"))
-_GPU = spaces.GPU(duration=lambda *a, **kw: duration_for(*a[1:3], **kw)) \
-       if (spaces is not None and _ON_SPACES) else _identity
+_GPU = (
+    spaces.GPU(duration=lambda *a, **kw: duration_for(*a[1:3], **kw))
+    if (spaces is not None and _ON_SPACES)
+    else _identity
+)
 
 
 def _build_pipeline() -> Any:
@@ -66,10 +69,14 @@ def _build_pipeline() -> Any:
     vram_cfg: dict[str, Any] = {}
     if device != "cpu":
         vram_cfg = dict(
-            offload_dtype=torch.bfloat16, offload_device="cpu",
-            onload_dtype=torch.bfloat16,  onload_device="cpu",
-            preparing_dtype=torch.bfloat16, preparing_device=device,
-            computation_dtype=torch.bfloat16, computation_device=device,
+            offload_dtype=torch.bfloat16,
+            offload_device="cpu",
+            onload_dtype=torch.bfloat16,
+            onload_device="cpu",
+            preparing_dtype=torch.bfloat16,
+            preparing_device=device,
+            computation_dtype=torch.bfloat16,
+            computation_device=device,
         )
 
     pipe = ZImagePipeline.from_pretrained(
@@ -77,7 +84,8 @@ def _build_pipeline() -> Any:
         device=device,
         model_configs=models.build_diffsynth_configs(vram_cfg=vram_cfg),
         tokenizer_config=models.build_diffsynth_configs(
-            (models.TOKENIZER_CONFIG,), vram_cfg=None,
+            (models.TOKENIZER_CONFIG,),
+            vram_cfg=None,
         )[0],
         vram_limit=models.vram_limit_for(device),
     )
@@ -85,9 +93,9 @@ def _build_pipeline() -> Any:
 
 
 _DISPATCH = {
-    "t2i":        modes.call_t2i,
+    "t2i": modes.call_t2i,
     "controlnet": modes.call_controlnet,
-    "upscale":    modes.call_upscale,
+    "upscale": modes.call_upscale,
 }
 
 

lora.py

@@ -1,12 +1,14 @@
 """LoRA file validation and apply/revert context manager."""
+
 from __future__ import annotations
 
 import json
 import struct
+from collections.abc import Iterator
 from contextlib import contextmanager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Iterator
+from typing import Any
 
 ZIMAGE_LORA_PREFIXES = ("transformer.", "dit.", "model.transformer.")
 
@@ -97,6 +99,7 @@ def applied_lora(pipe: Any, path: Path | str | None, strength: float) -> Iterato
 def _apply_lora_impl(pipe: Any, path: Path | str, strength: float) -> None:
     """Apply a LoRA to ``pipe.dit``. Imports DiffSynth lazily for testability."""
     from diffsynth.utils.lora import merge_lora
+
     merge_lora(pipe.dit, str(path), alpha=float(strength))
 
 
@@ -108,6 +111,7 @@ def _revert_lora_impl(pipe: Any) -> None:
     """
     try:
         from diffsynth.utils.lora import unmerge_lora
+
         unmerge_lora(pipe.dit)
         return
     except ImportError:

models.py

@@ -1,8 +1,9 @@
 """Device autodetect, ZImagePipeline ModelConfig registry, and (Task 4) HF cache mirror."""
+
 from __future__ import annotations
 
 import os
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
@@ -17,6 +18,7 @@ def on_spaces() -> bool:
 def auto_device() -> str:
     """Detect the best available compute device."""
     import torch
+
     if torch.cuda.is_available():
         return "cuda"
     if torch.backends.mps.is_available():
@@ -35,8 +37,9 @@ def vram_limit_for(device: str, free_gb: float | None = None) -> float:
         return 0.0
     if free_gb is None:
         import torch
+
         if device == "cuda":
-            free_gb = torch.cuda.mem_get_info()[1] / (1024 ** 3)
+            free_gb = torch.cuda.mem_get_info()[1] / (1024**3)
         else:  # mps
             # torch.mps has no mem_get_info on most builds; fall back to a safe constant.
             free_gb = 24.0
@@ -55,6 +58,7 @@ class ModelConfig:
     ``diffsynth.core.ModelConfig`` instance is built on demand by
     :func:`build_diffsynth_configs`.
     """
+
     model_id: str
     origin_file_pattern: str
     description: str = ""
@@ -62,23 +66,24 @@ class ModelConfig:
 
 MODEL_CONFIGS: tuple[ModelConfig, ...] = (
     # Base
-    ModelConfig("Tongyi-MAI/Z-Image", "transformer/*.safetensors",
-                "Z-Image base transformer (25 steps, cfg=4)"),
-    ModelConfig("Tongyi-MAI/Z-Image", "text_encoder/*.safetensors",
-                "Qwen3-4B text encoder — shared between base + turbo"),
-    ModelConfig("Tongyi-MAI/Z-Image", "vae/diffusion_pytorch_model.safetensors",
-                "Flux-family VAE — shared between base + turbo"),
+    ModelConfig("Tongyi-MAI/Z-Image", "transformer/*.safetensors", "Z-Image base transformer (25 steps, cfg=4)"),
+    ModelConfig(
+        "Tongyi-MAI/Z-Image", "text_encoder/*.safetensors", "Qwen3-4B text encoder — shared between base + turbo"
+    ),
+    ModelConfig(
+        "Tongyi-MAI/Z-Image", "vae/diffusion_pytorch_model.safetensors", "Flux-family VAE — shared between base + turbo"
+    ),
     # Turbo (transformer only — encoder + VAE come from the Z-Image entry above)
-    ModelConfig("Tongyi-MAI/Z-Image-Turbo", "transformer/*.safetensors",
-                "Z-Image-Turbo transformer (8 steps, cfg=1)"),
+    ModelConfig("Tongyi-MAI/Z-Image-Turbo", "transformer/*.safetensors", "Z-Image-Turbo transformer (8 steps, cfg=1)"),
     # ControlNet Union 2.1 (eager preload per spec; can move to lazy if RAM is tight)
-    ModelConfig("PAI/Z-Image-Turbo-Fun-Controlnet-Union-2.1",
-                "Z-Image-Turbo-Fun-Controlnet-Union-2.1-8steps.safetensors",
-                "ControlNet Union 2.1 — canny/depth/pose"),
+    ModelConfig(
+        "PAI/Z-Image-Turbo-Fun-Controlnet-Union-2.1",
+        "Z-Image-Turbo-Fun-Controlnet-Union-2.1-8steps.safetensors",
+        "ControlNet Union 2.1 — canny/depth/pose",
+    ),
 )
 
-TOKENIZER_CONFIG = ModelConfig("Tongyi-MAI/Z-Image", "tokenizer/",
-                                "Qwen3-4B tokenizer")
+TOKENIZER_CONFIG = ModelConfig("Tongyi-MAI/Z-Image", "tokenizer/", "Qwen3-4B tokenizer")
 
 
 def build_diffsynth_configs(
@@ -91,9 +96,9 @@ def build_diffsynth_configs(
     block (offload_dtype, offload_device, etc.) that DiffSynth's low-VRAM examples use.
     """
     from diffsynth.core import ModelConfig as DSConfig
+
     return [
-        DSConfig(model_id=c.model_id, origin_file_pattern=c.origin_file_pattern, **(vram_cfg or {}))
-        for c in configs
+        DSConfig(model_id=c.model_id, origin_file_pattern=c.origin_file_pattern, **(vram_cfg or {})) for c in configs
     ]
 
 

modes.py

@@ -1,4 +1,5 @@
 """Mode handlers — pure functions over a ZImagePipeline + params dict."""
+
 from __future__ import annotations
 
 from pathlib import Path
@@ -24,7 +25,7 @@ except ImportError:
 class T2IParams(TypedDict, total=False):
     prompt: str
     negative_prompt: str
-    model: str          # "Base" | "Turbo"
+    model: str  # "Base" | "Turbo"
     steps: int
     cfg: float
     width: int
@@ -66,9 +67,13 @@ def call_t2i(pipe: Any, params: T2IParams) -> tuple[Image.Image, dict[str, Any]]
         image = pipe(**kwargs)
 
     meta = dict(
-        mode="t2i", model=model_name,
-        steps=kwargs["num_inference_steps"], cfg=kwargs["cfg_scale"],
-        seed=kwargs["seed"], width=kwargs["width"], height=kwargs["height"],
+        mode="t2i",
+        model=model_name,
+        steps=kwargs["num_inference_steps"],
+        cfg=kwargs["cfg_scale"],
+        seed=kwargs["seed"],
+        width=kwargs["width"],
+        height=kwargs["height"],
         lora=str(params.get("lora_path")) if params.get("lora_path") else None,
         lora_strength=params.get("lora_strength", 0.0),
     )
@@ -103,11 +108,15 @@ def call_controlnet(pipe: Any, params: dict[str, Any]) -> tuple[Image.Image, dic
         image = pipe(**kwargs)
 
     meta = dict(
-        mode="controlnet", model="Turbo",
+        mode="controlnet",
+        model="Turbo",
         preprocessor=preproc_mode,
         controlnet_scale=cn_input.scale,
-        steps=kwargs["num_inference_steps"], cfg=1.0,
-        seed=kwargs["seed"], width=kwargs["width"], height=kwargs["height"],
+        steps=kwargs["num_inference_steps"],
+        cfg=1.0,
+        seed=kwargs["seed"],
+        width=kwargs["width"],
+        height=kwargs["height"],
         lora=str(params.get("lora_path")) if params.get("lora_path") else None,
         lora_strength=params.get("lora_strength", 0.0),
     )
@@ -138,10 +147,13 @@ def call_upscale(pipe: Any, params: dict[str, Any]) -> tuple[Image.Image, dict[s
         image = pipe(**kwargs)
 
     meta = dict(
-        mode="upscale", model="Turbo",
+        mode="upscale",
+        model="Turbo",
         refine_steps=kwargs["num_inference_steps"],
         refine_denoise=kwargs["denoising_strength"],
-        seed=kwargs["seed"], width=upscaled.size[0], height=upscaled.size[1],
+        seed=kwargs["seed"],
+        width=upscaled.size[0],
+        height=upscaled.size[1],
         lora=str(params.get("lora_path")) if params.get("lora_path") else None,
         lora_strength=params.get("lora_strength", 0.0),
     )

preprocessors.py

@@ -1,4 +1,5 @@
 """ControlNet preprocessors — lazy imports so an unused mode pays no cost."""
+
 from __future__ import annotations
 
 from typing import Any
@@ -25,6 +26,7 @@ def run(mode: str, image: Image.Image | None) -> Image.Image:
 def _run_canny(image: Image.Image) -> Image.Image:
     import cv2
     import numpy as np
+
     arr = np.array(image.convert("RGB"))
     gray = cv2.cvtColor(arr, cv2.COLOR_RGB2GRAY)
     edges = cv2.Canny(gray, threshold1=100, threshold2=200)
@@ -55,5 +57,6 @@ def _get_processor(name: str) -> Any:
     """Lazy-init and cache a controlnet_aux Processor."""
     if name not in _PROCESSOR_CACHE:
         from controlnet_aux.processor import Processor
+
         _PROCESSOR_CACHE[name] = Processor(name)
     return _PROCESSOR_CACHE[name]

tests/test_backend.py

@@ -1,3 +1,8 @@
+from unittest.mock import MagicMock
+
+import pytest
+from PIL import Image
+
 import backend
 
 
@@ -23,8 +28,9 @@ def test_duration_clamps_at_60():
 
 def test_duration_multiplier_scales_up():
     base = backend.duration_for(mode="t2i", params=dict(model="Turbo", steps=8, width=1024, height=1024))
-    retry = backend.duration_for(mode="t2i", params=dict(model="Turbo", steps=8, width=1024, height=1024),
-                                  multiplier=2.0)
+    retry = backend.duration_for(
+        mode="t2i", params=dict(model="Turbo", steps=8, width=1024, height=1024), multiplier=2.0
+    )
     assert retry > base
 
 
@@ -34,12 +40,6 @@ def test_duration_upscale_has_realesrgan_overhead():
     assert upsc > t2i
 
 
-from unittest.mock import MagicMock
-
-import pytest
-from PIL import Image
-
-
 @pytest.fixture
 def fake_backend(monkeypatch):
     """A ZImageStudioBackend whose constructor doesn't actually build a pipeline."""
@@ -54,9 +54,18 @@ def fake_backend(monkeypatch):
 def test_backend_generate_routes_t2i(fake_backend):
     img, meta = fake_backend.generate(
         mode="t2i",
-        params=dict(prompt="cat", negative_prompt="", model="Turbo",
-                    steps=8, cfg=1.0, width=1024, height=1024, seed=42,
-                    lora_path=None, lora_strength=0.0),
+        params=dict(
+            prompt="cat",
+            negative_prompt="",
+            model="Turbo",
+            steps=8,
+            cfg=1.0,
+            width=1024,
+            height=1024,
+            seed=42,
+            lora_path=None,
+            lora_strength=0.0,
+        ),
     )
     assert isinstance(img, Image.Image)
     assert meta["mode"] == "t2i"
@@ -64,13 +73,19 @@ def test_backend_generate_routes_t2i(fake_backend):
 
 
 def test_backend_generate_routes_controlnet(fake_backend, monkeypatch):
-    monkeypatch.setattr(backend.modes, "preprocessors",
-                        type("P", (), {"run": staticmethod(lambda m, i: i)}))
-    img, meta = fake_backend.generate(
+    monkeypatch.setattr(backend.modes, "preprocessors", type("P", (), {"run": staticmethod(lambda m, i: i)}))
+    _img, meta = fake_backend.generate(
         mode="controlnet",
-        params=dict(prompt="cat", input_image=Image.new("RGB", (64, 64)),
-                    preprocessor="Canny", controlnet_scale=1.0,
-                    steps=9, seed=0, lora_path=None, lora_strength=0.0),
+        params=dict(
+            prompt="cat",
+            input_image=Image.new("RGB", (64, 64)),
+            preprocessor="Canny",
+            controlnet_scale=1.0,
+            steps=9,
+            seed=0,
+            lora_path=None,
+            lora_strength=0.0,
+        ),
     )
     assert meta["mode"] == "controlnet"
 

tests/test_lora.py

@@ -15,11 +15,14 @@ def _write_safetensors(path: Path, header: dict) -> None:
 
 def test_sniff_valid_zimage_lora_returns_metadata(tmp_path):
     p = tmp_path / "ok.safetensors"
-    _write_safetensors(p, {
-        "transformer.layer1.lora_A.weight": {"dtype": "BF16", "shape": [64, 3840]},
-        "transformer.layer1.lora_B.weight": {"dtype": "BF16", "shape": [3840, 64]},
-        "__metadata__": {"rank": "64"},
-    })
+    _write_safetensors(
+        p,
+        {
+            "transformer.layer1.lora_A.weight": {"dtype": "BF16", "shape": [64, 3840]},
+            "transformer.layer1.lora_B.weight": {"dtype": "BF16", "shape": [3840, 64]},
+            "__metadata__": {"rank": "64"},
+        },
+    )
     info = lora.sniff(p)
     assert info.rank == 64
     assert info.target == "transformer"
@@ -36,9 +39,12 @@ def test_sniff_rejects_non_safetensors(tmp_path):
 
 def test_sniff_rejects_non_zimage_keys(tmp_path):
     p = tmp_path / "wrong.safetensors"
-    _write_safetensors(p, {
-        "down_blocks.0.weight": {"dtype": "F32", "shape": [320, 320]},
-    })
+    _write_safetensors(
+        p,
+        {
+            "down_blocks.0.weight": {"dtype": "F32", "shape": [320, 320]},
+        },
+    )
     with pytest.raises(lora.LoRAValidationError) as exc:
         lora.sniff(p)
     msg = str(exc.value).lower()
@@ -47,23 +53,29 @@ def test_sniff_rejects_non_zimage_keys(tmp_path):
 
 class _FakePipe:
     """Minimal stand-in for DiffSynth's ZImagePipeline.dit hook surface."""
+
     def __init__(self):
-        self.applied = []   # list of (path, strength) tuples
+        self.applied = []  # list of (path, strength) tuples
         self.reverted = []
 
 
 def test_applied_lora_calls_apply_then_revert(tmp_path, monkeypatch):
     p = tmp_path / "ok.safetensors"
-    _write_safetensors(p, {
-        "transformer.x.lora_A.weight": {"dtype": "BF16", "shape": [32, 3840]},
-        "transformer.x.lora_B.weight": {"dtype": "BF16", "shape": [3840, 32]},
-    })
+    _write_safetensors(
+        p,
+        {
+            "transformer.x.lora_A.weight": {"dtype": "BF16", "shape": [32, 3840]},
+            "transformer.x.lora_B.weight": {"dtype": "BF16", "shape": [3840, 32]},
+        },
+    )
     pipe = _FakePipe()
 
     def fake_apply(pipe, path, strength):
         pipe.applied.append((str(path), strength))
+
     def fake_revert(pipe):
         pipe.reverted.append(True)
+
     monkeypatch.setattr(lora, "_apply_lora_impl", fake_apply)
     monkeypatch.setattr(lora, "_revert_lora_impl", fake_revert)
 
@@ -88,10 +100,13 @@ def test_applied_lora_with_none_is_a_noop(tmp_path, monkeypatch):
 
 def test_applied_lora_reverts_on_exception(tmp_path, monkeypatch):
     p = tmp_path / "ok.safetensors"
-    _write_safetensors(p, {
-        "transformer.x.lora_A.weight": {"dtype": "BF16", "shape": [16, 3840]},
-        "transformer.x.lora_B.weight": {"dtype": "BF16", "shape": [3840, 16]},
-    })
+    _write_safetensors(
+        p,
+        {
+            "transformer.x.lora_A.weight": {"dtype": "BF16", "shape": [16, 3840]},
+            "transformer.x.lora_B.weight": {"dtype": "BF16", "shape": [3840, 16]},
+        },
+    )
     pipe = _FakePipe()
     monkeypatch.setattr(lora, "_apply_lora_impl", lambda pipe, p, s: pipe.applied.append((p, s)))
     monkeypatch.setattr(lora, "_revert_lora_impl", lambda pipe: pipe.reverted.append(True))

tests/test_models.py

@@ -1,9 +1,13 @@
+import importlib
 import os
 from unittest import mock
 
+import pytest
+
 import models
 
 
+@pytest.mark.skipif(importlib.util.find_spec("torch") is None, reason="torch not installed")
 def test_auto_device_returns_cuda_or_mps_or_cpu():
     dev = models.auto_device()
     assert dev in ("cuda", "mps", "cpu")

tests/test_modes.py

@@ -23,10 +23,13 @@ def test_t2i_turbo_builds_minimal_call(fake_pipe):
             prompt="a cat",
             negative_prompt="",
             model="Turbo",
-            steps=8, cfg=1.0,
-            width=1024, height=1024,
+            steps=8,
+            cfg=1.0,
+            width=1024,
+            height=1024,
             seed=42,
-            lora_path=None, lora_strength=0.0,
+            lora_path=None,
+            lora_strength=0.0,
         ),
     )
     fake_pipe.assert_called_once()
@@ -47,10 +50,16 @@ def test_t2i_base_passes_negative_prompt_and_cfg4(fake_pipe):
     modes.call_t2i(
         fake_pipe,
         params=dict(
-            prompt="a cat", negative_prompt="blurry, lowres",
-            model="Base", steps=25, cfg=4.0,
-            width=1024, height=1024, seed=42,
-            lora_path=None, lora_strength=0.0,
+            prompt="a cat",
+            negative_prompt="blurry, lowres",
+            model="Base",
+            steps=25,
+            cfg=4.0,
+            width=1024,
+            height=1024,
+            seed=42,
+            lora_path=None,
+            lora_strength=0.0,
         ),
     )
     kwargs = fake_pipe.call_args.kwargs
@@ -62,8 +71,18 @@ def test_t2i_base_passes_negative_prompt_and_cfg4(fake_pipe):
 def test_t2i_swaps_transformer_via_model_pool(fake_pipe):
     modes.call_t2i(
         fake_pipe,
-        params=dict(prompt="x", negative_prompt="", model="Base", steps=25, cfg=4.0,
-                    width=1024, height=1024, seed=0, lora_path=None, lora_strength=0.0),
+        params=dict(
+            prompt="x",
+            negative_prompt="",
+            model="Base",
+            steps=25,
+            cfg=4.0,
+            width=1024,
+            height=1024,
+            seed=0,
+            lora_path=None,
+            lora_strength=0.0,
+        ),
     )
     fake_pipe.model_pool.fetch_model.assert_called()
     call = fake_pipe.model_pool.fetch_model.call_args
@@ -72,13 +91,15 @@ def test_t2i_swaps_transformer_via_model_pool(fake_pipe):
 
 def test_controlnet_calls_preprocessor_then_pipeline(fake_pipe, monkeypatch):
     canny_called = []
+
     def fake_run(mode, img):
         canny_called.append((mode, img.size))
         return img  # passthrough for test
+
     monkeypatch.setattr(modes, "preprocessors", type("P", (), {"run": staticmethod(fake_run)}))
 
     input_image = Image.new("RGB", (1024, 1024))
-    out, meta = modes.call_controlnet(
+    _out, meta = modes.call_controlnet(
         fake_pipe,
         params=dict(
             prompt="cinematic portrait",
@@ -87,7 +108,8 @@ def test_controlnet_calls_preprocessor_then_pipeline(fake_pipe, monkeypatch):
             controlnet_scale=1.0,
             steps=9,
             seed=42,
-            lora_path=None, lora_strength=0.0,
+            lora_path=None,
+            lora_strength=0.0,
         ),
     )
 
@@ -106,22 +128,31 @@ def test_controlnet_rejects_missing_input_image(fake_pipe):
     with pytest.raises(ValueError):
         modes.call_controlnet(
             fake_pipe,
-            params=dict(prompt="x", input_image=None, preprocessor="Canny",
-                        controlnet_scale=1.0, steps=9, seed=0,
-                        lora_path=None, lora_strength=0.0),
+            params=dict(
+                prompt="x",
+                input_image=None,
+                preprocessor="Canny",
+                controlnet_scale=1.0,
+                steps=9,
+                seed=0,
+                lora_path=None,
+                lora_strength=0.0,
+            ),
         )
 
 
 def test_upscale_runs_realesrgan_then_pipeline(fake_pipe, monkeypatch):
     calls = {"upscale": None}
+
     def fake_2x(img, model_path):
         calls["upscale"] = (img.size, str(model_path))
         w, h = img.size
         return img.resize((w * 2, h * 2), Image.LANCZOS)
+
     monkeypatch.setattr(modes, "upscale", type("U", (), {"realesrgan_2x": staticmethod(fake_2x)}))
 
     input_image = Image.new("RGB", (512, 512))
-    out, meta = modes.call_upscale(
+    _out, meta = modes.call_upscale(
         fake_pipe,
         params=dict(
             prompt="masterpiece, 8k",
@@ -129,7 +160,8 @@ def test_upscale_runs_realesrgan_then_pipeline(fake_pipe, monkeypatch):
             refine_steps=5,
             refine_denoise=0.33,
             seed=42,
-            lora_path=None, lora_strength=0.0,
+            lora_path=None,
+            lora_strength=0.0,
             esrgan_model_path="/fake/path/RealESRGAN_x4plus.pth",
         ),
     )
@@ -145,7 +177,16 @@ def test_upscale_runs_realesrgan_then_pipeline(fake_pipe, monkeypatch):
 
 def test_upscale_rejects_missing_image(fake_pipe):
     with pytest.raises(ValueError):
-        modes.call_upscale(fake_pipe, params=dict(prompt="x", input_image=None,
-                                                   refine_steps=5, refine_denoise=0.33, seed=0,
-                                                   lora_path=None, lora_strength=0.0,
-                                                   esrgan_model_path="/fake.pth"))
+        modes.call_upscale(
+            fake_pipe,
+            params=dict(
+                prompt="x",
+                input_image=None,
+                refine_steps=5,
+                refine_denoise=0.33,
+                seed=0,
+                lora_path=None,
+                lora_strength=0.0,
+                esrgan_model_path="/fake.pth",
+            ),
+        )

tests/test_scaffold.py

@@ -1,26 +1,35 @@
 from pathlib import Path
-import re
 
 REPO = Path(__file__).resolve().parents[1]
 
+
 def test_required_files_exist():
     for rel in [
-        "pyproject.toml", "requirements.txt", "setup.sh",
-        "LICENSE", "CLAUDE.md", "README.md", ".gitignore",
-        "tests/__init__.py", "tests/conftest.py",
+        "pyproject.toml",
+        "requirements.txt",
+        "setup.sh",
+        "LICENSE",
+        "CLAUDE.md",
+        "README.md",
+        ".gitignore",
+        "tests/__init__.py",
+        "tests/conftest.py",
     ]:
         assert (REPO / rel).exists(), f"missing {rel}"
 
+
 def test_pyproject_targets_py311():
     text = (REPO / "pyproject.toml").read_text()
     assert "python = " not in text  # not poetry
     assert "py311" in text  # ruff target-version
 
+
 def test_requirements_has_core_deps():
     text = (REPO / "requirements.txt").read_text().lower()
     for dep in ["diffsynth-studio", "gradio", "spaces", "controlnet-aux", "torch", "safetensors", "ruff", "pytest"]:
         assert dep in text, f"missing dep: {dep}"
 
+
 def test_license_is_mit():
     text = (REPO / "LICENSE").read_text()
     assert "MIT License" in text

tests/test_tooltips.py

@@ -1,19 +1,35 @@
 import tooltips
 
 REQUIRED_KEYS = {
-    "prompt", "negative_prompt", "model", "lora", "lora_strength",
-    "steps", "cfg", "width", "height", "seed",
-    "controlnet_image", "controlnet_preprocessor", "controlnet_scale",
-    "upscale_image", "refine_steps", "refine_denoise", "output",
+    "prompt",
+    "negative_prompt",
+    "model",
+    "lora",
+    "lora_strength",
+    "steps",
+    "cfg",
+    "width",
+    "height",
+    "seed",
+    "controlnet_image",
+    "controlnet_preprocessor",
+    "controlnet_scale",
+    "upscale_image",
+    "refine_steps",
+    "refine_denoise",
+    "output",
 }
 
+
 def test_tooltips_has_all_required_keys():
     assert REQUIRED_KEYS <= set(tooltips.TOOLTIPS)
 
+
 def test_tooltips_values_are_non_empty_strings():
     for key, val in tooltips.TOOLTIPS.items():
         assert isinstance(val, str) and val.strip(), f"{key} is empty or non-string"
 
+
 def test_tooltips_values_are_short_enough_for_a_tooltip():
     for key, val in tooltips.TOOLTIPS.items():
         assert len(val) <= 200, f"{key} is too long for a tooltip ({len(val)} chars)"

tests/test_upscale.py

@@ -1,4 +1,3 @@
-from unittest import mock
 import pytest
 from PIL import Image
 
@@ -12,9 +11,11 @@ def small_image():
 
 def test_realesrgan_2x_produces_2x_image(small_image, monkeypatch):
     """RealESRGAN runs 4x then we scale down 0.5 → net 2x."""
+
     def fake_run_4x(_model_path, image):
         w, h = image.size
         return image.resize((w * 4, h * 4), Image.LANCZOS)
+
     monkeypatch.setattr(upscale, "_realesrgan_4x", fake_run_4x)
 
     out = upscale.realesrgan_2x(small_image, model_path="/dev/null")

tooltips.py

@@ -3,24 +3,25 @@
 Kept separate from ``ui.py`` so copy edits don't touch component wiring. Every
 key here MUST be referenced from a labeled component in ``ui.py`` (and vice versa).
 """
+
 from __future__ import annotations
 
 TOOLTIPS: dict[str, str] = {
-    "prompt":                  "What to generate. Be specific: subject, style, lighting, camera angle.",
-    "negative_prompt":         "What to avoid (Base only). e.g. 'blurry, low quality, distorted'.",
-    "model":                   "Base = 25 steps, higher quality. Turbo = 8 steps, fast.",
-    "lora":                    "Optional .safetensors LoRA file. Trained on Z-Image base or turbo.",
-    "lora_strength":           "LoRA influence. 0.6–1.0 typical. Higher = more LoRA, less base model.",
-    "steps":                   "Denoising steps. Turbo: 6–10. Base: 20–30. More = better detail, slower.",
-    "cfg":                     "Classifier-free guidance. Turbo: locked at 1.0. Base: 3–5 typical.",
-    "width":                   "Output width in pixels. Multiples of 64. Higher = more memory.",
-    "height":                  "Output height in pixels. Multiples of 64.",
-    "seed":                    "0 = random each run. Pin a number to reproduce an image exactly.",
-    "controlnet_image":        "Control image — the structural reference for the output.",
+    "prompt": "What to generate. Be specific: subject, style, lighting, camera angle.",
+    "negative_prompt": "What to avoid (Base only). e.g. 'blurry, low quality, distorted'.",
+    "model": "Base = 25 steps, higher quality. Turbo = 8 steps, fast.",
+    "lora": "Optional .safetensors LoRA file. Trained on Z-Image base or turbo.",
+    "lora_strength": "LoRA influence. 0.6-1.0 typical. Higher = more LoRA, less base model.",
+    "steps": "Denoising steps. Turbo: 6-10. Base: 20-30. More = better detail, slower.",
+    "cfg": "Classifier-free guidance. Turbo: locked at 1.0. Base: 3-5 typical.",
+    "width": "Output width in pixels. Multiples of 64. Higher = more memory.",
+    "height": "Output height in pixels. Multiples of 64.",
+    "seed": "0 = random each run. Pin a number to reproduce an image exactly.",
+    "controlnet_image": "Control image — the structural reference for the output.",
     "controlnet_preprocessor": "Canny = edges, Depth = depth map, Pose = body pose, Pre-processed = use image as-is.",
-    "controlnet_scale":        "How strongly the control image guides the output. 0.6–1.2 typical.",
-    "upscale_image":           "Input image to upscale 2x.",
-    "refine_steps":            "Steps for the Z-Image-Turbo refinement pass after RealESRGAN. 3–8 typical.",
-    "refine_denoise":          "How much the refinement alters pixels. 0.2–0.4 typical. Higher = more detail change.",
-    "output":                  "Generated image. Right-click to download full resolution.",
+    "controlnet_scale": "How strongly the control image guides the output. 0.6-1.2 typical.",
+    "upscale_image": "Input image to upscale 2x.",
+    "refine_steps": "Steps for the Z-Image-Turbo refinement pass after RealESRGAN. 3-8 typical.",
+    "refine_denoise": "How much the refinement alters pixels. 0.2-0.4 typical. Higher = more detail change.",
+    "output": "Generated image. Right-click to download full resolution.",
 }

upscale.py

@@ -3,6 +3,7 @@
 This module only handles the *pixel-space* upscale. The Z-Image-Turbo refinement
 pass (img2img at denoise=0.33) lives in :mod:`modes` since it shares the pipeline.
 """
+
 from __future__ import annotations
 
 from pathlib import Path
@@ -26,8 +27,8 @@ _MODEL_CACHE: dict[str, Any] = {}
 def _realesrgan_4x(model_path: Path | str, image: Image.Image) -> Image.Image:
     """Run RealESRGAN x4plus on ``image``. Caches the model in-process."""
     import numpy as np
-    from realesrgan import RealESRGANer
     from basicsr.archs.rrdbnet_arch import RRDBNet
+    from realesrgan import RealESRGANer
 
     key = str(model_path)
     if key not in _MODEL_CACHE:
@@ -36,10 +37,10 @@ def _realesrgan_4x(model_path: Path | str, image: Image.Image) -> Image.Image:
             scale=4,
             model_path=key,
             model=net,
-            tile=512,        # split into tiles to avoid OOM on large inputs
+            tile=512,  # split into tiles to avoid OOM on large inputs
             tile_pad=10,
             pre_pad=0,
-            half=False,      # bf16 elsewhere; keep this fp32 for stability
+            half=False,  # bf16 elsewhere; keep this fp32 for stability
             gpu_id=None,
         )