Gradio LoRA Space Builder

What "good" looks like for these demos

• Loads fast and runs fast — minimal model loading, sensible step count, no wasted computation per call.
• Has a UI with exactly the controls this LoRA needs and nothing else. Excess sliders are a cost, not a feature.
• Shows the user what's happening — progress, intermediate outputs where useful, the seed used, a clear error when input is missing.
• Honors the LoRA's own recommendations from its model card: trigger words, recommended step count, recommended guidance scale, recommended LoRA scale, example inputs.
• Is creative where creativity helps — interactive canvases, before/after sliders, side-by-side previews of intermediate processing — and plain where plainness is right.

Workflow

1. Gather the LoRA info needed to pick a pipeline and design a UI.
2. Pick the base pipeline and inference recipe.
3. Design the UI for this specific LoRA's task and inputs.
4. Write app.py, requirements.txt, and README.md together; show all three to the user for one batched approval.
5. Publish the Space (private).

Phase 1 — Gather LoRA info

from huggingface_hub import HfApi, get_token

cached_token = get_token()  # picks up HF_TOKEN env var or cached CLI login
if cached_token:
    try:
        info = HfApi().whoami(token=cached_token)
        username = info["name"]
        # info also has fine-grained token scope info if applicable
    except Exception:
        cached_token = None  # token exists but is invalid/expired

• If a valid cached token exists and it can read the repo, use it. No prompt needed.
• If no cached token, or the cached token can't read this private repo, ask the user for a token — once, with the explanation below.

I need a Hugging Face access token with write scope (to read the LoRA if it's private/gated, and to publish the Space). Create one at https://huggingface.co/settings/tokens. Paste it here.

• List the repo files (huggingface_hub.HfApi().list_repo_files(repo_id)). Look for .safetensors, README.md, example images/videos, multiple checkpoints.
• Fetch the model card (huggingface_hub.ModelCard.load(repo_id)). The data dict has structured fields; the text has the README body.
• If multiple .safetensors files exist, pick the right one — see "Picking the LoRA weights file" in references/zerogpu-and-publishing.md. Briefly: README-recommended file wins, then pytorch_lora_weights.safetensors, then latest training checkpoint, otherwise ask.

• Base model — the base_model field, or text mentions in the README. Usually present. Use it to pick the pipeline reference file (see Phase 2).
• Task — pipeline_tag if set, otherwise inferred from the base model and README text. The five tasks this skill handles: text-to-image, image-to-image, text-to-video, image-to-video, video-to-video.
• Trigger words — often called "trigger word", "instance prompt", "activation word"; sometimes embedded in example prompts.
• Recommended inference recipe — step count, guidance scale, true CFG scale, LoRA scale, resolution. Many LoRA cards include a Python snippet; trust its parameters (steps, guidance, CFG, LoRA scale, dtype). For loading mechanics, see adapting-to-the-lora.md — prefer pipe.load_lora_weights(...) over whatever loading approach the snippet uses.
• Example prompts and example media — use these as Gradio examples in the UI.
• Sub-task / specific use case — for image edits and video LoRAs, "what does this LoRA actually do" matters as much as the task category. A relighting LoRA, a face-swap LoRA, and a style LoRA all might be image-to-image, but the UI for each is different.

Phase 2 — Pick the base pipeline

• references/base-models/qwen-image.md — covers Qwen-Image and Qwen-Image-Edit family (text-to-image and image-to-image).
• references/base-models/ltx.md — covers LTX family (text-to-video, image-to-video, video-to-video, including IC-LoRAs).
• references/base-models/krea-2.md — covers Krea 2 (K2), text-to-image (train on RAW, run inference/LoRAs on the Turbo distilled checkpoint).

from huggingface_hub import ModelCard
base_card = ModelCard.load(base_model_id)
# Read base_card.text — find the diffusers inference snippet, note the pipeline class it imports.

• Qwen-Image-Edit uses QwenImageEditPipeline. Qwen-Image-Edit-2509 and Qwen-Image-Edit-2511 use QwenImageEditPlusPipeline — different class, different default parameters, takes a list of images instead of one. A LoRA targeting 2511 loaded onto QwenImageEditPipeline produces broken output.
• LTX-Video uses LTXPipeline/LTXImageToVideoPipeline/LTXConditionPipeline. LTX-2 uses LTX2Pipeline from a different module path. LTX-2.3 sometimes needs a native pipeline outside diffusers.

Phase 3 — Design the UI for this LoRA

• "Upload a video, pick a target aspect ratio, click Generate; the model fills the empty margins."
• "Draw colored brush strokes where you want light, pick an illumination style, click Generate; the model relights the photo."
• "Upload a video of someone moving and an image of a different character; the model produces a video of the character doing the motion."

• "Type a prompt and click generate." (Generic T2I — say more.)
• "Upload an image and an instruction." (Generic edit — what kind of edit?)

Phase 4 — Write the Space files

"Now I'll write the three files needed to publish a Space: app.py (the Gradio demo and inference code), requirements.txt (Python dependencies), and README.md (Space configuration including ZeroGPU hardware setting). Then I'll show all three for your review before publishing."

• Models go on cuda at module level (not lazy-loaded inside the GPU function). ZeroGPU has a CUDA emulation that makes this work pre-allocation, and module-level placement is significantly faster than deferred placement.
• The function that runs inference is decorated with @spaces.GPU(duration=...). Pick a duration appropriate for the task — short for image generation, longer for video.
• Don't use torch.compile — it's incompatible with ZeroGPU's process model.

app.py

• Imports — gradio as gr, torch, spaces, the pipeline class, anything the preprocessing needs.
• Constants — LORA_REPO, BASE_MODEL, recommended step count, guidance, LoRA scale, trigger word.
• Module-level model load — pipeline from_pretrained, .to("cuda"), load_lora_weights. If the LoRA repo is private, pass token=os.environ["HF_TOKEN"].
• Preprocessing functions (if any) — pose extraction, padding, mask building, etc. CPU code can run at module level; GPU code needs to be inside a @spaces.GPU function.
• The inference function — decorated with @spaces.GPU(duration=...). Validates inputs, applies trigger word, builds the pipeline kwargs, returns outputs.
• The Gradio Blocks — the UI from Phase 3, wired to the inference function.

• Return the actually-used seed alongside the result so the user can reproduce.
• gr.Progress(track_tqdm=True) on the inference function surfaces diffusers' internal progress bar.
• Validate inputs — raise gr.Error("Please upload an image first.") when a required input is missing, rather than letting the pipeline fail with a cryptic error.
• On gr.Examples, use cache_examples=True, cache_mode="lazy" — plain cache_examples=True runs examples at build time and fails on ZeroGPU; lazy mode defers caching to the first user click.

requirements.txt

1. Every top-level non-stdlib import in app.py. If app.py does import cv2, requirements.txt has opencv-python. If it does from controlnet_aux import OpenposeDetector, requirements.txt has controlnet-aux. Walk the imports mechanically. (Note the exclusions in the next paragraph — some imports are runtime built-ins and don't need to be listed.)
2. What the base-model reference's "Required dependencies" subsection says. Each base-model file lists the non-obvious extras the pipeline pulls in — torchvision for Qwen-Image (Qwen 2.5-VL text encoder), imageio[ffmpeg] for LTX (video export), etc. Include all of them. These are the deps that aren't picked up from imports because the pipeline's components import them transitively at load time.
3. What the LoRA's own model card explicitly mentions installing. If the LoRA README has its own pip install block, lift the deps from there.
4. The diffusers/ML stack: diffusers, transformers, accelerate, peft, safetensors. Default to plain (unpinned). Switch diffusers to git+https://github.com/huggingface/diffusers if the base-model reference says the model needs it (recent releases often do — Qwen-Image-Edit-2511 is a current example).

• gradio — controlled by the sdk_version: field in README.md's YAML frontmatter, not by requirements.txt. Listing it in requirements is at best ignored, at worst causes a version conflict with the SDK. Set the version in the README only.
• torch — provided by the Space runtime. Only add if you need a specific version pinned (rare, and usually a sign something else is wrong).
• spaces — provided by the Space runtime. Only add if you need a specific version pinned.
• huggingface_hub — provided by the Space runtime. Only add if you need a specific version pinned.

• xformers — pinned to specific torch versions, frequent source of conflicts. The ZeroGPU runtime ships torch 2.8+, so any pinned xformers version must support that. Additional gotcha on Blackwell: xformers' FA3 dispatch mis-gates the hardware (FA3 kernels are Hopper-only at sm_90a, but the dispatcher gates on device_capability >= (9, 0), which also matches Blackwell) and crashes at kernel launch with CUDA invalid argument. If a Space using xformers attention hits this, disable FA3 dispatch at module load:
  pythonCopy

  try:
      from xformers.ops.fmha import _set_use_fa3
      _set_use_fa3(False)
  except Exception:
      pass

  Only include xformers if app.py actually uses it.
• flash-attn — needs a build step, often fails to install. Same torch 2.8+ alignment caveat as xformers. Only include if app.py actually uses it.

README.md

---
title: <human-readable title>
emoji: 🎨
colorFrom: pink
colorTo: purple
sdk: gradio
sdk_version: <current Gradio version>
app_file: app.py
pinned: false
hardware: zero-a10g
short_description: <one short line for the Space tile, ~60 chars max>
models:
  - <base model repo>
  - <lora repo>
---

# <title>

A short description with links to the LoRA and base model.

• sdk: gradio — required for ZeroGPU.
• sdk_version — match the Gradio version you wrote against. Look up the current version (pip index versions gradio, or check https://www.gradio.app)) rather than guessing.
• hardware: zero-a10g — the legacy string for ZeroGPU. The actual hardware is NVIDIA RTX Pro 6000 Blackwell, but the identifier is zero-a10g. ZeroGPU is available to PRO, Team, and Enterprise accounts; if the user isn't subscribed, the Space will fall back to CPU. Mention this if you suspect they aren't on PRO.
• models: — list base and LoRA repos. This enables Hub caching and discovery.
• short_description — appears on the Space tile. Keep it short (~60 characters or less). The Hub's YAML validator rejects long values with a 400 from https://huggingface.co/api/validate-yaml, which surfaces as an HfHubHTTPError during create_repo or upload_file. The exact server-side limit isn't documented and may change, so target the visible-tile-length range rather than pushing right up to a cap. If you do hit the 400, the fix is almost always to shorten this field. One sentence describing what the Space does is plenty — the README body below the YAML is where you put longer prose.

Single batched approval — order of operations matters

1. Write app.py, requirements.txt, and README.md in succession with no intervening prose. No commentary between files. No "Now I'll write the next one." No description of what each file does as you produce it. Just the three files, back to back.
2. Then, in a single message, ask for approval covering all three at once. Something like: "Here's the Space — app.py (N lines), requirements.txt, and README.md. Review and confirm to publish, or tell me what to change."
3. The user responds once, covering whatever they want changed across any of the three files.

• Walking through app.py's structure or design choices after writing it but before writing the others. Save commentary for either the pre-writing announcement (Phase 4 opening) or the single approval message after all three exist.
• Asking "ready for the next one?" or "want me to continue with requirements?" — those are implicit per-file approvals.
• Showing one file inline and offering to "show the next when you're ready" — same trap.
• Treating any of the three files as optional or as a follow-up. They are produced together as one deliverable.

Phase 5 — Publish the Space

from huggingface_hub import HfApi, SpaceHardware

api = HfApi(token=hf_token)
username = api.whoami()["name"]
repo_id = f"{username}/{space_name}"

api.create_repo(
    repo_id=repo_id,
    repo_type="space",
    space_sdk="gradio",
    space_hardware=SpaceHardware.ZERO_A10G,
    private=True,
    exist_ok=True,
)

# Upload files
for path in ["app.py", "requirements.txt", "README.md"]:
    api.upload_file(path_or_fileobj=path, path_in_repo=path,
                    repo_id=repo_id, repo_type="space")

api.add_space_secret(repo_id=repo_id, key="HF_TOKEN", value=HF_TOKEN)

• HfHubHTTPError: 400 Bad Request from https://huggingface.co/api/validate-yaml during create_repo or upload_file. The README YAML failed server-side validation. By far the most common cause is a short_description that's too long; sometimes a stray field or malformed value. Fix: shorten short_description to ~60 characters and retry. If shortening doesn't fix it, look for typos in field names or invalid values (e.g. unsupported colors in colorFrom/colorTo, an invalid hardware string).
• 403 on create_repo with space_hardware="zero-a10g": user isn't on PRO/Team/Enterprise, so they can't request ZeroGPU at creation time. Fix: retry create_repo without space_hardware, leave hardware: zero-a10g in the README YAML — the Space gets created on CPU. The user can then either upgrade to PRO (auto-promotes to ZeroGPU) or apply for a community GPU grant (request via the Space's hardware settings).
• 401/403 on upload_file: token doesn't have write scope. Fix: ask the user for a write-scoped token.

• LoRA weight_name mismatch in load_lora_weights → check the actual filename via list_repo_files.
• Base model is gated and the token wasn't set as a Space secret.
• ZeroGPU not allocated (user not on PRO) → Space falls back to CPU and is unusably slow.
• Diffusers version doesn't recognize the pipeline class → pin to git diffusers in requirements.txt.
• Missing dependency at module load → see requirements.txt derivation rules above; the most common case is a transitive dep like torchvision for Qwen-Image's text encoder.

Phase 6 — Smoke-test the Space

import time
from huggingface_hub import HfApi
api = HfApi(token=hf_token)
while True:
    stage = api.get_space_runtime(repo_id).stage
    if stage == "RUNNING": break
    if stage in {"BUILD_ERROR", "RUNTIME_ERROR", "CONFIG_ERROR"}:
        raise RuntimeError(f"Build failed: {stage}. Logs: https://huggingface.co/spaces/{repo_id}/logs/container")
    time.sleep(15)

# Text-to-image:
gradio predict {repo_id} /predict '{"prompt": "...", "aspect_ratio": "1:1", ...}' --token $HF_TOKEN

# Image-to-image (file input):
gradio predict {repo_id} /predict '{"input_image": {"path": "/tmp/sample.jpg", "meta": {"_type": "gradio.FileData"}}, "prompt": "..."}' --token $HF_TOKEN

• Returns successfully and the output looks plausible → done. Share the URL.
• HTTPError 503 / "Space is sleeping" → the Space spun down between steps 1 and 3. Wake it (api.restart_space(repo_id)) and retry.
• Inference error mentioning weight_name / safetensors → the LoRA filename in app.py doesn't match the actual file in the LoRA repo. Re-check list_repo_files, fix weight_name=, re-upload app.py.
• Inference error mentioning a missing pipeline class or attribute → diffusers version too old. Switch requirements.txt to git+https://github.com/huggingface/diffusers and re-upload.
• ImportError at module load → missing dep. Add it to requirements.txt and re-upload. The runtime logs (/logs/run) name the missing package.
• OOM → reduce default resolution or step count, or pick a smaller base variant.
• Timeout / hangs → bump @spaces.GPU(duration=...) and re-upload.

What to avoid

• A generic "one demo for all LoRAs" template. The whole point of this skill is to tailor.
• Lazy-loading the model inside the GPU function. Slow on ZeroGPU, and hides startup errors until first request.
• torch.compile. Not supported on ZeroGPU.
• cache_examples=True without cache_mode="lazy" on ZeroGPU.
• Uploading the LoRA weights into the Space repo. Pull from the LoRA's own Hub repo at runtime.
• Asking for the HF token only at the end, then discovering the LoRA was private all along and you couldn't read the model card.
• Exposing every diffusers knob. Pick the 1–3 controls that matter for this LoRA.
• Long preambles in the chat reply once the Space is published. The Space URL is the deliverable; keep the wrap-up brief.