Scenario Model Training

Scenario Model Training

Overview

Train a custom model when one look must hold across many assets: an icon set, a recurring character, a product line. Prompts, references, and control maps are cheaper first steps: see scenario-consistency. Before quoting a training run, run the reference test scenario-consistency teaches for the subject at hand: the approved art as style references (with the prompt saying they set the style only) for a look, the hero as a subject reference for a character or product. At authoring time a style test matched the look of a custom LoRA on the same brief at a comparable per-image price, for the cost of one generation. Train when that test drifts across the set, not before; the worked example below starts after it.

The judgment calls live in two references: references/base-model-selection.md (the user interview that feeds recommend_training) and references/dataset-curation.md (dataset size, image rules, captions, and review per training type).

Connection and the core generation loop: see the scenario skill. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

Training tools are not in the default toolset: get schemas with scenario_tools_search, run reads (recommend_training, model_get) via scenario_tool_execute_read and writes (model_create, train, model_update) via scenario_tool_execute_write, or reconnect with ?toolsets=full.

Quick reference

Worked example: a style LoRA for game props

1. recommend_training with prompt: "hand-painted prop icons for a mobile RPG", modality: "image", dataset_shape: "single_images", plus subject, style, and priority from the interview. Returns a recommended variant, alternatives, and dataset_requirements (shape and size bounds). Cost-bearing: call it once with clear intent.
2. model_create with data: {"name": "rpg-prop-icons", "type": "<type from step 1>"}. Note the returned model id.
3. Curate the set first (dataset reference), matching dataset_requirements from step 1, then upload each file with upload_asset plus upload_asset_complete (see the scenario skill) and collect the asset ids. For image_pairs datasets, map pairs with train action set_pairs.
4. train with action: "upload_images", model_id, images: [<asset ids>], at most 10 per call (see Dataset limits); it changes data, so pass team_id and project_id (scope: the scenario skill).
5. train with action: "configure", config: {"epochs": 12, "sample_prompts": ["a rusty lantern icon, centered, plain field", "a blue mana potion icon, three-quarter view, plain field"]}, dry_run: true returns the quote and starts nothing. epochs is the main cost lever (scales linearly); size the other levers by dataset size (dataset reference). sample_prompts is not optional on a multi-epoch run: the trainer publishes a per-epoch checkpoint only for a run that has them, so a run without them finishes with its final weights alone, one epoch to choose from whatever epochs said, and a model that ends up overfit has nothing earlier to fall back to (a 12-epoch run that came back with a single selectable epoch was this). Caps are per family, 8 on the Flux LoRA family and 4 on Flux.2, Qwen and ZImage LoRAs at authoring time, so read them off the train schema. Write prompts that test the concept off-dataset, following the caption rules of the training type (a style set names new subjects and never the style; a character set leads with the trigger word and a new pose or setting): they are the previews you pick the epoch from, and generic prompts return generic scenes at every epoch, which is how one run spent its whole quote on twenty previews of four unrelated landscapes. Edit families take sample_source_images, one asset id per prompt in the same order; every other family rejects the field. Show the user the quote and get a go-ahead, then launch with action: "start" and the same config (unattended, launch only when the task already authorized training or a budget covering it; otherwise stop and report the quote). configure always quotes and never launches; dry_run: false there is rejected. Only start launches training; start with dry_run: true quotes instead. Treat start as spending the whole quote: do not count on stop returning any of it.
6. The launch response includes a job: jobs_wait with its id in job_ids. No job id means nothing launched: report it instead of retrying. Training outlasts the server wait budget, so re-call with the returned pending_job_ids until completed; never poll job_get.
7. Pick the epoch from the previews before generating: they sit on the model page in the web app, and the strongest is rarely the last. The pick is the user's; unattended, generate with the model as trained, say that the epoch choice was left open, and continue. Then model_schema_get on your new model id and model_run; custom models carry their own parameter contract. A LoRA runs on the base that the schema's runs_as and run_with.required_arguments name (see scenario) and on no other variant of its family, with one documented exception, the Z-Image LoRAs that carry across the Z-Image variants (base reference). A size mismatch or weight dimension error at generation means another variant was sent as the base, not that the training failed: do not retrain, re-read run_with and run the pair it names.
8. Manage: models_list with filters: {"privacy": "private", "status": "trained"} lists ready models. model_get with include_description: true fetches the full docs; model_update edits name, descriptions, privacy.