Request shapes, types, and defaults below come from the archived schema-version-5 build
0136121. Behavior notes describe separate checks on build af6670b on 6 November 2026. These sources describe different builds. The value API reference records source coverage; check the target deployment’s host-root /version before integration.Submit a training request
UsePOST /api/v1/domains/{domain_id}/value/train. The request requires session_id and request_id; fit settings belong inside options. warm_start_source belongs at the request level, alongside install and observation_ids.
Set
install: false when staging a candidate for separate evaluation. An installation request must still be checked against the actual result and promotion behavior. Do not treat install: true as evidence that a gate was bypassed or a replacement succeeded.
The schema defines HTTP 202 for an accepted training request. Poll POST /api/v1/domains/{domain_id}/value/state with the same session identity and inspect training.status. Recorded responses can retain a top-level status of configured while training.status is running.
State inspection request
request_id in your request journal. Its presence does not establish an idempotency guarantee; reconcile uncertain submissions through state before retrying. See operations and retries.
Choose the observation snapshot
Use the top-levelobservation_ids to identify the observations included in a fit. For continued learning, include earlier evidence along with new observations. Preserve the exact selection and the relevant model identities with the training report. A valid array length does not establish that the selected evidence meets the fitting prerequisites.
A continuation fit needs provided or outcome evidence in both fitting and validation partitions. Comparison training also needs declared comparison groups in both partitions. Verify these requirements after any filtering or group subsampling. See value observations for record construction and refusal messages.
Set initialization explicitly
Do not assume that omitting
warm_start starts a new model. This complete request body starts a cold fit for a configured object-graph value learner. It requests installation; inspect the resulting state to determine whether installation succeeded.
Initial value training request
Warm value training request
expected_initial_model_sha256 at the request level when you need to bind initialization to a particular incoming model. Supply the actual SHA reported by state, not a display label. Add observation_ids when selecting an explicit recorded dataset.
Fit and validation options
The following fields belong underoptions:
Use the configured representation and model type consistently. The observed graph workflow uses
object_graph configuration and object_value fitting. Explicit episode lists identify validation episodes; verify the resulting partitions and the continuation-evidence requirements in the report. The schema does not define the full precedence of primary validation lists or the exact chronological ordering rule.
Representation options
These are accepted schema fields. A default marked “Not declared” is absent from the archived schema; it is not a promise that the runtime resolves the field to
null. The schema does not describe every representation transformation or its interactions. Preserve the resolved options in the fit report when comparing runs.
Confirm the initialization used
Inspecttraining.report.warm_start.applied and the fields under training.report.continuation. The report exposes initial_model_sha256, warm_start_source, optimization_applied, and selected_epoch.
The checked warm fits reported regularization_target: "incumbent"; cold fits reported "zero". A checked cold fit reported warm_start.applied: false with reason: "no_initial_model". Record the actual report rather than inferring initialization solely from the request.
Record the initialization hash separately from target_refresh.reference_model_sha256. One identifies the incoming parameter state; the other identifies the model used to construct continuation targets.
Select the supervision scope
options.supervision_scope defaults to all and controls which supervision types participate in training. The names alone do not establish how the explicit outcome field is handled. The following table records the checked behavior of build af6670b:
Use
all when the fit must include explicit observed-outcome rows on this build. An upload can succeed while a later scope excludes its observations. Confirm the admitted source counts and the fit report together.
The intended distinction between the scope names and these observed exclusions remains unconfirmed. Do not infer untested behavior from the word terminal or silently substitute another scope after a refusal.
Train differences between alternatives
In the object-graph path, comparison groups let the fit use differences between related alternatives as well as their individual targets. Declare the groups in the observations throughmetadata.comparison_group; setting a training weight alone does not establish them.
At
comparison_weight: 0, the comparison contribution is disabled. A positive weight has no comparison contribution without declared groups. Training individual targets is a separate part of the fit.
The following request enables comparison training while keeping prediction-based checkpoint selection. These option values describe a checked configuration, not a universal optimum:
Comparison training request
422 when groups were missing from either fitting or validation. Read comparison_validation.groups after the fit; a completed request alone does not prove that the intended comparisons participated.
The schema exposes regret loss and adaptation_prediction selection. Their exact objective definitions are not established by the supplied contract. Keep the selected settings in the run record and inspect the resulting validation and checkpoint diagnostics.
Distinguish checkpoint selection from promotion
selection_objective participates in choosing a checkpoint within the fit. Promotion determines whether the candidate replaces the installed model. Configure and inspect each stage separately.
When selection_objective: "comparison_regret" was used in the checked warm fits, some fits returned selected_epoch: 0. That value means the selected checkpoint retained the incoming state. It does not prove that the optimizer never evaluated later checkpoints.
The reports also exposed selection_prediction_regression and prediction_bound_rejected_checkpoints. A bound of 0.05 appeared in those reports, alongside checkpoint rejection counts. This is an observed report value, not a documented default for every selection mode. The exact selection inequality and its relationship to promotion.maximum_prediction_regression remain unconfirmed.
Read optimization_applied, selected_epoch, and the model identities together. A nonzero selected epoch identifies a later selected checkpoint; it does not establish successful installation or improved application decisions.
Read the report by question
Inspecttraining.report in the value/state response.
Inspect the exact response structure returned by your deployment; preserve the full report alongside the fields your client consumes.
Prediction error and choice quality answer different questions
Validation MSE andvalidation_skill describe predictive performance. They do not directly measure whether the candidate selects the best alternative in an application. In the checked fits, a candidate could rank alternatives better while having worse validation MSE.
Use comparison_validation to inspect choices against the grouped targets. Target regret is a comparison against those targets; it does not replace a paired evaluation of executed application utility. If deployment success depends on decisions, follow application promotion before adoption.