Sking image-to-Minecraft-skin pipeline (AGPL-3.0)

Two-stage reproduction of EntropyDrop's open image-to-skin path.

stage 1 FLUX.2 [klein] 4B Base + sking_v73_flux_4b_000027000 LoRA
stage 2 EntropyDrop SKING_DDJ_v104 (BiRefNet foreground + Dense UV Parser)

Stage 2 runs in-process via runpy rather than subprocess so it works on
ZeroGPU, where child processes get no CUDA context. Dependency pins are
deviated from the bundle's tested_environments.json in three places to keep
the resolver satisfiable alongside diffusers==0.40.0; see DEPLOY.md.

app.py

@@ -1,22 +1,18 @@
 """Gradio front end for the Sking image -> Minecraft skin pipeline.
 
 Startup order is load-bearing:
-  0. import spaces         (installs ZeroGPU's CUDA emulation shim -- MUST be
-                            before anything touches torch)
-  1. weights.bootstrap()   (sets HF_HOME, downloads ~20 GB, verifies SHA-256)
-  2. stage1_flux.load()    (imports torch/diffusers; .to("cuda") at module scope,
-                            which the emulation shim makes safe)
+  0. import spaces          installs ZeroGPU's CUDA emulation shim -- MUST be
+                            before anything touches torch, or `.to("cuda")`
+                            dies with "No CUDA GPUs are available".
+  1. build + launch Gradio  immediately, so the container binds port 7860 well
+                            inside HF's health-check window.
+  2. bootstrap in a thread  downloads ~19 GB and verifies SHA-256 in the
+                            background. Blocking startup on this is what caused
+                            RUNTIME_ERROR with no traceback: the platform killed
+                            the container before it ever became healthy.
 """
 
 # --- 0. `spaces` MUST be imported before torch ------------------------------
-# On ZeroGPU there is no GPU at container start. The `spaces` package installs a
-# PyTorch CUDA *emulation* shim when it is imported, which is what allows
-# `.to("cuda")` at module scope to succeed and be materialised later when a real
-# GPU is attached inside an @spaces.GPU function. Importing torch first (or
-# touching cuda before this import) fails with:
-#     UserWarning: Can't initialize NVML
-#     RuntimeError: No CUDA GPUs are available
-# so this block has to stay above the weights bootstrap, which pulls in torch.
 try:
     import spaces  # type: ignore
 
@@ -32,51 +28,109 @@ except ImportError:  # dedicated-GPU Docker Space, or a local run
 
     ZERO_GPU = False
 
-# --- 1. bootstrap BEFORE any torch / transformers / diffusers import --------
-from sking_pipeline import weights  # must come after `spaces`, before torch
-
-BOOT = weights.bootstrap(progress=lambda m: print(m, flush=True))
-
+import base64  # noqa: E402
 import html  # noqa: E402
 import tempfile  # noqa: E402
+import threading  # noqa: E402
+import traceback  # noqa: E402
 from pathlib import Path  # noqa: E402
 
 import gradio as gr  # noqa: E402
 from PIL import Image  # noqa: E402
 
-from sking_pipeline import stage1_flux, stage2_uv  # noqa: E402
-
-# --- 2. load stage 1 at module scope, if this container can hold it ---------
-# FLUX.2 [klein] 4B Base needs ~16 GB of host RAM (8.05 GB Mistral text encoder
-# + 7.75 GB transformer, held simultaneously). The free ZeroGPU container has
-# 16 GB total and gets OOM-killed during weight materialisation -- no traceback,
-# the process just dies. weights.stage1_viable() gates on measured RAM so the
-# Space still boots and serves stage 2, which is the byte-identical production
-# UV parser and fits easily.
-STAGE1_OK = bool(BOOT.get("stage1_viable")) and BOOT.get("flux") is not None
-if STAGE1_OK:
-    stage1_flux.load(
-        BOOT["flux"], BOOT["lora"], progress=lambda m: print(m, flush=True)
-    )
-else:
-    print(
-        f"stage 1 disabled: {BOOT.get('stage1_reason')}\n"
-        "  stage 2 (SKING_DDJ_v104 render -> 64x64 skin) remains available.\n"
-        "  to enable stage 1, move to a GPU tier with >= 20 GiB RAM\n"
-        "  (1x L4 = 30 GiB, A10G-large = 46 GiB) or set SKING_STAGE1_MIN_RAM_GB\n"
-        "  lower to force an attempt.",
-        flush=True,
-    )
+from sking_pipeline import stage1_flux, stage2_uv, weights  # noqa: E402
 
 GPU_SECONDS = 180   # Flux @ 50 steps + BiRefNet + Dense UV Parser, with headroom
 STAGE2_SECONDS = 120
 
+# ---------------------------------------------------------------------------
+# background bootstrap
+# ---------------------------------------------------------------------------
+
+STATE = {
+    "stage": "starting",
+    "log": [],
+    "ready": False,
+    "stage1": False,
+    "boot": None,
+    "error": None,
+}
+_LOCK = threading.Lock()
+
+
+def _progress(msg: str) -> None:
+    with _LOCK:
+        STATE["log"].append(msg)
+        if len(STATE["log"]) > 200:
+            del STATE["log"][:100]
+    print(msg, flush=True)
+
+
+def _bootstrap() -> None:
+    try:
+        boot = weights.bootstrap(progress=_progress)
+        with _LOCK:
+            STATE["boot"] = boot
+        if boot.get("stage1_viable") and boot.get("flux"):
+            _progress("loading FLUX.2 [klein] 4B Base (background thread)")
+            stage1_flux.load(boot["flux"], boot["lora"], progress=_progress)
+            with _LOCK:
+                STATE["stage1"] = True
+        else:
+            _progress(f"stage 1 skipped: {boot.get('stage1_reason')}")
+        with _LOCK:
+            STATE["stage"] = "ready"
+            STATE["ready"] = True
+        _progress("READY")
+    except BaseException:  # noqa: BLE001 - surface anything, incl. MemoryError
+        with _LOCK:
+            STATE["error"] = traceback.format_exc()
+            STATE["stage"] = "error"
+        print(STATE["error"], flush=True)
+
+
+threading.Thread(target=_bootstrap, name="sking-bootstrap", daemon=True).start()
+
+
+def _bundle():
+    boot = STATE.get("boot")
+    if not boot:
+        raise gr.Error("Models are still downloading — see the status panel.")
+    return boot
+
+
+def _require_stage1():
+    if not STATE["ready"]:
+        raise gr.Error("Models are still downloading — see the status panel.")
+    if not STATE["stage1"]:
+        raise gr.Error(
+            "Stage 1 (FLUX.2 [klein] 4B) is not available on this hardware. "
+            "Use the 'Render → Skin' tab, which runs the identical production "
+            "UV parser on a render you supply."
+        )
+
+
+def status_md() -> str:
+    with _LOCK:
+        stage, err, log = STATE["stage"], STATE["error"], list(STATE["log"])
+        s1, ready = STATE["stage1"], STATE["ready"]
+    icon = {"starting": "⏳", "ready": "✅", "error": "❌"}.get(stage, "•")
+    tail = "\n".join(f"    {line}" for line in log[-14:])
+    head = (
+        f"### {icon} Status: `{stage}`\n\n"
+        f"- stage 1 (Flux + LoRA): **{'available' if s1 else 'not loaded'}**\n"
+        f"- stage 2 (SKING_DDJ_v104): **{'available' if ready else 'loading'}**\n"
+        f"- ZeroGPU: **{'yes' if ZERO_GPU else 'no (dedicated/local)'}**\n"
+    )
+    if err:
+        head += f"\n**Error**\n\n```\n{err.strip()[-2000:]}\n```\n"
+    return head + f"\n<details><summary>startup log</summary>\n\n```\n{tail}\n```\n</details>"
+
 
 # ---------------------------------------------------------------------------
 # helpers
 # ---------------------------------------------------------------------------
 
-# Fixed paths are safe because we run with default_concurrency_limit=1.
 _OUT_DIR = Path(tempfile.gettempdir()) / "sking-out"
 _OUT_DIR.mkdir(parents=True, exist_ok=True)
 SKIN_OUT = _OUT_DIR / "skin.png"
@@ -84,7 +138,6 @@ RENDER_OUT = _OUT_DIR / "render.png"
 
 
 def _upscale(img: Image.Image, factor: int = 8) -> Image.Image:
-    """Nearest-neighbour upscale so a 64x64 skin is actually visible."""
     w, h = img.size
     return img.resize((w * factor, h * factor), Image.NEAREST)
 
@@ -99,12 +152,11 @@ def _empty_viewer() -> str:
 
 
 def _viewer_iframe(skin_b64: str) -> str:
-    """3D preview via skinview3d, served through an iframe srcdoc.
+    """3D preview via skinview3d inside an iframe srcdoc.
 
-    An iframe is used deliberately: Gradio updates gr.HTML through innerHTML, and
-    browsers do not execute <script> tags inserted that way. A srcdoc document is
-    parsed normally, so its scripts do run. Degrades to a blank box if the CDN is
-    unreachable -- the 2D outputs are unaffected.
+    Gradio updates gr.HTML through innerHTML, and browsers do not execute
+    <script> inserted that way; a srcdoc document is parsed normally, so its
+    scripts do run. Degrades to a blank box if the CDN is unreachable.
     """
     if not skin_b64:
         return _empty_viewer()
@@ -158,17 +210,10 @@ def _validate_square(img: Image.Image) -> Image.Image:
 @gpu(GPU_SECONDS)
 def image_to_skin(image, seed, steps, guidance, size):
     """Full pipeline: reference image -> edited render -> 64x64 RGBA skin."""
-    import base64
-
-    if not STAGE1_OK:
-        raise gr.Error(
-            "Stage 1 (FLUX.2 [klein] 4B) is disabled on this hardware: the "
-            "container does not have enough RAM to hold the text encoder and "
-            "transformer together. Use the 'Render → Skin (debug)' tab, which "
-            "runs the identical production UV parser on a render you supply."
-        )
+    _require_stage1()
     if image is None:
         raise gr.Error("Upload a reference image first.")
+    boot = _bundle()
 
     render = stage1_flux.generate(
         image, seed=int(seed), steps=int(steps),
@@ -177,11 +222,10 @@ def image_to_skin(image, seed, steps, guidance, size):
     render.save(RENDER_OUT, format="PNG")
 
     stage2_uv.render_to_uv(
-        RENDER_OUT, SKIN_OUT, BOOT["bundle"], release=BOOT.get("release")
+        RENDER_OUT, SKIN_OUT, boot["bundle"], release=boot.get("release")
     )
     skin = Image.open(SKIN_OUT).convert("RGBA")
     skin.load()
-
     with open(SKIN_OUT, "rb") as fh:
         skin_b64 = base64.b64encode(fh.read()).decode()
 
@@ -195,16 +239,20 @@ def image_to_skin(image, seed, steps, guidance, size):
 
 @gpu(STAGE2_SECONDS)
 def render_to_skin_only(render):
-    """Debug tab: feed a combined front/back render straight into v104."""
-    import base64
-
+    """Feed a combined front/back render straight into v104."""
+    if not STATE["ready"]:
+        raise gr.Error(
+            "Stage 2 is still loading its 2.58 GB bundle — check the status "
+            "panel and refresh. This usually takes 1-3 minutes."
+        )
     if render is None:
         raise gr.Error("Upload a combined front/back render (even square, 256-4096 px).")
+    boot = _bundle()
 
     src = _OUT_DIR / "debug_render.png"
     _validate_square(render).save(src, format="PNG")
     out = _OUT_DIR / "debug_skin.png"
-    stage2_uv.render_to_uv(src, out, BOOT["bundle"], release=BOOT.get("release"))
+    stage2_uv.render_to_uv(src, out, boot["bundle"], release=boot.get("release"))
 
     skin = Image.open(out).convert("RGBA")
     skin.load()
@@ -234,8 +282,8 @@ Co., Ltd.) — [entropydrop.com](https://entropydrop.com) ·
 - `EntropyDrop/Sking` and `SKING_DDJ_v104` — **AGPL-3.0**. This Space is
   therefore AGPL-3.0 too; its complete source is this public repository.
 - `black-forest-labs/FLUX.2-klein-base-4B` — **Apache-2.0**.
-- BiRefNet and SigLIP2 keep their own licenses; see `NOTICE.md` and the
-  bundle's `THIRD_PARTY_NOTICES.md`.
+- BiRefNet and SigLIP2 keep their own licenses; see `NOTICE.md`.
+- The images in `testdata/` are real entropydrop.com generations, **CC BY-NC 4.0**.
 
 Not affiliated with or endorsed by EntropyDrop, Mojang or Microsoft.
 Uploads are processed in memory and are not stored or used for training.
@@ -250,51 +298,25 @@ with gr.Blocks(
         """
         # Sking · image → Minecraft skin
 
-        An open reimplementation of **EntropyDrop**'s two-stage pipeline, running
-        on free ZeroGPU.
+        An open reimplementation of **EntropyDrop**'s two-stage pipeline.
 
-        **Stage 1** — FLUX.2 [klein] 4B Base + the `sking_v73` LoRA turns your
+        **Stage 1** — FLUX.2 [klein] 4B Base + the `sking_v73` LoRA turns a
         reference image into a combined front/back character render.
         **Stage 2** — `SKING_DDJ_v104` (BiRefNet foreground + Dense UV Parser)
-        converts that render into a real **64×64 RGBA** skin with inner and outer
-        layers, ready to drop into Minecraft.
-
-        > ⏱️ Free ZeroGPU quota is **5 minutes/day**. A 50-step run costs roughly
-        > 2–3 minutes of GPU time, so expect one or two skins per day. Lower the
-        > step count to stretch it; PRO ($9/mo) gets 8× the quota.
-        >
-        > 🐢 First load after a rebuild re-downloads the weights and can take
-        > several minutes before the UI appears.
+        converts that render into a real **64×64 RGBA** skin with inner and
+        outer layers, ready to drop into Minecraft.
+
+        > ⏳ **Models download in the background on first start** (~19 GB, 1–4
+        > min). Watch the status panel below and hit *Refresh* — the UI is live
+        > before the weights are.
         """
     )
 
-    if not STAGE1_OK:
-        gr.Markdown(
-            f"""
-            > ### ⚠️ Stage 1 is disabled on this hardware
-            >
-            > {BOOT.get('stage1_reason','')}
-            >
-            > FLUX.2 [klein] 4B Base holds an **8.05 GB** Mistral text encoder and
-            > a **7.75 GB** transformer in host memory at the same time. The text
-            > encoder cannot be dropped or cached — FLUX.2 conditions on your
-            > reference *image* through it, so its output differs per request.
-            > Loading it here gets the container OOM-killed.
-            >
-            > **Still fully working:** the *Render → Skin* tab below runs
-            > `SKING_DDJ_v104`, which is byte-identical to EntropyDrop's
-            > production UV parser. Feed it any combined front/back render —
-            > including the real production examples provided — and it returns a
-            > genuine 64×64 RGBA skin.
-            >
-            > **To enable stage 1:** Settings → Space hardware → **1× L4**
-            > ($0.80/hr, 30 GiB RAM) or **A10G-large** ($1.50/hr, 46 GiB), then
-            > restart. Nothing else needs to change; the code detects the RAM
-            > and turns stage 1 on.
-            """
-        )
+    status = gr.Markdown(status_md())
+    refresh = gr.Button("Refresh status", size="sm")
+    refresh.click(fn=status_md, inputs=None, outputs=status)
 
-    with gr.Tab("Image → Skin" if STAGE1_OK else "Image → Skin (unavailable)"):
+    with gr.Tab("Image → Skin"):
         with gr.Row():
             with gr.Column(scale=5):
                 inp = gr.Image(type="pil", label="Reference image", height=340)
@@ -329,15 +351,18 @@ with gr.Blocks(
             fn=image_to_skin,
             inputs=[inp, seed, steps, guidance, size],
             outputs=[out_render, out_preview, out_file, out_info, out_3d],
-        )
+        ).then(fn=status_md, inputs=None, outputs=status)
 
-    with gr.Tab("Render → Skin (debug)"):
+    with gr.Tab("Render → Skin"):
         gr.Markdown(
-            "Skip stage 1 and feed the v104 parser directly. Input must be an "
-            "**even square between 256 and 4096 px**, left half = front view, "
-            "right half = back view — the layout EntropyDrop calls `front_left` "
-            "and `back_left`. Handy for parsing their own published renders, or "
-            "yours from another generator. Uploads are centre-cropped to a square."
+            "Runs **stage 2 only** — EntropyDrop's `SKING_DDJ_v104` UV parser, "
+            "byte-identical to their production release. Input must be an **even "
+            "square between 256 and 4096 px**, left half = front view, right "
+            "half = back view (their `front_left` / `back_left` layout). "
+            "Uploads are centre-cropped to a square.\n\n"
+            "This tab works even when stage 1 is unavailable, and the examples "
+            "below are **real renders captured from entropydrop.com**, so you "
+            "can compare directly against their published output."
         )
         with gr.Row():
             with gr.Column(scale=5):
@@ -354,18 +379,20 @@ with gr.Blocks(
                 examples=[[str(p)] for p in _fixtures],
                 inputs=[d_in],
                 label=(
-                    "Real production renders captured from entropydrop.com "
+                    "Real production renders from entropydrop.com "
                     "(CC BY-NC 4.0 — see testdata/README.md)"
                 ),
             )
         d_run.click(
             fn=render_to_skin_only, inputs=[d_in], outputs=[d_preview, d_file, d_3d]
-        )
+        ).then(fn=status_md, inputs=None, outputs=status)
 
     gr.Markdown(_CREDITS)
 
 
 if __name__ == "__main__":
+    # Launch immediately: binding 7860 fast is what keeps HF's health check
+    # happy while ~19 GB downloads in the background thread.
     demo.queue(default_concurrency_limit=1).launch(
         server_name="0.0.0.0", server_port=7860, show_api=False
     )

sking_pipeline/weights.py

@@ -218,6 +218,17 @@ def system_memory_gb() -> float:
     return min(candidates) / (1024 ** 3)
 
 
+def disk_report(path: str = "/tmp") -> str:
+    """Free/total disk on the volume holding the weights."""
+    import shutil
+
+    try:
+        u = shutil.disk_usage(path)
+        return f"disk({path}) free={u.free/1024**3:.1f} GiB total={u.total/1024**3:.1f} GiB"
+    except OSError as exc:
+        return f"disk({path}) unreadable: {exc}"
+
+
 def memory_report() -> str:
     """Diagnostic line for the startup log."""
     try:
@@ -267,6 +278,7 @@ def bootstrap(progress=print) -> dict:
 
     viable, ram, reason = stage1_viable(progress)
     progress(f"memory: {memory_report()}")
+    progress(disk_report(str(WEIGHTS_ROOT.parent)))
     progress(f"stage 1 {'ENABLED' if viable else 'DISABLED'} ({reason})")
 
     bundle = download_bundle(progress)
@@ -275,10 +287,12 @@ def bootstrap(progress=print) -> dict:
         f"      verified {len(release['sha256'])} files "
         f"({release['model_version']})"
     )
+    progress("      " + disk_report(str(WEIGHTS_ROOT.parent)))
     link_offline_cache(bundle, progress)
 
     if viable:
         flux_dir, lora = download_flux(progress)
+        progress("      " + disk_report(str(WEIGHTS_ROOT.parent)))
     else:
         # Do not waste 16 GB of ephemeral disk and cold-start time on weights
         # this container cannot hold in memory. Stage 2 alone is the