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

# Evaluate and promote a value candidate

> Separate value checkpoint selection from installation, compare paired application utility, and use model identity guards when promoting a candidate.

Fit an Adapt-1 value candidate while the installed model continues to serve decisions. Evaluate the candidate against the measure your application needs, then confirm adoption through the installed model identity. The training report records the fit; value state records the serving model.

## Separate three decisions

| Decision | Relevant settings or evidence | What it establishes |
| - | - | - |
| Select a fitted checkpoint | `selection_objective`, `selected_epoch`, and checkpoint rejection diagnostics | Which parameters the fit retained as its result |
| Assess predictions and choices | Validation error, `comparison_validation`, and paired application outcomes | How the candidate performs under the selected evaluation |
| Adopt a replacement | `promotion.mode`, `value/promote`, expected hashes, and installed model identity | Whether the serving value model changed |

The [training guide](https://docs.reilabs.org/docs/neuroadapt/value-training.md) covers checkpoint selection. This page covers adoption.

## Choose a promotion measure

The schema defines `promotion.mode` as `prediction` or `application`, with `prediction` as the default. Promotion settings also include `minimum_cases` (default `16`), `required_improvement` (default `0`), and `maximum_prediction_regression` (default `0.05`).

An observed prediction gate reported the criterion `paired_validation_mse_and_episode_confidence`. It can reject a candidate whose validation mean squared error is worse even when that candidate selects better alternatives. Prediction error and decision utility are different measurements.

Use prediction diagnostics when accurate value estimates are the deployment objective. Use paired application utility when deployment success is defined by the consequences of chosen actions. Continue to inspect prediction regressions and comparison diagnostics so the reason for a change remains visible.

> [!NOTE]
>
> Request fields describe schema version 5. The complete relationship between application-mode automatic promotion, registered cases, and `install: true` requires confirmation for your deployment. Use `install: false` for a separate candidate evaluation, then read back the installed identity after promotion.

## Check continuation-candidate installation

Recorded attempts to install fits using `continuation` rows have returned HTTP `422` and left the fits as candidates. Evaluate these candidates through the explicit candidate sources below and confirm the supported installation route for your deployment before automating adoption.

Stage continuation fits with `install: false`. Once a candidate exists, you can select it explicitly with `model_source: candidate` for [value prediction](https://docs.reilabs.org/docs/neuroadapt/value-api/predict.md), or `evaluator_source: value_candidate` for [planning](https://docs.reilabs.org/docs/planning/options.md#select-the-evaluator). Bind the candidate hash you intend to evaluate.

Before automating the next adoption round, establish the supported installation path for that deployment. For an installation refusal, retain the endpoint, request settings, response reason, candidate hash, and incumbent hash, then inspect `value/state`. Keep using the confirmed installed model as the continuation reference until state confirms an adoption. Changing the expected hashes or relabelling continuation rows to make a refused request pass changes the intended workflow.

## Run a paired application comparison

Choose the evaluation cases and utility definition before comparing models. For each case, evaluate the candidate and incumbent under the same initial conditions, execution rules, and planning budget. Record the model SHA-256 identities that actually produced the two outcomes.

Keep these cases separate from model fitting when they are intended to measure generalization. Control or record randomness, initial conditions, execution rules, and planning budgets alongside each pair of utility values so the paired comparison is reproducible.

Use measured application utility for execution comparisons. Assess the reference and candidate through [native planning](https://docs.reilabs.org/docs/planning/options.md#select-the-evaluator), preserving the evaluator and model identity used by each call.

## Submit a canary with model guards

Build the `POST /domains/{domain_id}/value/promote` body from the actual `installed_sha256`, `candidate_sha256`, and complete `paired_cases` recorded by your evaluation. Each hash is a 64-character model identity. Canary utility values must be between `0` and `1`.

```python Build a paired promotion request theme={null}
minimum_cases = 16
if len(paired_cases) < minimum_cases:
    raise ValueError("The paired evaluation has too few cases")

promotion_request = {
    "session_id": "ignored",
    "expected_current_model_sha256": installed_sha256,
    "expected_model_sha256": candidate_sha256,
    "canary": {
        "minimum_cases": minimum_cases,
        "required_improvement": 0.0,
        "cases": paired_cases,
    },
}
```

Each entry in `paired_cases` follows this row shape. The rounded numbers illustrate an equal-utility case; use your own measured outcomes.

```json One paired case theme={null}
{
  "case_id": "<paired case id>",
  "incumbent_utility": 0.58,
  "candidate_utility": 0.58
}
```

`expected_current_model_sha256` binds the incumbent. `expected_model_sha256` binds the candidate. These guards prevent promotion against a different model pair if another operation has changed state.

An equal-utility canary has returned HTTP `409` with the following reason (excerpt):

```text theme={null}
application canary did not demonstrate improvement
```

With `required_improvement: 0`, the observed gate required a strictly positive confidence lower bound. Confirm the confidence estimator and complete application-mode rules against your deployment's contract.

After a successful promotion response, read `value/state` and confirm that the installed model is the candidate you evaluated. After a rejection, preserve the reason and inspect the incumbent identity before continuing.

## Registered cases and recorded outcomes

The deployed schema also exposes the following fields:

| Surface | Field | Declared row shape |
| - | - | - |
| `value/train` | `application_cases` | `case_id`, `context_sha256`; between 2 and 4096 cases |
| `value/observe` | `application_outcomes` | `case_id`, `context_sha256`, `model_sha256`, `utility` |

These fields identify application cases, their contexts, and the model associated with a utility measurement. Their end-to-end registration, matching, and automatic promotion rules require confirmation from the deployment contract. Use the explicit paired-canary flow above for the documented example, and obtain the complete deployed request and lifecycle contract before implementing the registered-case flow.

## Reconcile an uncertain promotion

If the response times out, read current value state before resending. A successful promotion may already have changed the installed model. Reconcile that identity against the candidate and incumbent hashes you recorded.

Keep the two guards on a retry; do not replace them with newly read identities and reuse old case results as if they evaluated the new models. See [operations and retries](https://docs.reilabs.org/docs/neuroadapt/operational-behavior-and-retries.md).

## Record the adoption result

Retain the fit request, selected observation IDs, reference and candidate hashes, checkpoint-selection report, paired cases, promotion result, and final installed identity. Together they show what was fitted, what was compared, and what later planning used.

Continue with the [value-learning cycle](https://docs.reilabs.org/docs/neuroadapt/value-learning.md) after adoption. A new continuation round must record its new reference model identity.


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