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

Adapt-1 can fit a value candidate while an installed model continues to serve decisions. Evaluate the candidate against the measure your application needs, then check whether promotion actually changed the installed model. A training report and an installed model describe different stages of this process.

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

In the checked deployment, the 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 come from archived schema-version-5 build `0136121bd2cf9d4cdbcb114565c7e1ffb74c5a63`; the canary behavior below was checked on 6 November 2026, build `af6670b`. The complete relationship between application-mode automatic promotion, registered cases, and `install: true` is not yet confirmed. Use `install: false` for a separate candidate evaluation, then read back the installed identity after promotion.

## 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. If outcomes depend on randomness, control or record it so paired differences have a clear interpretation. These are application evaluation choices; the canary's two utility values do not themselves establish that the cases were paired correctly.

Do not replace measured application utility with value predictions while describing the result as an execution comparison. The reference and candidate can be assessed through [native planning](https://docs.reilabs.org/docs/planning/options.md#select-the-evaluator), but preserve which evaluator and model identity each call used.

## 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 numbers illustrate an equal-utility case from the recorded integration; use your own measured outcomes.

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

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

On the checked build, equal utilities on 36 paired cases returned HTTP 409 with:

```text theme={null}
application canary did not demonstrate improvement; cases=36, lower_bound=0
```

`required_improvement: 0` therefore did not accept a tie. The observed gate required a strictly positive confidence lower bound. The confidence estimator and the full set of application-mode rules must come from the deployment contract; the example does not define them.

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 have not been established by the recorded integration. 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.