Upload README.md with huggingface_hub

README.md

@@ -1,3 +1,116 @@
 ---
 license: unknown
+pipeline_tag: text-to-image
+tags:
+  - text-to-image
+  - image-to-image
+  - image-editing
+  - multi-reference
+  - distilled
+  - turbo
 ---
+
+# Mage-Flow Turbo + Edit Turbo
+
+4-step photographic text-to-image (**~3 s** per 1024² image on an RTX 5090)
+and a companion instruction-editing model that takes up to **three**
+reference images.
+
+> **What this repo is:** the Mage-Flow turbo and turbo-edit transformers, a
+> shared Qwen2.5-VL text encoder and VAE — weights only, not a retrain. The
+> settings below are the values these weights are actually run with day to
+> day.
+
+---
+
+## Samples — `mage-flow-turbo` (txt2img)
+
+Four steps, guidance 1.0. Photorealism is this model's strength.
+
+<table>
+<tr><td><img src="https://huggingface.co/ChrisColeTech/Mage-Flow/resolve/main/samples/apple.png" width="380" alt="prompt: a red apple on a rustic wooden table beside a window, soft daylight, fine skin texture and wood grain, studio photograph, sharp focus — 1024×1024, 4 steps, guidance 1.0, seed 12345"></td><td><img src="https://huggingface.co/ChrisColeTech/Mage-Flow/resolve/main/samples/portrait.png" width="380" alt="prompt: portrait of an older fisherman with a weathered face, natural window light, shallow depth of field, photorealistic — 1024×1024, 4 steps, guidance 1.0, seed 99"></td></tr>
+<tr><td><sub>**prompt:** `a red apple on a rustic wooden table beside a window, soft daylight, fine skin texture and wood grain, studio photograph, sharp focus` — 1024×1024, 4 steps, guidance 1.0, seed 12345</sub></td><td><sub>**prompt:** `portrait of an older fisherman with a weathered face, natural window light, shallow depth of field, photorealistic` — 1024×1024, 4 steps, guidance 1.0, seed 99</sub></td></tr>
+<tr><td><img src="https://huggingface.co/ChrisColeTech/Mage-Flow/resolve/main/samples/street.png" width="380" alt="prompt: a rain-slicked Tokyo street at night, neon signs reflecting in puddles, cinematic, 35mm photograph — 1024×1024, 4 steps, guidance 1.0, seed 1234"></td><td></td></tr>
+<tr><td><sub>**prompt:** `a rain-slicked Tokyo street at night, neon signs reflecting in puddles, cinematic, 35mm photograph` — 1024×1024, 4 steps, guidance 1.0, seed 1234</sub></td><td></td></tr>
+</table>
+
+---
+
+## Editing — `mage-flow-edit-turbo` (img2img)
+
+Plain-language instructions against a reference image. Identity, pose,
+lighting and camera are preserved; only what the instruction names changes.
+
+<table>
+<tr><td><img src="https://huggingface.co/ChrisColeTech/Mage-Flow/resolve/main/samples/portrait.png" width="250" alt="reference"></td><td><img src="https://huggingface.co/ChrisColeTech/Mage-Flow/resolve/main/samples/edit-hat.png" width="250" alt="edit: put a brown flat cap on his head"></td><td><img src="https://huggingface.co/ChrisColeTech/Mage-Flow/resolve/main/samples/edit-beach.png" width="250" alt="edit: change the background to a sunny beach"></td></tr>
+<tr><td><sub>**reference** — the seed-99 portrait above</sub></td><td><sub>**instruction:** `put a brown flat cap on his head` — 4 steps, seed 7 (~88 s)</sub></td><td><sub>**instruction:** `change the background to a sunny beach with the ocean behind him` — 4 steps, seed 7 (~60 s)</sub></td></tr>
+</table>
+
+Both edits keep the subject essentially pixel-identical — same skin detail,
+same jacket, same catchlights — while adding an object in one case and
+replacing the entire environment in the other. Up to **three** reference
+images may be supplied together (subject, style, context).
+
+## Recommended settings
+
+Values these builds are run with in practice.
+
+| Parameter | `mage-flow-turbo` | `mage-flow-edit-turbo` | Meaning |
+|---|---|---|---|
+| `width` × `height` | `1024` × `1024` | follows the reference | Output size |
+| `steps` | `4` | `4` | Denoising steps |
+| `guidance` | `1.0` | `1.0` | Distilled — CFG is not used |
+| `max_size` | — | `1024` | Longest edge the reference is fitted to |
+| `vl_condition_long_edge` | — | `384` | Resolution the VL encoder sees the reference at |
+
+**Supported modes:** `txt2img` (turbo), `img2img` / instruction editing (edit-turbo, 1–3 references)
+
+### Notes and gotchas
+
+- **Four steps is correct.** Both variants are step-distilled at guidance 1.0;
+  raising either is not the lever for quality.
+- **Editing costs far more than generating** — ~60–90 s versus ~3 s, because
+  the reference must be encoded through the VL tower before denoising begins.
+  That asymmetry is inherent to the architecture, not a misconfiguration.
+- **Write edits as instructions, not descriptions** — `put a brown flat cap on
+  his head`, not `a man wearing a brown flat cap`.
+- **`torchvision` is a hard dependency** of the Mage-Flow pipeline (the VL
+  image preprocessing path) even though the rest of this stack does not need
+  it. Install the build matching your torch (`torchvision==0.28.0` for torch
+  2.13.0+cu130) or loading fails with `ModuleNotFoundError`.
+- **Three transformers ship here**: `base` (30 steps, guidance 5.0 — the
+  undistilled model), `turbo` and `turbo-edit` (4 steps, guidance 1.0). The
+  samples on this card are from the two turbo variants; the base transformer
+  is included for anyone who wants the slower, higher-guidance path.
+- Each transformer directory is self-contained — download only the variant you
+  intend to run (8.2 GB each) plus the shared encoder, VAE and scheduler.
+
+---
+
+## Layout
+
+Components ship as separate directories under `split/`: one transformer
+directory per variant (`turbo`, `turbo-edit`), plus the shared text encoder,
+VAE and scheduler config. Loaders that accept a diffusers-style component tree
+can consume this directly.
+
+---
+
+## Files
+
+| Path | Size | Role |
+|---|---|---|
+| `split/transformer/turbo/diffusion_pytorch_model.safetensors` | 8.23 GB | txt2img transformer (4-step distilled) — **the tier these settings were measured on** |
+| `split/transformer/turbo-edit/diffusion_pytorch_model.safetensors` | 8.23 GB | instruction-editing transformer (4-step distilled) |
+| `split/transformer/base/diffusion_pytorch_model.safetensors` | 8.23 GB | undistilled transformer (30 steps, guidance 5.0) |
+| `split/text_encoder/` | 8.88 GB | Qwen2.5-VL text/vision encoder (2 shards) |
+| `split/vae/diffusion_pytorch_model.safetensors` | 345 MB | VAE |
+| `split/scheduler/scheduler_config.json` | 169 B | scheduler config |
+
+---
+
+## Provenance
+
+- **Upstream base model:** Mage-Flow (turbo and turbo-edit distillations)
+- **This build:** redistributed as a split component tree with the shared encoder and VAE alongside. Weights are not retrained here.
+- **License:** left as `unknown` in this repo's metadata. Refer to the upstream model's license for redistribution and commercial-use terms.