Choose this workflow
Use this path when you can supply states and their outcomes, and your application needs to compare alternatives before a final outcome is available. Exact transition rules and learned values serve different roles: the rules determine the successor, while the value learner estimates its utility. For action values learned from ordered transitions and feedback, see sequential learning. For predictions of the next observable state, see transition learning. These interfaces have distinct observation, training, and state contracts.Request schemas are drawn from the archived schema-version-5 build
0136121bd2cf9d4cdbcb114565c7e1ffb74c5a63. Behavior notes also use integration checks from 6 November 2026, build af6670b. The value API reference identifies the source boundaries. Check /version at the API host root to match the guide’s behavior notes to your deployment.Establish the task contract
Choose a Domain, a value relation and policy, a state representation, and an outcome scale. Keep the meaning and perspective of a value consistent across observations, terminal scores, continuation targets, and application comparisons. Theprojected representation reduces objects and relations to counts. The object_graph representation preserves their connections. The documented comparison-group workflow uses object_graph.
Decide how you will judge a replacement model. Prediction error measures agreement with value targets. Application utility measures the consequences of the decisions made with those values. A candidate can improve one measure without improving the other.
Run the learning cycle
1
Configure the value learner
Call
value/configure with the task’s relation, policy, representation, sample retention, and promotion settings. Require a response with status: configured. The API reference includes the confirmed request shape.2
Record observed outcomes
Upload observations through
value/observe. Give each row a stable record_id, an episode_id, and a step. Supply exactly one supervision source: a provided numeric target, an observed outcome, or a model-based continuation. Begin with targets derived from measured outcomes, or with observed outcome rows, so the first reference has outcome evidence.Verify that accepted + duplicates accounts for all submitted rows. Keep the original observation content for exact retries. See value observations.3
Fit and install the first reference
Set
options.warm_start: false explicitly for an independent first fit. Use options.model_type: object_value for the graph example and top-level install: true to request installation. The train route returns HTTP 202; inspect value/state until the training job has finished, then confirm which model is installed. Save its SHA-256 identity.A completed fit does not establish installation. A nonterminal continuation requires a fitted reference model, so confirm the installed reference before proceeding. Do not interpret install: true as permission to bypass an adoption gate.4
Reconsider recorded states
For each selected recorded state, generate legal successors through the task’s transition rules. Submit a continuation observation containing those successors. Give a completed successor its exact
terminal_value; the reference model evaluates unfinished successors.Retain provided or outcome observations in both the fitting and validation partitions. Continuation training refuses a snapshot without this evidence. Limit the number of successors per fit; the exact deployment cap must be confirmed from its contract.5
Declare comparisons between alternatives
When using the graph path, represent each compared alternative as its own observation. Give related alternatives the same
metadata.comparison_group value. In the verified arrangement, these observations are sibling child states, each with its own continuation target.A continuation’s successors array does not declare a comparison group. Both fitting and validation partitions need groups when comparison training is enabled.6
Continue fitting from retained parameters
Train a candidate with
options.warm_start: true, top-level warm_start_source: installed, and install: false. Set expected_initial_model_sha256 to the retained reference identity. Select the earlier and new observations through top-level observation_ids so the fit retains evidence from previous rounds. Use a new request_id for the intended fit.A verified example uses comparison_weight: 1, comparison_loss: squared, and selection_objective: prediction. These are example settings, not a performance guarantee. Inspect the training report to see which checkpoint was selected and whether continuation targets and comparisons participated.7
Compare application decisions and promote
Evaluate the candidate and incumbent on paired cases under the same application conditions. Preserve the model identities and measured utility for each case. Submit the paired canary through
value/promote with both expected model hashes.Inspect the promotion response and read back the installed model identity. A rejected candidate leaves the adoption question unresolved; a successful fit alone must not switch the application to a different model. See value promotion.8
Repeat with the adopted reference
Use the newly installed model as the reference for the next continuation round. Add new observed outcomes and retain the earlier evidence selected for the fit. Record the reference, candidate, and installed model identities at each boundary.
Confirm what each stage changed
selected_epoch: 0 means the selected parameters are the incoming checkpoint. It does not prove that the fit performed no optimization. Keep target construction, checkpoint selection, and installation as separate checks.
Use the retained value in planning
Set request-levelevaluator_source: value_model to select the installed value learner, or value_candidate to evaluate a candidate. Bind the expected model identity using the planning contract and check the returned evaluator identity. See planning integration and planning options.
Supply exact terminal_value scores only for completed outcomes. An unfinished state’s estimate should retain its model provenance. Record search evaluations and transitions separately from admitted observations and executed episodes.
During frozen evaluation, stop observation and training writes, call value/freeze with session_id and expected_model_sha256, and compare model identities before and after planning. The value-freeze request does not establish that every other Domain learner is frozen.
Keep observed outcomes and assessments distinct
A continuation target is a model-based assessment. An observed outcome is evidence from an executed episode. Preserve both sources in your application record, along with episode, step, and model identity. The Coupled Learning and Planning article describes targets that combine an assessment with an observed outcome. The observed API accepts one supervision source per row. If your application computes a blended scalar, submit it astarget and retain its inputs and provenance separately. Uploading outcome rows alongside continuation rows does not establish a per-row blend. See target construction.