Refine a sequence for its context

Use contextual_execution to adapt an acquired sequence to the current observation. The mechanism learns offsets for the base’s command coordinates; your application combines those offsets with the preserved base before execution. Start with the selected execution from Structural stages and the shared Python helper.

During learning	During retained use
Propose candidates and execute each on repeatable contexts	Send the current context to `evaluate`
Return one complete measured comparison	Compose returned offsets with the same base
Retain the resulting correction state	Execute without a training observation

During frozen use, evaluate computes offsets from the current observation using unchanged learned state.

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.

Value	Shape	Meaning
`selected_base.actions`	`H × 2`	Selected sequence returned as `selected_execution` by the preceding structural stage
One context	`4`	`[target_dx, target_dy, initial_vx, initial_vy]` in a fixed application encoding
`contexts`	`N × 4`	Contexts measured at real training resets
Evaluated `offsets`	`H × 2`	Additive corrections in the same normalized command units as the base
Executed command list	`8 × 2`, unless the environment terminates	Corrected base followed by neutral `[0, 0]` commands under this application’s fixed execution rule

H is the selected base length. Apply corrections to those H commands, then append neutral padding in the executor. Keep this rule identical during comparisons and retained use. Here target_dx = goal_x - initial_x and target_dy = goal_y - initial_y. Relative position lets the correction distinguish starts at different locations. This encoding suits the example’s planar relative-position task; include absolute position, obstacles, or other measured state if your environment makes them relevant. 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, and your application preserves the base sequence. Changing the base or its command count changes what the offsets mean.

Configure the refinement Domain

Use PREFIX, 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:

Hook	Required behavior
`registered_context_ids(partition)`	Return the IDs of actual saved scenarios in the requested application-owned partition. Each ID maps to reset conditions, including the initial state, target and environment randomness.
`reset_and_measure(context_id)`	Reset the registered scenario and return its measured `state` and requested `goal` using the acquisition adapter. Reject invalid reset measurements before constructing a refinement context.
`execute_actions(actions, command_seconds=0.5)`	Execute the supplied command list from the current reset state and return measured `completion` and `progress` using the definition below. Preserve the same limits and termination rules used by earlier stages.

Register separate refinement-support, refinement-training and evaluation partitions in your scenario registry. Use support vectors to configure the context representation and training scenarios for candidate comparisons. Reserve evaluation scenarios until retained evaluation. The code below constructs support vectors from real resets using the same coordinate scales as acquisition. If you need the optional precision settings, choose the configuration and executor settings before running create_stage.

import math

def reset_context(context_id):
    initial = reset_and_measure(context_id)
    if initial["initial_valid"] is not True:
        raise ValueError("Refinement requires a valid measured reset context")
    state, goal = initial["state"], initial["goal"]
    assert len(state) == 4 and len(goal) == 2
    context = [goal[0] - state[0], goal[1] - state[1],
               state[2], state[3]]
    assert all(math.isfinite(x) and abs(x) <= 1e12 for x in context)
    return context

support_context_ids = registered_context_ids("refinement-support")
assert 1 <= len(support_context_ids) <= 257
assert len(support_context_ids) == len(set(support_context_ids))
training_contexts = [reset_context(cid) for cid in support_context_ids]

structural_domain = structural_domains["ordering"]
selected_base = trajectory(structural_domain, "state")["selected_execution"]
base_actions = selected_base["actions"]
H = len(base_actions)

assert 1 <= H <= 8
assert all(len(row) == 2 for row in base_actions)
assert all(math.isfinite(x) and -1 <= x <= 1
           for row in base_actions for x in row)
assert 1 <= len(training_contexts) <= 257
assert all(len(row) == 4 for row in training_contexts)
assert all(math.isfinite(x) for row in training_contexts for x in row)

refinement_domain = PREFIX + "-refinement"
config = {
    "mechanism": "contextual_execution",
    "horizon": H,
    "action_dimensions": 2,
    "contexts": training_contexts,
    "objective_names": ["completion", "progress"],
    "candidate_count": 8,
    "max_contexts": 64,
    "seed": 18,
    "radius": 0.08,
    "retained_variance": 0.99,
    "contextual": True,
    "action_trust_region": True,
}
create_stage(refinement_domain, config)

The helper sends POST /domains/{domain_id}/trajectory/configure with the JSON body {"config": config} after creating a fresh Domain and checking its trajectory state.

Configuration field	Required or default	Constraint
`mechanism`	Required	`"contextual_execution"`
`horizon`	Required	Integer from `1` to `256`; use the base command count
`action_dimensions`	Required	Integer from `1` to `32`; use the base row width
`contexts`	Required	`1–257` numeric rows, each `1–128` coordinates; enforce one consistent width
`objective_names`	Required	`1–8` nonempty names; preserve their order in feedback
`candidate_count`	Default `8`	Integer from `2` to `16`
`max_contexts`	Default `64`	Integer from `2` to `64`
`seed`	Default `0`	Integer from `0` to `2147483647`
`radius`	Default `0.08`	Positive numeric value
`retained_variance`	Default `0.99`	Positive numeric value
`contextual`	Default `true`	Boolean
`action_trust_region`	Default `false`	Boolean; this example explicitly enables it

The contexts vectors supplied at configuration establish the numeric context representation. In the comparison loop, your adapter maps each context_id to repeatable reset conditions and measures the resulting context for evaluate.

Precision across operating conditions

When an acquired sequence needs different corrections across a broad range of observations, consider the following optional configuration. Merge this fragment into config before the first create_stage call, with a client that supports context-bound response guidance.

Optional precision configuration fragment

{
  "normalize_context": true,
  "context_basis": "quadratic",
  "retained_variance": 1.0,
  "response_guidance": true,
  "action_trust_region": true,
  "objective_names": ["quality"]
}

Setting	Purpose
`normalize_context`	Normalize numeric context scales before forming the correction
`context_basis: "quadratic"`	Allow nonlinear context-dependent corrections; the default basis is `linear`
`retained_variance: 1.0`	Retain the full context variance
`response_guidance`	Add candidate proposals informed by measured execution responses
`action_trust_region` and `radius`	Constrain candidate search; verify the resulting controls after decoding

Normalization and response guidance are optional and default off. Response-guided proposals still require execution on discovery and confirmation contexts before an update is retained. Context binding: response guidance requires context_observations on propose, binding every training context ID to its measured numeric observation. Implement this field using the proposal schema supported by your deployment, and verify that your client forwards it with the configuration options above. The basic comparison example below supports the default search. Extend its proposal body with the required context bindings before enabling response guidance.

Pair the search radius with the decoder

The executor composes corrections as clip(base + offset_scale * offset, -1, 1). The example uses a scale of 1.0. Choose the search radius and residual scale together so candidates can make useful changes within the action limits. Set the scale in your executor and radius in the trajectory configuration. Set both before training and preserve them for candidate and retained evaluation. Changing the scale changes the reachable corrections within the decoded control bounds of [-1, 1]. Record the proposed offsets and decoded controls to check the effect of the search radius, including how often clipping collapses distinct proposals to the same command. Keep the base, scale, and clipping rule with the saved refinement state.

Use a measured precision objective

When an application measures continuous error, a smooth quality score can distinguish partial improvements. Keep the actual completion test separate. For example:

def error_quality(error, measurement_valid, scale):
    if not math.isfinite(scale) or scale <= 0:
        raise ValueError("Choose a positive, fixed quality scale")
    if not measurement_valid:
        return 0.0
    if not math.isfinite(error) or error < 0:
        raise ValueError("Expected a measured nonnegative error")
    return 1.0 / (1.0 + (error / scale) ** 2)

Keep scale fixed in the application’s scoring contract. This example assigns zero quality to an executed attempt without a valid error measurement; record the reason separately. With objective_names: ["quality"], have execute_actions return a measured quality value alongside the task’s actual completion result. The comparison loop reads the configured objective names, producing one quality value per outcome row for this configuration. Use representative operating conditions together in each comparison, with separate discovery and confirmation subsets. Budget physical executions as returned candidates × contexts per update. Choose stopping from development checks; keep final evaluation contexts unused until learning stops.

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. Keep this batch within the training partition.

context_ids = registered_context_ids("refinement-training")
assert 2 <= len(context_ids) <= config["max_contexts"]
assert len(context_ids) == len(set(context_ids))
assert set(context_ids).isdisjoint(support_context_ids)
assert all(isinstance(cid, str) and cid.strip() and len(cid) <= 128
           for cid in context_ids)
discovery_ids = context_ids[::2]
confirmation_ids = context_ids[1::2]
assert discovery_ids and confirmation_ids

proposal = trajectory(refinement_domain, "propose", {
    "state": training_contexts[0],
    "goal": [0.0],
    "mode": "explore",
    "request_id": PREFIX + "-refinement-update-0",
    "context_ids": context_ids,
    "discovery_context_ids": discovery_ids,
})
decision_id = proposal["decision_id"]
candidate_count = len(proposal["candidates"])
assert 2 <= candidate_count <= 16

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. Send each execution’s actual context to evaluate and its measured objectives to observe. 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 the reset_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. In this example, 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.

def measure_refinement_outcome(initial_state, final_state, goal, safety_stopped):
    assert len(initial_state) == len(final_state) == 4 and len(goal) == 2
    assert all(math.isfinite(x) for row in (initial_state, final_state, goal)
               for x in row)
    initial_distance = math.hypot(initial_state[0] - goal[0],
                                  initial_state[1] - goal[1])
    final_distance = math.hypot(final_state[0] - goal[0],
                                final_state[1] - goal[1])
    final_speed = math.hypot(final_state[2], final_state[3])
    completion = (not safety_stopped
                  and final_distance <= 0.05 and final_speed <= 0.1)
    if initial_distance > 0:
        progress = max(0.0, min(1.0, 1.0 - final_distance / initial_distance))
    else:
        progress = float(final_distance == 0.0)
    return {"completion": float(completion), "progress": progress}

Have execute_actions return this result using its measured trace and actual goal. This example adds progress as an objective for the contextual-refinement stage. Reset separately for every candidate/context pair. Candidates must face the same reset conditions and scoring rules.

# Executor setting: choose once before training and retain with the base.
# Tune alongside the configured search radius; the example uses 1.0.
OFFSET_SCALE = 1.0

def compose_actions(offsets):
    if len(offsets) != H or any(len(row) != 2 for row in offsets):
        raise ValueError("offsets must match the selected base shape")
    if not all(math.isfinite(x) for row in offsets for x in row):
        raise ValueError("offsets must contain finite numbers")
    corrected = [
        [max(-1.0, min(1.0, base + OFFSET_SCALE * delta))
         for base, delta in zip(base_row, offset_row)]
        for base_row, offset_row in zip(base_actions, offsets)
    ]
    return corrected + [[0.0, 0.0] for _ in range(8 - H)]

outcomes = []
for candidate_index in range(candidate_count):
    for context_id in context_ids:
        context = reset_context(context_id)
        assert len(context) == 4
        assert all(math.isfinite(x) for x in context)
        evaluated = trajectory(refinement_domain, "evaluate", {
            "context": context,
            "candidate_index": candidate_index,
            "decision_id": decision_id,
        })
        actions = compose_actions(evaluated["offsets"])
        result = execute_actions(actions, command_seconds=0.5)
        objectives = [float(result[name]) for name in config["objective_names"]]
        assert all(math.isfinite(value) and 0 <= value <= 1 for value in objectives)
        if "completion" in config["objective_names"]:
            assert float(result["completion"]) in (0.0, 1.0)
        outcomes.append({
            "candidate_index": candidate_index,
            "context_id": context_id,
            "objectives": objectives,
        })

The evaluate request requires context. For a pending candidate, provide both candidate_index and decision_id. Read offsets from the response and add them to the saved base using the same action limits used in training. This example composes scaled offsets with the base and clips the resulting controls. If your adapter applies a coordinate transform, validate its inputs and preserve the transform and composition order through training and retained use.

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.

expected = {(i, cid) for i in range(candidate_count) for cid in context_ids}
actual = {(row["candidate_index"], row["context_id"]) for row in outcomes}
assert actual == expected and len(outcomes) == len(expected)
assert all(len(row["objectives"]) == len(config["objective_names"]) for row in outcomes)

observe_body = {"decision_id": decision_id, "outcomes": outcomes}
# The shared HTTP helper checks the serialized request against the 1 MiB limit.
observation = trajectory(refinement_domain, "observe", observe_body)

Each row uses candidate_index, context_id and objectives; the top-level body uses decision_id and outcomes. Keep objective values in the configured order. Record measured task failures as outcomes. Finish all scheduled executions before submitting the batch, or reconcile an interrupted decision through retained use and recovery. The request must satisfy both the schema’s 32768-row maximum and the route’s 1 MiB body 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. The following excerpts come from a recorded API interaction. They retain selected response fields, with the decision ID replaced by one consistent label. This comparison used eight candidates across 64 contexts, split equally between discovery and confirmation.

{
  "phase": "refinement",
  "status": "proposed",
  "learning": true,
  "decision_id": "decision-example-01",
  "objective_names": [
    "quality"
  ],
  "fingerprint": "e192d0a93897a973a00216f61104be41e12d5a47221b85de6f6308a8679087e8"
}

{
  "status": "learned",
  "decision_id": "decision-example-01",
  "executions": 512,
  "fingerprint": "9f83b7e5bb54c4a3d946c1748321943e6681531b8cda1f81c6b69f99070aede4",
  "update": {
    "version": 0,
    "nominee": 3,
    "selected": 3,
    "confirmation_gain": [
      0.0026429989307821256
    ],
    "scope": "empirical training confirmation, not statistical significance"
  }
}

The observation receipt covers 512 candidate/context executions. Candidate 3 was nominated on the discovery contexts and retained after confirmation. confirmation_gain contains one value because this comparison used one objective, quality. The fingerprint changed when the update was retained. The candidate index identifies a position within this proposal. Keep the same decision ID on candidate evaluations and the complete observation batch. Separate completed evaluations have compared an acquired base with its learned contextual correction on the same reserved conditions while learning was stopped. The corrections improved execution on unseen conditions and restored successful behavior after changes to the environment or actuator response. Follow-up runs reproduced the acquired behavior after a client reconnect, with unchanged learner fingerprints. These evaluations connect an accepted update to its effect on later execution.

Decide whether the correction helps

Use development comparisons to choose when to stop practice. Keep final evaluation contexts reserved until the policy is frozen. Compare the acquired base and contextual policy on the same cases, recording both repaired failures and lost successes. When context changes include different operating regimes, add the relevant measured variables and retain representative original conditions in practice when preservation matters. Create a new refinement lineage when the context encoding changes, because existing corrections depend on the original encoding.

Use the retained correction

After learning, omit both pending-candidate fields from evaluate to obtain the retained correction for a newly measured context.

held_out_context_ids = registered_context_ids("evaluation")
assert held_out_context_ids
assert set(held_out_context_ids).isdisjoint(support_context_ids)
assert set(held_out_context_ids).isdisjoint(context_ids)
held_out_context_id = held_out_context_ids[0]

before = trajectory(refinement_domain, "state")["fingerprint"]
context = reset_context(held_out_context_id)
retained = trajectory(refinement_domain, "evaluate", {"context": context})
result = execute_actions(compose_actions(retained["offsets"]),
                         command_seconds=0.5)
after = trajectory(refinement_domain, "state")["fingerprint"]
assert after == before

This path makes no propose or observe call. Save results in the application’s evaluation log. An unchanged refinement fingerprint verifies the exposed refinement state. Check the corresponding state for any other learning mechanisms used during evaluation. See Retained use and operational checks for reconnecting, preserving the base and adapter, and handling interrupted requests.

Get started

Concepts

Guides

Planning

Discovery

Operations

API reference

Keep the base and context contract together

Configure the refinement Domain

Precision across operating conditions

Pair the search radius with the decoder

Use a measured precision objective

Propose a comparison

Evaluate and execute every candidate on every context

Submit one complete measured comparison

Read a recorded refinement update

Decide whether the correction helps

Use the retained correction

​Keep the base and context contract together

​Configure the refinement Domain

​Precision across operating conditions

​Pair the search radius with the decoder

​Use a measured precision objective

​Propose a comparison

​Evaluate and execute every candidate on every context

​Submit one complete measured comparison

​Read a recorded refinement update

​Decide whether the correction helps

​Use the retained correction

Keep the base and context contract together

Configure the refinement Domain

Precision across operating conditions

Pair the search radius with the decoder

Use a measured precision objective

Propose a comparison

Evaluate and execute every candidate on every context

Submit one complete measured comparison

Read a recorded refinement update

Decide whether the correction helps

Use the retained correction