> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reilabs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Train and inspect value candidates

> Choose observation snapshots, cold or warm initialization, comparison training, and checkpoint selection; verify each stage through the fit report.

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.

> [!NOTE]
>
> 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](https://docs.reilabs.org/docs/neuroadapt/value-api.md) 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`.

| Request field | Type, default, or schema constraint |
| - | - |
| `session_id` | Required nonempty string; use the hosted identity rules in [HTTP and contracts](https://docs.reilabs.org/docs/neuroadapt/request-contracts.md) |
| `request_id` | Required string, 1 to 256 characters |
| `options` | `ValueTrainOptions` object |
| `install` | Boolean, default `true` |
| `warm_start_source` | `installed` or `candidate`, default `installed` |
| `expected_initial_model_sha256` | Optional 64-character lowercase hexadecimal SHA, or `null` |
| `observation_ids` | Optional array of 4 to 20,000 strings, or `null` |
| `application_cases` | Optional array of 2 to 4,096 cases, or `null`; each case requires `case_id` and `context_sha256` |

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`.

```json State inspection request theme={null}
{
  "session_id": "ignored"
}
```

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](https://docs.reilabs.org/docs/neuroadapt/operational-behavior-and-retries.md).

### 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:

| Field | What to inspect |
| - | - |
| `model.model_sha256` | Identity of the installed model |
| `model.model_type` | Installed model type |
| `model.trained_samples` | Sample count recorded with that model |
| `training.request_id` | Matches the training request you are waiting for |
| `candidate.model_sha256` | Identity of a staged candidate, when one exists |
| `training.status` | State of the reported fit |
| `training.installed` | Whether that fit installed a model |
| `training.finished_at` | Reported completion time |
| `training.reason` | Reason supplied for a rejected fit |
| `training.report.validation_skill` | Prediction skill reported for the fit |
| `training.report.validation_checks.prediction_span` | Prediction spread recorded in the fit report |

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:

| `training.status` | Interpretation |
| - | - |
| `queued` | Treat this as pending; keep waiting for the matching request |
| `running` | The fit is still in progress |
| `candidate` | The fit completed with a candidate for evaluation; do not wait for `trained` when fitting with `install: false` |
| `trained` | The fit completed; inspect `training.installed` and the installed model identity |
| `rejected` | The fit was rejected; inspect `training.reason` and read back which model remains installed |

These illustrative response fragments use reported field names and status values. The SHA is a placeholder, and other state fields are omitted.

```json Installed model and completed fit (illustrative) theme={null}
{
  "model": {
    "model_sha256": "<installed-model-sha256>",
    "model_type": "mlp_v2"
  },
  "training": {
    "status": "trained",
    "installed": true
  }
}
```

```json Rejected fit (illustrative) theme={null}
{
  "training": {
    "status": "rejected",
    "reason": "collapsed_predictions"
  }
}
```

Use the rejection reason to choose the next check:

| Reason | What to inspect before another fit |
| - | - |
| `collapsed_predictions` | Numeric input placement, variation between states and targets, coverage, and the reported prediction spread. Use [projected-input checks](https://docs.reilabs.org/docs/neuroadapt/value-observations.md#verify-projected-inputs) to isolate input placement. |
| `candidate_failed_validation` | The validation report and the original outcome labels. Check that preprocessing preserved the measured outcome, that inputs distinguish relevant states, and that fitting and validation contain useful evidence. This refusal has occurred for fits with no validation skill. |

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](https://docs.reilabs.org/docs/neuroadapt/value-api/predict.md) 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](https://docs.reilabs.org/docs/neuroadapt/value-client-workflow.md) 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](https://docs.reilabs.org/docs/planning/options.md#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](https://docs.reilabs.org/docs/neuroadapt/value-observations.md) for record construction and refusal messages.

## Set initialization explicitly

| Field path | Schema default or values | Integration use |
| - | - | - |
| `options.warm_start` | Boolean, default `true` | Set `false` for a deliberate cold fit; set `true` when continuing from existing parameters |
| `warm_start_source` | Default `installed`; also `candidate` | Identify which parameter state should initialize a warm fit |
| `options.function_retention_weight` | Number from `0` to `100`, default `0` | Exposed by the schema; its exact penalty and interaction with the fit require a confirmed deployment contract |
| `options.trainable_layers` | `all`, `readout`, `new_inputs`; default `all` | Exposed layer-selection modes; confirm the parameter coverage of each mode before relying on a frozen subset |

`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.

```json Initial value training request theme={null}
{
  "session_id": "ignored",
  "request_id": "value-initial-001",
  "install": true,
  "options": {
    "model_type": "object_value",
    "warm_start": false,
    "supervision_scope": "all"
  }
}
```

For continuation from the installed model, stage a candidate with a separate request:

```json Warm value training request theme={null}
{
  "session_id": "ignored",
  "request_id": "value-continuation-001",
  "install": false,
  "warm_start_source": "installed",
  "options": {
    "model_type": "object_value",
    "warm_start": true,
    "supervision_scope": "all"
  }
}
```

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`:

| Field | Type and allowed values | Schema default |
| - | - | - |
| `model_type` | `linear`, `mlp_v2`, `object_value` | `mlp_v2` |
| `dimensions` | Integer, 8 to 4,096 | `64` |
| `epochs` | Integer, 1 to 2,000 | `200` |
| `learning_rate` | Number greater than `0` and at most `1` | `0.003` |
| `loss_function` | `squared`, `log_loss` | `squared` |
| `validation_mode` | `chronological`, `episode_hash` | `chronological` |
| `validation_episode_ids` | Array of 1 to 10,000 strings, or `null` | Not declared |
| `primary_validation_episode_ids` | Array of 1 to 10,000 strings, or `null` | Not declared |
| `supervision_scope` | `all`, `terminal_and_continuation`, `provided_and_terminal`, `provided_terminal_and_continuation` | `all` |

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.

| Setup | How to use it |
| - | - |
| `representation: object_graph` with `options.model_type: object_value` | Use the graph requests on this page. The comparison example uses `selection_objective: prediction`; declare comparison groups before enabling their loss. |
| `representation: projected` with `options.model_type: mlp_v2` | This combination has produced installed models. First verify [numeric input placement](https://docs.reilabs.org/docs/neuroadapt/value-observations.md#verify-projected-inputs), then reuse that encoding for prediction and planning. |
| `selection_objective: adaptation_prediction` | Use this with a dense-model configuration whose compatibility you have confirmed. It has returned HTTP `422` for object-graph fits. Use the graph example's settings for that workflow; this guide does not define every accepted dense-model configuration. |

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

| Field under `options` | Type and allowed values | Schema default |
| - | - | - |
| `dense_inputs` | Boolean | `true` |
| `preserve_binary_inputs` | Boolean | `true` |
| `quadratic_pairs` | Boolean | `false` |
| `pair_geometry` | Boolean | `false` |
| `dense_hidden_dimensions` | Integer, 8 to 256, or `null` | Not declared |
| `object_hidden_dimensions` | Integer, 8 to 256, or `null` | Not declared |
| `peak_pooling` | Boolean or `null` | Not declared |
| `interaction_selection` | `lexical`, `evidence`, or `null` | Not declared |

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:

| Scope | `target` rows | `outcome` rows | `continuation` rows |
| - | - | - | - |
| `all` | Used | Used | Used |
| `provided_and_terminal` | Used | Excluded | Excluded |
| `terminal_and_continuation` | Not established | Excluded; the fit was refused | Used |
| `provided_terminal_and_continuation` | Not characterized | Not characterized | Not characterized |

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.

| Option | Schema default | Accepted values |
| - | - | - |
| `comparison_weight` | `0` | Number from `0` to `10` |
| `comparison_loss` | `squared` | `squared`, `regret` |
| `selection_objective` | `prediction` | `prediction`, `comparison_regret`, `adaptation_prediction` |

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:

```json Comparison training request theme={null}
{
  "session_id": "ignored",
  "request_id": "value-comparison-001",
  "install": false,
  "warm_start_source": "installed",
  "options": {
    "model_type": "object_value",
    "warm_start": true,
    "supervision_scope": "all",
    "comparison_weight": 1,
    "comparison_loss": "squared",
    "selection_objective": "prediction"
  }
}
```

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](#choose-a-compatible-training-setup) 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](https://docs.reilabs.org/docs/neuroadapt/value-promotion.md) 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.

| Question | Relevant fields |
| - | - |
| Did warm initialization apply? | `warm_start.applied`, its reason when returned, and `continuation.warm_start_source` |
| Which parameters initialized the fit? | `continuation.initial_model_sha256` |
| Did the fit construct continuation targets? | `target_refresh.continuation_records`, `modeled_successors`, and `declared_terminal_successors` |
| Which model produced those targets? | `target_refresh.reference_model_sha256` |
| Can you identify the materialized target set? | `target_refresh.materialized_targets_sha256` |
| Which regularization target was used? | `regularization_target` |
| Did optimization affect the reported continuation? | `continuation.optimization_applied` |
| Which checkpoint was selected? | `continuation.selected_epoch`, and `selected_epoch` where exposed in the fit report |
| Were checkpoints excluded by prediction constraints? | `selection_prediction_regression`, `prediction_bound_rejected_checkpoints` |
| Did comparisons enter validation? | `comparison_validation.groups`, `informative_groups` |
| How did the candidate select among grouped targets? | `comparison_validation.top_choice_agreement`, `mean_target_regret`, and the available `informative_*` metrics |

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](https://docs.reilabs.org/docs/neuroadapt/value-promotion.md) 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](https://docs.reilabs.org/docs/neuroadapt/value-promotion.md) 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](https://docs.reilabs.org/docs/neuroadapt/value-promotion.md) before recording a model change.

For the complete sequence from the first observed outcomes through repeated refinement, follow [value learning](https://docs.reilabs.org/docs/neuroadapt/value-learning.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.