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
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@ Turn a character, style, or concept into a ready-to-train LoRA dataset. One refe

## Current state

_Last verified: 2026-10-09_
_Last verified: 2026-10-24_

- **Status:** in active development; main is v0.20.0 (git tag `v0.20.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`. Since 0.20.0: a **⚡ Quick build** tab (first tab: drop images, name, Cloud or Local, trainer; Build runs ①→②, untick, Finish runs ③→④→⑤) and `cli build` share `pipeline.build_start`/`build_finish`, and `cli build` writes ⑤ configs with `--trainer/--model`; a failed isolation keeps the photo and gives ② the whole image; builtin SAM3 retries `person` on real photos; a ComfyUI job's timeout no longer runs while it waits in the queue; `HUGGINGFACE_API_KEY` stands in when there is neither an `HF_TOKEN` nor an `hf auth login`; a caption that opens with the name in another case (`Ann` for trigger `ann`) now opens with the trigger's exact casing; `cli build` and Quick build Finish show ⑤'s undersized/upscaled warnings.
- **Status:** in active development; main is v0.20.1 (git tag `v0.20.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. 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`. Since 0.20.0: a **⚡ Quick build** tab (first tab: drop images, name, Cloud or Local, trainer; Build runs ①→②, untick, Finish runs ③→④→⑤) and `cli build` share `pipeline.build_start`/`build_finish`, and `cli build` writes ⑤ configs with `--trainer/--model`; a failed isolation keeps the photo and gives ② the whole image; builtin SAM3 retries `person` on real photos; a ComfyUI job's timeout no longer runs while it waits in the queue; `HUGGINGFACE_API_KEY` stands in when there is neither an `HF_TOKEN` nor an `hf auth login`; a caption that opens with the name in another case (`Ann` for trigger `ann`) now opens with the trigger's exact casing; `cli build` and Quick build Finish show ⑤'s undersized/upscaled warnings. Since 0.20.1: `.jfif` sources are listed (exported and uploaded as `.jpg`), ④ re-encodes BMP/TIFF to PNG because ai-toolkit silently skips them, and `validation.md` ends with a LoRA-strength sweep.
- **In progress:** nothing half-built on main. The phased LoRA best-practice update (0.17.3–0.20.0) is complete; the optional local face model (drift flag, verified coverage) awaits a go-ahead. 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.
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ ai-toolkit, kohya, musubi or Fizgig, and a validation pack for picking the best
- **Curate by clicking the images.** Toggle any shot straight from the gallery, with a ✅/⬜ mark
on each thumbnail. Your pick follows you: what you keep in ② is what ③ captions, and what ③
captions is what ④ preselects for export — nothing is silently re-added behind you.
- **Trainer-ready output.** Flat `NN.png` + `NN.txt` (JPEG/WEBP sources keep their own extension),
- **Trainer-ready output.** Flat `NN.png` + `NN.txt` (JPEG/WEBP sources keep their own extension; BMP/TIFF become PNG),
`metadata.json`/`metadata.jsonl`, optional `.zip` and Hugging Face publish, and a generated config
for Flux / SDXL / Qwen-Image / Krea / Pony and more.
- **Interruptible, and hard to derail.** **⏹ Stop** ends a long run after the current image and
Expand Down Expand Up @@ -254,7 +254,7 @@ have one, or try ②'s **Anchor shot**, which builds every shot from one generat
⑤ sets training in **epochs**: every epoch saves a checkpoint and renders the same 8 test
prompts at the same seed. Leave **Repeats** at 0 and it sizes each epoch for you; the exposure
line shows the total. The `validation/` folder it writes holds the prompts, a short guide and a
score sheet. To test likeness fairly, set **Hold out N reference photos** in ④: those photos
score sheet; the guide ends with a LoRA-strength sweep (0.6 to 1.4) for the epoch you pick. To test likeness fairly, set **Hold out N reference photos** in ④: those photos
stay out of training, in a `-heldout` folder beside the dataset, to compare samples against.

## CLI
Expand Down
5 changes: 4 additions & 1 deletion docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Architecture

Version: 0.20.0
Version: 0.20.1

```
app.py Gradio UI — thin wiring over the stage functions (⚡ Quick
Expand Down Expand Up @@ -556,6 +556,9 @@ quietly gets someone else's value.
folder. `package.py` now preserves the (normalised, lowercased, `.jpeg`→`.jpg`) suffix and
`metadata.jsonl`'s `file_name` is the name actually written, which HF `imagefolder`
resolves literally. Captions still pair by stem, so a mixed-format folder is fine.
The exceptions are BMP and TIFF, which are re-encoded to `NN.png`: ai-toolkit's loader
reads only jpg/jpeg/png/webp and silently skips the rest, leaving an orphan caption.
`.jfif` (Chrome's name for a downloaded JPEG on Windows) is listed and exports as `.jpg`.
- **Caption sidecars are user files; read them forgivingly.** Every read used strict
`encoding="utf-8"`, so a cp1252 `.txt` from another tool raised `UnicodeDecodeError` and
killed the whole stage, and a UTF-8 BOM silently prefixed `` to the trigger word in
Expand Down
2 changes: 1 addition & 1 deletion studio/__init__.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
"""Dataset Deviser: turn a character, style, or concept into a ready-to-train LoRA dataset."""

__version__ = "0.20.0"
__version__ = "0.20.1"
4 changes: 3 additions & 1 deletion studio/comfy_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -239,7 +239,9 @@ def upload_image(path: Path) -> str:
tmp = _shrink_for_upload(path) if path.stat().st_size > MAX_UPLOAD_BYTES else None
send = tmp or path
try:
name = f"lds_{uuid.uuid4().hex[:10]}{send.suffix.lower()}"
ext = send.suffix.lower()
# ComfyUI lists input files by mimetype; Linux has none for .jfif (a JPEG).
name = f"lds_{uuid.uuid4().hex[:10]}{'.jpg' if ext == '.jfif' else ext}"
with send.open("rb") as f:
r = httpx.post(
f"{settings.comfy_url}/upload/image",
Expand Down
3 changes: 2 additions & 1 deletion studio/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -471,7 +471,8 @@ def save_caption_model_cache(models: list[dict]) -> None:
"""Persist the live Gemini caption-model list with a timestamp."""
_save_model_cache_file(CAPTION_MODEL_CACHE_FILE, models)

IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".webp", ".bmp", ".tif", ".tiff"}
# .jfif is a JPEG; Chrome on Windows saves downloads with it.
IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".jfif", ".webp", ".bmp", ".tif", ".tiff"}


class Settings(BaseSettings):
Expand Down
24 changes: 21 additions & 3 deletions studio/package.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,28 @@ def normalize_suffix(suffix: str) -> str:
Export copies source bytes verbatim, so the extension it writes has to be the
source's real one — it used to hard-code `.png`, which mislabelled every JPEG
and WEBP source as PNG. Normalising keeps a folder from ending up half `.JPG`
and half `.jpeg` for the same format.
and half `.jpeg` for the same format. BMP and TIFF map to `.png`: export
re-encodes them, because ai-toolkit reads only jpg/jpeg/png/webp and skips
anything else without a word.
"""
suffix = (suffix or "").lower()
return ".jpg" if suffix == ".jpeg" else suffix or ".png"
if suffix in (".jpeg", ".jfif"):
return ".jpg"
return ".png" if suffix in _REENCODE or not suffix else suffix


_REENCODE = {".bmp", ".tif", ".tiff"}


def _write_image(src: Path, dst: Path) -> None:
"""Copy the source bytes, or re-encode a BMP/TIFF to PNG."""
if src.suffix.lower() not in _REENCODE:
shutil.copy2(src, dst)
return
from PIL import Image

with Image.open(src) as im:
im.convert("RGBA" if "A" in im.getbands() else "RGB").save(dst, "PNG")


@dataclass
Expand Down Expand Up @@ -141,7 +159,7 @@ def package_dataset(
for i, (img, caption) in enumerate(items, start=1):
stem = f"{i:02d}"
filename = f"{stem}{normalize_suffix(img.suffix)}"
shutil.copy2(img, ds_dir / filename)
_write_image(img, ds_dir / filename)
(ds_dir / f"{stem}.txt").write_text(caption, encoding="utf-8")
# HuggingFace `imagefolder` caption metadata, so the dataset also loads
# directly via datasets.load_dataset("imagefolder", ...) with captions.
Expand Down
2 changes: 1 addition & 1 deletion studio/preprocess.py
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ def _needs_restoration(img: Image.Image, path: Path, target: int) -> str:
long_side = max(img.size)
if long_side < target:
return f"long side {long_side}px < target {target}px"
if path.suffix.lower() in (".jpg", ".jpeg", ".webp") and long_side < 2 * target:
if path.suffix.lower() in (".jpg", ".jpeg", ".jfif", ".webp") and long_side < 2 * target:
return "lossy source format"
if _laplacian_variance(_resize_to_target(img, target)) < BLUR_THRESHOLD:
return "low sharpness (blur/grain)"
Expand Down
7 changes: 7 additions & 0 deletions studio/trainer_configs.py
Original file line number Diff line number Diff line change
Expand Up @@ -677,6 +677,13 @@ def _guide(cfg: TrainConfig, prompts: list[str]) -> str:
"3. Keep the earliest epoch where likeness stops improving. When adherence "
"drops or unwanted traits climb, later epochs are overfitting.\n"
f"{held_block}\n"
"## Then sweep the strength\n\n"
f"Render prompts 1 and 2 with the chosen checkpoint at LoRA strength 0.6, 0.8, "
f"1.0, 1.2 and 1.4, seed {VALIDATION_SEED} each time. A good LoRA looks right "
"near 1.0. Likeness only arriving at 1.2 or more means undertrained: take a later "
"epoch. Likeness already there at 0.6-0.8 while 1.0 breaks the prompt means "
"overtrained: take an earlier one. If you will use the LoRA on a finetune or "
"merge of the base, run the same sweep there too.\n\n"
f"## Inference settings\n\n{settings}\n\n"
f"## Prompts (seed {VALIDATION_SEED})\n\n{numbered}")

Expand Down
14 changes: 14 additions & 0 deletions tests/test_comfy_upload_size.py
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,17 @@ def fake_post(url, files, data, timeout):
monkeypatch.setattr(comfy_api.httpx, "post", fake_post)
comfy_api.upload_image(src)
assert sent["path"] == str(src)


def test_jfif_source_is_uploaded_with_a_jpg_name(tmp_path, monkeypatch):
src = tmp_path / "download.jfif"
Image.new("RGB", (8, 8)).save(src, "JPEG")
sent = {}

def fake_post(url, files, data, timeout):
sent["name"] = files["image"][0]
return _Resp()

monkeypatch.setattr(comfy_api.httpx, "post", fake_post)
comfy_api.upload_image(src)
assert sent["name"].endswith(".jpg")
Loading
Loading