---

name: fine-tuning description: "Use the legacy Pytorch-Wildlife companion workflows to validate camera-trap classification or detection datasets, prepare configuration, and integrate produced weights without launching expensive training by default." disable-model-invocation: true metadata: disco-role: operating license: MIT

Fine-tuning

Use this sub-skill for the companion/legacy classification and detection fine-tuning modules. It covers dataset contracts, split design, YAML/config preflight, CLI orientation, and post-training weight handoff. These modules are separate from the current core inference APIs and are best treated as experimental compatibility workflows.

Safety and status

• Do not start training, validation, inference, model downloads, external loggers, or services as a default action. They can be GPU-hour, disk, network, or credential bound.
• Run the bundled split helper and static/YAML checks first; inspect a small fixture before approving a real run.
• The classification companion documents Python 3.9 and its environment pins Python 3.8-era dependencies, including Lightning 1.9 and old TorchVision. The detection companion documents Python 3.10 and a separate Ultralytics stack. The installed package is PytorchWildlife 1.3.0 and requires Python

  =3.10, so do not assume either companion environment is interchangeable with the core environment.

• A checkpoint produced by a companion workflow is not automatically a core PytorchWildlife weight. Validate architecture, checkpoint format, class names, and wrapper expectations before using it for core inference.

Choose a workflow

1. Choose classification for a flat image directory and a CSV with path, classification, and label columns. Add Location for a location split or Photo_Time for a sequence split.
2. Choose detection for YOLO-format images and labels arranged into train/val/test partitions, with a dataset YAML describing those partitions.
3. Choose data validation before either workflow, especially when images came from camera bursts or when a YAML was authored by hand.
4. Route core model inference and detector-to-classifier crop behavior to the detection/classification sub-skills. Route audio training to bioacoustics.

Detailed contracts and checks:

• Classification fine-tuning
• Detection fine-tuning
• Data validation
• Troubleshooting
• Safe classification splitter

Required preflight

1. Work from a copied config and a reproducible output directory. Preserve the original annotation file; the companion split utility writes three CSVs.
2. Confirm every referenced image exists, is a supported image type, and is readable as RGB. Confirm labels are contiguous integers where the selected training code expects them, and that class names do not disagree by split.
3. For camera traps, prefer location or sequence grouping over random splitting. Random splitting can place near-identical burst frames in train and validation, producing leakage and inflated metrics.
4. Validate YAML paths relative to the YAML's intended dataset root, and check that every image has a matching label file where detection labels are expected. Reject out-of-range or malformed normalized boxes.
5. Record the Python, Torch/Lightning or Ultralytics versions, device choice, model identifier, class mapping, split seed, and output directory before any expensive command.

The bundled helper is intentionally limited to annotation splitting. Its --help path and tiny CSV fixture are safe checks; it never constructs a model, downloads weights, starts a logger, or trains.

Decision boundaries

• Use a random split only when temporal, location, and burst independence are already established. Otherwise prefer the strongest grouping metadata available, and state when class balance is sacrificed.
• A classification CSV is not enough to prove that the companion crop stage is ready. Confirm the crop annotations, detector checkpoint, and output paths separately; core detector inference belongs to the detection route.
• A valid detection label file is not enough to prove model compatibility. Check YAML class ordering, the selected YOLO/RTDETR family, license terms, and the installed Ultralytics version before a user-approved run.
• Treat CPU parser and fixture checks as structural verification only. They do not validate GPU throughput, convergence, mAP, or checkpoint quality.
• Keep experiment logs local by default. A remote logger, service, or upload is an explicit follow-up decision, not part of preflight.

Verification evidence

For a safe handoff, retain the splitter command and seed, emitted row counts, location/sequence disjointness result, YAML parse result, class mapping, and version/device notes. Mark model loading, weight integration, training, validation, and inference as unverified unless they were explicitly run with approved local artifacts. A failure caused by an old companion dependency is an environment limitation, not evidence that the dataset or model is correct.

Handoff checklist

Before integrating a produced checkpoint, retain the training config and class mapping next to the weight, identify the actual run directory and best checkpoint, and test loading with a local weight in an isolated environment. Do not infer compatibility from a filename. If the core wrapper rejects the weight or expects a different state-dict/model format, keep the checkpoint in its companion workflow and route ordinary inference elsewhere.