Skip to main content
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.
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 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. 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.
Value observation request
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 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.
Size observation uploads
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.

Choose one supervision source

Each observation sent to value/observe carries exactly one of target, outcome, or continuation. Omit the other two fields. A row with conflicting or missing supervision rejects the whole observation batch with HTTP 422. The observed error is:

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

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 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. 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.
Shared input constructors
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.

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.
Provided-target observation fragment

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.
Observed-outcome observation fragment
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.
Continuation observation construction fragment
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:
Terminal successor construction fragment
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

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.
Sibling identity fragments
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 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 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.

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. Check target refresh, supervision scope, and comparison coverage together to confirm which admitted rows and comparisons participated in the fit.