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

# Value observations and continuation targets

> Prepare value observations with one supervision source, generate continuation targets from legal successors, and declare groups of alternatives.

Use Adapt-1 value observations to attach supervision to recorded states. Stable record identities make uploads retryable; separate supervision sources preserve the distinction between an observed outcome, a supplied target, and an estimate produced by a reference model.

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

## Send an observation batch

Send `POST /api/v1/domains/{domain_id}/value/observe` with a nonempty `session_id` and an `observations` array. The schema permits at most 50 observations per request. Use `"session_id": "ignored"` on the authenticated hosted service as described in [HTTP and contracts](https://docs.reilabs.org/docs/neuroadapt/request-contracts.md).

This complete request body shows one supplied target with numeric policy features. Replace the illustrative IDs, feature names, and values with the encoding used by your configured value learner.

```json Value observation request theme={null}
{
  "session_id": "ignored",
  "observations": [
    {
      "record_id": "episode-001-step-004-target-v1",
      "episode_id": "episode-001",
      "step": 4,
      "policy_features": {
        "progress": 0.4,
        "capacity": 0.8
      },
      "target": 0.7
    }
  ]
}
```

The same envelope also accepts `application_outcomes`, an array of at most 50 application-evaluation records. Those records have `case_id`, `context_sha256`, `model_sha256`, and `utility`; they are separate from supervised observations. See [application promotion](https://docs.reilabs.org/docs/neuroadapt/value-promotion.md) for their contract.

## Choose one supervision source

Each observation sent to `value/observe` carries exactly one of `target`, `outcome`, or `continuation`. Omit the other two fields.

| Source | Supply it when | Target meaning |
| - | - | - |
| `target` | Your application already has the scalar to fit | The supplied number in `[0, 1]` is used as-is |
| `outcome` | You have an observed terminal result and its episode position | The terminal result is discounted toward a neutral value according to the steps remaining |
| `continuation` | A fitted reference model can evaluate the supplied alternatives | The server constructs a target from successor values |

A row with conflicting or missing supervision rejects the whole observation batch with HTTP `422`. The observed error is:

```text theme={null}
provide exactly one of target or an observed outcome or a continuation
```

## Identify the record and its inputs

Keep `record_id`, `episode_id`, and `step` alongside the state representation. `record_id` identifies a particular observation; `episode_id` and `step` identify its place in the recorded sequence.

| Fields | Type and schema constraints | Purpose |
| - | - | - |
| `record_id`, `episode_id` | Required strings, each 1 to 256 characters | Record identity and episode membership |
| `step` | Required number, at least `0` | Position in the recorded episode |
| `objects` | Array of at most 512 objects, or `null` | Objects supplied to the configured representation |
| `relations` | Array of at most 4,096 objects | Relations between the supplied objects |
| `conditions`, `context` | Numeric maps, at most 16 properties each | Numeric state inputs accepted by the value schema |
| `policy_features` | Numeric map, at most 4,096 properties | Application-provided policy features |
| `metadata` | Object with arbitrary properties | Record metadata, including the comparison-group identifier |
| `include_positions` | Boolean, default `true` | Representation control exposed by the input schema |
| `include_moments` | Boolean, default `false` | Representation control exposed by the input schema |

The observation schema rejects additional top-level fields. The object and relation entries allow application-defined properties. The schema specifies the types and defaults of the representation controls but does not define their full projection behavior.

The `projected` representation reduces objects and relations to counts. The `object_graph` representation retains the objects and the relations between them. The comparison-group workflow below uses the graph path. Configure the representation before collecting the observations for a fit; see [value learning](https://docs.reilabs.org/docs/neuroadapt/value-learning.md).

### Provided target

This supervision fragment identifies an application-provided value. Combine it with the state's required inputs and the full `value/observe` request envelope.

```json Provided-target observation fragment theme={null}
{
  "record_id": "episode-001-step-004-target-v1",
  "episode_id": "episode-001",
  "step": 4,
  "target": 0.7
}
```

### Observed outcome

An `outcome` requires `value` and `terminal_step`. Its `value`, `discount`, and `neutral` are numbers in `[0, 1]`; `terminal_step` is a nonnegative number. `discount` defaults to `1` and `neutral` to `0.5`. Discounting moves the recorded terminal value toward the neutral value for earlier states. With `discount: 1`, that distance from the neutral value is unchanged.

```json Observed-outcome observation fragment theme={null}
{
  "record_id": "episode-001-step-004-outcome-v1",
  "episode_id": "episode-001",
  "step": 4,
  "outcome": {
    "value": 1.0,
    "terminal_step": 12,
    "discount": 1.0,
    "neutral": 0.5
  }
}
```

The IDs, steps, and values in these fragments illustrate the fields. Your application defines utility within the API's `[0, 1]` range and supplies the actual episode boundaries.

## Build continuation observations

Your application supplies legal successor states. The server evaluates unfinished successors with a fitted reference model and uses these evaluations to construct the continuation target. A completed successor carries its exact `terminal_value`, which takes precedence over the model's estimate.

In the construction fragment below, `recorded_state` is the current state's supported descriptor. `legal_successors` is the list of successor descriptors generated by the application's rules or transition interface.

```python Continuation observation construction fragment theme={null}
continuation_row = {
    **recorded_state,
    "record_id": "episode-001-step-004-continuation-v1",
    "episode_id": "episode-001",
    "step": 4,
    "continuation": {
        "maximizing": True,
        "discount": 1.0,
        "neutral": 0.5,
        "successors": legal_successors,
    },
}
```

`maximizing` is a required Boolean. The `successors` array requires 1 to 256 entries per continuation row. The continuation schema defaults `discount` to `1` and `neutral` to `0.5`, with both constrained to `[0, 1]`. Set `maximizing` for the value perspective used by this comparison and keep successor values in that perspective.

Supply the legal alternatives intended for the backup. If that set exceeds the per-row schema limit, resolve the integration contract instead of silently dropping alternatives.

For a completed successor, attach the exact score to its descriptor:

```python Terminal successor construction fragment theme={null}
terminal_successor = {
    **terminal_state,
    "terminal_value": exact_terminal_utility,
}
```

`terminal_value` is a number in `[0, 1]`. Successor descriptors use the same numeric maps, object arrays, relation arrays, and representation flags as a value input. They can also carry an optional `counterpart` in the `ValueInput` shape; the schema alone does not establish how an evaluator combines the two perspectives.

Place the constructed observation in the `observations` array of the complete request envelope above. Preserve the real recorded outcome separately in your application record when the continuation is an estimated target.

### Satisfy the fitting prerequisites

| Requirement | What to do | Observed refusal |
| - | - | - |
| Fitted reference for unfinished successors | Fit on provided targets or observed outcomes, install the initial model, and record its SHA before continuation fitting | `nonterminal continuation targets require a fitted reference model` |
| Provided or outcome evidence in both partitions | Retain such evidence in both the fitting and validation partitions of the continuation fit | `continuation training requires provided or outcome evidence in both fitting and validation partitions` |
| Successor work within the per-fit limit | Count the successor workload across the selected observations and reduce it if the fit exceeds its limit | `continuation target inference exceeds the per-fit successor limit` |

Each refusal above was returned as HTTP `422`. The aggregate per-fit successor cap is separate from the schema limit of 256 successors per observation. Its exact value, whether terminal successors count toward it, and a route for inspecting it are not established by the available contract. Do not infer a supported aggregate limit from the size of one successful request. When reducing or sampling comparison groups, preserve the evidence and group coverage required in both partitions.

## Declare comparisons between alternatives

Rows sharing `metadata.comparison_group` belong to the same comparison group in the observed graph workflow. A continuation's `successors` array does not create a comparison group by itself.

Use one observation per alternative child of a recorded parent state. Each child's row describes that child and carries its own continuation over that child's successors. Give the sibling rows the same parent comparison identifier, while preserving distinct `record_id` values.

```json Sibling identity fragments theme={null}
[
  {
    "record_id": "episode-001-step-004-child-a-v1",
    "episode_id": "episode-001",
    "step": 5,
    "metadata": { "comparison_group": "episode-001-step-004" }
  },
  {
    "record_id": "episode-001-step-004-child-b-v1",
    "episode_id": "episode-001",
    "step": 5,
    "metadata": { "comparison_group": "episode-001-step-004" }
  }
]
```

These fragments show identity and grouping only. Each real row also needs the child's state and one supervision source. Keep the group's target values in the same viewpoint so their differences have a consistent meaning.

Comparison training requires groups in both fitting and validation partitions. Set a positive `comparison_weight` to add the comparison contribution; its default is `0`. A positive weight does not create missing groups. The [training guide](https://docs.reilabs.org/docs/neuroadapt/value-training.md) explains the options and report fields.

The checked arrangement used continuation supervision for sibling rows. Mixed `target`, `outcome`, and `continuation` supervision within one group has not been characterized by these checks.

## Keep a blended target explicit

The [coupled learning and planning method](https://reilabs.org/blog/coupled-learning-and-planning) describes targets of the form `y = λu + (1 − λ)z̄`, where `u` is a planning assessment and `z̄` is a discounted observed outcome.

If your application computes this scalar, send the result as `target`. It then enters as a provided target, rather than a continuation that the server refreshes from successors. Retain the observed outcome, assessment, blend settings, and reference-model identity in the application record so you can reconstruct the calculation.

The inspected interface does not expose a λ field. Matching `episode_id` and `step` on separate rows does not establish an automatic blend. Neither `continuation.discount` nor `neutral` is documented as a λ control. Keeping outcome rows and continuation rows in the same fit preserves both kinds of examples; it does not by itself reproduce a per-row blended target.

## Retry identical observations

`value/observe` uses `record_id` to recognize identical replays. An accepted replay contributes to `duplicates`; reusing the ID with changed content returns HTTP `409`.

After an uncertain upload, resend the identical records with their original IDs, then check that `accepted + duplicates` accounts for every submitted row. Treat a changed observation as a distinct record with a new ID. Do not change a target under an existing ID and expect the request to update it in place.

This rule belongs to value observations. Domain feedback has a different retry contract; see [operations and retries](https://docs.reilabs.org/docs/neuroadapt/operational-behavior-and-retries.md).

## Verify admission and target refresh

The observation response reports `target_sources.model_continuation` and `target_sources.provided_or_observed`. These counters identify admitted source types. Inspect the subsequent fit through `value/state` and `training.report.target_refresh` to verify the target work used by training.

| Report field | What to check |
| - | - |
| `target_semantics` | Continuation refresh reports `model_based_continuation_not_observed_reward` |
| `continuation_records` | Greater than zero when continuation records were used |
| `modeled_successors` | Work scored with the reference model |
| `declared_terminal_successors` | Successors supplied with terminal values |
| `reference_model_sha256` | Matches the reference you intended the fit to use |
| `materialized_targets_sha256` | Identifies the targets constructed for that fit |

An accepted upload alone does not show that a later training scope included its rows. Check target refresh, [supervision scope](https://docs.reilabs.org/docs/neuroadapt/value-training.md#select-the-supervision-scope), and comparison coverage together.


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