# Base model selection

The base architecture is the one training decision that cannot be undone: a LoRA is bound to the base it was trained on, and that choice fixes the quality ceiling, generation speed, and per-image cost of every future run. Interview the user first, then let `recommend_training` make the call. The cheat sheet below is for discussing trade-offs in the user's terms, never for asserting a model id: availability differs per team and the catalog moves, so the returned `type` is the only value to build on.

## The interview

Ask (or extract from the brief) before recommending anything, and map each answer to a `recommend_training` argument:

1. **What must the model reproduce?** A character, a product or object, an environment, an overall style, or a transformation applied to existing images. Maps to `subject` (an overall style is `"style_transfer"`); a transformation means an edit LoRA, so also `dataset_shape: "image_pairs"`.
2. **Realistic, stylized, or mixed rendering?** Maps to `style`.
3. **What matters most: quality, speed, or cost?** Maps to `priority` (default `balanced`). Anchor it with expected volume: hero art and key visuals justify `quality`; thousands of assets or near real-time use justify `speed` or `cost`.
4. **What does the dataset look like?** Single images or before/after pairs; audio for voice. Maps to `dataset_shape` (and `modality: "voice"` for cloning, covered in SKILL.md).
5. **Any tie to an existing family?** Existing LoRAs to pair with or a pipeline pinned to an older base are the only reasons to set `legacy_ok: true`; the default excludes legacy families on purpose.

Then call `recommend_training` once, passing the user's original wording as `prompt` plus the extracted arguments. It returns the family, the exact `type` for `model_create`, up to three alternatives, and `dataset_requirements` to curate against (see [dataset-curation.md](dataset-curation.md)).

## Family cheat sheet

Positioning of the current image families, as documented in the Scenario knowledge base (help.scenario.com):

| Family                 | Positioning                                                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Flux 2 Dev             | Largest variant (32B): highest detail and prompt adherence; hero-quality work at the highest cost.                                                |
| Flux 2 Klein 9B        | The quality-speed sweet spot, faster than Dev; a strong default for production volume.                                                            |
| Flux 2 Klein 4B        | Smallest and fastest: near real-time generation and high-volume pipelines at the lowest cost in the family.                                       |
| Z-Image                | Strong training fidelity for character and style LoRAs at low cost; strong for photoreal characters and bilingual English/Chinese text rendering. |
| Z-Image Turbo          | The fastest, cheapest inference in the family but lower training fidelity: train on Z-Image, since the LoRA carries across the Z-Image variants.  |
| Qwen Image             | Strong text rendering (signs, UI, HUDs) and prompt adherence for complex scenes; cost-effective at volume; caption-sensitive training.            |
| Flux 2 Edit, Qwen Edit | Edit LoRAs trained on before/after pairs; Qwen Edit responds best to context-preserving instructions ("replace X with Y").                        |
| Flux.1, Flux Kontext   | Legacy families, excluded from recommendations unless `legacy_ok: true`.                                                                          |

Z-Image is the only family whose trained LoRA carries across its own variants; treat every other version choice as final. That portability also settles a conflict the tool can create: with `priority: "cost"`, `recommend_training` may recommend the Turbo variant, which trains worse; prefer the plain Z-Image alternative from the same response and run the finished LoRA on Turbo. When the user hesitates between quality and speed tiers, ask where the volume will be generated, not where the training happens: training is a one-time cost, inference is forever.

## Confirm the cost

The training quote is computed server-side from the base version, image count, and configuration, so never assert a price: `train` `action: "configure"` with `dry_run: true` returns the estimate without starting anything, and `action: "start"` launches once the quote is approved, exactly as the worked example in SKILL.md shows.

# Dataset curation

Read this before uploading training images, and whenever the task is to build or review a dataset. Nearly every disappointing LoRA traces back to the dataset or its captions, not to hyper-parameters, so spend the conversation here before touching `config`.

## Universal rules

- **Small and deliberate beats big and noisy.** 5 to 15 images is the sweet spot for most single-image LoRAs (styles tolerate up to about 20); a 12-image set with one clear intent outperforms 40 mixed pieces. Trimming also keeps you clear of the per-plan dataset ceiling described in SKILL.md.
- **Resolution floor.** Aim for 1024px or more on every side; upscale marginal images in-platform before training instead of feeding soft sources.
- **Consistency in the one thing being taught, variety in everything else.** Every image must reinforce the same target (same character, same artistic hand, same material). Everything the model should treat as variable (subject, pose, background, framing, lighting) should actually vary across the set.
- **Drop duplicates and near-duplicates.** Repetition teaches the repeated composition, not the concept. A set generated from one source image is the disguised case: twenty renders of the same face in new poses share one lighting, one camera distance, one expression range, and the model learns that render rather than the person. The symptom is a model that reproduces the same wrong face consistently while matching the caption text (hair, skin, age), because the captions carried more signal than the pictures. Rebuild the set from genuinely different shots, and where the only source is one image, shoot the variety deliberately (different lens distances, expressions, lighting, backgrounds) before treating any of it as a dataset.

## Composition by training type

| Type              | Sweet spot | Rules                                                                                                                                                                                                                                                             |
| ----------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Character         | 5-15       | Identical defining traits everywhere; at least 3 distinct poses even in a 5-8 image set; vary angle (front, profile, three-quarter), expression, and framing; mix backgrounds so the character does not learn to live in one room; crop out any second character. |
| Style             | 10-20      | One cohesive aesthetic; vary subjects, environments, and zoom so no subject becomes part of the style; never mix two styles in one dataset (train them separately).                                                                                               |
| Multi-character   | 8-15       | Every character appears in every image with its own constant traits; vary interactions and scenes.                                                                                                                                                                |
| Object or product | 5-15       | Constant geometry, material, and branding; vary angle, lighting, background, and scale.                                                                                                                                                                           |
| Environment       | 5-15       | Signature location elements constant; vary time of day, weather, and camera angle.                                                                                                                                                                                |
| Texture           | 10-15      | One material or pattern family; neutral ambient lighting keeps the result relightable; sources need not tile, the model handles tiling at generation time.                                                                                                        |
| Edit pairs        | 5-15 pairs | Counted in pairs: input, output, and a written instruction each; the transformation must be the same idea in every pair; drop pairs whose transformation diverges from the rest.                                                                                  |

## Captions decide constant versus variable

Every uploaded image gets an auto-generated caption; treat it as a draft, not an endpoint. The single principle everything follows from: **describe what should vary, never what must stay.** Whatever a caption names, the model learns to treat as promptable; whatever no caption names, it absorbs as part of the concept.

- Character, object, environment: open every caption with the same invented trigger word (`KAEL_07`, `MYBRAND_X`), then the constant identity traits, then the per-image variables (pose, expression, setting, light). A trigger word is caption text, not a training parameter; use it in every caption or in none, and reuse it later in generation prompts.
- Style: never name the style ("watercolor", "anime"); the style is what the model learns implicitly, and naming it ties the look to a word instead. Describe subject and scene only. A trigger word is optional, and auto-captions are often close enough for styles.
- Edit pairs: instructions, not descriptions, with one uniform verb pattern across the whole set ("turn the photo into MYSTYLE watercolor"). Context-preserving phrasing ("replace X with Y") outperforms whole-scene phrasing on edit families.
- Family note: Qwen-based training weighs captions heavily; fifteen minutes of caption cleanup routinely beats parameter tuning there.

## Reviewing a dataset through MCP

Training consumes each image's asset `description` as its caption: a rewritten description wins, and the auto-generated caption stays visible as `automaticCaptioning`, the fallback when no description is set. Scenario-generated images are already assets, so their ids go straight to `upload_images` with no upload step, and the `upload_images` response returns each attached image's auto-caption, the natural starting point for review. For a dataset attached earlier, `model_get` (via `scenario_tool_execute_read`) returns the training images with both fields; `asset_analyze` (catalog, cost-bearing) inspects image content at scale ("is a second character visible", "does this match the style of the others"). Fixes: rewrite a caption with `asset_update` (`metadata: {"description": "..."}`), remove an image with `train` `action: "delete_image"`, replace one with `action: "update_image"`. For a dataset still on disk, check dimensions and duplicates locally before spending uploads.

## Audit before launch

- Every image sharp and at or above the resolution floor; no duplicates.
- One intent per dataset; anything off-concept cropped out or removed.
- Trigger word all-or-none and byte-identical; constants present in every caption; variables genuinely differ per image.
- Edit sets: whole pairs only, one verb pattern, an instruction on every pair.
- No generic auto-caption boilerplate left ("beautiful", "stunning").
- Then `train` `configure` with `dry_run: true` for the cost before launching with `start`.

## Parameters follow the dataset

Per-family defaults and ranges live on the `train` config schema; scale them by dataset size (per the Scenario knowledge base):

| Images | learning_rate | epochs | nb_repeats |
| ------ | ------------- | ------ | ---------- |
| 5-10   | 5e-5          | 15-20  | 20-30      |
| 10-25  | 1e-4          | 10     | 15-20      |
| 25-50  | 2e-4          | 6-8    | 10-15      |

Underfit shows as the concept barely surfacing; overfit as training compositions reproduced literally and prompt changes losing effect. Per-epoch previews are how you tell the two apart before spending on generations: `config.sample_prompts` (at least one on any run with more than one epoch, per-family cap on the `train` schema, edit families also needing `sample_source_images` in the same order) renders every prompt at every epoch, and without them the trainer publishes no per-epoch checkpoints at all. Write them as off-dataset tests of the concept (trigger word, new pose, new setting, new framing), then pick the epoch on the model page and confirm with `model_run` on fresh prompts.