Configure a Machina Domain

Use this guide to turn a control task into an explicit numeric contract. You will create an owned Domain, configure its trajectory mechanism, and connect it to your executor.

These examples use the production API address and adapt the trajectory request schema and reference client. They have not been run against production. The response fields shown are those used by the client.

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.

Production URL and authentication

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.

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

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.

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.

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.

Get started

Build

Advanced Domain design

Operate

Modalities

Domains

Interval policies

State

System

Spatial Vision API

Choose the API surface

Production URL and authentication

Define the vector schema

Separate API configuration from executor configuration

Create and configure

Acquisition fields

Optional acquisition profile

Shared Python request helper

Choose the next guide

Acquire a sequence

Structural stages

Contextual refinement

Retained use and recovery

​Choose the API surface

​Production URL and authentication

​Define the vector schema

​Separate API configuration from executor configuration

​Create and configure

​Acquisition fields

​Optional acquisition profile

​Shared Python request helper

​Choose the next guide

Acquire a sequence

Structural stages

Contextual refinement

Retained use and recovery

Choose the API surface

Production URL and authentication

Define the vector schema

Separate API configuration from executor configuration

Create and configure

Acquisition fields

Optional acquisition profile

Shared Python request helper

Choose the next guide