Skip to main content
Fit Adapt-1 value candidates from a selected observation snapshot. The fit report identifies the initialization, target generation, and selected checkpoint; the installed model identity identifies the model serving your application.
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

Use POST /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
Keep 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 HTTP 409 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

Read training.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 rejection reason to choose the next check: 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

  1. 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.
  2. After HTTP 202, read value/state for the same Domain and identity. Require training.request_id to match the submitted request. Inspect training.status, not the top-level configured status. Keep polling while that fit is queued or running, with a bounded client wait.
  3. Stop waiting when the fit matching your request_id reports candidate, trained, or rejected. Retain the returned training details and reconcile them with your request journal.
  4. For a completed fit, inspect training.installed, candidate.model_sha256 when present, and model.model_sha256. To evaluate an uninstalled candidate, use model_source: candidate in value prediction and put candidate.model_sha256 in expected_model_sha256. For a rejection, inspect the reason and which model remains installed before choosing another request.
The Python workflow client implements these checks. For an absent or unfamiliar status, preserve the response and resolve it against the deployment’s status contract before recording completion. If the client stops waiting, the server-side fit may still be running; follow the recovery procedure below before submitting another fit. Before using the result in search, check evaluator readiness.

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, read value/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-level observation_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
For continuation from the installed model, stage a candidate with a separate request:
Warm value training request
Add 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 under options: 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

Inspect training.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 through metadata.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
Comparison training was refused with HTTP 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

Inspect training.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 and validation_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:
  1. Keep a fixed set of representative inputs with the same feature names, units, and representation flags.
  2. Evaluate each model with its actual expected_model_sha256, preserving which response belongs to each input.
  3. Compare the numeric predictions using a tolerance appropriate to your value scale. If your application chooses between alternatives, compare those choices as well.
A probe comparison measures change on those inputs. Use the paired application evaluation in value promotion to assess whether a change improves the decisions that matter.

Continue to adoption

After training, inspect which candidate exists and which model remains installed. Use the candidate’s identity when evaluating it, preserve the incumbent’s identity for paired comparisons, and apply the promotion checks before recording a model change. For the complete sequence from the first observed outcomes through repeated refinement, follow value learning.