diffusers-workflow 0.4.0__py3-none-any.whl

dw/docs/AGENT_LOOP.md

@@ -0,0 +1,95 @@
+# Agent Loop
+
+Some of the Issues in this repo are worked by an automated implementer/tester
+agent loop, not a human. It lives in a separate repo
+([`dkackman/iterate`](https://github.com/dkackman/iterate) — private) that
+drives two Claude Code agents in strict alternation against this repo's
+Issues. Nothing about running the loop lives here; this page exists so that
+anyone who opens or comments on one of its Issues — a human, or another
+agent joining in — knows how to act on it correctly.
+
+## The two roles
+
+- **Implementer** — has this repo checked out and SSH access to the box
+  running the MCP server. Reproduces, fixes, deploys, and hands the ticket
+  back. Never verifies its own fix.
+- **Tester** — talks to the MCP server only as a protocol client (MCP tool
+  calls), no source checkout, no shell/SSH access to the server box. Its job
+  is independent verification: it re-runs the original repro over MCP and
+  either confirms the fix or bounces the ticket back.
+
+That asymmetry — the only role that can mark an issue verified is the one
+with no ability to patch around a bug — is the entire point of the loop. A
+human or third agent joining in should preserve it: don't fix and verify the
+same ticket yourself.
+
+A third, standalone **regression agent** periodically runs a growing suite
+of scripted MCP calls (`regression-suite-*.md` in the `iterate` repo) against
+the live server and files/comments on Issues for anything that regresses. It
+doesn't participate in the implementer/tester handoff.
+
+## Outside filings
+
+The loop runs as one GitHub login (the repo owner's) and must not act
+unattended on text filed by anyone else in this public repo. An issue filed
+under a different login — including a `field-report` from someone else's
+session — is relabelled `owner:don` + `status:needs-approval` before either
+role works it, and is handed to the loop, or not, only after the maintainer
+reviews it.
+
+## Reading a ticket
+
+Tickets use the **MCP agent-loop ticket** issue template. Two label
+families carry all the state — check both before acting:
+
+- **`owner:*`** — exactly one of `owner:implementer` / `owner:tester` /
+  `owner:don` at a time: whoever is expected to act on it next. If you're
+  not that owner, leave the issue alone beyond reading it (or the specific
+  handoff comment/label a role prompt allows).
+- **`status:*`** — where the ticket is in its lifecycle:
+  - *(no status label)* — open, ready for the implementer to reproduce.
+  - `status:fixed-pending-verify` — implementer has fixed and deployed;
+    waiting on the tester to re-run the repro over MCP.
+  - `status:verified` — tester confirmed the fix over MCP; issue is closed
+    as `completed`.
+  - `status:needs-info` — a question bounce; whoever is asked needs to
+    answer before work continues.
+  - `status:needs-approval` (+ `owner:don`) — parked for the human. The
+    implementer uses this for anything beyond a rename-level change
+    (engine behavior, breaking syntax). Neither agent touches a parked
+    issue.
+
+Two built-in GitHub labels close a ticket without a fix:
+
+- **`wontfix`** — the implementer's call, with a reason in a comment; issue
+  closed as `not planned`. The tester may reopen once with new evidence; a
+  second `wontfix` is final.
+- **`duplicate`** — closed as `not planned`, with a comment naming the
+  issue it duplicates (`duplicate of #NN`). A closed issue is still
+  canonical for duplicate detection — the implementer checks
+  `gh issue list --state all` before starting work, not just open issues.
+
+`breaking-change` marks an Issue whose fix changed the MCP interface, so the
+tester adjusts its calls instead of filing the change as a new bug.
+
+## If you want to participate
+
+Whether you're a human or another agent:
+
+- Only touch an issue that's currently owned by you (or, for a human, one
+  parked with `owner:don`).
+- When you hand a ticket to the next owner, swap the `owner:*` label and
+  say what you did in a comment — the next actor has no memory of this
+  session, only the issue thread.
+- Keep implementer and tester roles separate. If you're fixing code, don't
+  also close the issue as verified — that requires an independent MCP call
+  from someone who didn't write the patch.
+- Reference the issue number in any commit that fixes it
+  (`fix(mcp): #42 - ...`), and work on a branch merged to `develop`, never
+  `master`.
+- Only the tester (or an equivalently independent verifier) closes an issue
+  as `completed`/`status:verified`, and only after a real MCP call
+  reproduces the fix — not by reading the diff.
+
+See the `iterate` repo's `CLAUDE.md` for the full protocol this is
+summarized from, including how the automated loop itself is run.

dw/docs/DEPENDENCIES.md

@@ -0,0 +1,91 @@
+# Dependencies
+
+## Installation
+
+### Linux / macOS (Recommended)
+
+```bash
+bash ./install.sh
+source ./activate
+```
+
+### Windows
+
+```powershell
+.\install.ps1
+.\venv\scripts\activate
+```
+
+The install scripts handle everything: Python version detection (3.10-3.14), virtual environment creation, PyTorch, diffusers, and all dependencies.
+
+### Manual Installation
+
+If you prefer manual control:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+
+pip install torch torchvision torchaudio  # add --index-url https://download.pytorch.org/whl/cu130 for CUDA on Linux
+pip install -r requirements.txt
+pip install git+https://github.com/huggingface/diffusers
+```
+
+## Where the Dependency List Lives
+
+`pyproject.toml` is the single source: its `dependencies` list (plus the
+`server` and `dev` extras) is what the published wheel declares, what
+`requirements.txt` and `requirements-test.txt` resolve (they are one-line
+pointers, `-e .[server]` and `-e .[dev]`), and what the install scripts
+and CI install. To add or change a dependency, edit pyproject.toml -
+every install path picks it up.
+
+Things pyproject can't express stay in the scripts: the PyTorch CUDA
+index, diffusers from git HEAD, and the macOS/Windows-specific extras
+below. bitsandbytes carries a `sys_platform == 'linux'` marker in
+pyproject; install.ps1 installs it explicitly on Windows.
+
+## Platform-Specific Dependencies
+
+**All platforms (core ML):** peft, transformers, accelerate, safetensors, controlnet_aux, sentencepiece, torchsde, torchao, optimum-quanto, gguf, kornia, ftfy, sdnq, spandrel, facexlib (spandrel + facexlib back the `upscale` and `restore_faces` tasks)
+
+**All platforms (utilities):** fastapi, uvicorn (the `dw.serve` HTTP server and web UI), av, aiohttp, matplotlib, opencv-python-headless, concurrent-log-handler, qrcode, protobuf, imageio, imageio-ffmpeg, beautifulsoup4, soundfile, jsonschema, black, python-dotenv
+
+**Linux (CUDA):** bitsandbytes
+
+**Windows (CUDA):** bitsandbytes, kernels
+
+**macOS (MPS):** fp4-fp8-for-torch-mps (FP8/FP4 dtype support for Metal), fluidtop
+
+## Optional
+
+**flash_attn** — Improved attention performance on CUDA. Requires the [CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit):
+
+```bash
+pip install flash_attn
+```
+
+**piexif** (installed by default) — Embeds generation metadata as EXIF `UserComment` when a step's `result.embed_metadata` is `true` and the content type is JPEG/WebP (PNG embedding uses Pillow's `PngInfo` and needs nothing extra). Without it, saving falls back to a logged warning and no embedded metadata.
+
+## Specifying Python Version
+
+```bash
+export INSTALL_PYTHON_VERSION=3.13
+bash ./install.sh
+```
+
+## Troubleshooting
+
+**Hugging Face authentication (401/403 downloading a model):** Most workflows under `workflows/` (Flux, LTX-2, MiniMax...) point at **gated** models on the Hub — repos that require the owner to approve your account before you can download them. A run against one of these fails with an actionable error naming the repo and `huggingface-cli login` (mapped from the Hub's 401/403 in `load_component()`, `dw/pipeline_processors/pipeline.py`) — request access on the model's page (e.g. [black-forest-labs/FLUX.1-dev](https://huggingface.co/black-forest-labs/FLUX.1-dev)) and then log in once, locally:
+
+```bash
+huggingface-cli login
+```
+
+`workflows/templates/text-to-image.json` uses an ungated model and needs no login - start there if you just want to confirm the install works.
+
+**Package conflicts:** Re-run the install script — it recreates the venv from scratch.
+
+**CUDA not detected:** `install.sh` probes for a working `nvidia-smi` on Linux and installs the CUDA build of torch (cu130) only when it finds one; otherwise (or on a manual install with plain `pip install torch`) you get PyPI's CPU-only Linux wheel. Verify with `python -c "import torch; print(torch.cuda.is_available())"`.
+
+**MPS not detected:** Requires Apple Silicon. Verify with `python -c "import torch; print(torch.backends.mps.is_available())"`.

dw/docs/IP_ADAPTER.md

@@ -0,0 +1,109 @@
+# IP-Adapter
+
+IP-Adapter enables image-prompt conditioning — use a reference image to influence the style or content of generated images alongside a text prompt. It works with any pipeline whose `load_ip_adapter()` diffusers supports — Flux, Stable Diffusion 1.5, SDXL, SD 3.5, and others.
+
+## Usage
+
+Add an `ip_adapter` block to the pipeline definition and pass `ip_adapter_image` in arguments:
+
+```json
+{
+    "pipeline": {
+        "configuration": {
+            "component_type": "FluxPipeline",
+            "offload": "sequential"
+        },
+        "from_pretrained_arguments": {
+            "model_name": "black-forest-labs/FLUX.1-dev",
+            "torch_dtype": "torch.bfloat16"
+        },
+        "ip_adapter": {
+            "model_name": "XLabs-AI/flux-ip-adapter",
+            "weight_name": "ip_adapter.safetensors"
+        },
+        "arguments": {
+            "prompt": "A marmot sits at a counter drinking a milkshake",
+            "ip_adapter_image": {
+                "location": "https://example.com/reference_style.jpg"
+            },
+            "num_inference_steps": 25,
+            "guidance_scale": 3.5
+        }
+    }
+}
+```
+
+## Properties
+
+| Property | Required | Description |
+| -------- | -------- | ----------- |
+| `model_name` | Yes | HuggingFace Hub repo ID for the IP-Adapter weights |
+| `weight_name` | No | Specific weight file in the repo |
+| `subfolder` | No | Subfolder within the repo |
+| `scale` | No | Adapter strength (default: 1.0). Lower = less influence from reference image |
+
+Any other property (e.g. `revision`) is forwarded as-is to the underlying `load_ip_adapter()` call.
+
+## Models Without a Built-in Image Encoder
+
+Some base models (e.g. Stable Diffusion 3.5) don't ship a default image encoder, so diffusers needs one configured explicitly. Add `image_encoder` and `feature_extractor` components alongside `ip_adapter`, the same way any other pipeline component is configured:
+
+```json
+{
+    "pipeline": {
+        "configuration": { "component_type": "StableDiffusion3Pipeline" },
+        "feature_extractor": {
+            "configuration": { "component_type": "transformers.SiglipImageProcessor" },
+            "from_pretrained_arguments": { "model_name": "google/siglip-so400m-patch14-384" }
+        },
+        "image_encoder": {
+            "configuration": { "component_type": "transformers.SiglipVisionModel" },
+            "from_pretrained_arguments": { "model_name": "google/siglip-so400m-patch14-384" }
+        },
+        "ip_adapter": {
+            "model_name": "InstantX/SD3.5-Large-IP-Adapter",
+            "weight_name": "ip-adapter.bin",
+            "scale": 0.6
+        },
+        "from_pretrained_arguments": {
+            "model_name": "stabilityai/stable-diffusion-3.5-large",
+            "torch_dtype": "torch.bfloat16"
+        },
+        "arguments": {
+            "prompt": "a marmot drinks a milkshake",
+            "ip_adapter_image": { "location": "https://example.com/reference.jpg" }
+        }
+    }
+}
+```
+
+See [ip-adapter.json](../workflows/templates/ip-adapter.json) for the full workflow.
+
+## Image Argument
+
+The `ip_adapter_image` uses the standard image loading format:
+
+```json
+"ip_adapter_image": {
+    "location": "https://example.com/image.jpg"
+}
+```
+
+```json
+"ip_adapter_image": {
+    "location": "./local/reference.png",
+    "width": 512,
+    "height": 512
+}
+```
+
+Can also reference a previous step's output:
+
+```json
+"ip_adapter_image": "previous_result:preprocessing_step"
+```
+
+## Examples
+
+- [ip-adapter.json](../workflows/templates/ip-adapter.json) — Flux with IP-Adapter for style transfer
+- [ip-adapter.json](../workflows/templates/ip-adapter.json) — FLUX.1 dev with an IP-Adapter, and the face-model variant in its description

dw/docs/LORAS.md

@@ -0,0 +1,131 @@
+# LoRA Support
+
+LoRA (Low-Rank Adaptation) models apply lightweight style or subject modifications to a base model. Add one or more LoRAs to any pipeline step.
+
+## Basic Usage
+
+```json
+{
+    "pipeline": {
+        "configuration": { "component_type": "FluxPipeline" },
+        "from_pretrained_arguments": {
+            "model_name": "black-forest-labs/FLUX.1-dev",
+            "torch_dtype": "torch.bfloat16"
+        },
+        "loras": [
+            {
+                "model_name": "XLabs-AI/flux-RealismLora"
+            }
+        ],
+        "arguments": {
+            "prompt": "a photorealistic landscape"
+        }
+    }
+}
+```
+
+## LoRA Properties
+
+```json
+"loras": [
+    {
+        "model_name": "user/lora-repo",
+        "weight_name": "specific_weights.safetensors",
+        "subfolder": "lora_subfolder",
+        "adapter_name": "my_adapter",
+        "scale": 0.8
+    }
+]
+```
+
+| Property | Required | Description |
+| -------- | -------- | ----------- |
+| `model_name` | Yes | HuggingFace Hub repo ID |
+| `weight_name` | No | Specific weight file in the repo |
+| `subfolder` | No | Subfolder within the repo |
+| `adapter_name` | No | Named identifier for the adapter. Defaults to the LoRA's position in the list (`"0"`, `"1"`, ...) if omitted |
+| `scale` | No | Blend strength (default: 1.0). Lower = less effect |
+
+Any other property (e.g. `revision`) is forwarded as-is to the underlying `load_lora_weights()` call.
+
+## Multiple LoRAs
+
+Stack multiple LoRAs. They are blended via weighted adapter composition:
+
+```json
+"loras": [
+    {
+        "model_name": "XLabs-AI/flux-RealismLora",
+        "adapter_name": "realism",
+        "scale": 0.7
+    },
+    {
+        "model_name": "user/style-lora",
+        "adapter_name": "style",
+        "scale": 0.5
+    }
+]
+```
+
+## LoRA with Quantization
+
+LoRAs work with quantized models:
+
+```json
+{
+    "pipeline": {
+        "transformer": {
+            "configuration": { "component_type": "SD3Transformer2DModel" },
+            "quantization_config": {
+                "configuration": { "config_type": "BitsAndBytesConfig" },
+                "arguments": { "load_in_4bit": true, "bnb_4bit_quant_type": "{nf4}" }
+            },
+            "from_pretrained_arguments": {
+                "model_name": "stabilityai/stable-diffusion-3.5-large",
+                "subfolder": "transformer",
+                "torch_dtype": "torch.bfloat16"
+            }
+        },
+        "configuration": { "component_type": "StableDiffusion3Pipeline" },
+        "from_pretrained_arguments": {
+            "model_name": "stabilityai/stable-diffusion-3.5-large",
+            "torch_dtype": "torch.bfloat16"
+        },
+        "loras": [
+            {
+                "model_name": "crystalwizard/cubic-abstract-1",
+                "weight_name": "cubic-abstract-lora.safetensors"
+            }
+        ],
+        "arguments": { "prompt": "cubart a leaf" }
+    }
+}
+```
+
+## Variable LoRA
+
+Make the LoRA configurable via workflow variables:
+
+```json
+{
+    "variables": {
+        "lora": "XLabs-AI/flux-RealismLora"
+    },
+    "steps": [{
+        "pipeline": {
+            "loras": [{ "model_name": "variable:lora" }],
+            "arguments": { "prompt": "variable:prompt" }
+        }
+    }]
+}
+```
+
+```bash
+python -m dw.run workflow.json lora="other-user/other-lora"
+```
+
+## Examples
+
+- [lora.json](../workflows/templates/lora.json) — Flux with realism LoRA and variables
+- [lora.json](../workflows/templates/lora.json) — SD 3.5 with yarn art style LoRA
+- [lora.json](../workflows/templates/lora.json) — A LoRA adapter on FLUX.1 dev, with the SD 3.5 variant in its description