> ## 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, then inspect what the fit actually used and selected. Initialization, target generation, checkpoint selection, and installation are separate decisions. A completed fit does not establish that a new model is serving your application.

> [!NOTE]
>
> 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](https://docs.reilabs.org/docs/neuroadapt/value-api.md) records source coverage; check the target deployment's host-root `/version` before integration.

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

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

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

## 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. 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](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 |

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.

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

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

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

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

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

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 through `metadata.comparison_group`; setting a training weight alone does not establish them.

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

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:

```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; 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](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 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

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

## Record reproducibility without assuming it

Repeated cold and warm fits on identical inputs produced identical results in the reported checks. The inspected schema exposed no fit seed option. These observations do not establish a determinism guarantee across builds, hardware, or deployments.

Record the build, observation IDs, fit options, input model SHA, target-reference SHA, materialized-target SHA, and selected checkpoint. Repeating the same deterministic fit is not independent evidence of performance across different data. Evaluate across the independently chosen data and cases appropriate to your task.

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