train_prepare_dataset
Prepare and manage LoRA training datasets. Stage, list, inspect, edit, delete, and caption images so they're ready for ComfyUI training jobs.
Instructions
Stage and curate the training DATASETS a LoRA run consumes — the images and their captions. Datasets are keyed by name; the jobs that train on them live in the separate train_start tool and are keyed by id. Driven by the action parameter:
action:"prepare" — Stage training images + captions into a dataset dir the trainer consumes. Each item is an image (absolute
path, OR a ComfyUIref{filename,subfolder?,type?} resolved against the connected ComfyUI's output/input dirs — how phone/panel pickers hand over selections) with an optional caption (a missing caption falls back to defaultCaption — typically the trigger word). Requiresname+items. Returns the datasetPath to pass to train_start (action:"start"). Character LoRA guidance: 10-30 varied images; caption what changes between images, keep the trigger word constant.action:"list" — List staged datasets, newest-first, with image/caption counts. Read-only, takes no other parameters. Pair with action:"detail" to see one dataset's images + captions.
action:"detail" — Show ONE staged dataset by
name: its dir (datasetPath — reusable as train_start's datasetPath) and every image with its caption (null when uncaptioned). Images render via action:"file". Read-only.action:"update" — Edit a staged dataset by
name: set/replace per-image captions (setCaptions) and/or delete individual images with their caption files (deleteImages). Refuses while a running/queued job trains from it. Returns per-file warnings for unknown files. This is the SURGICAL edit — it removes only the filenames you list, leaving the dataset itself in place.action:"delete" — DESTROY a whole staged DATASET by
name: every image and every caption under it. Irreversible, and the images are typically hand-curated and unrecoverable — confirm with the user first. Refuses while a running/queued job trains from it. THIS DELETES A DATASET, NOT A TRAINING JOB: to delete a finished job's record and checkpoints use the separatetrain_starttool with action:"delete", which is keyed byidrather thanname. To remove only SOME images, use action:"update" withdeleteImages.action:"file" — Fetch an image under the training root (dataset image, job sample) by absolute
pathas an inline image — the tunnel-safe way for a phone/panel to render training files it can't reach over /view. Bounded: image files only, ≤ 2MB.action:"caption_image" — Caption ONE image by absolute
pathwith the user's own Claude subscription (one vision turn through the Agent SDK — not a paid API). Returns the bare caption and does NOT write it — review, then save with action:"update", or use action:"caption_dataset" to write directly. Optionalguidesteers the style; optionaltriggeris prepended by the model.action:"caption_dataset" — Caption a whole staged dataset by
name(or theonlysubset) with the user's own Claude subscription and WRITE the captions into its .txt files (one vision turn per image, sequential). Captioning ALWAYS runs through Claude (Agent SDK) regardless of the panel's active backend, so it needs a logged-in Claude Code session (or ANTHROPIC_API_KEY). Use after gathering images, before train_start (action:"start"). Per-file transient failures are reported without stopping the batch, but a persistent auth/credential failure stops immediately with an actionable error rather than failing every image. Optionalguidesteers all captions; optionaltriggeris prepended to each.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Dataset name — the staging dir name. REQUIRED for actions "prepare" (it is created), "detail", "update", "delete" and "caption_dataset" (from action:"list"). This is a DATASET name, never a training job id. | |
| only | No | action:"caption_dataset" — subset of filenames to caption (default: all images). | |
| path | No | Absolute path of a file under the training root. REQUIRED for action:"file" (a dataset image or job sample, from action:"detail"'s datasetPath or train_start action:"status"'s samples) and for action:"caption_image" (the image to caption). | |
| guide | No | actions "caption_image"/"caption_dataset" — extra style guidance for the captioner (e.g. 'focus on outfits and backgrounds'). | |
| items | No | action:"prepare" — the images to stage. REQUIRED for that action. | |
| action | Yes | Which dataset operation to perform. "list" takes no other parameters; "prepare" requires `name` + `items`; "detail", "update", "delete" and "caption_dataset" require `name`; "file" and "caption_image" require `path`. NOTE "delete" here destroys a DATASET (images + captions) — deleting a training JOB is train_start action:"delete". | |
| trigger | No | actions "caption_image"/"caption_dataset" — trigger word to prepend to the caption(s). | |
| setCaptions | No | action:"update" — {filename: caption} pairs to write (replaces existing captions). | |
| deleteImages | No | action:"update" — image filenames to delete from the dataset (caption files go too). Removes only these files; action:"delete" removes the whole dataset. | |
| defaultCaption | No | action:"prepare" — fallback caption for items without one; usually the trigger word. |