Configure a Machina Domain

Define state, goal, action, and timing contracts, then configure a numeric trajectory learner on the production API.

Create a Domain that learns a bounded sequence of numeric controls. This guide defines the interface once; the following guides use it to acquire a sequence, test revisions, and reuse a context-dependent correction.

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

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

Creating a Domain does not configure its trajectory learner. For the numeric pipeline, the mechanism lives inside the config object sent to /trajectory/configure. It does not belong inside DomainCreateRequest.learning, query_templates, or a generic /schemas request.

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 is a desired state, not a successful control sequence. 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; it cannot infer the physical meaning of an array position.

action_dimensions is the number of values applied together in one command. horizon limits the ordered command count. Their product is the maximum number of scalar outputs in a proposal, not the number of inputs or physical joints. 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.

command_duration, action_bounds, and padding are not fields in the referenced trajectory configuration schema. Do not insert them into the API body. Implement and version them in your executor. A neutral command means the declared neutral actuator input; it does not imply that the moving platform stops immediately.

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 does not count as completion. 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. The reference client requires status: "not_configured" before configuring a fresh trajectory learner. This check concerns trajectory state; it does not assert that every possible Domain subsystem is empty.

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, not universal tuning recommendations.

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, not acquisition episode budget
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. Use goal_error only with an adapter that implements the deployed goal-error contract; changing the string does not change your scorer automatically.

Optional acquisition profile

The reference sequence client explicitly enables the following options. They are supported field names from that configuration, not settings required for every task:

{
  "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
}

This is a configuration fragment to merge into config before initial configuration, not a separate endpoint or a live patch request. 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 performs HTTP requests; it is not a simulator, scheduler, durable journal, or retry manager. Add request-intent and response recording before using it for 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.

These production-address examples are adapted from the available trajectory request schemas and exercised client workflow. They have not been executed against production as part of this documentation update.

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

Use learned state without writes and reconcile interrupted operations.