contextual_execution after you have acquired and selected an execution. This mechanism learns an offset for each command coordinate as a function of the initial context. Your application keeps the selected base sequence and combines it with the returned offsets before execution.
The examples use the production base URL and helpers from Domain configuration. Their request contracts follow the available trajectory schemas and exercised client workflow; this guide does not report a production validation run.
Keep the base and context contract together
This example continues with a two-coordinate command interface. Both coordinates use normalized values in[-1, 1], and each command lasts 0.5 seconds. The selected base contains between one and eight commands.
H is the selected base length, not the original acquisition limit. Corrections cover those H commands. Neutral padding is an application rule applied afterward; it is not an API field or an extra learned command. Keep this rule identical during comparisons and retained use.
Keep the context coordinate order, normalization, base sequence, command decoder, command duration and padding rule together when saving the controller. The refinement Domain stores corrections; its configuration does not include the base sequence. Changing the base or its command count changes what the offsets mean.
Configure the refinement Domain
UsePREFIX, trajectory and create_stage from the configuration guide, structural_domains from Structural stages, and the application’s reset_and_measure adapter from Sequence acquisition.
Before running this guide, implement the following application hooks. These are not API operations:
Register separate
refinement-support, refinement-training and evaluation partitions in your scenario registry. The support vectors configure the context representation; the training scenarios supply paired comparisons; the evaluation scenarios remain unused until retained evaluation. The code below constructs support vectors from real resets using the same coordinate scales as acquisition.
POST /domains/{domain_id}/trajectory/configure with the JSON body {"config": config} after creating a fresh Domain and checking its trajectory state.
The context vectors supplied at configuration establish the numeric context representation.
context_ids used below are application identifiers for repeatable environment resets; they do not replace these vectors. The adapter owns the mapping from each identifier to its reset conditions.
Propose a comparison
Prepare a batch of repeatable training contexts. Use a discovery subset and a separate confirmation subset within the batch. The example assigns alternating IDs to discovery; the remaining IDs are the confirmation contexts. These are training comparisons, not the final held-out evaluation.state and goal are required by the shared proposal envelope. For this contextual comparison workflow, the client supplies one representative context as state and [0.0] as goal. Each execution’s actual context is sent to evaluate; the placeholder goal is not a target action or a success label.
Use a fresh request_id for each new comparison. Keep the returned decision_id with the batch until its measured outcomes are submitted. Candidate indices are zero-based positions in this proposal’s candidates array; do not reuse an index with another proposal’s decision ID.
Evaluate and execute every candidate on every context
Use thereset_context function defined above and your execute_actions adapter. In this example, measured completion is 0 or 1, and measured progress lies in [0, 1]; larger values mean better outcomes.
Completion uses the same rule as the preceding guides: after the eight command slots, or an earlier task termination, the measured planar distance to the goal is at most 0.05 metres and the measured speed is at most 0.1 metres/second. A safety stop sets completion to false. Progress measures the fraction of the initial target distance removed, clipped to [0, 1]. If the initial distance is exactly zero, progress is 1 only when the final distance is also zero; otherwise it is 0.
The application adapter computes these values from the actual initial and final measurements of each execution. The example’s position and velocity coordinates are divided by one metre and one metre/second respectively, so the numeric thresholds below use those units directly.
execute_actions return this result using its measured trace and actual goal. Progress is an additional contextual-refinement objective in this example; it does not change the preceding stages’ completion outcome or the command interface.
Reset separately for every candidate/context pair. Candidates must face the same reset conditions and scoring rules.
evaluate request requires context. For a pending candidate, provide both candidate_index and decision_id. The consumed response field is offsets; it is not a complete action sequence. Add it to the saved base and apply the same action limits used in training.
This example uses direct addition and clipping. If your established adapter instead performs geometric retargeting, keep its transform and composition order unchanged throughout training and retained use. Do not add a geometric transform to an interface whose action coordinates are nongeometric.
Submit one complete measured comparison
Feedback needs one row for every returned candidate and every requested context, including the confirmation contexts. Do not send only the winner or the discovery rows.candidate_index, context_id and objectives; the top-level body uses decision_id and outcomes. Keep objective values in the configured order. A simulator or task failure is a measured outcome; a missing execution is not. Finish all scheduled executions before submitting the batch, or resolve the interrupted decision without fabricating missing rows.
The request schema permits up to 32768 outcome rows, but the body must also fit the route’s 1 MiB limit. Size the candidate/context batch before running it. Do not divide one complete comparison into separate partial observe calls unless your deployed service explicitly supports that operation.
Use the retained correction
After learning, omit both pending-candidate fields fromevaluate. The client workflow uses this form to obtain the retained correction for a newly measured context.
propose or observe call. Save results in the application’s evaluation log. An unchanged refinement fingerprint checks the state exposed by that mechanism; it does not by itself certify every other learner in the application.
See Retained use and operational checks for reconnecting, preserving the base and adapter, and handling interrupted requests.