Add custom train-recipe support (describe schema/template, train_recipe on create_training, CLI)

[leeclemnet]

What does this PR do?

Adds SDK + CLI support for training with a custom trainRecipe (hyperparameter/augmentation sweeps) against the v2 trainings API. The surface is deliberately consolidated on train_recipe as the single recipe input: describe → edit the server template → submit.

• Adapters (roboflow/adapters/rfapi.py): get_train_recipe (GET .../v2/trainings/recipe?modelType=) is new; the canonical v2 create adapter from Feature: Multiple Models Per Version #497, create_training_v2, gains train_recipe (camelCase trainRecipe body key). Listing/fetching runs uses Feature: Multiple Models Per Version #497's list_trainings_for_version / get_training unchanged.
• SDK (roboflow/core/version.py): Version.describe_train_recipe(model_type) (schema + ready-to-submit template + availability) is new; Feature: Multiple Models Per Version #497's canonical Version.create_training(...) gains train_recipe (returns a Training object — poll via .refresh(), list runs via Version.trainings()). The model_type guard and epochs fold run before any network call. The blocking Version.train() is untouched.
• Epochs correctness (roboflow/util/train_recipe.py): fold_epochs_into_recipe — the server dense-fills recipe hyperparameters and resolves recipe epochs ahead of body epochs, so a provided epochs= is folded into the submitted recipe unless the recipe sets its own (explicit recipe value wins).
• CLI: roboflow train recipe -p <project> -v <N> -m <model_type> (prints schema+template JSON) and --train-recipe '<json>' on roboflow train start (v2 path, prints the new trainingId; non-object JSON fails fast with a structured error before any network call).

Related Issue(s): Companion to roboflow/roboflow#13699 (the backend describe endpoint — describe_train_recipe/train recipe require it; deploy order: platform first, then release this). MCP companion (same consolidated shape): roboflow/roboflow-mcp#120. Rebased on #497 (the canonical MMPV SDK surface): this PR now adds only the recipe capabilities on top — no duplicated trainings plumbing. Note one adopted behavior change: training creation returns a Training object rather than a raw dict.

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
• localapi tests

uv run roboflow train --help
warning: No `requires-python` value found in the workspace. Defaulting to `>=3.14`.

 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.                                                                           │
│ recipe   Show the training recipe schema and template for a model type.                                              │
│ 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 recipe --help
warning: No `requires-python` value found in the workspace. Defaulting to `>=3.14`.

 Usage: roboflow train recipe [OPTIONS]

 Show the training recipe schema and template for a model type.

 Prints the tunable hyperparameter schema, the allowed online
 augmentation/preprocessing steps, and a ready-to-submit ``template``
 that can be edited and passed to ``roboflow train start --train-recipe``.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *  --model-type,--type  -m,-t      TEXT     Model type to describe (e.g. rfdetr-medium) [required]                   │
│ *  --project            -p         TEXT     Project ID [required]                                                    │
│ *  --version            -v         INTEGER  Version number [required]                                                │
│    --help               -h                  Show this message and exit.                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

uv run roboflow train start --help
warning: No `requires-python` value found in the workspace. Defaulting to `>=3.14`.

 Usage: roboflow train start [OPTIONS]

 Start training for a dataset version.

 With --train-recipe, the training is created via the v2 trainings API
 and the new trainingId is printed. Start from the ``template`` field of
 ``roboflow train recipe`` output, edit it (hyperparameters, online
 augmentation), and pass it inline or as ``@path/to/file.json``; --epochs is folded into its
 hyperparameters unless the recipe already sets epochs.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *  --project       -p      TEXT     Project ID to train [required]                                                   │
│ *  --version       -v      INTEGER  Version number to train [required]                                               │
│    --checkpoint            TEXT     Checkpoint to resume training from                                               │
│    --epochs                INTEGER  Number of training epochs                                                        │
│    --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                                                                      │
│    --help          -h               Show this message and exit.                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

API_URL="https://localapi.roboflow.one" \
ROBOFLOW_API_KEY=$API_KEY \
REQUESTS_CA_BUNDLE="$HOME/Library/Application Support/mkcert/rootCA.pem" \
uv run roboflow train recipe -p lee-sandbox/chess-pieces-fmhpz -v 110 -m rfdetr-medium

Staging evidence: roboflow train recipe -p lee-sandbox/chess-pieces-fmhpz -v 110 -m rfdetr-medium CLI output

warning: No `requires-python` value found in the workspace. Defaulting to `>=3.14`.
{
  "modelType": "rfdetr-medium",
  "canonicalModelType": "rfdetr-medium",
  "family": "rf-detr",
  "taskType": "object-detection",
  "availability": {
    "entitled": true,
    "runtimeEnabled": true
  },
  "schema": {
    "hyperparameters": [
      {
        "key": "epochs",
        "type": "int",
        "valid": {
          "ge": 1
        },
        "advice": {
          "default": 100,
          "low": 50,
          "high": 150
        }
      },
      {
        "key": "lr",
        "type": "float",
        "valid": {
          "gt": 0
        },
        "advice": {
          "default": 0.0001,
          "low": 1e-05,
          "high": 0.01
        }
      },
      {
        "key": "lr_encoder",
        "type": "float",
        "valid": {
          "gt": 0
        },
        "advice": {
          "default": 0.00015,
          "low": 1e-05,
          "high": 0.01
        }
      },
      {
        "key": "bbox_loss_coef",
        "type": "float",
        "valid": {
          "ge": 0
        },
        "advice": {
          "default": 5,
          "low": 0.5,
          "high": 20
        }
      },
      {
        "key": "giou_loss_coef",
        "type": "float",
        "valid": {
          "ge": 0
        },
        "advice": {
          "default": 2,
          "low": 0.5,
          "high": 20
        }
      },
      {
        "key": "set_cost_class",
        "type": "float",
        "valid": {
          "ge": 0
        },
        "advice": {
          "default": 2,
          "low": 0.5,
          "high": 20
        }
      },
      {
        "key": "set_cost_bbox",
        "type": "float",
        "valid": {
          "ge": 0
        },
        "advice": {
          "default": 5,
          "low": 0.5,
          "high": 20
        }
      },
      {
        "key": "set_cost_giou",
        "type": "float",
        "valid": {
          "ge": 0
        },
        "advice": {
          "default": 2,
          "low": 0.5,
          "high": 20
        }
      },
      {
        "key": "cls_loss_coef",
        "type": "float",
        "valid": {
          "ge": 0
        },
        "advice": {
          "default": 1,
          "low": 0.1,
          "high": 10
        }
      }
    ],
    "online_augmentation": {
      "splits": [
        "train"
      ],
      "steps": [
        {
          "name": "flip",
          "params": {
            "horizontal": {
              "type": "boolean",
              "required": true
            },
            "vertical": {
              "type": "boolean",
              "required": true
            }
          },
          "atLeastOne": [
            "horizontal",
            "vertical"
          ],
          "probability": true
        },
        {
          "name": "ninety",
          "params": {
            "clockwise": {
              "type": "boolean",
              "required": true
            },
            "counter-clockwise": {
              "type": "boolean",
              "required": true
            },
            "upside-down": {
              "type": "boolean",
              "required": true
            }
          },
          "atLeastOne": [
            "clockwise",
            "counter-clockwise",
            "upside-down"
          ],
          "probability": true
        },
        {
          "name": "rotate",
          "params": {
            "degrees": {
              "type": "integer",
              "min": 0,
              "max": 45,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "brightness",
          "params": {
            "percent": {
              "type": "integer",
              "min": 0,
              "max": 100,
              "required": true
            },
            "brighten": {
              "type": "boolean",
              "required": true
            },
            "darken": {
              "type": "boolean",
              "required": true
            }
          },
          "atLeastOne": [
            "brighten",
            "darken"
          ],
          "probability": true
        },
        {
          "name": "exposure",
          "params": {
            "percent": {
              "type": "integer",
              "min": 0,
              "max": 100,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "blur",
          "params": {
            "pixels": {
              "type": "number",
              "min": 0,
              "max": 25,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "noise",
          "params": {
            "percent": {
              "type": "number",
              "min": 0,
              "max": 100,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "crop",
          "params": {
            "min": {
              "type": "integer",
              "min": 0,
              "max": 100,
              "required": true
            },
            "percent": {
              "type": "integer",
              "min": 0,
              "max": 100,
              "required": true
            }
          },
          "ordered": [
            "min",
            "percent"
          ],
          "probability": true
        },
        {
          "name": "cutout",
          "params": {
            "count": {
              "type": "integer",
              "min": 1,
              "max": 25,
              "required": true
            },
            "percent": {
              "type": "integer",
              "min": 0,
              "max": 100,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "mosaic",
          "params": {},
          "probability": true
        },
        {
          "name": "shear",
          "params": {
            "horizontal": {
              "type": "integer",
              "min": 0,
              "max": 45,
              "required": true
            },
            "vertical": {
              "type": "integer",
              "min": 0,
              "max": 45,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "saturation",
          "params": {
            "percent": {
              "type": "integer",
              "min": 0,
              "max": 100,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "hue",
          "params": {
            "degrees": {
              "type": "integer",
              "min": 0,
              "max": 180,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "rgrayscale",
          "params": {
            "percent": {
              "type": "integer",
              "min": 0,
              "max": 100,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "motion-blur",
          "params": {
            "pixels": {
              "type": "integer",
              "min": 1,
              "max": 1000,
              "required": true
            },
            "angle": {
              "type": "number",
              "min": 0,
              "max": 90,
              "required": true
            },
            "hdr_frames": {
              "type": "integer",
              "min": 1,
              "max": 5,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "camera-gain",
          "params": {
            "amount": {
              "type": "integer",
              "min": 1,
              "max": 1,
              "required": false
            },
            "variance_scale": {
              "type": "number",
              "min": 0.01,
              "max": 0.5,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "bbflip",
          "params": {
            "horizontal": {
              "type": "boolean",
              "required": true
            },
            "vertical": {
              "type": "boolean",
              "required": true
            }
          },
          "atLeastOne": [
            "horizontal",
            "vertical"
          ],
          "probability": true
        },
        {
          "name": "bbninety",
          "params": {
            "clockwise": {
              "type": "boolean",
              "required": true
            },
            "counter-clockwise": {
              "type": "boolean",
              "required": true
            },
            "upside-down": {
              "type": "boolean",
              "required": true
            }
          },
          "atLeastOne": [
            "clockwise",
            "counter-clockwise",
            "upside-down"
          ],
          "probability": true
        },
        {
          "name": "bbrotate",
          "params": {
            "degrees": {
              "type": "integer",
              "min": 0,
              "max": 45,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "bbcrop",
          "params": {
            "min": {
              "type": "integer",
              "min": 0,
              "max": 100,
              "required": true
            },
            "percent": {
              "type": "integer",
              "min": 0,
              "max": 100,
              "required": true
            }
          },
          "ordered": [
            "min",
            "percent"
          ],
          "probability": true
        },
        {
          "name": "bbshear",
          "params": {
            "horizontal": {
              "type": "integer",
              "min": 0,
              "max": 45,
              "required": true
            },
            "vertical": {
              "type": "integer",
              "min": 0,
              "max": 45,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "bbbrightness",
          "params": {
            "percent": {
              "type": "integer",
              "min": 0,
              "max": 100,
              "required": true
            },
            "brighten": {
              "type": "boolean",
              "required": true
            },
            "darken": {
              "type": "boolean",
              "required": true
            }
          },
          "atLeastOne": [
            "brighten",
            "darken"
          ],
          "probability": true
        },
        {
          "name": "bbexposure",
          "params": {
            "percent": {
              "type": "integer",
              "min": 0,
              "max": 100,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "bbblur",
          "params": {
            "pixels": {
              "type": "number",
              "min": 0,
              "max": 25,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "bbnoise",
          "params": {
            "percent": {
              "type": "number",
              "min": 0,
              "max": 100,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "bbmotion-blur",
          "params": {
            "pixels": {
              "type": "integer",
              "min": 1,
              "max": 1000,
              "required": true
            },
            "angle": {
              "type": "number",
              "min": 0,
              "max": 90,
              "required": true
            },
            "hdr_frames": {
              "type": "integer",
              "min": 1,
              "max": 5,
              "required": true
            }
          },
          "probability": true
        },
        {
          "name": "bbcamera-gain",
          "params": {
            "amount": {
              "type": "integer",
              "min": 1,
              "max": 1,
              "required": false
            },
            "variance_scale": {
              "type": "number",
              "min": 0.01,
              "max": 0.5,
              "required": true
            }
          },
          "probability": true
        }
      ]
    },
    "online_preprocessing": {
      "steps": [
        "resize",
        "grayscale",
        "contrast"
      ]
    },
    "input": {
      "onlineResizeAllowed": true,
      "resolutionRounding": "Width, height, and resolution are rounded to the nearest multiple of 32, with a minimum of 32."
    }
  },
  "template": {
    "schema_version": 1,
    "input": {
      "width": 640,
      "height": 640,
      "resize": {
        "enabled": true,
        "format": "Stretch to",
        "width": 640,
        "height": 640
      },
      "resolution": 640,
      "splits": [
        "train",
        "valid",
        "test"
      ]
    },
    "online_preprocessing": [],
    "online_augmentation": {
      "splits": [
        "train"
      ],
      "steps": []
    },
    "source_version": {
      "dataset_id": "7vSK9kc3i6eFm700KWFt",
      "version_id": "110",
      "baked_preprocessing": {
        "auto-orient": {
          "enabled": true
        }
      },
      "baked_augmentation": {},
      "assertions": {
        "resize_baked": false,
        "augmentation_baked": false
      }
    },
    "hyperparameters": {}
  },
  "usage": "The template is ready to submit verbatim as `trainRecipe` on a POST to this project/version's /v2/trainings path alongside `modelType`. To tune training, set a sparse subset of the keys listed in schema.hyperparameters under template.hyperparameters \u2014 any key you omit is filled with its advice.default server-side. advice.low/high is the recommended sweep range; valid.* are hard bounds the server enforces. Add augmentation steps from schema.online_augmentation.steps to template.online_augmentation.steps; each step is submitted as {name, params: {...}} \u2014 params is required, {} when a step has no fields \u2014 with the step's listed params plus an optional params.probability between 0 and 1. Submitting a trainRecipe requires the workspace's online-augmentation training entitlement (the train request is rejected with a 403 without it) and requires the deployment's online-train-recipe runtime to be enabled; the availability field reports both."
}

API_URL="https://localapi.roboflow.one" \
ROBOFLOW_API_KEY=$API_KEY \
REQUESTS_CA_BUNDLE="$HOME/Library/Application Support/mkcert/rootCA.pem" \
uv run roboflow train start -p lee-sandbox/chess-pieces-fmhpz -v 110 -t rfdetr-medium --train-recipe @train_recipe.json
warning: No `requires-python` value found in the workspace. Defaulting to `>=3.14`.
Exporting version in coco format (required for rfdetr-medium)...
  Export complete.
Training created for chess-pieces-fmhpz version 110. trainingId: eee271d1bffe1781c021

train_recipe.json

{
  "schema_version": 1,
  "input": {
    "width": 640,
    "height": 640,
    "resize": {
      "enabled": true,
      "format": "Stretch to",
      "width": 640,
      "height": 640
    },
    "resolution": 640,
    "splits": [
      "train",
      "valid",
      "test"
    ]
  },
  "online_preprocessing": [
    {
      "name": "grayscale"
    }
  ],
  "online_augmentation": {
    "splits": [
      "train"
    ],
    "steps": [
      {
        "name": "rotate",
        "params": {
          "degrees": 15,
          "probability": 0.5
        }
      }
    ]
  },
  "source_version": {
    "dataset_id": "7vSK9kc3i6eFm700KWFt",
    "version_id": "110",
    "baked_preprocessing": {
      "auto-orient": {
        "enabled": true
      }
    },
    "baked_augmentation": {},
    "assertions": {
      "resize_baked": false,
      "augmentation_baked": false
    }
  },
  "hyperparameters": {
    "lr": 0.0003
  }
}

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) — CLI-COMMANDS.md + CHANGELOG.md updated; docs.roboflow.com reference is a tracked follow-up

Additional Context

Sweep usage the PR enables:

v = rf.workspace().project("safety-vests").version(5)
template = v.describe_train_recipe("rfdetr-nano")["template"]
ids = []
for lr in (1e-5, 1e-4, 1e-3):
    recipe = copy.deepcopy(template)
    recipe["hyperparameters"] = {"lr": lr}   # sparse: omitted keys keep server defaults
    ids.append(v.create_training(model_type="rfdetr-nano", train_recipe=recipe).training_id)

Recipe-based training requires the workspace's online-augmentation training entitlement (403 otherwise); the describe response's availability field reports both gates up front.

🤖 Generated with Claude Code

[leeclemnet]

/jarbas review, considering https://github.com/roboflow/roboflow/pull/13699 and https://github.com/roboflow/roboflow-mcp/pull/120 as well. Ensure you read the PR descriptions as they contain the bulk of the test evidence.

[leeclemnet]

Jarb approval: https://github.com/roboflow/roboflow/pull/13699#issuecomment-5048531237

[jarbas-roboflow]

Status: ❌ Request Changes — Gist: https://gist.github.com/jarbasrf/9f37f34dfe806a002ab789e6885d414a. Resumo: An explicitly empty --train-recipe bypasses validation and can silently start legacy training instead. The adapter and SDK design are otherwise sound with substantial test coverage.

[jarbas-roboflow]

Status: ✅ Approve — Gist: https://gist.github.com/jarbasrf/c90908d109b3044acdda67b4e193ffce. Resumo: The prior empty --train-recipe issue is fully resolved with targeted no-network regression coverage. One minor malformed-input error-reporting edge case remains, but it is not merge-blocking.

[mkaic]

LGTM!

I think your new _start_v2 function has some duplicated logic from the new MMPV Version.create_training, but after chatting with Fable I think the right thing to do would be to make that method use your code, not the other way around, I think the way you implemented things is potentially more idiomatic. Anyhow, not really in-scope for this PR, so approving, and I can always open a consolidation/cleanup PR myself later.