---

name: model-lifecycle description: "Guides RoboSat model training, checkpoint resume, ONNX export, batch prediction, on-demand serving, U-Net APIs, configs, and CPU/CUDA troubleshooting." disable-model-invocation: true metadata: disco-role: operating license: MIT

Model lifecycle

Use this sub-skill for RoboSat work that sits on the model side of the pipeline.

Use this route when the user needs to

• train a segmentation model on an existing slippy-map dataset
• resume or fine-tune from a .pth checkpoint
• export a trained checkpoint to an ONNX .pb
• run batch prediction and write probability tiles
• serve on-demand mask tiles through the Flask tile server
• inspect or reason about UNet, losses, metrics, transforms, or dataset wrappers
• debug CPU/CUDA, checkpoint, or config problems

Do not use this route for

• imagery download, OSM extraction, rasterization, class-weight generation, or tile-layout work
• probability-to-mask conversion, GeoJSON feature extraction, merge/dedupe/compare workflows
• Docker publishing or maintainer release workflows

Read first

• references/workflows.md for command templates and validation steps.
• references/configuration.md for model/dataset TOML fields and checkpoint format.
• references/api-reference.md for model classes, losses, metrics, transforms, and buffered tile helpers.
• references/troubleshooting.md for the common failure modes and recovery paths.

Bundled checks

• scripts/unet_cpu_smoke.py proves the installed package can build UNet(pretrained=False) and run a tiny CPU forward pass.
• scripts/check_training_layout.py validates the training/ and validation/ splits, matching tile ids, and optional batch/drop-last risk.

Short route map

Train or resume

1. Check the dataset layout and class-weight assumptions in configuration.md.
2. Run scripts/check_training_layout.py against the dataset root before launching training.
3. Use rs train or python -m robosat.tools train with a writable checkpoint directory.
4. Inspect the generated .pth, log, and history-*.png files.

Export

1. Start from a trained checkpoint with the matching class count.
2. Use rs export or python -m robosat.tools export to write the ONNX .pb.
3. Verify the file exists and can be consumed by downstream ONNX tooling.

Predict

1. Reuse the matching model and dataset config plus a trained checkpoint.
2. Use rs predict or python -m robosat.tools predict on a slippy-map tile tree.
3. Check the probability tile directory for z/x/y.png outputs.

Serve

1. Reuse the same checkpoint, model config, and dataset config.
2. Set the map access token and a tile URL template with {x}, {y}, and {z} placeholders.
3. Use rs serve or python -m robosat.tools serve for quick on-demand mask inspection.

Cross-route guidance

• If the task is about creating the dataset itself, use the data-preparation route instead.
• If the task is about turning probability masks into GeoJSON or comparing/merging masks, use the feature-postprocessing route instead.
• If a workflow hits a missing dependency or backend issue, read references/troubleshooting.md before changing the command.