docs/COMFY_BACKEND.md

# Embedded ComfyUI Backend

This Space keeps the Gradio UI and ZeroGPU decorator but runs generation through
embedded ComfyUI nodes instead of Diffusers or a separate Comfy server.

## Runtime Flow

1. `app.py` validates Gradio inputs into `GenerationParams`.
2. `src.comfy_backend.run_generation()` initializes ComfyUI imports and model
   folder paths.
3. Comfy loader outputs for UNET, CLIP, and VAE are cached per worker.
4. Before caching, the UNET may pass through **`ModelSamplingAuraFlow`** (unless
   `ZANIME_DISABLE_AURA_SAMPLING=1`) to mirror the official Z-Anime workflow.
5. Each generation runs `CLIPTextEncode`, `EmptyLatentImage`, native `KSampler`,
   and `VAEDecode`.
6. Decoded tensors become RGB `PIL.Image` objects for the Gradio gallery.

No Comfy HTTP server (`/prompt`, websocket, etc.).

Only core Comfy nodes load by default; **`ModelSamplingAuraFlow`** is pulled from
`comfy_extras.nodes_model_advanced` without loading all optional node packs.

Set `ZANIME_INIT_COMFY_EXTRA_NODES=1` only if you intentionally need broader Comfy extra/custom initialization.

Optional audio-related imports may pull `torchaudio`; by default a stub is installed when the real wheel is missing or incompatible.

## Source And Models

ComfyUI source lives at `ComfyUI/`. If missing, the runtime downloads the
pinned archive (see `COMFYUI_SOURCE.md`), unless `ZANIME_DISABLE_COMFY_SOURCE_FETCH=1`.

Model layout under `ZANIME_MODELS_ROOT` or `ComfyUI/models/`:

- `diffusion_models/z-anime-distill-8step-fp8.safetensors`
- `text_encoders/qwen_3_4b-fp8.safetensors`
- `vae/ae.safetensors`
- optional mirror: `clip/qwen_3_4b-fp8.safetensors` (bootstrap tries to hardlink/copy)

## ZeroGPU Notes

Heavy work runs inside `@spaces.GPU`. Loader outputs stay cached per worker.

If Comfy removes `CLIPLoader` support for `type="qwen_image"` or changes loader APIs,
startup or first generation fails with a user-facing error.