start grpo run
start_grpo_runStart a budget-bounded GRPO training run that improves a fine-tunable model against a calibrated judge, using logged traffic or candidate queue to produce a trained adapter.
Instructions
Start an online-RL (GRPO) training run that improves a fine-tunable base model against a calibrated judge as the reward, with hard reward and GPU-hour budgets — use it to turn logged traffic or the candidate queue into a trained adapter. POST /v1/grpo/runs (API-key scope: platform:write). SPENDS MONEY: this starts billable work on the workspace wallet. Returns: 201 with { trigger_run_id: string } — the orchestration handle for the run (the GrpoRun id shows up in GET /v1/grpo/runs once registered). Notes: SPENDS MONEY: the whole commitment (rewardBudgetUsd + GPU hours at the frozen marked-up rate, or a conservative ceiling for autoProvision) is atomically HELD on the wallet at start; 402 when the wallet can't hold it; 400 'No wallet for this workspace' when there is no payment method. Body keys are camelCase only (except environment.proxy_base_url / max_steps and verifier[].timeout_sec, which are snake_case); unknown keys pass through. Zod validation failure returns 400 { error: 'Invalid body: — ' } (flat error shape). Rate limited to 20 starts/min per workspace (429). Feature-flag gated (fineTuning flag off → 404). Requires OWNER/ADMIN (403). Other 400 refusals: unaligned/wrong-unit/drift-flagged judge, iterated-RL round gate (fresh grades needed on a self-trained policy), model not fine-tunable, promptCount < 10, not enough logged prompts or queued candidates, autoAdopt alias missing, no GPU price set, orchestration not configured.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | The policy model to train. Must be on the platform's fine-tunable base-model list, otherwise 400. | |
| qlora | No | QLoRA 4-bit training. Default true. | |
| reward | Yes | Reward spec (camelCase keys). Either { mode: "single", criterionId: string } or { mode: "compositional", criterionIds: string[] (min 1), assertions?: object[] }. Each assertion is { type: "json_valid"|"json_schema"|"regex_match"|"contains"|"not_contains"|"max_length"|"min_length"|"completed"|"tool_called"|"no_tool_call", value?: string } or an exec assertion { type: "exec", command: string, timeoutSec?: integer (1..120) } — exec assertions are only allowed when `environment` is set (agentic/trace-unit rewards). Every criterion must exist in the workspace and be calibrated; a non-agentic run requires request-unit criteria, an agentic run (with `environment`) requires trace-unit criteria. | |
| paramsB | No | Parameter count (billions) override for models whose name doesn't carry it. Must be > 0; capped at 1000. | |
| useVllm | No | Colocated vLLM rollouts (much faster steps). Forced true when `environment` is set. | |
| maxSteps | No | Training steps. Default 100, clamped 1..5000. | |
| autoAdopt | No | Opt-in auto-deploy on an 'improved' bake-off verdict: { aliasName: string (1..120, must already exist in the workspace or the start is refused), canaryPercent?: integer 1..50, gpuType: string, region: string, templateFlavor?: string }. Deploys to a dedicated endpoint, canaries on the alias, and the online gate earns the promote. Inconclusive/regressed rounds never deploy. | |
| groupSize | No | Rollouts sampled per prompt. Default 8, clamped 2..16. | |
| promptTag | No | Draw training prompts only from logged requests carrying this tag. Omit to sample the whole workspace's successful logged traffic. | |
| environment | No | Agentic mode — run episodes inside the tool environment: { proxy_base_url: string (snake_case, required), max_steps?: integer, simulate?: boolean }. Setting this forces useVllm=true and requires trace-unit reward criteria. | |
| platformGpu | No | Bill a platform-provisioned GPU: { gpuType: string, region: string, gpuCount?: integer (clamped 1..8) }. Rate + markup are frozen at start. Omit for bring-your-own compute (no GPU billing). 400 if no price is set for that GPU/region. | |
| promptCount | Yes | Number of prompts to train on. Minimum 10 (400 below that); clamped to 1..10000 at scheduling. A ~20% holdout (min 3) is carved off on top, and the workspace must have promptCount+holdout matching prompts logged or the run is refused with the real counts. | |
| tasksInline | No | Up to 10000 task objects for agentic runs: { goal: any[] (min 1), image?: string (<=500 chars), recorded?: any[], verifier?: [ { command: string (1..4000 chars), timeout_sec?: integer 1..120 } ] }. | |
| holdoutCount | No | Holdout size override (rounded, clamped 1..2000). Use 50+ for a real bake-off claim. Default max(3, ceil(promptCount*0.2)). | |
| autoProvision | No | Let the platform provision an auto-sized GPU box. 400 if provisioning isn't configured; holds a conservative GPU commitment (highest active rate x 8 GPUs x gpuHourBudget) on the wallet. | |
| gpuHourBudget | Yes | Hard cap on GPU hours. Must be > 0. For platform-provisioned GPUs the hours x frozen marked-up rate are held on the wallet at start. | |
| rewardBudgetUsd | Yes | Hard cap (USD) on judge/reward spend. Must be > 0. Held on the wallet at start. | |
| allowSideEffects | No | Agentic runs only: permit calls to tools not declared read-only. Default false. | |
| useCandidateQueue | No | Train on the workspace's GRPO candidate queue (the self-improvement give-up set) for the single reward criterion instead of a tag sample. Only effective with reward.mode=single. | |
| curriculumMixRatio | No | Candidate-queue runs: fraction of the training slice drawn from regular successful traffic. Clamped 0..0.9. | |
| maxCompletionTokens | No | Per-rollout generated-token budget, clamped 256..32768. Defaults: 8192 agentic, 1024 single-turn. | |
| vllmGpuMemoryUtilization | No | Clamped 0.05..0.9. |