Use two-Space architecture: workflow frontend calls akaliq backend

mrfakename/Z-Image-Turbo becomes a pure gr.Workflow frontend that calls
the akaliq/Z-Image-Turbo Blocks backend via its /generate_image
endpoint. The canvas's call_space server function forwards the visitor's
HF OAuth token through gradio_client's call_space path, so signed-in
PRO users on mrfakename get their PRO quota metered against the
backend Space rather than being throttled as anonymous on a saturated
shared single-Space pool.

- workflow.json: operator kind converted fn -> space, target
akaliq/Z-Image-Turbo with endpoint /generate_image. Same 6 inputs
(prompt, height, width, num_inference_steps, seed, randomize_seed)
and 2 outputs (image, seed_used); same references, subjects, edges.
- app.py: dropped the local pipeline, the bound generate_image, the
PR-91 LocalContext wrapper, and the duration/error helpers. Pure
frontend: gr.Workflow(graph=workflow.json).launch().

The bound-fn path with @spaces.GPU + LocalContext.request.set was
unable to recover PRO metering on a shared ZeroGPU Space because the
session-to-X-IP-Token binding does not propagate account context on the
/component_server route. The cross-Space call_space path does, because
mrfakename's canvas forwards auth.token (the visitor's HF OAuth access
token) via gradio_client.Client(token=...). The backend's @spaces.GPU
reads the resulting account-bound token through its standard
per-request flow and applies PRO's 40-min / highest queue priority.

app.py

@@ -1,208 +1,12 @@
-import os
-import tempfile
-from contextlib import contextmanager
-
-import spaces
-import torch
 import gradio as gr
-from gradio.context import LocalContext
-from diffusers import DiffusionPipeline
-
-# Load the pipeline once at startup. The Space is a ZeroGPU space, so the
-# model weights stay resident and `@spaces.GPU` allocates a worker per call.
-print("Loading Z-Image-Turbo pipeline...")
-pipe = DiffusionPipeline.from_pretrained(
-    "Tongyi-MAI/Z-Image-Turbo",
-    torch_dtype=torch.bfloat16,
-    low_cpu_mem_usage=False,
-)
-pipe.to("cuda")
-print("Pipeline loaded!")
-
-
-def _save_image(image) -> dict:
-    """Mirror of `gradio.workflow._save_tmp`: serialize a PIL.Image as a JSON
-    pointer the canvas can render. `Workflow.launch()` already adds the
-    tempdir to `allowed_paths`, so the /gradio_api/file=… URL resolves."""
-    path = os.path.join(
-        tempfile.gettempdir(), f"zimage_{os.urandom(8).hex()}.png"
-    )
-    image.save(path)
-    return {
-        "path": path,
-        "url": f"/gradio_api/file={path}",
-        "orig_name": "zimage.png",
-        "mime_type": "image/png",
-    }
-
-
-def _estimate_duration(prompt, height, width, num_inference_steps, seed, randomize_seed) -> int:
-    """Rough wall-clock estimate (seconds) for one Z-Image-Turbo call.
-
-    ZeroGPU's default per-call duration is 60s. Requesting less than you need
-    *raises* queue priority (shorter tasks get scheduled sooner) and — crucially
-    for a busy shared Space — frees the GPU slot for the next visitor far
-    sooner than holding it for a full minute, so far fewer users hit the
-    Space's "reached its GPU limit" rejection. Scaled by pixel count and steps;
-    clamped to a small floor/ceiling so a runaway slider can't starve the queue
-    or under-budget a big call.
-
-    Signature mirrors the GPU function exactly because @spaces.GPU passes the
-    decorated function's inputs straight through to the duration callable.
-
-    See: https://huggingface.co/docs/hub/en/spaces-zerogpu#duration-management
-    """
-    pixels = max(int(height), 1) * max(int(width), 1)
-    # ~0.4s/step at 1024^2, linear-ish in pixels. Big calls still need headroom.
-    per_step = 0.4 * (pixels / (1024 * 1024))
-    seconds = int(num_inference_steps) * per_step
-    return max(20, min(int(seconds) + 15, 120))
-
-
-def _friendly_gpu_error(err: Exception) -> str:
-    """Turn ZeroGPU's terse allocator rejections into a clear, honest message.
-
-    'Space app has reached its GPU limit' is a *Space-level* capacity rejection
-    (the shared ZeroGPU pool is saturated), not a per-user quota wall — it
-    reproduces regardless of inputs, account tier, or sign-in state. Don't make
-    an upgrade claim whose truth we can't pin down, so the message is neutral:
-    shared GPU at capacity, retry shortly.
-    """
-    msg = (str(err) or "").lower()
-    capacity_hints = (
-        "gpu limit", "reached its gpu limit", "gpu quota", "out of quota",
-        "quota", "no gpu", "could not allocate", "gpu is busy", "too many",
-        "concurrent",
-    )
-    if any(h in msg for h in capacity_hints):
-        return (
-            "⛔ This demo's shared GPU is at capacity right now — it's not a "
-            "problem with your prompt or your account. The GPU pool is fully "
-            "booked by other users at the moment. Please wait a minute and "
-            "retry; demand clears between bursts."
-        )
-    if "out of memory" in msg or "oom" in msg or "cuda" in msg:
-        return (
-            "💥 Image generation ran out of GPU memory. Try a smaller "
-            "Height/Width or fewer Inference Steps, then retry."
-        )
-    return (
-        "⚠️ Image generation failed. Please try again in a moment — if it "
-        "keeps happening, simplify your prompt or lower the resolution."
-    )
-
-
-@contextmanager
-def _with_request_context(request):
-    """Publish the incoming request to Gradio's LocalContext for the duration
-    of the GPU call so the ZeroGPU allocator can read the caller's X-IP-Token.
-
-    ZeroGPU meters per-user quota via the X-IP-Token header the HF Hub injects
-    on every request to a Space; the allocator/gradio_client reads it from
-    LocalContext.request (see gradio_client.add_zero_gpu_headers). Normal event
-    handlers get this for free because Gradio sets LocalContext.request around
-    the handler. The workflow's call_fn route hands us the request via
-    _special_args (when we type-hint gr.Request) but does *not* publish it to
-    LocalContext, so without this wrap every workflow call runs with the token
-    missing and is metered as unauthenticated (2 min/day, lowest priority) —
-    which saturates a busy Space for everyone, signed-in PRO users included.
-    This restores per-user metering. Idempotent: set()/reset() restores prior.
-    """
-    if request is None:
-        yield
-        return
-    token = LocalContext.request.set(request)
-    try:
-        yield
-    finally:
-        LocalContext.request.reset(token)
-
-
-@spaces.GPU(duration=_estimate_duration)
-def _generate_image_gpu(
-    prompt: str,
-    height: int,
-    width: int,
-    num_inference_steps: int,
-    seed: int,
-    randomize_seed: bool,
-):
-    """The GPU-decorated worker. Runs only under a ZeroGPU allocation; the
-    allocator raises *before* this body if no GPU can be granted, which is why
-    the rewording lives in the plain `generate_image` wrapper below, not here.
-    """
-    if not prompt or not prompt.strip():
-        raise gr.Error("Please enter a prompt.")
-
-    if randomize_seed:
-        seed = torch.randint(0, 2**32 - 1, (1,)).item()
-
-    generator = torch.Generator("cuda").manual_seed(int(seed))
-    image = pipe(
-        prompt=prompt,
-        height=int(height),
-        width=int(width),
-        num_inference_steps=int(num_inference_steps),
-        guidance_scale=0.0,
-        generator=generator,
-    ).images[0]
-
-    return _save_image(image), int(seed)
-
-
-def generate_image(
-    prompt: str,
-    height: int,
-    width: int,
-    num_inference_steps: int,
-    seed: int,
-    randomize_seed: bool,
-    request: gr.Request | None = None,
-):
-    """Workflow-facing wrapper around the GPU worker.
-
-    Bound to the canvas as a `fn` operator node — the workflow calls this
-    Python function directly server-side, so the entire pipeline (frontend +
-    ZeroGPU) lives in a single Space. The `request` param is injected by Gradio
-    (`_special_args`) and is *not* exposed as a canvas port (injected params are
-    excluded from the workflow port schema), so workflow.json topology is
-    unchanged.
-
-    This wrapper does two jobs:
-      1. Publish `request` to LocalContext (via `_with_request_context`) so the
-         @spaces.GPU allocator sees the caller's X-IP-Token and meters the call
-         to the actual user — restoring per-user ZeroGPU quota/priority.
-      2. Catch rejections from the allocator (which fire before the worker body
-         runs) and reword them into a clear, honest user-facing message.
-
-    Returns (image_dict, seed_used). The image is serialized to a /gradio_api
-    file URL so JSON serialization across the fn bridge succeeds; the
-    executor's `fromGradioOutput` turns the dict back into an image port value.
-    """
-    try:
-        with _with_request_context(request):
-            return _generate_image_gpu(
-                prompt, height, width, num_inference_steps, seed, randomize_seed
-            )
-    except gr.Error:
-        # Already a user-facing validation message (e.g. empty prompt) — pass
-        # it through unchanged.
-        raise
-    except Exception as e:
-        # Allocator rejection (GPU limit / quota / OOM / etc.) — reword.
-        raise gr.Error(_friendly_gpu_error(e)) from e
 
+# Pure-frontend workflow. The canvas's `space` operator calls
+# akhaliq/Z-Image-Turbo's /generate_image via gradio_client's call_space
+# server function, forwarding the visitor's HF OAuth token. That proxy
+# identity flows into the backend @spaces.GPU, where ZeroGPU budgets the
+# call against the visitor's / PRO account.
 
-# The workflow (workflow.json) wires `generate_image` as a `fn` operator:
-#   Prompt, Height, Width, Inference Steps, Seed, Randomize Seed ─▶
-#   generate_image (fn operator, kind="fn") ─▶ Output Image, Seed Used
-#
-# On a Space with `hf_oauth: true`, visiting the canvas runs this function
-# under a ZeroGPU worker using each visitor's own HF token.
-demo = gr.Workflow(
-    graph="workflow.json",
-    bind={"generate_image": generate_image},
-)
+demo = gr.Workflow(graph="workflow.json")
 
 if __name__ == "__main__":
-    demo.launch()
+    demo.launch()

workflow.json

@@ -1,17 +1,33 @@
 {
   "schema_version": "2",
   "name": "Z-Image-Turbo",
-  "description": "Ultra-fast AI image generation with Z-Image-Turbo on ZeroGPU, driven by a gr.Workflow fn-bound @spaces.GPU function. Single Space: the workflow frontend and the GPU worker share one process.",
-  "runtime": { "default": "client" },
-  "view": { "default": "canvas" },
+  "description": "Two-Space architecture: this Space is a gr.Workflow frontend that calls the akhaliq/Z-Image-Turbo Blocks backend via its /generate_image endpoint. The canvas forwards the visitor's HF OAuth token through gradio_client's call_space path, so signed-in PRO users get their proper quota metered against the backend Space.",
+  "runtime": {
+    "default": "client"
+  },
+  "view": {
+    "default": "canvas"
+  },
   "references": [
     {
       "id": "ref_prompt",
       "label": "Prompt",
       "role": "reference",
       "asset_type": "text",
-      "inputs": [{ "id": "in", "label": "Prompt", "type": "text" }],
-      "outputs": [{ "id": "out", "label": "Prompt", "type": "text" }],
+      "inputs": [
+        {
+          "id": "in",
+          "label": "Prompt",
+          "type": "text"
+        }
+      ],
+      "outputs": [
+        {
+          "id": "out",
+          "label": "Prompt",
+          "type": "text"
+        }
+      ],
       "x": 60,
       "y": 160,
       "width": 240,
@@ -25,92 +41,198 @@
       "label": "Height",
       "role": "reference",
       "asset_type": "number",
-      "inputs": [{ "id": "in", "label": "Height", "type": "number" }],
-      "outputs": [{ "id": "out", "label": "Height", "type": "number" }],
+      "inputs": [
+        {
+          "id": "in",
+          "label": "Height",
+          "type": "number"
+        }
+      ],
+      "outputs": [
+        {
+          "id": "out",
+          "label": "Height",
+          "type": "number"
+        }
+      ],
       "x": 60,
       "y": 300,
       "width": 200,
       "height": 90,
-      "data": { "out": 1024 }
+      "data": {
+        "out": 1024
+      }
     },
     {
       "id": "ref_width",
       "label": "Width",
       "role": "reference",
       "asset_type": "number",
-      "inputs": [{ "id": "in", "label": "Width", "type": "number" }],
-      "outputs": [{ "id": "out", "label": "Width", "type": "number" }],
+      "inputs": [
+        {
+          "id": "in",
+          "label": "Width",
+          "type": "number"
+        }
+      ],
+      "outputs": [
+        {
+          "id": "out",
+          "label": "Width",
+          "type": "number"
+        }
+      ],
       "x": 60,
       "y": 410,
       "width": 200,
       "height": 90,
-      "data": { "out": 1024 }
+      "data": {
+        "out": 1024
+      }
     },
     {
       "id": "ref_steps",
       "label": "Inference Steps",
       "role": "reference",
       "asset_type": "number",
-      "inputs": [{ "id": "in", "label": "Steps", "type": "number" }],
-      "outputs": [{ "id": "out", "label": "Steps", "type": "number" }],
+      "inputs": [
+        {
+          "id": "in",
+          "label": "Steps",
+          "type": "number"
+        }
+      ],
+      "outputs": [
+        {
+          "id": "out",
+          "label": "Steps",
+          "type": "number"
+        }
+      ],
       "x": 60,
       "y": 520,
       "width": 200,
       "height": 90,
-      "data": { "out": 9 }
+      "data": {
+        "out": 9
+      }
     },
     {
       "id": "ref_seed",
       "label": "Seed",
       "role": "reference",
       "asset_type": "number",
-      "inputs": [{ "id": "in", "label": "Seed", "type": "number" }],
-      "outputs": [{ "id": "out", "label": "Seed", "type": "number" }],
+      "inputs": [
+        {
+          "id": "in",
+          "label": "Seed",
+          "type": "number"
+        }
+      ],
+      "outputs": [
+        {
+          "id": "out",
+          "label": "Seed",
+          "type": "number"
+        }
+      ],
       "x": 60,
       "y": 630,
       "width": 200,
       "height": 90,
-      "data": { "out": 42 }
+      "data": {
+        "out": 42
+      }
     },
     {
       "id": "ref_randomize",
       "label": "Randomize Seed",
       "role": "reference",
       "asset_type": "boolean",
-      "inputs": [{ "id": "in", "label": "Randomize", "type": "boolean" }],
-      "outputs": [{ "id": "out", "label": "Randomize", "type": "boolean" }],
+      "inputs": [
+        {
+          "id": "in",
+          "label": "Randomize",
+          "type": "boolean"
+        }
+      ],
+      "outputs": [
+        {
+          "id": "out",
+          "label": "Randomize",
+          "type": "boolean"
+        }
+      ],
       "x": 60,
       "y": 740,
       "width": 200,
       "height": 90,
-      "data": { "out": true }
+      "data": {
+        "out": true
+      }
     }
   ],
   "operators": [
     {
       "id": "op_generate",
-      "label": "generate_image",
+      "label": "Z-Image-Turbo (backend)",
       "role": "operator",
-      "kind": "fn",
-      "source": "fn",
-      "fn": "generate_image",
+      "kind": "space",
+      "source": "hf://spaces/akhaliq/Z-Image-Turbo",
       "inputs": [
-        { "id": "in_0", "label": "prompt", "type": "text", "required": true },
-        { "id": "in_1", "label": "height", "type": "number" },
-        { "id": "in_2", "label": "width", "type": "number" },
-        { "id": "in_3", "label": "num_inference_steps", "type": "number" },
-        { "id": "in_4", "label": "seed", "type": "number" },
-        { "id": "in_5", "label": "randomize_seed", "type": "boolean" }
+        {
+          "id": "in_0",
+          "label": "prompt",
+          "type": "text",
+          "required": true
+        },
+        {
+          "id": "in_1",
+          "label": "height",
+          "type": "number"
+        },
+        {
+          "id": "in_2",
+          "label": "width",
+          "type": "number"
+        },
+        {
+          "id": "in_3",
+          "label": "num_inference_steps",
+          "type": "number"
+        },
+        {
+          "id": "in_4",
+          "label": "seed",
+          "type": "number"
+        },
+        {
+          "id": "in_5",
+          "label": "randomize_seed",
+          "type": "boolean"
+        }
       ],
       "outputs": [
-        { "id": "out_0", "label": "image", "type": "image", "output_index": 0 },
-        { "id": "out_1", "label": "seed_used", "type": "number", "output_index": 1 }
+        {
+          "id": "out_0",
+          "label": "image",
+          "type": "image",
+          "output_index": 0
+        },
+        {
+          "id": "out_1",
+          "label": "seed_used",
+          "type": "number",
+          "output_index": 1
+        }
       ],
       "x": 420,
       "y": 320,
       "width": 280,
       "height": 220,
-      "data": {}
+      "data": {},
+      "space_id": "akhaliq/Z-Image-Turbo",
+      "endpoint": "/generate_image"
     }
   ],
   "subjects": [
@@ -119,8 +241,20 @@
       "label": "Output Image",
       "role": "subject",
       "asset_type": "image",
-      "inputs": [{ "id": "in", "label": "Image", "type": "image" }],
-      "outputs": [{ "id": "out", "label": "Image", "type": "image" }],
+      "inputs": [
+        {
+          "id": "in",
+          "label": "Image",
+          "type": "image"
+        }
+      ],
+      "outputs": [
+        {
+          "id": "out",
+          "label": "Image",
+          "type": "image"
+        }
+      ],
       "x": 820,
       "y": 280,
       "width": 240,
@@ -132,8 +266,20 @@
       "label": "Seed Used",
       "role": "subject",
       "asset_type": "number",
-      "inputs": [{ "id": "in", "label": "Seed", "type": "number" }],
-      "outputs": [{ "id": "out", "label": "Seed", "type": "number" }],
+      "inputs": [
+        {
+          "id": "in",
+          "label": "Seed",
+          "type": "number"
+        }
+      ],
+      "outputs": [
+        {
+          "id": "out",
+          "label": "Seed",
+          "type": "number"
+        }
+      ],
       "x": 820,
       "y": 460,
       "width": 240,
@@ -142,13 +288,69 @@
     }
   ],
   "edges": [
-    { "id": "e_prompt",     "from_node_id": "ref_prompt",     "from_port_id": "out", "to_node_id": "op_generate", "to_port_id": "in_0", "type": "text" },
-    { "id": "e_height",     "from_node_id": "ref_height",     "from_port_id": "out", "to_node_id": "op_generate", "to_port_id": "in_1", "type": "number" },
-    { "id": "e_width",      "from_node_id": "ref_width",      "from_port_id": "out", "to_node_id": "op_generate", "to_port_id": "in_2", "type": "number" },
-    { "id": "e_steps",      "from_node_id": "ref_steps",      "from_port_id": "out", "to_node_id": "op_generate", "to_port_id": "in_3", "type": "number" },
-    { "id": "e_seed",       "from_node_id": "ref_seed",       "from_port_id": "out", "to_node_id": "op_generate", "to_port_id": "in_4", "type": "number" },
-    { "id": "e_randomize",  "from_node_id": "ref_randomize",  "from_port_id": "out", "to_node_id": "op_generate", "to_port_id": "in_5", "type": "boolean" },
-    { "id": "e_image_out",  "from_node_id": "op_generate",    "from_port_id": "out_0", "to_node_id": "sub_image", "to_port_id": "in", "type": "image" },
-    { "id": "e_seed_out",   "from_node_id": "op_generate",    "from_port_id": "out_1", "to_node_id": "sub_seed",  "to_port_id": "in", "type": "number" }
+    {
+      "id": "e_prompt",
+      "from_node_id": "ref_prompt",
+      "from_port_id": "out",
+      "to_node_id": "op_generate",
+      "to_port_id": "in_0",
+      "type": "text"
+    },
+    {
+      "id": "e_height",
+      "from_node_id": "ref_height",
+      "from_port_id": "out",
+      "to_node_id": "op_generate",
+      "to_port_id": "in_1",
+      "type": "number"
+    },
+    {
+      "id": "e_width",
+      "from_node_id": "ref_width",
+      "from_port_id": "out",
+      "to_node_id": "op_generate",
+      "to_port_id": "in_2",
+      "type": "number"
+    },
+    {
+      "id": "e_steps",
+      "from_node_id": "ref_steps",
+      "from_port_id": "out",
+      "to_node_id": "op_generate",
+      "to_port_id": "in_3",
+      "type": "number"
+    },
+    {
+      "id": "e_seed",
+      "from_node_id": "ref_seed",
+      "from_port_id": "out",
+      "to_node_id": "op_generate",
+      "to_port_id": "in_4",
+      "type": "number"
+    },
+    {
+      "id": "e_randomize",
+      "from_node_id": "ref_randomize",
+      "from_port_id": "out",
+      "to_node_id": "op_generate",
+      "to_port_id": "in_5",
+      "type": "boolean"
+    },
+    {
+      "id": "e_image_out",
+      "from_node_id": "op_generate",
+      "from_port_id": "out_0",
+      "to_node_id": "sub_image",
+      "to_port_id": "in",
+      "type": "image"
+    },
+    {
+      "id": "e_seed_out",
+      "from_node_id": "op_generate",
+      "from_port_id": "out_1",
+      "to_node_id": "sub_seed",
+      "to_port_id": "in",
+      "type": "number"
+    }
   ]
-}
+}