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

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

### Batch by serialized size and row count

Check both the number of rows and the size of the complete UTF-8 JSON body. A batch with fewer than 50 graph observations can still exceed the request-body limit. HTTP `413` has been observed for bodies near 1 MiB. The helper below uses a 900 KiB client margin, not a declared service quota.

This helper builds observation-only request bodies. It preserves each row and its identity, rejects a row that cannot fit by itself, and leaves network retries to the caller.

```python Size observation uploads theme={null}
import json


def observation_bodies(observations, max_body_bytes=900 * 1024):
    def encode(rows):
        return json.dumps(
            {"session_id": "ignored", "observations": rows},
            separators=(",", ":"),
            ensure_ascii=False,
            allow_nan=False,
        ).encode("utf-8")

    batch = []
    for row in observations:
        if len(encode([row])) > max_body_bytes:
            raise ValueError(
                f"Observation {row['record_id']} exceeds the client body limit"
            )
        proposed = batch + [row]
        if batch and (len(proposed) > 50 or len(encode(proposed)) > max_body_bytes):
            yield encode(batch)
            batch = [row]
        else:
            batch = proposed
    if batch:
        yield encode(batch)
```

Send the returned bytes as the request body with `Content-Type: application/json`; re-serializing them differently can change the size. If you also send `application_outcomes`, include that array in the byte calculation and enforce its separate 50-row limit. After each upload, check `accepted + duplicates` against that batch's observation count. Preserve the original rows for [identical retries](#retry-identical-observations).

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

### Verify projected inputs

Verify numeric field placement before collecting a larger dataset. Numeric state values supplied only in `conditions` have produced `training.reason: collapsed_predictions` with `projected`. Compare separate variants of `conditions`, `context`, and `policy_features` to identify which maps supply useful inputs.

Use a small diagnostic fit to check the encoding:

1. Keep the same states, targets, episode split, representation, and training options.
2. Test `conditions`, `context`, and `policy_features` separately. Give changed observations new `record_id` values and use `observation_ids` to select only that variant's records. Set `install: false` and `options.warm_start: false` for independent diagnostic candidates.
3. Inspect the training status, candidate identity, prediction spread, and decisions on held-out states to verify that the encoding distinguishes states relevant to the task. If the fit is rejected, use its reported reason to diagnose the encoding.
4. Use the verified field placement, feature names, types, units, and representation flags in observations, continuation successors, and planner node descriptors.

Use the verified field placement for each feature. Confirm the exact numeric projection mapping and rejection check against your deployment's contract. See [training-state diagnostics](https://docs.reilabs.org/docs/neuroadapt/value-training.md#inspect-training-state) for the reported fields.

### Reuse one state encoding across calls

Build the state descriptor once in your application and reuse the same encoder for every value request. Keep feature names, units, object identities, relations, and representation flags consistent. Each successor and planner node must describe its own state using that encoder.

| Operation | Place the encoded state fields here | Add separately |
| - | - | - |
| Observe a labelled state | `observations[i]` | `record_id`, `episode_id`, `step`, and one supervision source |
| Predict a value | `inputs[i]` | Request-level model source and expected model hash |
| Supply a continuation alternative | `observations[i].continuation.successors[j]` | Exact `terminal_value` only when that successor is terminal |
| Plan over states | `root` and the relevant `nodes[i]` descriptor | Planning identity, turn perspective, and legal children required by the [planning contract](https://docs.reilabs.org/docs/planning/api.md) |

The shared value descriptor can contain `objects`, `relations`, `conditions`, `context`, `policy_features`, `include_positions`, and `include_moments`. Add observation IDs, metadata, and supervision separately when constructing an observation row. Use this mapping with the verified `projected` feature placement described above.

### Start from a recorded input shape

The constructors below show a numeric `projected`/`mlp_v2` input using `policy_features`, and an `object_graph`/`object_value` input using object/relation descriptors with numeric `conditions`. Supply your application's observed features and graph, then add supervision when constructing the observation rows.

```python Shared input constructors theme={null}
from copy import deepcopy


def numeric_input(features):
    return {"policy_features": deepcopy(features)}


def graph_input(objects, relations, conditions):
    return {
        "objects": deepcopy(objects),
        "relations": deepcopy(relations),
        "conditions": deepcopy(conditions),
        "policy_features": {},
        "include_positions": True,
        "include_moments": False,
    }
```

Call the same constructor for a recorded state, a prediction input, and each generated successor. Add the observation or planning fields from the table above around that descriptor. Start with the numeric example's placement and confirm the handling of each combination of `conditions`, `context`, and `policy_features` you use against your deployment's contract.

### Check representation capacity before a large upload

Use a diagnostic fit with representative input sizes before collecting a full dataset. Larger object-graph inputs have produced a vocabulary-limit refusal with `projected`. The numerical vocabulary cap and its counting rule require confirmation from your deployment's contract.

Keep the response reason and the encoding that produced it. If you change representation or reduce the encoded vocabulary, make that an explicit input-design change and repeat the prediction checks. Check request size, row count, and the fit's vocabulary requirement separately. See [compatible training setups](https://docs.reilabs.org/docs/neuroadapt/value-training.md#choose-a-compatible-training-setup).

### 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. Confirm how your evaluator combines the two perspectives before using that option.

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`. Count successors across the complete observation snapshot selected for a fit, recording terminal and nonterminal counts separately. This workload is defined by the fit's selected observations, independently of upload batch size. To reduce it, choose an explicit set of `observation_ids` and preserve outcome evidence and complete comparison groups in both partitions. The aggregate per-fit successor cap is separate from the schema limit of 256 successors per observation. Confirm its exact value, treatment of terminal successors, and inspection route against your deployment's contract.

## Declare comparisons between alternatives

Use `metadata.comparison_group` to group related observation rows in the graph workflow. Use each row's `continuation.successors` to supply alternatives for that row's target.

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.

Declare comparison groups in both fitting and validation partitions, then set a positive `comparison_weight` to add their contribution. The default weight of `0` disables the comparison contribution. The [training guide](https://docs.reilabs.org/docs/neuroadapt/value-training.md) explains the options and report fields.

This example uses continuation supervision for sibling rows. Confirm support for mixed `target`, `outcome`, and `continuation` supervision before combining them within one group.

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

For a per-row blend, choose λ in your application, compute `y = λu + (1 − λ)z̄` from the planning assessment and discounted observed outcome, and submit `y` as `target`. Preserve the observed outcome, planning assessment, and blend settings alongside it. `continuation.discount` and `neutral` control continuation target construction. Outcome rows and continuation rows supplied separately remain separate examples in the fit.

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

Check target refresh, [supervision scope](https://docs.reilabs.org/docs/neuroadapt/value-training.md#select-the-supervision-scope), and comparison coverage together to confirm which admitted rows and comparisons participated in the fit.


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