Configure a Machina Domain

Configure a Domain to learn a bounded sequence of numeric controls. The examples below define the interface used by the acquisition and refinement guides. You need a Unit API Key and an application that can reset or observe an environment, execute bounded controls, and measure what happened. Start with execution patterns if you are still choosing the control interface.

This example	Contract
Input	Four measured state values and a two-coordinate goal
Output	Up to eight commands, each containing two control values
Execution	A fixed half-second hold per command; eight physical slots
Feedback	Measured completion after the attempt
First result	A configured trajectory Domain ready for `propose`

Match the controls to the executor

Define which values your application can measure, which controls it can execute together, and how long each command lasts. Set the dimensions and horizon from that interface. The two-actuator example below shows the API shapes; replace its coordinate meanings with your own measured contract.

Choose the API surface

What your application needs	Interface
Acquire a bounded numeric action sequence	`trajectory/configure` with `episode_credit`, then `propose` and `observe`
Select, shorten, or reorder acquired executions	`confirmed_execution` with `selection`, `deletion`, or `ordering`
Learn context-dependent offsets around an acquired base	`contextual_execution`, then candidate `evaluate` and comparison `observe`
Choose a named discrete policy after each observation	The separate Domain query and feedback workflow

After creating the Domain, configure its trajectory learner by sending the mechanism inside the config object to /trajectory/configure.

Connect to the API

https://rei-neuroadapt-api.reilabs.org/api/v1

Send Authorization: Bearer <Unit API Key> and Content-Type: application/json. Keep the key server-side. The bearer token determines the owner; omit body session_id and never send a trusted owner header to select a tenant.

Define the vector schema

Consider a planar platform with two continuous control coordinates. This small example has four state coordinates and up to eight commands. Replace these choices with your own measured interface.

Array	Index	Meaning	Example convention
`state`	0	Measured x position	Position divided by 1 metre
`state`	1	Measured y position	Position divided by 1 metre
`state`	2	Measured x velocity	Velocity divided by 1 metre/second
`state`	3	Measured y velocity	Velocity divided by 1 metre/second
`goal`	0	Desired x position	Same coordinates and scale as `state[0]`
`goal`	1	Desired y position	Same coordinates and scale as `state[1]`
Each action row	0	First actuator command	Normalized to `[-1, 1]`
Each action row	1	Second actuator command	Normalized to `[-1, 1]`

The goal specifies the desired state. goal_indices: [0, 1] maps the two goal coordinates into the state vector. Every index must be smaller than state_dimensions; the goal length must equal the number of goal indices. Keep names, units, ordering, scaling, and invalid-measurement rules in an application-owned manifest. The trajectory API receives numeric arrays; your manifest defines the physical meaning of each position. action_dimensions is the number of values applied together in one command. horizon limits the ordered command count. Their product gives the maximum number of scalar outputs in a proposal. A later retained sequence may be shorter than the acquisition horizon.

Separate API configuration from executor configuration

Native configuration	Application-owned settings
State/action dimensions, goal indices, logical horizon, mechanism, retention capacity, pending limit, seed, outcome mode	Coordinate meanings, sensor scale, physical action bounds, command duration, actuator decoder, reset logic, safety stops, padding, outcome calculation

For this example, the application holds each command for 0.5 seconds and uses a fixed eight-slot execution window. If structural deletion shortens the logical sequence, it appends neutral commands to the unused slots. That preserves the physical duration while the logical command list changes. Implement and version command_duration, action_bounds, and padding in your executor, outside the trajectory configuration body. A neutral command applies the declared neutral actuator input. The platform may continue moving under its existing velocity. For a concrete outcome contract, define completion as finishing within 0.05 metres of the goal with speed at most 0.1 metres/second. Assess it after the eight-slot window, or at a declared earlier task-terminal state. A safety stop sets completion to false. The acquisition reward and structural completion objective both use float(completed). These tolerances are example application settings; choose and keep fixed the values appropriate to your task.

Create and configure the Domain

Choose a fresh run-specific Domain ID. POST to https://rei-neuroadapt-api.reilabs.org/api/v1/domains:

{
  "domain_id": "control-example-UNIQUE-acquisition",
  "description": "Bounded two-actuator sequence acquisition"
}

Then POST {} to /domains/control-example-UNIQUE-acquisition/trajectory/state. Require status: "not_configured" before configuring a fresh trajectory learner. This check concerns trajectory state. Check the state of any other Domain mechanisms your workflow uses separately. POST to /domains/control-example-UNIQUE-acquisition/trajectory/configure, relative to the production base:

{
  "config": {
    "mechanism": "episode_credit",
    "state_dimensions": 4,
    "action_dimensions": 2,
    "goal_indices": [0, 1],
    "horizon": 8,
    "capacity": 128,
    "max_pending": 1,
    "seed": 1,
    "outcome_mode": "reward"
  }
}

The dimensions and resource settings above are an example profile. Choose them from the actual interface and the number of proposals your runner can execute and reconcile. Capacity limits retained records. Set the attempt budget in your runner. Start with one pending proposal while checking an adapter, then increase concurrency only when every returned decision can be matched to its measured execution.

Acquisition fields

Field	Required / schema default	Meaning and constraint
`mechanism`	Defaults to `episode_credit`	Set explicitly to identify the interface
`state_dimensions`	Required	Integer, 1–128; length of every state row
`action_dimensions`	Required	Integer, 1–32; length of every action row
`goal_indices`	Required	Nonempty integer indices into the state vector; validate their range locally
`horizon`	Required	Integer, 1–256; maximum logical sequence length
`capacity`	Default 128	Integer, 1–512; configured retention capacity
`max_pending`	Default 16	Integer, 1–64; example uses one outstanding proposal
`seed`	Default 0	Integer, 0–2,147,483,647; learner seed, separate from environment reset seeds
`outcome_mode`	Default `goal_error`	`goal_error` or `reward`; example supplies a measured higher-is-better reward

These limits come from the reference request schema. A deployed service can impose lower account or runtime limits. Read and save the resolved configuration; do not assume schema maxima are available capacity. For reward, explicitly return the application’s measured outcome after execution. Keep its direction and scale fixed. Using goal_error requires an adapter that implements the deployed goal-error contract.

Optional acquisition profile

The following optional settings control proposal edits and retention. Choose them for your measured feedback and execution contract:

{
  "coherent_edits": true,
  "global_recall": true,
  "executed_prefix_mutation": true,
  "progress_guided_mutation": true,
  "sequence_compaction": true,
  "outcome_tier_exploration": true,
  "retain_prefix_failures": false
}

Merge this configuration fragment into config before initial configuration. The minimal example leaves native defaults in place. Enable progress-related options only with a defined, measured per-command outcome stream; do not manufacture intermediate outcomes from the terminal value. Save the full resolved settings with the run.

Choose the feedback granularity

The example uses outcome_mode: "reward" and a binary completion measurement. You can define a more informative measured reward for your own task while keeping the same proposal and observation shapes.

Available measurement	Possible reward contract
Completion only	`0.0` or `1.0` after the attempt
Reliable task stages	A declared value for the stage actually reached
Physical error or progress	A fixed higher-is-better score derived from measured consequences

Keep the completion test separate from the learning score. Preserve score direction, scale, and assessment time within a learning run. If you change this example’s binary scorer, also change the binary validation in the acquisition loop. Supply step_outcomes only when you measure outcomes at each executed command.

Request helper

Shared Python request helper

The following helper uses the Python standard library. Set ADAPT1_API_KEY in the server process environment. All later snippets use these functions and the same PREFIX.

import json
import os
import uuid
from urllib.request import Request, urlopen

BASE = "https://rei-neuroadapt-api.reilabs.org/api/v1"
PREFIX = "control-" + uuid.uuid4().hex[:16]
ACQUISITION_DOMAIN = PREFIX + "-acquisition"

def post(path, body):
    encoded = json.dumps(body, allow_nan=False).encode("utf-8")
    if len(encoded) > 1024 * 1024:
        raise ValueError("Request exceeds the reference 1 MiB body limit")
    request = Request(
        BASE + path,
        data=encoded,
        method="POST",
        headers={
            "Authorization": "Bearer " + os.environ["ADAPT1_API_KEY"],
            "Content-Type": "application/json",
        },
    )
    # Deliberately no automatic mutation retry.
    with urlopen(request, timeout=180) as response:
        return json.load(response)

def trajectory(domain, operation, body=None):
    return post(
        f"/domains/{domain}/trajectory/{operation}",
        {} if body is None else body,
    )

def create_stage(domain, config):
    post("/domains", {"domain_id": domain})
    state = trajectory(domain, "state")
    if state.get("status") != "not_configured":
        raise RuntimeError("Expected a fresh trajectory learner")
    receipt = trajectory(domain, "configure", {"config": config})
    configured_state = trajectory(domain, "state")
    if configured_state.get("status") == "not_configured":
        raise RuntimeError("Trajectory configuration was not applied")
    return receipt, configured_state

Generate PREFIX once, then persist and reload it to resume. Regenerating it creates a new lineage. The helper sends HTTP requests. Your runner supplies execution scheduling and recovery. Add request-intent and response recording before a long run, as described in Retained use and recovery.

Check the configured interface

Read /trajectory/state and save the resolved mechanism and configuration with your executor manifest. Then make one measured attempt and confirm its observation acknowledgement before increasing the run budget. Check each mechanism your application will use: acquisition, one complete structural comparison, and contextual evaluation. For precision refinement, also check support for the optional context and search settings. Preserve rejected fields and their validation errors for diagnosis.

Choose the next guide

Acquire a sequence

Propose, execute, validate, and return actual trajectory observations.

Structural stages

Export acquired records and run selection, deletion, and ordering.

Contextual refinement

Configure contexts and evaluate candidate offsets around a retained base.

Retained use and recovery

Execute with learning stopped and reconcile interrupted operations.

Get started

Concepts

Guides

Planning

Discovery

Operations

API reference

Match the controls to the executor

Choose the API surface

Connect to the API

Define the vector schema

Separate API configuration from executor configuration

Create and configure the Domain

Acquisition fields

Optional acquisition profile

Choose the feedback granularity

Request helper

Check the configured interface

Choose the next guide

Acquire a sequence

Structural stages

Contextual refinement

Retained use and recovery

​Match the controls to the executor

​Choose the API surface

​Connect to the API

​Define the vector schema

​Separate API configuration from executor configuration

​Create and configure the Domain

​Acquisition fields

​Optional acquisition profile

​Choose the feedback granularity

​Request helper

​Check the configured interface

​Choose the next guide

Acquire a sequence

Structural stages

Contextual refinement

Retained use and recovery

Match the controls to the executor

Choose the API surface

Connect to the API

Define the vector schema

Separate API configuration from executor configuration

Create and configure the Domain

Acquisition fields

Optional acquisition profile

Choose the feedback granularity

Request helper

Check the configured interface

Choose the next guide