# 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.