Recipes and version locking

Method catalog, recipe.lock.json, and the framework version matrix

sf methods                    # what this deployment publishes
sf recipe status my-grpo      # what my experiment is pinned to
sf recipe upgrade my-grpo     # move it to the current catalog

A recipe is the full declaration of a post-training method: entrypoint, tunable hyperparameters with their types and ranges, supported framework versions, image artifact, metrics contract, artifacts contract. All of them together are the catalog.

The client and the server load the same files from starforge-core, so the two cannot disagree about what a method is.

Method ids

Two-part <framework>/<method>:

sf methods                  # list
sf methods nemo-rl/grpo     # hyperparameters for this method

Current catalog: NeMo-RL, verl, TRL, OpenRLHF, evalkit (benchmarks), custom. Full table: Method catalog.

Lockfile: recipe.lock.json

sf new writes recipe.lock.json:

Field	Meaning
recipe.name / version	Method and recipe version
recipe.digest	Digest of manifest + templates
framework.kind / version	Exact framework version (nemo-rl@0.7.0, verl@0.9.0, openrlhf@0.11.0)
framework.runtime_id	Key for the deployment artifact (OCI image / SIF / SQSH)
requires.core	Compatible starforge-core range

At submit the CLI handshakes with the server catalog. The lock must match the published recipe exactly.

After the platform publishes a new recipe version, an old lock is rejected. That is intentional. sf recipe status shows the diff; sf recipe upgrade applies it.

sf recipe status my-exp
sf recipe upgrade my-exp
sf recipe upgrade my-exp --framework-version 0.9.0
sf submit my-exp --upgrade-recipe

Framework version matrix

One recipe can publish several framework versions at once (verl/grpo has 0.8.0 and 0.9.0). Entrypoint changes, parameter-path moves, and images are declared on the version, not as branches in adapter code:

sf new my-verl --method verl/grpo --framework-version 0.9.0

• Entrypoint override: verl 0.9 dropped main_ppo_sync for a unified main_ppo.
• Parameter path override: path_overrides when a hyperparameter moved in the config tree.
• Runtime artifact: each version binds a runtime_id, resolved from a framework default, the deployment registry, or --image. Prefer a digest in production. Slurm wants SIF/SQSH.

Adopting a new upstream version is usually YAML + an image, not a platform code change. Upstream adoption.

Custom recipe

Frameworks that are not in the catalog use custom/custom. The platform runs train.sh in the experiment directory. It does not guess an entrypoint, and it does not fall back to custom after another adapter fails.

sf new my-custom --method custom/custom
sf submit my-custom --profile h200:8 \
  --image myregistry.io/my-train:v1

--image is required. Tags work; pin a digest in production. The registry must be on FORGE_ALLOWED_IMAGE_REGISTRIES.

The catalog custom recipe currently defaults to external observability, so those submits still need --observability-url. Logs follow stdout. Console curves need starforge.report in training code. Cookbook: Custom training. Image build: Custom images.

Config layers

Effective config is four layers, later wins:

recipe template config.yaml          # official base (e.g. the grpo_math_1B.yaml chain)
└─ experiment config.yaml            # your diffs (defaults + overrides)
   └─ hardware profile               # server registry: parallelism, memory knobs
      └─ sf submit --set k=v         # one-shot override, type-checked locally

sf validate walks the same stack locally. Struct mode rejects unknown keys.