Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ HF_TOKEN=
# LDS_QWEN21_MODEL=qwen_image_2.1_int8_convrot.safetensors
# LDS_QWEN21_TEXT_ENCODER=qwen3vl_8b_int8_convrot.safetensors
# LDS_QWEN21_VAE=qwen_image_2.1_vae_bf16.safetensors
# LDS_QWEN21_MAX_REFS=1 # references per local shot (1-16)
# LDS_QWEN21_RESOLUTION=1536 # reference/output size, about N x N pixels
# LDS_UPSCALE_MODEL=4xNomosWebPhoto_RealPLKSR.safetensors
# LDS_DEJPG_MODEL=1xDeJPG_OmniSR.pth
# LDS_SAM3_CHECKPOINT=sam3.1_multiplex_fp16.safetensors
8 changes: 4 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ Turn a character, style, or concept into a ready-to-train LoRA dataset. One refe

_Last verified: 2026-10-08_

- **Status:** in active development; main is v0.18.1 (git tag `v0.18.1`). **Every version bump must ship a GitHub Release** or the in-app update check never fires. The project was renamed twice (lora-dataset-studio → lora-distillery → dataset-deviser); older references under the previous names are stale.
- **Works:** all five stages end to end (preprocess → generate & curate → caption → export → train config); the three dataset types (character, style, concept) with their own shot plans and caption framing; local and cloud paths for every stage; gallery curation with selection carried forward between stages, including shift-click range select; advisory dedupe, quality flags and caption lint; trainer configs for ai-toolkit (incl. SDXL), kohya sd-scripts, musubi-tuner and Fizgig; opt-in private Hugging Face publish. Since 0.15.0: per-image fault isolation in ① (one bad source never ends the batch), a cooperative ⏹ Stop across ①/②/③ with documented resume paths, translated ComfyUI failures (missing node, bad input, unreachable server) and an in-app 🩺 setup check. Since 0.15.1: a ② **shot style** (default = keep the reference's own medium; eight presets + custom text) threaded into both prompt builders, the CLI, ④ metadata and ⑤'s sample prompt, a final-prompt preview, and a prev/next/save-and-next caption editor with the image on screen. Since 0.16.0: **one name box and one trigger box in the header** that ②/③/④/⑤ all read (they used to be per-tab and went stale), ④ stating the pair it stamped, an opt-in ④ **hand-off to [Idiot LoRa Builder](https://github.com/Fablestarexpanse/Idiot-Lora-Builder)** (writes its `.lora-studio/ratings.json` so its grid opens pre-triaged — nothing is launched), a ⑤ advisory when the dataset can't fill the training resolution, every bundled ComfyUI model filename overridable from `.env`, and a `cli build` preflight for the local engine. Since 0.17.0: the local ② engine is **Qwen-Image 2.1** (plain-English prompts shared with Gemini, ~26 s/shot, `LDS_QWEN21_*` filenames) instead of Qwen-Image-Edit 2511 + the Multiple-Angles LoRA, whose graph stays in `studio/comfy_workflows/legacy/`; a dead ComfyUI mid-batch now fails one shot, not the run. Since 0.17.1: the UI port is chosen by `_pick_port` in `app.py` — 7861 if bindable, else an OS-assigned free port (Windows reserves a ~500-port block around 7861), or `LDS_PORT` to pin one. Since 0.17.2: `comfy_api.upload_image` downscales a source over 90 MB before upload (ComfyUI answers 413 above its 100 MB `--max-upload-size`). Since 0.17.3: the cloud image model defaults to **`auto`** (Google shut down the `-preview` ids on 2026-06-25; `resolve_image_model` picks from the cached live list, Nano Banana 2.1 first), Groq captions use `qwen/qwen3.8-27b` (key `groq-qwen`, old key aliased), every API image goes through `config.api_image` (true mime, size cap), musubi commands include the cache steps and the per-architecture network module, ai-toolkit gains Qwen-Image 2.1 and a correct Krea 2 (Raw) preset and keeps every checkpoint, ① applies EXIF rotation, no longer 4x-upscales large JPEGs, and can jump a busy ComfyUI queue like ② (`--front` on `preprocess`/`build`). Since 0.18.0: ⑤ counts **epochs** (one checkpoint and one sample set each) with auto repeats sized to a step target and a live exposure line; every config ships a `validation/` pack (8 fixed prompts at seed 42, `validation.md`, a per-epoch score sheet); **Fizgig** is a ⑤ target (Krea 2 / Qwen Image 2.1 / Klein); ① stamps a `dd_source` provenance PNG chunk so ⑤ names upscaled sources and ④ knows real photos; ④ can hold out N real photos in a `-heldout` sibling as a likeness test. Since 0.18.1: a ⑤ optimizer dropdown, AdamW8bit by default, Prodigy (lr 1.0, its diffusion args) for ai-toolkit/musubi/kohya; Fizgig stays AdamW8bit.
- **In progress:** a phased LoRA best-practice update. 0.19.0 is next: training copies keep their background, identity policy (outfits vary by default), framing tiers, a coverage panel, a full-body warning, near-duplicate/burst flags, an anchor shot, local multi-reference. Then 0.20.0 (a Quick build tab). Nothing from those is half-built on main. The attention-only toggle planned for 0.18.0 was deferred (ARCHITECTURE.md → Future ideas).
- **Known gaps / next steps:** Auto's model order (`IMAGE_MODEL_PREFERENCE`, Nano Banana 2.1 then Pro) rests on one A/B subject — see ARCHITECTURE.md; local ② still sends only the first reference. Otherwise pick up from `docs/ARCHITECTURE.md` → "Future ideas" / "Deferred", and read its *Maintainer principles* before changing anything; `gradio` is pinned `<6` because of a real stuck-loading-overlay regression — unpinning needs that verified fixed upstream; training is never launched for you and is not planned to be; the default export `output_root` writes into the repo root, so a smoke-test export leaves an untracked dataset folder to delete before committing.
- **Status:** in active development; main is v0.19.0 (git tag `v0.19.0`). **Every version bump must ship a GitHub Release** or the in-app update check never fires. The project was renamed twice (lora-dataset-studio → lora-distillery → dataset-deviser); older references under the previous names are stale.
- **Works:** all five stages end to end (preprocess → generate & curate → caption → export → train config); the three dataset types (character, style, concept) with their own shot plans and caption framing; local and cloud paths for every stage; gallery curation with selection carried forward between stages, including shift-click range select; advisory dedupe, quality flags and caption lint; trainer configs for ai-toolkit (incl. SDXL), kohya sd-scripts, musubi-tuner and Fizgig; opt-in private Hugging Face publish. Since 0.15.0: per-image fault isolation in ① (one bad source never ends the batch), a cooperative ⏹ Stop across ①/②/③ with documented resume paths, translated ComfyUI failures (missing node, bad input, unreachable server) and an in-app 🩺 setup check. Since 0.15.1: a ② **shot style** (default = keep the reference's own medium; eight presets + custom text) threaded into both prompt builders, the CLI, ④ metadata and ⑤'s sample prompt, a final-prompt preview, and a prev/next/save-and-next caption editor with the image on screen. Since 0.16.0: **one name box and one trigger box in the header** that ②/③/④/⑤ all read (they used to be per-tab and went stale), ④ stating the pair it stamped, an opt-in ④ **hand-off to [Idiot LoRa Builder](https://github.com/Fablestarexpanse/Idiot-Lora-Builder)** (writes its `.lora-studio/ratings.json` so its grid opens pre-triaged — nothing is launched), a ⑤ advisory when the dataset can't fill the training resolution, every bundled ComfyUI model filename overridable from `.env`, and a `cli build` preflight for the local engine. Since 0.17.0: the local ② engine is **Qwen-Image 2.1** (plain-English prompts shared with Gemini, ~26 s/shot, `LDS_QWEN21_*` filenames) instead of Qwen-Image-Edit 2511 + the Multiple-Angles LoRA, whose graph stays in `studio/comfy_workflows/legacy/`; a dead ComfyUI mid-batch now fails one shot, not the run. Since 0.17.1: the UI port is chosen by `_pick_port` in `app.py` — 7861 if bindable, else an OS-assigned free port (Windows reserves a ~500-port block around 7861), or `LDS_PORT` to pin one. Since 0.17.2: `comfy_api.upload_image` downscales a source over 90 MB before upload (ComfyUI answers 413 above its 100 MB `--max-upload-size`). Since 0.17.3: the cloud image model defaults to **`auto`** (Google shut down the `-preview` ids on 2026-06-25; `resolve_image_model` picks from the cached live list, Nano Banana 2.1 first), Groq captions use `qwen/qwen3.8-27b` (key `groq-qwen`, old key aliased), every API image goes through `config.api_image` (true mime, size cap), musubi commands include the cache steps and the per-architecture network module, ai-toolkit gains Qwen-Image 2.1 and a correct Krea 2 (Raw) preset and keeps every checkpoint, ① applies EXIF rotation, no longer 4x-upscales large JPEGs, and can jump a busy ComfyUI queue like ② (`--front` on `preprocess`/`build`). Since 0.18.0: ⑤ counts **epochs** (one checkpoint and one sample set each) with auto repeats sized to a step target and a live exposure line; every config ships a `validation/` pack (8 fixed prompts at seed 42, `validation.md`, a per-epoch score sheet); **Fizgig** is a ⑤ target (Krea 2 / Qwen Image 2.1 / Klein); ① stamps a `dd_source` provenance PNG chunk so ⑤ names upscaled sources and ④ knows real photos; ④ can hold out N real photos in a `-heldout` sibling as a likeness test. Since 0.18.1: a ⑤ optimizer dropdown, AdamW8bit by default, Prodigy (lr 1.0, its diffusion args) for ai-toolkit/musubi/kohya; Fizgig stays AdamW8bit. Since 0.19.0: ① training copies **keep their background** and the isolated copy goes to `prepped/refs/` for ② only (angle re-isolation is its own ② option, off); a header **identity policy** for characters (Identity only varies outfits and captions clothing; Signature costume keeps the outfit out of captions); four framing tiers in the shot plan and a ② coverage line with a dominance warning; a cut-off-reference warning; ② near-duplicate finder and primary-reference preview, ④ burst grouping; local ② sends several references (`LDS_QWEN21_MAX_REFS`, default 1) at `LDS_QWEN21_RESOLUTION` (1536); Gemini gets a per-shot aspect and a reference cap; an opt-in **anchor shot**; SAM3 load errors name a stale `HF_TOKEN`.
- **In progress:** a phased LoRA best-practice update. 0.20.0 is next: a ⚡ Quick build tab and `cli build` on shared `pipeline.build_start`/`build_finish`. Nothing from it is half-built on main. The attention-only toggle planned for 0.18.0 was deferred (ARCHITECTURE.md → Future ideas).
- **Known gaps / next steps:** Auto's model order (`IMAGE_MODEL_PREFERENCE`, Nano Banana 2.1 then Pro) rests on one A/B subject — see ARCHITECTURE.md; the local defaults (one reference, 1536, anchor off) likewise rest on one A/B subject. Otherwise pick up from `docs/ARCHITECTURE.md` → "Future ideas" / "Deferred", and read its *Maintainer principles* before changing anything; `gradio` is pinned `<6` because of a real stuck-loading-overlay regression — unpinning needs that verified fixed upstream; training is never launched for you and is not planned to be; the default export `output_root` writes into the repo root, so a smoke-test export leaves an untracked dataset folder to delete before committing.
- **Deep docs:** `docs/ARCHITECTURE.md` (module map, stage and backend detail, gotchas, backlog — the deep reference), `docs/comfyui-setup.md`. Worklogs under `docs/` are gitignored and local-only by design.

## Architecture in 60 seconds
Expand Down
32 changes: 21 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,13 +222,22 @@ CLI: `--shot-style anime`, or `--shot-style custom --shot-style-text "a woodcut

## Two things that ruin a character LoRA

Both have a switch in ②, because both bit us:
Both are handled by default, because both bit us:

- **Same clothes in every image** → the LoRA learns the outfit as the character. Hit
**🎲 Randomize outfits** to dress each angle/pose shot differently.
- **Same clothes in every image** → the LoRA learns the outfit as the character. The header's
**Identity policy** is *Identity only* by default: every angle/pose shot gets a different
outfit and the captions name the clothing. Pick *Signature costume* when the outfit **is** the
character (a superhero suit): outfits stay as drawn and captions leave them out.
- **Props copied into every shot** (a backpack in the reference → the LoRA thinks the backpack
*is* the character). Best fix: **isolate the source in ①** — SAM3 keeps bags and held objects
out of the subject mask. The "Exclude props" toggle in ② helps too, especially on Gemini.
*is* the character). Best fix: **isolate the source in ①** and name anything held (a cup, a
plate) in **Objects to remove** — SAM3 counts a held object as part of the person. The
"Exclude props" toggle in ② helps too, on Gemini only.

① keeps your photos' own backgrounds for training: the white cut-out it makes goes to
`prepped/refs/` and is only ②'s reference. ② shows the coverage of the shots you keep (framing,
turnaround, expressions, outfits) and can flag near-duplicates. If your only photos are cut off
at the waist, ① says so: full-body shots will invent the legs, so add a full-body photo if you
have one, or try ②'s **Anchor shot**, which builds every shot from one generated front view.

## Picking the best checkpoint

Expand All @@ -244,9 +253,10 @@ Every stage is a standalone subcommand; `--help` shows all options.

```bash
python cli.py preprocess ./sources --out ./prepped
python cli.py generate ./prepped --name "Sy Snootles" --engine comfyui --randomize-outfits
python cli.py generate ./prepped --name "Sy Snootles" --shot-style anime # keep an illustrated look
python cli.py generate ./prepped --name "brass compass" --dataset-type concept # 18-shot object set
python cli.py generate ./prepped/refs --name "Sy Snootles" --engine comfyui
python cli.py generate ./prepped/refs --name "Sy Snootles" --identity costume # outfit is the character
python cli.py generate ./prepped/refs --name "Sy Snootles" --shot-style anime # keep an illustrated look
python cli.py generate ./prepped/refs --name "brass compass" --dataset-type concept # 18-shot object set
python cli.py caption ./folder --trigger sysnootles # prose sidecars
python cli.py caption ./folder --trigger sysnootles --caption-style tags # Danbooru tags
python cli.py caption ./folder --trigger mystyle --dataset-type style # style-framed
Expand Down Expand Up @@ -283,9 +293,9 @@ Set or change any of them with `python cli.py keys` — they live only in a giti
generation, built-in SAM3, local captioning and export all work without it. **No custom nodes
required.** See [docs/comfyui-setup.md](docs/comfyui-setup.md).
- **Sources are never modified**; every stage writes copies.
- **Alpha cutout, on request.** ① Preprocess can export the isolated subject on a transparent
background instead of white (builtin SAM3 backend only) — for your own compositing workflows.
Leave it off (default) if you're continuing to ② Generate, which expects a white reference.
- **Alpha cutout, on request.** ① Preprocess can make the `refs/` cut-out transparent instead
of white (builtin SAM3 backend only) — for your own compositing workflows. ② expects a white
reference, so ① then leaves ②'s source folder for you to fill.
- The UI binds to `127.0.0.1` with **no authentication** — don't expose it. So galleries can
preview images from any folder you point a tab at, the local file server can read any file the
app process can while it's running; that's safe only behind the localhost bind, so never forward
Expand Down
Loading
Loading