Separate three decisions
The training guide covers checkpoint selection. This page covers adoption.
Choose a promotion measure
The schema definespromotion.mode as prediction or application, with prediction as the default. Promotion settings also include minimum_cases (default 16), required_improvement (default 0), and maximum_prediction_regression (default 0.05).
An observed prediction gate reported the criterion paired_validation_mse_and_episode_confidence. It can reject a candidate whose validation mean squared error is worse even when that candidate selects better alternatives. Prediction error and decision utility are different measurements.
Use prediction diagnostics when accurate value estimates are the deployment objective. Use paired application utility when deployment success is defined by the consequences of chosen actions. Continue to inspect prediction regressions and comparison diagnostics so the reason for a change remains visible.
Request fields describe schema version 5. The complete relationship between application-mode automatic promotion, registered cases, and
install: true requires confirmation for your deployment. Use install: false for a separate candidate evaluation, then read back the installed identity after promotion.Check continuation-candidate installation
Recorded attempts to install fits usingcontinuation rows have returned HTTP 422 and left the fits as candidates. Evaluate these candidates through the explicit candidate sources below and confirm the supported installation route for your deployment before automating adoption.
Stage continuation fits with install: false. Once a candidate exists, you can select it explicitly with model_source: candidate for value prediction, or evaluator_source: value_candidate for planning. Bind the candidate hash you intend to evaluate.
Before automating the next adoption round, establish the supported installation path for that deployment. For an installation refusal, retain the endpoint, request settings, response reason, candidate hash, and incumbent hash, then inspect value/state. Keep using the confirmed installed model as the continuation reference until state confirms an adoption. Changing the expected hashes or relabelling continuation rows to make a refused request pass changes the intended workflow.
Run a paired application comparison
Choose the evaluation cases and utility definition before comparing models. For each case, evaluate the candidate and incumbent under the same initial conditions, execution rules, and planning budget. Record the model SHA-256 identities that actually produced the two outcomes. Keep these cases separate from model fitting when they are intended to measure generalization. Control or record randomness, initial conditions, execution rules, and planning budgets alongside each pair of utility values so the paired comparison is reproducible. Use measured application utility for execution comparisons. Assess the reference and candidate through native planning, preserving the evaluator and model identity used by each call.Submit a canary with model guards
Build thePOST /domains/{domain_id}/value/promote body from the actual installed_sha256, candidate_sha256, and complete paired_cases recorded by your evaluation. Each hash is a 64-character model identity. Canary utility values must be between 0 and 1.
Build a paired promotion request
paired_cases follows this row shape. The rounded numbers illustrate an equal-utility case; use your own measured outcomes.
One paired case
expected_current_model_sha256 binds the incumbent. expected_model_sha256 binds the candidate. These guards prevent promotion against a different model pair if another operation has changed state.
An equal-utility canary has returned HTTP 409 with the following reason (excerpt):
required_improvement: 0, the observed gate required a strictly positive confidence lower bound. Confirm the confidence estimator and complete application-mode rules against your deployment’s contract.
After a successful promotion response, read value/state and confirm that the installed model is the candidate you evaluated. After a rejection, preserve the reason and inspect the incumbent identity before continuing.
Registered cases and recorded outcomes
The deployed schema also exposes the following fields:
These fields identify application cases, their contexts, and the model associated with a utility measurement. Their end-to-end registration, matching, and automatic promotion rules require confirmation from the deployment contract. Use the explicit paired-canary flow above for the documented example, and obtain the complete deployed request and lifecycle contract before implementing the registered-case flow.
