Request shapes, types, and defaults below describe schema version 5. Behavior notes record observed responses. Check
/version at the API host root and use the value API reference to confirm your deployment’s request contract and limits.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. install: true requests installation through the configured promotion behavior. Confirm the result through training.installed and the installed model identity.
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 for correlation. Apply the deployment’s idempotency contract for training and reconcile uncertain submissions through state before retrying. See operations and retries.
Schedule fits for one owner
An overlapping fit can return HTTP409 with one value fit may run per owner. Schedule value fits serially for that owner. Domains and API keys belonging to the same authenticated owner share this fit slot.
After this explicit busy refusal, allow the active fit to finish and retry with bounded backoff. Limit the retry count and keep the intended request in your journal. For a timeout or uncertain server response, first reconcile the submitted request through value/state, then choose the next action from its recorded outcome.
Inspect training state
Readtraining.status, installation fields, and model identity together. Inspect these state fields:
The nested request, model, and report paths above describe observed response shapes. Handle
queued as pending. The following status table is not an exhaustive enum:
These illustrative response fragments use reported field names and status values. The SHA is a placeholder, and other state fields are omitted.
Installed model and completed fit (illustrative)
Rejected fit (illustrative)
Use the full report to identify the data or configuration issue and confirm the applicable rejection threshold against your deployment’s contract. Correct the identified issue and read the installed model identity independently of the latest fit’s outcome.
Poll until the fit finishes
- Before submitting a fit, save the current value state, the intended observation selection, and the training request with its
request_id. Keep submissions serialized so you can distinguish the new fit from an earlier result. - After HTTP
202, readvalue/statefor the same Domain and identity. Requiretraining.request_idto match the submitted request. Inspecttraining.status, not the top-levelconfiguredstatus. Keep polling while that fit isqueuedorrunning, with a bounded client wait. - Stop waiting when the fit matching your
request_idreportscandidate,trained, orrejected. Retain the returned training details and reconcile them with your request journal. - For a completed fit, inspect
training.installed,candidate.model_sha256when present, andmodel.model_sha256. To evaluate an uninstalled candidate, usemodel_source: candidatein value prediction and putcandidate.model_sha256inexpected_model_sha256. For a rejection, inspect the reason and which model remains installed before choosing another request.
Recover from a long or interrupted fit
For long fits, record the workload, duration, and reported result. If a fit fails under load, inspect its reason and use the deployment contract for service timeouts and row limits. Measure training time for the intended workload and options. After a client timeout or interruption, readvalue/state before another training write. If the fit is still queued or running, continue monitoring it within your application’s wait budget. If it has completed, use the completion and installation checks above. If the state or failure remains uncertain, retain the request and response history for reconciliation instead of starting another fit blindly.
After a confirmed failure, preserve the reason and report before changing the workload. Record a smaller observation selection or fewer epochs as a revised fit. Keep provided or outcome evidence in both partitions for continuation training, and keep comparison groups in both partitions when using comparison training. Use a new request_id for a deliberately revised fit. Measure the workload sizes you intend to use and confirm capacity limits against your deployment’s contract.
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. Check the selected evidence against the fitting prerequisites as well as the array-length limits.
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
warm_start defaults to true. Set it explicitly to false for a cold fit, as in this complete request for a configured object-graph value learner. The request also asks for installation; inspect the resulting state to confirm the installed model.
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.
Choose a compatible training setup
Choose the representation and model together before adding optional training objectives.
Choose a compatible combination of representation, model, and training options. If a combination is rejected, preserve the refusal and resolve its requirements before changing the learning setup.
Representation options
These are accepted schema fields. For a default marked “Not declared”, inspect the runtime’s resolved value. Confirm representation transformations and their interactions against your deployment’s contract, and 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.
Observed warm fits reported regularization_target: "incumbent"; cold fits reported "zero". A 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. Use the following observed scope behavior and confirm the handling of explicit outcome rows for your deployment:
Use
all for the workflow shown here when the fit must include explicit observed-outcome rows. An upload can succeed while a later scope excludes its observations. Confirm the admitted source counts and the fit report together.
Preserve the requested scope and any returned refusal. Confirm the intended handling of each supervision source with your deployment before selecting a different scope.
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, then set the training weight for their contribution.
A positive
comparison_weight enables the comparison contribution for declared groups; 0 disables it. Training individual targets remains a separate part of the fit.
The following request enables comparison training while keeping prediction-based checkpoint selection. These option values define the example configuration; select settings for your application:
Comparison training request
422 when groups were missing from either fitting or validation. Read comparison_validation.groups after the fit to confirm that the intended comparisons participated.
Confirm the exact objective definitions for regret loss and adaptation_prediction selection against your deployment’s contract. Check model compatibility before selecting a mode, keep the 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 observed warm fits, some fits returned selected_epoch: 0. That value identifies the incoming state as the selected checkpoint. Use the optimization and checkpoint diagnostics to inspect the fitting work.
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. Record the bound and selection mode for each fit. Confirm the mode’s default, selection inequality, and relationship to promotion.maximum_prediction_regression against your deployment’s contract.
Read optimization_applied, selected_epoch, and the model identities together. A nonzero selected epoch identifies a later checkpoint. Use the installed model identity to confirm adoption and paired application utility to measure decision quality.
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. Grouped-choice diagnostics and paired application utility measure decision quality. Observed candidates have ranked alternatives better while having worse validation MSE.
Use comparison_validation to inspect choices against the grouped targets and target regret to measure differences from those targets. Use a paired evaluation of executed application utility to assess deployment decisions, following application promotion before adoption.
Record reproducibility without assuming it
Repeated cold and warm fits on identical inputs have produced identical results. Record the build, hardware, and deployment when checking reproducibility. The documented request schema exposes no fit seed option. Record the build, observation IDs, fit options, input model SHA, target-reference SHA, materialized-target SHA, and selected checkpoint. Measure performance across independently chosen data and cases appropriate to your task, alongside repeated-fit reproducibility. A repeated fit can return a new model SHA while producing identical predictions. Use the SHA to bind a model artifact, and compare predictions to check for a functional change:- Keep a fixed set of representative inputs with the same feature names, units, and representation flags.
- Evaluate each model with its actual
expected_model_sha256, preserving which response belongs to each input. - Compare the numeric predictions using a tolerance appropriate to your value scale. If your application chooses between alternatives, compare those choices as well.
