Select, reduce, and order executions

Use confirmed_execution to test changes to executions Adapt-1 has already acquired. Your application runs the returned candidates on repeatable contexts; Adapt-1 uses their measured objectives to retain a selected execution.

Intervention	Question
`selection`	Which acquired execution works across the supplied contexts?
`deletion`	Can commands or spans be removed while preserving the objective?
`ordering`	Does changing the order of control changes improve execution?

Each intervention has its own Domain in this example, so its input, comparisons, and selected result remain inspectable. Use the shared request helper. This guide continues the two-axis example in Configuration. It uses the same post, trajectory, and create_stage helpers, ACQUISITION_DOMAIN, and PREFIX. The application observes [x, y, vx, vy], accepts two normalized command values in [-1, 1], and holds each command for 0.5 seconds.

Export the acquired executions

Finish pending acquisition observations and stop acquisition writes before exporting. Retrieve every page, retain the API-generated record IDs, and carry the returned incumbent_id into the next configuration.

def export_executions(domain):
    records = []
    offset = 0
    expected_total = None
    incumbent_id = None

    while True:
        page = trajectory(domain, "records", {
            "best_only": True,
            "offset": offset,
            "limit": 64,
        })
        if expected_total is None:
            expected_total = page["total"]
            incumbent_id = page["incumbent_id"]
        elif (page["total"] != expected_total
              or page["incumbent_id"] != incumbent_id):
            raise RuntimeError("Acquisition changed during export; export again.")

        batch = page["records"]
        records.extend(batch)
        offset += len(batch)
        if offset == expected_total:
            break
        if not batch or offset > expected_total:
            raise RuntimeError("Unexpected records pagination.")

    if not 1 <= len(records) <= 512:
        raise RuntimeError("A structural stage needs 1–512 executions.")
    ids = [record["id"] for record in records]
    if len(set(ids)) != len(ids) or incumbent_id not in ids:
        raise RuntimeError("Export is missing unique IDs or its incumbent.")

    records.sort(key=lambda record: record["id"])
    return records, incumbent_id


records, incumbent_id = export_executions(ACQUISITION_DOMAIN)

The export response fields used here are records, total, and incumbent_id. Each execution carries id, actions, initial_state, and its initial measurement validity (initial_valid). Preserve these fields during transfer. Do not replace the returned IDs with array positions or manufacture a new incumbent.

Execution record field	Contract
`id`	Required nonnegative integer.
`actions`	Required numeric matrix. The generic record schema allows 1–257 rows and 1–128 values per row; the example’s action contract is stricter: at most 8 rows, exactly 2 values per row.
`initial_state`	Required numeric vector with 1–128 values; exactly 4 for this example.
`initial_valid`	Boolean; defaults to `true` when omitted. Preserve the exported value.

These later Domains start with the acquired executions explicitly transferred into them. Create a separate Domain for each intervention so that each stage’s configuration and selected result remain inspectable.

Configure a structural stage

Configuration field	Contract
`mechanism`	Required: `"confirmed_execution"`.
`executions`	Required: 1–512 execution records.
`incumbent_id`	Required: nonnegative integer identifying the current execution among the supplied records.
`intervention`	`"selection"`, `"deletion"`, or `"ordering"`; default `"selection"`.
`command_budget`	Integer from 1 to 256; default 256. This example uses 8.
`objective_names`	Required: 1–8 nonblank names, each at most 128 characters. Order defines the meaning of each feedback objective.
`max_contexts`	Integer from 1 to 64; default 64.

For each intervention, execute the returned candidates and report their outcomes before accepting the stage’s selected execution. Use the complete returned action matrix, including any row-count change produced by ordering. Preserve the declared command budget, duration, and padding rule while checking the returned shape. Count the returned candidates before scheduling the comparison. Each nomination or confirmation request needs all of its candidate/context executions; a fixed budget chosen before proposal generation may be too small. Carry the service’s selected execution into the next stage even when it retains the incumbent.

def configure_structural_stage(domain, intervention, records, incumbent_id):
    create_stage(domain, {
        "mechanism": "confirmed_execution",
        "executions": records,
        "incumbent_id": incumbent_id,
        "intervention": intervention,
        "command_budget": 8,
        "objective_names": ["completion"],
        "max_contexts": 4,
    })

Structural configuration receives the acquired execution records. Apply the same action width, adapter, and bounds used during acquisition.

Make contexts repeatable

Your application maps each context_id to a reproducible scenario, including its initial position, velocity, target, and relevant environment randomness. Reset that scenario before every candidate execution. Implement reset_from_context_id and the returned environment object’s methods in your simulator or device adapter. Use the same timing convention across acquisition and structural comparisons. In this example, each trial has eight command slots, and a shorter candidate spends the remaining slots under the declared neutral command.

import math


def reset_from_context_id(context_id):
    # Load your saved scenario specification, reset the environment, and return
    # an object implementing hold_command(command, duration) and completion().
    raise NotImplementedError("Connect this to your environment reset.")


def execute_candidate(execution, context_id):
    actions = execution["actions"]
    if not 1 <= len(actions) <= 8:
        raise ValueError("Candidate exceeds the configured command budget.")
    for action in actions:
        if len(action) != 2 or any(
            not math.isfinite(value) or not -1 <= value <= 1
            for value in action
        ):
            raise ValueError("Candidate violates the two-axis action contract.")

    env = reset_from_context_id(context_id)
    for action in actions:
        env.hold_command(action, duration=0.5)
    for _ in range(8 - len(actions)):
        env.hold_command([0.0, 0.0], duration=0.5)

    # completion() uses the shared distance, speed, and safety-stop contract.
    # One value, in the same order as objective_names=["completion"].
    return [float(env.completion())]

For hardware, the adapter also owns fixed command limits and termination handling. Apply the same declared rules to every candidate. Preserve the declared observation window when a command is removed. Use the completion definition from Schemas and configuration: distance at most 0.05 metres and speed at most 0.1 metres/second at the declared assessment time, with safety stops returning False. hold_command must stop physical actuation after a terminal event; further calls must not restart the device or simulator.

Run nomination and confirmation

Use one set of contexts for nomination, then a separate set for confirmation. For each proposal, evaluate every returned candidate on every supplied context. The candidate count can change between proposals; derive it from the response each time.

def compare_candidates(domain, request_id, context_ids, reference_state):
    if not 1 <= len(context_ids) <= 4:
        raise ValueError("Use 1–4 contexts for this configuration.")
    if len(set(context_ids)) != len(context_ids):
        raise ValueError("Context IDs must be unique within a comparison.")

    proposal = trajectory(domain, "propose", {
        "state": reference_state,
        "goal": [0.0],
        "mode": "explore",
        "request_id": request_id,
        "context_ids": context_ids,
    })
    candidates = proposal["candidates"]
    if not candidates:
        raise RuntimeError("Proposal returned no candidates.")

    outcomes = []
    for candidate_index, candidate in enumerate(candidates):
        for context_id in context_ids:
            objectives = execute_candidate(candidate["execution"], context_id)
            outcomes.append({
                "candidate_index": candidate_index,
                "context_id": context_id,
                "objectives": objectives,
            })

    return trajectory(domain, "observe", {
        "decision_id": proposal["decision_id"],
        "outcomes": outcomes,
    })

The shared propose request requires state and goal. For these structural comparisons, this example sends an exported execution’s initial_state and the placeholder goal [0.0]; measured objectives supply the comparison outcome. Each reset context supplies the environment’s actual target. request_id labels the proposal for application tracking. Complete the first proposal’s observation before requesting the confirmation comparison. Use candidate_index for the position in the current proposal’s candidates array. Execution record id identifies the retained execution. Attach the returned decision_id to the complete candidate/context result batch. Each outcome requires candidate_index (integer, 0–4095), context_id (a nonblank string of at most 128 characters), and objectives (a numeric vector). Send one objective per configured name, in that exact order. The request schema allows 1–32768 outcome rows; numeric values must be finite and within [-1e12, 1e12]. The single completion objective in this example is 0.0 or 1.0. If execution is interrupted, preserve the proposal and measurements so that you can finish the batch. If you abandon it, cancel the pending decision using trajectory(domain, "cancel", {"decision_id": decision_id}); cancellation supplies no learning outcome.

Carry the selected execution into the next stage

Register the context IDs below in your application before running this loop. Each ID must resolve to its own saved scenario. The nomination and confirmation sets are disjoint, and the next intervention starts in a new Domain.

structural_domains = {}

for intervention in ("selection", "deletion", "ordering"):
    domain = f"{PREFIX}-{intervention}"
    structural_domains[intervention] = domain
    configure_structural_stage(domain, intervention, records, incumbent_id)

    for phase in ("nomination", "confirmation"):
        context_ids = [f"{intervention}-{phase}-{i}" for i in range(4)]
        compare_candidates(
            domain=domain,
            request_id=f"{phase}-v1",
            context_ids=context_ids,
            reference_state=records[0]["initial_state"],
        )

    stage_state = trajectory(domain, "state", {})
    selected = stage_state["selected_execution"]
    if not selected:
        raise RuntimeError("Stage did not return a selected execution.")
    records = [selected]
    incumbent_id = selected["id"]

base_execution = records[0]

Transfer Adapt-1’s selected_execution unchanged and preserve it as base_execution for Contextual refinement.

Keep a useful result even when a stage makes no change

A confirmed stage may return the same execution it received. Keep that native result and move on according to your run plan. A shorter sequence is useful only if it preserves the measured task behavior under the declared timing rules. Reconcile pending work and seal the acquired source before these comparisons. If you later add acquisition and change that source, create a new downstream lineage from the new export. Preserve the earlier selected base and refinement state for comparison. Count the actual work from the returned candidates multiplied by the supplied contexts. Selection, reduction, ordering, and later refinement all execute the environment; they are additional learning work beyond initial acquisition.

Get started

Concepts

Guides

Planning

Discovery

Operations

API reference

Export the acquired executions

Configure a structural stage

Make contexts repeatable

Run nomination and confirmation

Carry the selected execution into the next stage

Keep a useful result even when a stage makes no change

​Export the acquired executions

​Configure a structural stage

​Make contexts repeatable

​Run nomination and confirmation

​Carry the selected execution into the next stage

​Keep a useful result even when a stage makes no change

Export the acquired executions

Configure a structural stage

Make contexts repeatable

Run nomination and confirmation

Carry the selected execution into the next stage

Keep a useful result even when a stage makes no change