feat: delete (soft) and restore training runs via SDK and CLI

[leeclemnet]

What does this PR do?

Adds SDK and CLI support for the platform's new training deletion feature (roboflow/roboflow#13869), which is soft-delete-first: deleting a training moves it (and every model it produced) to the workspace Trash for 30 days, hidden from listings but restorable, before permanent cleanup.

• rfapi.delete_version_training(...) — thin wrapper for DELETE /{ws}/{project}/{version}/v2/trainings/{training_id} (the platform's entity trash pattern; training_id required). Restore goes through the existing rfapi.restore_trash_item(..., "training", id) — the same shared POST /{ws}/trash/restore route project/version/workflow restores use; there is no bespoke trainings restore route. rfapi.resolve_version_training_id(...) resolves an omitted id to the version's sole run client-side (several runs raise MULTIPLE_TRAININGS with the ids listed).
• Version.delete_training(training_id=None) / Version.restore_training(training_id) — mirror the existing Version.delete()/Version.restore() trash semantics; Training.delete()/Training.restore() do the same on the run object returned by the trainings APIs.
• CLI — roboflow train delete <project>/<version> [--training-id ...] and roboflow train restore <project>/<version> --training-id ..., with actionable hints for the refusal cases (in-flight run → stop/cancel first; multi-run version needs --training-id; item not in trash → roboflow trash list). The version's hosted endpoint always serves the oldest remaining run's model: when the deleted run was serving, the API reports versionAliasAction: "repointed" (+ versionAliasTarget) or "deleted" when no run survives, and train delete prints the switch or the stop. roboflow train list <project>/<version> enumerates a version's runs with their ids (reading the API's id field) so MMPV training ids are discoverable. Blank/whitespace --training-id values fail as structured usage errors (exit code 2) instead of raw tracebacks, and restore_trash_item validates its id for every trash type.

Deletion is soft-only on the public API by design — permanent deletion stays in the web UI's Trash view, consistent with the existing note in rfapi that permanent trash actions are never exposed to API keys.

Related Issue(s): Depends on roboflow/roboflow#13869 (platform endpoints) — merge/deploy that first; until then these calls return 404.

Type of Change

• New feature (non-breaking change that adds functionality)

Testing

• I have tested this change locally
• I have added/updated tests for this change

Test details:

• unit tests
• e2e staging test with localapi built from https://github.com/roboflow/roboflow/pull/13869

> uv run roboflow train --help

 Usage: roboflow train [OPTIONS] [COMMAND] [ARGS]...

 Train a model

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --checkpoint            TEXT     Checkpoint to resume training from                                                  │
│ --epochs                INTEGER  Number of training epochs                                                           │
│ --project       -p      TEXT     Project ID to train                                                                 │
│ --speed                 TEXT     Training speed preset                                                               │
│ --type          -t      TEXT     Model type (e.g. rfdetr-nano, yolov8n)                                              │
│ --train-recipe          TEXT     Full trainRecipe as inline JSON or @path/to/file.json (see 'roboflow train          │
│                                  recipe'); --epochs is folded into its hyperparameters unless the recipe already     │
│                                  sets epochs                                                                         │
│ --version       -v      INTEGER  Version number to train                                                             │
│ --help          -h               Show this message and exit.                                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ cancel   Cancel an in-flight training run.                                                                           │
│ delete   Move a terminal training run to the workspace Trash (soft delete).                                          │
│ list     List a version's training runs with their ids.                                                              │
│ recipe   Show the training recipe schema and template for a model type.                                              │
│ restore  Restore a trashed training run (and its models) back into listings.                                         │
│ results  Run-level training results bundle.                                                                          │
│ start    Start training for a dataset version.                                                                       │
│ stop     Request a graceful early-stop on an in-flight training run.                                                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

 > uv run roboflow train delete --help

 Usage: roboflow train delete [OPTIONS] TARGET

 Move a terminal training run to the workspace Trash (soft delete).

 The run and every model it produced disappear from listings but stay
 restorable for 30 days ('roboflow train restore' or the web Trash view),
 after which they are permanently deleted. In-flight runs are refused —
 stop or cancel first — as is the run backing the version's registered
 model. Permanent deletion is only available in the web UI's Trash view.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    target      TEXT  Training to delete as 'project/version' [required]                                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --training-id          TEXT  Training id of the run to delete (versions can own several). Omit to target the         │
│                              version's sole run.                                                                     │
│ --help         -h            Show this message and exit.                                                             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

> uv run roboflow train delete chess-pieces-fmhpz/112 --training-id b704c8e6ee031f3ef563

Training moved to Trash for chess-pieces-fmhpz version 112. Restorable for 30 days via 'roboflow train restore'.

> uv run roboflow train restore chess-pieces-fmhpz/112 --training-id b704c8e6ee031f3ef563

Training restored for chess-pieces-fmhpz version 112.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in hard-to-understand areas
• My changes generate no new warnings or errors
• I have updated the documentation accordingly (if applicable)

Additional Context

Mirrors the existing cancel_version_training/stop_version_training adapter pattern and the train cancel/train stop CLI command pattern. The companion MCP PR (roboflow/roboflow-mcp#124) was closed by design: MCP has no trash-lifecycle tools for any entity yet, so trainings won't lead there.

🤖 Generated with Claude Code

[mkaic]

LGTM

[mkaic]

LGTM