Deploy from GitHub Actions

.gitattributes

@@ -33,3 +33,10 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+examples/latte.jpg filter=lfs diff=lfs merge=lfs -text
+examples/latte_vector.png filter=lfs diff=lfs merge=lfs -text
+examples/latte_watercolor.png filter=lfs diff=lfs merge=lfs -text
+examples/room.jpg filter=lfs diff=lfs merge=lfs -text
+examples/room_scandi.png filter=lfs diff=lfs merge=lfs -text
+examples/street.jpg filter=lfs diff=lfs merge=lfs -text
+examples/street_snow.png filter=lfs diff=lfs merge=lfs -text

PRD.md

@@ -0,0 +1,169 @@
+# PRD — Shopfront (Product Photo Studio)
+
+> Turn a tiny business's phone snapshots into clean, professional product photos.
+> Upload a plain phone photo of a handmade product; FLUX.2 [klein] re-lights and
+> re-stages it on preset backgrounds (marble, linen, a sunlit windowsill) while
+> keeping the product itself intact — and returns a grid of variations to pick
+> from.
+
+| Field | Value |
+| --- | --- |
+| **Hackathon** | [Build Small](https://huggingface.co/build-small-hackathon) (Hugging Face × Gradio) |
+| **Track** | 🏡 Backyard AI (practical — solve a real problem for someone you know) |
+| **Partner kit** | Black Forest Labs — FLUX.2 [klein] |
+| **Model** | `black-forest-labs/FLUX.2-klein-4B` (4B, Apache 2.0); optional brand LoRA on `FLUX.2-klein-base-4B` |
+| **Badges targeted** | 🏅 Tiny Titan (≤4B), 🎨 Off Brand (custom UI), 🎬 Best Demo, 🧩 Bonus Quest Champion |
+| **Deadline** | **June 15, 2026 · 23:59 UTC** |
+| **Starter** | Forked from `stephenbtl/klein-build-small-starter` (this repo) |
+
+---
+
+## 1. Summary
+
+Shopfront is a single-purpose **image-editing** app for one very real user: a
+friend who sells something handmade (jewelry, candles, baked goods) and whose
+product photos are phone snaps on a cluttered table. Good product photography is
+expensive; Shopfront does the re-lighting and staging with klein's image-editing,
+keeping the actual product recognizable. The user never writes a prompt — they
+upload a photo and click a **scene preset**.
+
+This is the most directly "Backyard AI" of the three concept branches (lifted
+from `STARTER_IDEAS.md` #1, "Shopfront"). It's a focused tool for one user with
+preset styling — explicitly *not* a generic prompt box.
+
+## 2. The problem & user
+
+**User:** a small/handmade seller (Etsy-scale) with no photography budget.
+**Job-to-be-done:** "make my product look like it was shot for a catalogue,
+without a studio." **Constraint that makes it a product:** the product must stay
+*intact and recognizable* — only the lighting/background/staging changes.
+
+## 3. Why it fits "Build Small" (rule → how we satisfy it)
+
+| Rule / badge | How this app delivers it |
+| --- | --- |
+| **REQ-01 ≤ 32B** | klein 4B = 4B params (+ optional small brand LoRA). ✅ |
+| **REQ-02 Gradio Space in org** | Forked Gradio Space; deploy into the Build Small HF org. ✅ |
+| **REQ-03 Demo video** | Phone snap → 3 staged scenes → 4-variation grid, end to end. |
+| **REQ-04 Social post** | Before/after of a real product, linked from README. |
+| **REQ-05 ZeroGPU ≤10 apps/user** | Single Space on ZeroGPU (`zero-a10g`). ✅ |
+| **REQ-06 README tags + write-up** | See §9 for the exact YAML block. |
+| 🏅 **Tiny Titan (≤4B)** | Runs entirely on klein **4B** — qualifies for the ≤4B badge. |
+| 🎨 **Off Brand** | Replace the dev tabs with a "studio counter" UI: upload, scene chips, variation grid. |
+| 🎬 **Best Demo** | Real product + real seller story sells hard on video. |
+
+## 4. Scope
+
+### MVP (must ship by deadline)
+1. **Upload → scene presets → result.** A row of named **scene chips** (e.g.
+   "White Marble", "Linen Flat-lay", "Sunlit Windowsill", "Soft Studio Grey").
+2. Each scene = a curated **edit prompt** that re-lights/re-stages while
+   preserving the product. One click; no prompt writing.
+3. **Generate 4 variations** (4 seeds) shown as a grid so the seller picks the
+   best one.
+4. Clear **before → after** so the value is obvious.
+
+### Stretch
+- **Brand LoRA:** train on ~20 of the seller's existing on-brand shots so every
+  generated scene matches *their* aesthetic (the "push it further" in idea #1).
+- **Aspect presets** for marketplace formats (1:1 for Etsy/IG, 4:5 portrait) via
+  the starter's `SIZE_PRESETS`.
+- **Light "keep product, change only background"** guidance text + a strength
+  control.
+
+### Out of scope
+- True background *segmentation*/compositing (klein edits holistically; we rely on
+  prompt + low change). Pixel-perfect product masking is a later iteration.
+- In-Space training (offline via AI Toolkit — §6).
+
+## 5. Technical design (grounded in the starter `app.py`)
+
+This is the starter's **Image → Image** path, specialized and re-skinned.
+
+- **Pipeline:** keep the starter's ZeroGPU setup verbatim — `import spaces`
+  before `torch`; `Flux2KleinPipeline.from_pretrained("black-forest-labs/FLUX.2-klein-4B", torch_dtype=torch.bfloat16)` built on CPU at module scope; `get_pipe()` moves it to cuda inside the `@GPU` call.
+- **Edit call:** reuse `img2img()`. **Footgun:** call `pipe(prompt=…, image=…)`
+  **by keyword** (`image` is the first positional arg).
+- **Prompts (from `PROMPTING.md`):** *describe the change, not the whole scene* —
+  e.g. "Place the product on white marble in soft daylight, clean studio
+  background, gentle reflections" rather than re-describing the product. Avoid
+  "for a mug / as a logo" phrasing (the model would draw the mug).
+- **Sizing:** `klein_size()` snaps input to a legal size; offer marketplace aspect
+  presets via `SIZE_PRESETS`.
+- **Variation grid:** call the edit 4× with different seeds; return a
+  `gr.Gallery`.
+- **Steps/guidance:** distilled 4B → `num_inference_steps=4`, `guidance_scale=1.0`
+  (starter defaults). Optional "High quality" path → `FLUX.2-klein-base-4B`, 50
+  steps, guidance 4.0.
+
+### Files to change
+| File | Change |
+| --- | --- |
+| `app.py` | Collapse to one editing screen; add `SCENES = {name: edit_prompt}`; add 4-seed variation grid; wire scene chips → `img2img`. Keep ZeroGPU + `klein_size`. |
+| `README.md` | New frontmatter + submission write-up + demo/social links (§9). |
+| `configs/my_lora_klein_4b.yaml` | (Stretch) brand LoRA — trigger word, dataset path. |
+| `examples/` | Add real before/after product pairs for the demo + `gr.Examples`. |
+
+## 6. Optional brand LoRA (stretch — earns the fine-tuning angle)
+
+Per `TRAIN_A_LORA.md`: train on **`FLUX.2-klein-base-4B`** with 15–40 of the
+seller's on-brand photos; caption *content only*, coined trigger (e.g.
+`SHOPBRAND`); keep `arch: "flux2_klein_4b"`; ~$0.50 / ~30 min on RunPod; pick the
+best sample checkpoint (~step 750–1500), not the last. Load with
+`pipe.load_lora_weights(...)` so scenes inherit the brand look.
+
+## 7. Demo & social plan (REQ-03 / REQ-04)
+
+- **Demo video (2–4 min):** real friend's product, real phone snap → three scene
+  presets → variation grid → "the photo they'll actually post." Tell the seller's
+  story.
+- **Social post:** side-by-side before/after + Space link; link it back from the
+  README.
+
+## 8. Risks & mitigations
+
+| Risk | Mitigation |
+| --- | --- |
+| Product identity drifts during edit | Prompt the *change* only; keep edits restrained; expose a strength control; offer base-4B/50-step "High quality". |
+| Hallucinated text/labels on packaging | `PROMPTING.md`: klein text is unreliable — avoid label-dependent products in the demo; add "no text, no logos" to prompts. |
+| ZeroGPU cold start / 75s budget | Keep the starter's module-scope CPU build; distilled 4-step default; `@GPU(duration=75)`. |
+| Deadline today | MVP = upload + scenes + 4-grid. Brand LoRA + aspect presets are stretch. |
+
+## 9. Submission checklist (REQ-01 → REQ-06)
+
+- [ ] **REQ-01** Every model ≤32B — klein 4B (+ optional small LoRA). ✅ (≤4B → Tiny Titan)
+- [ ] **REQ-02** Gradio Space uploaded into the Build Small HF org.
+- [ ] **REQ-03** Demo video recorded and linked.
+- [ ] **REQ-04** One social post, linked from README.
+- [ ] **REQ-05** ≤10 ZeroGPU apps for this user.
+- [ ] **REQ-06** README YAML tagged + idea/tech write-up.
+
+**README frontmatter to apply at submission (REQ-06):**
+```yaml
+title: Shopfront — Product Photo Studio
+short_description: Turn phone snaps into clean product photos on klein 4B
+sdk: gradio
+app_file: app.py
+license: apache-2.0
+suggested_hardware: zero-a10g
+models:
+  - black-forest-labs/FLUX.2-klein-4B
+  - black-forest-labs/FLUX.2-klein-base-4B
+tags:
+  - build-small-hackathon
+  - backyard-ai          # track
+  - tiny-titan           # ≤4B badge
+  - off-brand            # custom UI badge
+  - best-demo            # badge
+  - flux
+  - image-to-image
+```
+
+## 10. Definition of done
+
+- The Space loads on ZeroGPU (no token), accepts a product photo, and returns a
+  re-staged result for at least 3 scene presets, plus a 4-variation grid.
+- Before → after is obvious in one screen.
+- README has track + badge tags, an idea/tech write-up, and links to the demo
+  video and social post.
+- Submitted into the Build Small org before 23:59 UTC.

PROMPTING.md

@@ -0,0 +1,63 @@
+# Getting good output from klein 4B
+
+A 4B model rewards good prompting more than a big model does. These are the
+habits that separate sharp klein output from generic mush.
+
+## Text → Image
+
+**Front-load the subject, then layer detail.** klein reads the start of the
+prompt most strongly.
+
+```
+A red fox curled asleep in autumn leaves, golden afternoon light,
+shallow depth of field, photographic, 50mm
+```
+
+**Name the medium and lighting explicitly.** "cinematic", "flat vector",
+"watercolor", "studio softbox", "harsh midday sun" — these move the output a
+lot. Vague prompts get vague images.
+
+**Steps:** the distilled model (`FLUX.2-klein-4B`) is already great at **4
+steps**. Going higher rarely helps it. If you want the smooth step-count→quality
+curve, run the **base** model at 50 steps instead.
+
+**Guidance** around **4.0** is the sweet spot. On the distilled model, cranking
+guidance does *not* sharpen prompt-following the way it does on base — it's
+mostly baked in.
+
+## Image → Image
+
+**Describe the change, not the whole scene.** For an edit, say what's different:
+
+```
+Turn this into a watercolor painting, soft washes, visible paper texture
+```
+
+not "a watercolor painting of a cat on a sofa" (you already gave it the cat).
+
+**Aspect ratio:** the Space auto-resizes your input to a klein-legal size
+(multiples of 16, under the 4096-patch ceiling). If you need a specific output
+size, crop the input to that ratio first.
+
+## Pitfalls that bite everyone
+
+- **Text rendering is unreliable.** klein can sometimes spell short words, but
+  don't build a project that depends on long, accurate text in the image.
+- **Don't write "for a t-shirt" / "as a logo" / "on a mug" in the prompt.** The
+  model will draw the t-shirt or the mug. Generate the *artwork* clean, then
+  composite it onto the product yourself.
+- **Oil/painterly prompts can hallucinate a painter's signature** in a corner.
+  Add "no signature, no text" if you see it.
+- **Editing footgun (in code):** `image` is the first positional argument,
+  `prompt` is second. Always `pipe(prompt=…, image=…)` by keyword.
+
+## A prompt that shows the model off
+
+```
+A cozy ramen stall at night in the rain, warm paper-lantern glow,
+steam rising from the bowl, reflections on wet pavement, cinematic,
+shallow depth of field
+```
+
+Copy it into the Text → Image tab to see what a clean klein render looks like,
+then start swapping pieces.

README.md

@@ -1,13 +1,100 @@
 ---
-title: Shopfront
-emoji: 📉
-colorFrom: pink
-colorTo: red
+title: Shopfront — Product Photo Studio
+emoji: 🛍️
+colorFrom: green
+colorTo: gray
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: 5.49.1
 app_file: app.py
 pinned: false
+license: apache-2.0
+suggested_hardware: zero-a10g
+short_description: Turn phone snaps into clean product photos on klein 4B
+models:
+  - black-forest-labs/FLUX.2-klein-4B
+  - black-forest-labs/FLUX.2-klein-base-4B
+tags:
+  - build-small-hackathon
+  - backyard-ai
+  - tiny-titan
+  - off-brand
+  - best-demo
+  - flux
+  - image-to-image
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🛍️ Shopfront — Product Photo Studio
+
+**Selling something handmade? Turn a plain phone snap into a clean product photo.**
+Upload a photo of your product; Shopfront restages it on a well-lit scene —
+marble, linen, a sunlit windowsill — **keeping the product itself intact** — and
+hands you four variations to pick from. No prompt writing, no studio. Built for
+the [Build Small Hackathon](https://huggingface.co/build-small-hackathon)
+(🏡 *Backyard AI* track) on **FLUX.2 [klein] 4B**.
+
+> ▶️ **Demo video:** _add link_  ·  📣 **Social post:** _add link_
+
+## How it works
+
+1. **Upload** a plain phone photo of your product.
+2. **Pick a scene** — *White marble, Linen flat-lay, Sunlit windowsill, Studio
+   grey, Botanical*. No prompt writing.
+3. Shopfront runs a guarded image-edit (*"keep the product, change only the
+   background and lighting"*) and returns a **4-variation grid** so you choose the
+   best shot.
+
+It's a focused tool for one real user — a small seller — not a generic prompt box.
+
+## Idea & tech (Build Small write-up)
+
+- **The problem.** Good product photography is expensive; most small sellers have
+  phone snaps on a cluttered table. Shopfront does the lighting and staging.
+- **The model.** [`FLUX.2-klein-4B`](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B)
+  — 4B params, **Apache 2.0**, open weights, runs on the Space GPU (~13 GB,
+  4-step distilled), no token/gating.
+- **The engine.** A `diffusers` `Flux2KleinPipeline` in **image→image** mode,
+  built on CPU at module scope and moved to GPU inside a `@spaces.GPU` call
+  (ZeroGPU). Inputs are snapped to a klein-legal size; the edit is called with
+  `pipe(prompt=…, image=…)` (keyword — `image` is positional-first).
+- **The craft.** Scene presets are guarded edit prompts that change only
+  background/surface/light; four seeds give a pick-your-favourite grid. A custom
+  single-purpose UI replaces the stock starter tabs.
+- **Renders reliably on Spaces.** System-font theme (no Google-Fonts fetch) and
+  `ssr_mode=False`.
+
+## Why it fits "Build Small"
+
+| Rule / badge | How Shopfront delivers it |
+| --- | --- |
+| **REQ-01 · Models ≤ 32B** | klein **4B** — also ≤ 4B → 🏅 **Tiny Titan**. |
+| **REQ-02 · Gradio app in the org** | A Gradio Space; deploy/duplicate into the Build Small HF org. |
+| **REQ-03 · Demo video** | _add link above_ |
+| **REQ-04 · Social post** | _add link above_ |
+| **REQ-05 · ZeroGPU limit** | Single ZeroGPU Space (`zero-a10g`). |
+| **REQ-06 · Tagged README** | Track + badge tags + this write-up. |
+| 🎨 **Off Brand** | Purpose-built studio UI, not the stock tabs. |
+| 🎬 **Best Demo** | A real seller's before→after sells on video. |
+
+## Submission checklist
+
+- [x] Runs on klein 4B (≤ 32B, and ≤ 4B for Tiny Titan)
+- [x] Gradio Space
+- [ ] Demo video recorded + linked above
+- [ ] One social post + linked above
+- [ ] Space uploaded into the Build Small org
+- [x] README tagged with track + badges + write-up
+
+## Push it further
+
+Train a **brand LoRA** on ~20 of the seller's existing on-brand shots (see
+`TRAIN_A_LORA.md` + `configs/my_lora_klein_4b.yaml`) so every staged scene matches
+their aesthetic — load it with `pipe.load_lora_weights(...)`.
+
+---
+
+**Links:** [FLUX.2 [klein]](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B)
+· [GitHub](https://github.com/black-forest-labs/flux2)
+· [Docs](https://docs.bfl.ai)
+· [Build Small Hackathon](https://huggingface.co/build-small-hackathon)
+
+Built on the [klein Build Small starter](https://huggingface.co/spaces/stephenbtl/klein-build-small-starter).

STARTER_IDEAS.md

@@ -0,0 +1,91 @@
+# Three starter projects you can fork
+
+Don't ship a thin wrapper around "type prompt → get image." The judges have
+seen a hundred of those. Each idea below is a real, finishable weekend project
+that uses klein for something the prompt box alone can't do, maps to one of the
+two tracks, and stacks merit badges.
+
+The two tracks:
+
+- 🏡 **Backyard AI** — solve a real problem for someone you know.
+- 🍄 **Thousand Token Wood** — build something delightful and whimsical.
+
+---
+
+## 1. 🏡 "Shopfront" — product photos for a tiny business
+
+**The problem.** A friend sells something handmade (jewelry, candles, baked
+goods) and their product photos are phone snaps on a cluttered table. Good
+product photography is expensive.
+
+**The build.** Image → Image. They upload a plain phone photo of the product;
+your app re-lights and re-stages it on clean backgrounds — marble, linen, a
+sunlit windowsill — keeping the product itself intact. Add a row of preset
+"scenes" so they just click.
+
+**Why it's more than a wrapper.** It's a focused tool for one real user with
+preset styling, not a generic prompt box. That's the whole point of Backyard AI.
+
+**Badges:** 🔌 Off the Grid (runs the open weights), 🎨 Off-Brand (your own UI),
+🎯 Well-Tuned if you train a LoRA on *their* brand look.
+
+**Push it further.** Train a small LoRA on 20 of their existing on-brand shots
+so every generated scene matches their aesthetic. Add a "generate 4 variations"
+grid so they can pick.
+
+---
+
+## 2. 🍄 "Sticker Forge" — a whimsical creature/sticker maker
+
+**The idea.** A playful generator that turns a few words ("a grumpy mushroom
+knight", "a sleepy cloud cat") into a die-cut sticker: bold outline, flat
+shading, transparent-ready background.
+
+**The build.** Text → Image with a baked-in style. The user types just the
+subject; you append the sticker-style scaffolding to the prompt under the hood
+so every output is consistent. Show a sheet of 6 at once.
+
+**Why it's delightful.** Constraint + consistency is what makes it feel like a
+*product*, not a demo. Thousand Token Wood rewards charm and polish.
+
+**Badges:** 🎯 Well-Tuned (train a LoRA so the sticker style is truly yours and
+not promptable by anyone), 🎨 Off-Brand, 🔌 Off the Grid.
+
+**Push it further.** Train a sticker-style LoRA from ~25 reference stickers so
+the look is locked and recognizable. Add post-processing that crops to the
+subject and adds a white die-cut border.
+
+---
+
+## 3. 🏡 / 🍄 "Before & After" — a personal restyle studio
+
+**The idea.** Upload a photo of a room, an outfit, a garden — and see it
+restyled. "What would my living room look like in mid-century modern / cottagecore
+/ Scandinavian?" Useful (Backyard) *and* fun (Wood) depending on how you frame it.
+
+**The build.** Image → Image with a set of named style presets. Each preset is a
+curated edit prompt. Show the original and the restyle side by side.
+
+**Why it works.** The side-by-side is inherently demo-friendly and the presets
+make it usable by someone non-technical in five seconds.
+
+**Badges:** 🔌 Off the Grid, 🎨 Off-Brand. 🎯 Well-Tuned if you train a LoRA on
+one specific aesthetic and make that your app's signature look.
+
+**Push it further.** Let users save a "look" and apply it across several of their
+photos so the whole set is consistent — that consistency is the thing a plain
+prompt can't give them.
+
+---
+
+## The pattern behind all three
+
+1. Pick **one** real user or **one** delightful constraint. Narrow beats broad.
+2. Hide the prompt engineering. The user gives intent; your app supplies the
+   craft (style scaffolding, presets, a LoRA).
+3. Make the output **consistent** — that's what a LoRA buys you, and what makes
+   it read as a product.
+4. Show a **before/after** or a **grid**. It demos better than a single image.
+
+See `TRAIN_A_LORA.md` for the LoRA step and `PROMPTING.md` for getting clean
+output. Fork `app.py` — the three tabs are already wired up.

TRAIN_A_LORA.md

@@ -0,0 +1,187 @@
+# Train your own FLUX.2 [klein] LoRA in ~30 minutes
+
+A LoRA teaches klein a **style**, **character**, or **look** from a handful of
+images. It's a quick way to give your project its own visual identity, and it
+earns the 🎯 **Well-Tuned** merit badge.
+
+This guide is self-contained. You need: ~20 images, a GPU for ~30 minutes
+(a RunPod RTX 4090 is about **$0.50** for a full run), and the config in
+`configs/my_lora_klein_4b.yaml`.
+
+Trainer used here: [ostris/ai-toolkit](https://github.com/ostris/ai-toolkit) — a
+popular community trainer (one of several; you can use any klein-compatible trainer).
+Model: [`FLUX.2-klein-base-4B`](https://huggingface.co/black-forest-labs/FLUX.2-klein-base-4B) (Apache 2.0).
+
+> Don't want to train? You don't have to. The **🎯 Your LoRA** tab in the Space
+> has a dropdown of ready-made klein LoRAs from the Hub, and there are dozens
+> more at
+> [huggingface.co/models](https://huggingface.co/models?other=base_model:adapter:black-forest-labs/FLUX.2-klein-4B).
+> Train one when you want a specific look that the ready-made ones don't cover.
+
+---
+
+## Pick your path (easiest first)
+
+AI Toolkit has a **no-code web UI** — you don't edit YAML by hand unless you want
+to. Three ways to run it:
+
+| Path | Best for | Setup |
+| --- | --- | --- |
+| **RunPod official template** | most people, ~$0.50/run | one click, UI auto-launches |
+| **AI Toolkit UI locally** | you have a 24 GB+ NVIDIA GPU | `git clone` + `npm run build_and_start` |
+| **Modal** (serverless) | no local GPU, pay per second | `pip install modal && modal setup` |
+
+**RunPod (recommended):** deploy the official
+[AI Toolkit by Ostris template](https://console.runpod.io/deploy?template=0fqzfjy6f3)
+on an RTX 4090 (24 GB) or L40S with an ≥80 GB volume. The pod auto-launches the
+AI Toolkit web UI — you create a job, point it at your images, pick
+`FLUX.2-klein-base-4B`, and click Start. The `configs/my_lora_klein_4b.yaml` in
+this Space is the same job expressed as YAML, so you can either fill the UI form
+or paste the config. Ostris has a [2-minute walkthrough video](https://youtu.be/HBNeS-F6Zz8).
+
+**Local UI:** if you have the GPU, follow the
+[ai-toolkit README](https://github.com/ostris/ai-toolkit#gradio-ui) — clone,
+install, `npm run build_and_start`, open `localhost:8675`. Same UI as the pod.
+
+**Modal:** clone ai-toolkit, `pip install modal`, `modal setup`, add a READ
+HF token, then run their Modal training command. Good if you'd rather not rent a
+pod. Steps are in the [ai-toolkit README](https://github.com/ostris/ai-toolkit#training-in-modal).
+
+Whichever you pick, the dataset + caption rules below are identical, and you end
+up with a `.safetensors` you load in the **🎯 Your LoRA** tab.
+
+---
+
+## 1. Build a dataset (15–40 images)
+
+A **style** LoRA is the easy win for a weekend. Collect 15–40 images that share
+one look — your own art, photos you have rights to, public-domain works
+(Wikimedia Commons is reliable and license-clean).
+
+- Diverse subjects, angles, compositions. Avoid the same background repeated.
+- ≥1024 px on the long edge.
+- Name them `img (1).png`, `img (2).png`, … each paired with `img (1).txt`, …
+
+### Captions: describe the CONTENT, never the style
+
+This is the one rule people get wrong. For a **style** LoRA, your captions must
+describe *what is in the image* and say **nothing about the style** — that's
+exactly what you want the model to infer on its own.
+
+Each caption starts with your trigger word, then a literal description:
+
+```
+MYSTYLE7. A portrait of an older man with a beard, facing left, plain background.
+MYSTYLE7. A wide shot of a small fishing boat on calm water at dawn.
+```
+
+Do **not** write "watercolor", "painterly", "vellum", "retro", "muted palette".
+If you describe the style in the caption, the model learns to need that word
+instead of baking the style into the weights.
+
+> Don't want to caption by hand? Any vision model (Qwen2.5-VL, GPT-4o, Gemini)
+> can auto-caption with a "describe only content, no style words" prompt — then
+> skim the `.txt` files and delete any style adjectives that leaked in (they
+> leak ~25% of the time).
+
+Pick a trigger word that is **not a real word** so it can't collide with the
+model's vocabulary: `MYSTYLE7`, `RISO_PR1NT`, `ZK_TOON`. Use it identically in
+every caption and in the config.
+
+---
+
+## 2. Get a GPU
+
+**RunPod (recommended, ~$0.50/run):**
+
+1. Deploy the official **AI Toolkit (Ostris)** template on an **RTX 4090 (24 GB)**
+   or **L40S**. It auto-launches the AI Toolkit UI.
+2. Volume ≥ 80 GB mounted at `/workspace` (weights + checkpoints need room).
+3. Upload your dataset folder to `/workspace/datasets/my_style/` and the config
+   to `/workspace/configs/my_lora_klein_4b.yaml`.
+
+**Colab:** an L4 or A100 runtime works too — `pip install` ai-toolkit, upload
+the dataset, point the config at your Drive path.
+
+---
+
+## 3. Edit three lines in the config
+
+Open `configs/my_lora_klein_4b.yaml` and change the lines marked `<<< CHANGE >>>`:
+
+- `name:` — your output folder name.
+- `trigger_word:` — your trigger (must match your captions).
+- `datasets: folder_path:` — where you uploaded the images.
+
+Also update the three `sample.prompts` to use your trigger so the in-training
+preview images show your style forming.
+
+**The one line you must NOT delete:** `arch: "flux2_klein_4b"`. Without it
+ai-toolkit falls back to a Stable Diffusion loader and crashes on a missing-unet
+error ([issue #691](https://github.com/ostris/ai-toolkit/issues/691)). The
+official BFL example omits it — that's a bug, the included config keeps it.
+
+---
+
+## 4. Train
+
+In the AI Toolkit UI: paste the config, click **Start**. Or from the CLI:
+
+```bash
+cd /app/ai-toolkit
+python run.py /workspace/configs/my_lora_klein_4b.yaml
+```
+
+It checkpoints every 250 steps into `/app/ai-toolkit/output/<name>/` and writes
+sample images alongside. A 1800-step run on a 4090 takes roughly 30–40 minutes.
+
+**Watch the samples, not the loss.** Loss keeps dropping past the point where the
+images start to overfit. For most style LoRAs the visual peak is around
+**step 750–1500**, not the final step. Open the sample images, pick the
+checkpoint that looks best, and use that `.safetensors`.
+
+---
+
+## 5. Use it
+
+Download the `.safetensors` you picked, then in this Space open the
+**🎯 Your LoRA** tab, upload it, put your **trigger word** in the prompt, and
+compare base vs your fine-tune at the same seed.
+
+In code it's two lines on top of the normal pipeline:
+
+```python
+from diffusers import Flux2KleinPipeline
+import torch
+
+pipe = Flux2KleinPipeline.from_pretrained(
+    "black-forest-labs/FLUX.2-klein-base-4B", torch_dtype=torch.bfloat16
+).to("cuda")
+pipe.load_lora_weights("my_lora.safetensors")
+
+img = pipe(
+    prompt="MYSTYLE7. a portrait of a person, studio lighting",
+    num_inference_steps=50, guidance_scale=4.0,
+).images[0]
+```
+
+> You trained on **base** (50 steps). The LoRA also loads on the distilled
+> `FLUX.2-klein-4B` (4 steps) for fast demos, with mild drift. The Space's LoRA
+> tab uses distilled by default for speed; switch `KLEIN_MODEL_ID` to base for
+> the cleanest results.
+
+---
+
+## Quick knobs
+
+| You want | Change in the config |
+| --- | --- |
+| More texture / grain | `linear: 128`, keep `timestep_type: shift` |
+| Cleaner / simpler shapes | `weight_decay: 0.0002` |
+| Flat vector / graphic look | `linear: 64`, `conv: 32`, 15–20 images |
+| A character (not a style) | 10–15 images, `steps: 1000` |
+| Loss stalls | `lr: 0.0002` |
+| Loss oscillates | `lr: 0.00005` |
+
+More detail: [BFL klein training docs](https://docs.bfl.ai/flux_2/flux2_klein_training)
+· [training example](https://docs.bfl.ai/flux_2/flux2_klein_training_example).

app.py

@@ -0,0 +1,152 @@
+"""
+🛍️ Shopfront — Product Photo Studio.
+
+Upload a plain phone snap of a product; klein restages it on a clean, well-lit
+scene while keeping the product itself intact, and returns a grid of variations
+to pick from. Image -> Image on FLUX.2 [klein] 4B. Build Small (Backyard AI).
+Built on the klein starter's verified ZeroGPU + pipeline pattern.
+"""
+from __future__ import annotations
+
+import os
+import random
+import time
+
+# --- ZeroGPU shim: import `spaces` BEFORE torch -----------------------------
+try:
+    import spaces  # type: ignore
+
+    GPU = spaces.GPU
+except Exception:  # local / non-ZeroGPU fallback
+
+    def GPU(*dargs, **dkwargs):  # noqa: N802
+        if len(dargs) == 1 and callable(dargs[0]) and not dkwargs:
+            return dargs[0]
+
+        def wrap(fn):
+            return fn
+
+        return wrap
+
+
+import gradio as gr
+import torch
+from diffusers import Flux2KleinPipeline
+from PIL import Image
+
+MODEL_ID = "black-forest-labs/FLUX.2-klein-4B"  # 4B, Apache 2.0, ungated
+STEPS = 4
+GUIDANCE = 1.0
+MAX_SEED = 2**31 - 1
+VARIANTS = 4
+
+pipe = None
+LOAD_ERR = ""
+try:
+    print(f"Loading {MODEL_ID} on CPU…")
+    pipe = Flux2KleinPipeline.from_pretrained(MODEL_ID, torch_dtype=torch.bfloat16)
+    print("  loaded.")
+except Exception as e:  # noqa: BLE001
+    LOAD_ERR = str(e)
+    print("Model load failed:", e)
+
+
+def klein_size(w: int, h: int, target_area: int = 1024 * 1024, divisor: int = 16):
+    """Snap (w, h) to multiples of 16 under klein's 4096-patch ceiling."""
+    aspect = w / h
+    nh = int((target_area / aspect) ** 0.5)
+    nw = int(nh * aspect)
+    nw = max(divisor, (nw // divisor) * divisor)
+    nh = max(divisor, (nh // divisor) * divisor)
+    return nw, nh
+
+
+# Each scene is an edit instruction: describe the *change* (background, surface,
+# light), not the product — klein keeps the subject and restages around it.
+SCENES = {
+    "White marble": "a clean white marble surface, soft bright daylight, minimal "
+                    "studio background, gentle reflection, professional product photo",
+    "Linen flat-lay": "a top-down flat-lay on natural linen fabric, soft diffused "
+                      "light, a few tasteful props, professional product photography",
+    "Sunlit windowsill": "a sunlit wooden windowsill, warm morning light, soft "
+                         "natural shadows, cozy lifestyle product photo",
+    "Studio grey": "a seamless soft grey studio backdrop, even softbox lighting, "
+                   "subtle reflection, clean e-commerce style",
+    "Botanical": "soft green foliage and fresh natural light, botanical setting, "
+                 "professional product photo",
+}
+# Prepended to every scene so the product stays recognizable.
+GUARD = ("Keep the product itself unchanged and recognizable; change only the "
+         "background, surface and lighting. Restage it on ")
+
+_EX = os.path.join(os.path.dirname(__file__), "examples")
+EXAMPLES = [os.path.join(_EX, f) for f in ("latte.jpg", "room.jpg", "street.jpg")
+            if os.path.exists(os.path.join(_EX, f))]
+
+
+@GPU(duration=120)
+def stage(input_image: Image.Image | None, scene_key: str):
+    if pipe is None:
+        raise gr.Error(f"Model isn't loaded (this Space needs a GPU). {LOAD_ERR[:200]}")
+    if input_image is None:
+        raise gr.Error("Upload a product photo first (or pick an example).")
+    pipe.to("cuda")
+    img = input_image.convert("RGB")
+    w, h = klein_size(*img.size)
+    if img.size != (w, h):
+        img = img.resize((w, h), Image.LANCZOS)
+    prompt = GUARD + SCENES.get(scene_key, next(iter(SCENES.values())))
+    out, t = [], time.time()
+    for _ in range(VARIANTS):
+        seed = random.randint(0, MAX_SEED)
+        # Footgun: pass prompt and image by keyword (`image` is positional-first).
+        res = pipe(
+            prompt=prompt,
+            image=img,
+            width=w,
+            height=h,
+            num_inference_steps=STEPS,
+            guidance_scale=GUIDANCE,
+            generator=torch.Generator(device="cuda").manual_seed(seed),
+        ).images[0]
+        out.append(res)
+    return out, f"{VARIANTS} variations · {scene_key} · klein 4B · {time.time() - t:.1f}s"
+
+
+THEME = gr.themes.Soft(
+    font=["system-ui", "-apple-system", "Segoe UI", "Roboto", "Helvetica", "Arial", "sans-serif"],
+    font_mono=["ui-monospace", "SFMono-Regular", "Consolas", "monospace"],
+)
+CSS = """
+footer {visibility: hidden;}
+.gradio-container, .gradio-container .prose, .gradio-container p,
+.gradio-container h1, .gradio-container h2, .gradio-container h3 {
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif !important;
+}
+"""
+
+with gr.Blocks(title="Shopfront — Product Photo Studio", theme=THEME, css=CSS) as demo:
+    gr.Markdown(
+        "# 🛍️ Shopfront — Product Photo Studio\n"
+        "Selling something handmade? Upload a plain phone photo of your product and "
+        "**Shopfront** restages it on a clean, well-lit scene — keeping the product "
+        "itself intact — then hands you **four variations** to choose from. No prompt "
+        "writing, no studio. Powered by **FLUX.2 [klein] 4B** (4B params, Apache 2.0)."
+    )
+    with gr.Row():
+        with gr.Column():
+            in_img = gr.Image(type="pil", label="Your product photo", height=320)
+            scene = gr.Dropdown(list(SCENES), value="White marble", label="Scene")
+            btn = gr.Button("📸 Restage it", variant="primary")
+            if EXAMPLES:
+                gr.Examples(EXAMPLES, in_img, label="No product handy? Try a photo")
+        with gr.Column():
+            out = gr.Gallery(label="Pick your favourite", columns=2, height=420, object_fit="contain")
+            info = gr.Markdown()
+    btn.click(stage, [in_img, scene], [out, info])
+
+if __name__ == "__main__":
+    # ssr_mode=False: Gradio-5 SSR commonly renders unstyled raw HTML on Spaces.
+    demo.queue(max_size=8).launch(
+        server_name="0.0.0.0", server_port=7860, show_error=True, ssr_mode=False
+    )

configs/my_lora_klein_4b.yaml

@@ -0,0 +1,95 @@
+---
+# AI Toolkit config — a STYLE LoRA for FLUX.2 [klein] 4B.
+#
+# This trains klein to reproduce a visual style (illustration look, a product
+# aesthetic, a character) from 15-40 captioned images. Unlike an edit LoRA it
+# has NO control_path — it's plain text-to-image.
+#
+# Run it (on a RunPod pod with the official AI Toolkit template, or any 24GB+ GPU):
+#
+#     cd /app/ai-toolkit
+#     python run.py /workspace/configs/my_lora_klein_4b.yaml
+#
+# Before you run, change the three things marked  <<< CHANGE >>>  below.
+#
+# Full walkthrough: TRAIN_A_LORA.md (same folder).
+job: "extension"
+config:
+  name: "my_lora_klein_4b_v1"          # <<< CHANGE >>> names your output folder
+  process:
+    - type: "diffusion_trainer"
+      training_folder: "/app/ai-toolkit/output"
+      device: "cuda"
+
+      # Your trigger word. Use something that is NOT a real word so it can't
+      # collide with the model's vocabulary — e.g. MYSTYLE7, RISO_PR1NT, ZK_TOON.
+      # Every caption .txt must start with this exact token.
+      trigger_word: "MYSTYLE7"          # <<< CHANGE >>>
+
+      network:
+        type: "lora"
+        # 128/64/64/32 — strong default for klein (textured/painterly styles).
+        # Drop to 64/32/32/16 for flat vector / graphic styles.
+        linear: 128
+        linear_alpha: 64
+        conv: 64
+        conv_alpha: 32
+
+      save:
+        dtype: "bf16"
+        save_every: 250                 # checkpoint every 250 steps so you can pick
+        max_step_saves_to_keep: 8
+
+      datasets:
+        - folder_path: "/workspace/datasets/my_style"   # <<< CHANGE >>> your images+captions
+          caption_ext: "txt"
+          caption_dropout_rate: 0.05
+          shuffle_tokens: false
+          cache_latents_to_disk: true
+          resolution:
+            - 512
+            - 768
+            - 1024
+
+      train:
+        batch_size: 1
+        steps: 1800                     # 15-20 imgs: ~1500; 20-40 imgs: 1500-2000
+        gradient_accumulation_steps: 1
+        gradient_checkpointing: true
+        noise_scheduler: "flowmatch"    # required for klein
+        optimizer: "adamw8bit"
+        timestep_type: "shift"
+        content_or_style: "balanced"
+        lr: 0.0001
+        optimizer_params:
+          weight_decay: 0.00015
+        dtype: "bf16"
+
+      model:
+        # ALWAYS the BASE (un-distilled) checkpoint. Distilled won't fine-tune.
+        name_or_path: "black-forest-labs/FLUX.2-klein-base-4B"
+        # REQUIRED for klein. Without it ai-toolkit falls back to
+        # StableDiffusionPipeline and dies on a missing-unet error.
+        # https://github.com/ostris/ai-toolkit/issues/691
+        arch: "flux2_klein_4b"
+        quantize: true                  # keeps headroom on a 24GB GPU
+        low_vram: false                 # set true on <22GB, accept slower training
+
+      sample:
+        sampler: "flowmatch"
+        sample_every: 250
+        width: 1024
+        height: 1024
+        seed: 42
+        walk_seed: true
+        guidance_scale: 4
+        sample_steps: 20
+        prompts:
+          # Use YOUR trigger word here so the in-training samples show the style.
+          - "MYSTYLE7. a portrait of a young woman, soft light"
+          - "MYSTYLE7. a small house on a hill, wide shot"
+          - "MYSTYLE7. a cat sitting on a windowsill"
+
+meta:
+  name: "my_lora_klein_4b"
+  version: "1.0"

requirements.txt

@@ -0,0 +1,15 @@
+# FLUX.2 [klein] needs a diffusers build that has Flux2KleinPipeline.
+# As of writing that's diffusers main, not a tagged release.
+git+https://github.com/huggingface/diffusers.git
+torch
+transformers
+accelerate
+# peft is the backend diffusers uses for load_lora_weights() — without it the
+# LoRA tab raises "PEFT backend is required for this method."
+peft
+safetensors
+sentencepiece
+protobuf
+pillow
+# Provides @spaces.GPU on ZeroGPU hardware. Harmless elsewhere.
+spaces