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
SendPOST /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
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. HTTP413 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
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 tovalue/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
Keeprecord_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 inconditions 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:
- Keep the same states, targets, episode split, representation, and training options.
- Test
conditions,context, andpolicy_featuresseparately. Give changed observations newrecord_idvalues and useobservation_idsto select only that variant’s records. Setinstall: falseandoptions.warm_start: falsefor independent diagnostic candidates. - 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.
- Use the verified field placement, feature names, types, units, and representation flags in observations, continuation successors, and planner node descriptors.
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 numericprojected/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
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 withprojected. 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 fullvalue/observe request envelope.
Provided-target observation fragment
Observed outcome
Anoutcome 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
[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 exactterminal_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
Usemetadata.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
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 formy = λ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 reportstarget_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.
