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 tables describe schema version 5, and behavior notes describe observed API responses. Check
/version at the API host root and confirm compatibility with your deployment before integration. Use the value API reference for request contracts.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.
The value schema accepts numeric maps in conditions, context, and policy_features. Verify which entries participate in projected inputs before collecting a larger dataset. Use one state encoder across observations, prediction, continuations, and planning, and choose a compatible training setup.
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.
For a complete Python client using your own observations, see Run the value API workflow. It connects upload, fitting, job polling, prediction, candidate comparison, and explicit promotion, tracking fitting and installation separately.
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.Batch by serialized bytes as well as row count. 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; follow the polling procedure until that fit has finished, then confirm which model is installed. Save its SHA-256 identity.For nonterminal continuations, confirm that the fitted reference is installed before proceeding. install: true requests installation through the configured adoption gate; value/state reports the installed model.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 this workflow, 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.The example configuration uses comparison_weight: 1, comparison_loss: squared, and selection_objective: prediction. A finished uninstalled fit can report training.status: candidate; treat that as completion when staging a candidate. Inspect the training report for the selected checkpoint and the contribution of continuation targets and comparisons.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. For continuation-trained candidates, first check the reported installation restriction. Submit the paired-canary request to
value/promote with both expected model hashes, and handle an installation refusal as described there.Inspect the promotion response and read back the installed model identity. Advance the installed reference after state confirms adoption; after a refusal, keep the confirmed incumbent as the reference and retain the candidate’s evaluation result. See value promotion.8
Repeat with the adopted reference
Advance the reference only after
value/state confirms the evaluated candidate is installed. If installation or promotion was refused, retain the existing reference and the candidate evaluation as separate results. 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 identifies the incoming checkpoint as the selected parameter state. Inspect the full fit report for optimization and checkpoint diagnostics. Check target construction, checkpoint selection, and installation separately. Use the model SHA to identify the artifact and compare predictions on fixed inputs to measure functional changes.
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. Check evaluator readiness before the first planning request. 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.
Use an outcome target with a terminal-outcome planner by aligning utility, neutral value, discount, perspective, and step units. Include intermediate rewards and path costs in that objective where the task requires them. Align the value objective before combining learned frontier estimates with terminal values.
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. Freeze every other participating Domain learner through its own controls and verify its state separately.
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 API accepts one supervision source per row. For a per-row blend, compute the scalar in your application, submit it astarget, and retain its inputs and provenance. Outcome rows and continuation rows supplied separately remain separate supervised examples. See target construction.