Skip to main content
Fit an Adapt-1 value candidate while the installed model continues to serve decisions. Evaluate the candidate against the measure your application needs, then confirm adoption through the installed model identity. The training report records the fit; value state records the serving model.

Separate three decisions

The training guide covers checkpoint selection. This page covers adoption.

Choose a promotion measure

The schema defines promotion.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 using continuation 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 the POST /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
Each entry in 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):
With 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.

Reconcile an uncertain promotion

If the response times out, read current value state before resending. A successful promotion may already have changed the installed model. Reconcile that identity against the candidate and incumbent hashes you recorded. Keep the two guards on a retry; do not replace them with newly read identities and reuse old case results as if they evaluated the new models. See operations and retries.

Record the adoption result

Retain the fit request, selected observation IDs, reference and candidate hashes, checkpoint-selection report, paired cases, promotion result, and final installed identity. Together they show what was fitted, what was compared, and what later planning used. Continue with the value-learning cycle after adoption. A new continuation round must record its new reference model identity.