> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reilabs.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Project Machina
> Examples of Adapt-1 control setups for sequence acquisition, chunked control, contextual correction, and persistent action.
export const MachinaLoop = () => {
const stages = [{
index: "01",
label: "Observe",
detail: "Record only the state available before action."
}, {
index: "02",
label: "Propose",
detail: "Adapt-1 returns a structured action, parameter, block, or sequence."
}, {
index: "03",
label: "Execute",
detail: "The application commits the selected operation."
}, {
index: "04",
label: "Measure",
detail: "The environment produces the next state and consequence."
}, {
index: "05",
label: "Retain or revise",
detail: "Eligible evidence changes what later calls can use."
}];
return
One observable learning loop
Action is learned through measured use
state → action → outcome
{stages.map(stage =>
{stage.index}
{stage.label}
{stage.detail}
)}
Preserve the pre-action observation, returned result, executed operation, measured consequence, feedback write, and learner-state change at every boundary.
;
};
**Project Machina** uses Adapt-1 to acquire and retain task-specific actions through interaction. Choose a setup below, define what your application can observe and execute, then connect measured outcomes to the learner.
Machina is not an LLM wrapper around a pretrained robot policy. The relevant output is a structured action, parameter, command block, or action sequence that the surrounding application executes. Generated language is not required in the control loop.
## Start with a working contract
The numeric trajectory guides use one two-actuator example throughout. They cover the production URL, authentication, exact configuration bodies, array shapes, execution hooks, and stage handoffs.
Define state, goal, action, timing, and outcome conventions. Create and configure a Domain.
Request a sequence and return the actual actions, measured states, and outcome.
Export acquired records, then select, shorten, and order executions.
Learn context-dependent offsets around the selected base.
Reconnect to retained state, run without learning, and handle interrupted requests.
## The operating boundary
Machina separates the learner from the system that senses and acts.
| Part | Responsibility |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Task contract** | Defines observable fields, permitted actions, outcome meaning, episode boundaries, and safety limits without encoding the withheld solution |
| **Adapter** | Converts simulator or sensor state into the declared input representation |
| **Core through Adapt-1** | Forms task-specific state and returns a structured action, parameter, sequence, prediction, or abstention |
| **Executor** | Applies the selected operation; it may include disclosed motor control, inverse kinematics, collision handling, or other task infrastructure |
| **Environment** | Produces the state transition, physics, termination, and measurable consequence |
| **Recorder** | Preserves the complete interaction and returns the declared consequence to Adapt-1 |
An authored controller is not automatically leakage. A fixed actuator or inverse-kinematics layer can execute a learned target when the example is about acquiring those targets. A supplied route is not appropriate when the withheld capability is route acquisition.
**Empty start** means no applicable task-specific learned state. It does not mean no simulator, observations, actuator interface, safety envelope, outcome definition, or execution controller.
## Choose the API path
Choose from the output your application needs to execute.
| Application output | Adapt-1 path |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| A numeric sequence or command block | [`episode_credit` acquisition](/docs/machina/acquisition): `propose`, execute, `observe` |
| A selected, shorter, or reordered acquired sequence | [`confirmed_execution` structural stages](/docs/machina/structural-stages) |
| Context-dependent offsets around a preserved base | [`contextual_execution` refinement](/docs/machina/refinement) |
| A named discrete action selected after each observation | The [Domain query and Sequential Discovery workflow](/docs/neuroadapt/discovery-sequential) |
| Retained numeric behavior without further learning | [Retained use](/docs/machina/retained-use) |
The numeric trajectory workflow uses `/trajectory/configure`, `/trajectory/propose`, and `/trajectory/observe`. Its payloads are separate from generic Domain query and feedback payloads. Use the schema for the mechanism you configure.
## Setup examples
### Example 1: Image-goal manipulation with a fixed executor
Use this pattern when the learner should acquire task-level movement while conventional software handles low-level actuation.
| Boundary | Example setup |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Task | Pick a visible object and place it in a visible receptacle whose layout changes |
| Observation | Object and receptacle positions from three calibrated cameras, plus end-effector pose, orientation, gripper state, and joint state |
| Adapt-1 output | A bounded sequence of continuous seven-dimensional end-effector position, orientation, and gripper targets |
| Supplied harness | Fixed color measurement, camera calibration, inverse kinematics, joint actuation, collision handling, and simulator dynamics |
| Consequence | Reached-stage information during acquisition and terminal placement outcome |
| State lifecycle | Empty acquisition state, followed by optional candidate selection, ordering, and contextual refinement |
The application loop is:
1. Reset to a new layout.
2. Record only the image-derived and proprioceptive state available before movement.
3. Ask Adapt-1 for the complete end-effector sequence.
4. Convert each target through fixed inverse kinematics and execute it.
5. Measure pickup and placement consequences.
6. Return the declared outcome and retain the resulting learner state.
The fixed executor may translate targets into joint motion, but it must not choose the task-solving target sequence. This keeps the withheld capability at the level Adapt-1 is meant to acquire.
Start with [Sequence acquisition](/docs/machina/acquisition), replacing the example's state and action dimensions with your measured interface. If actions are absolute spatial targets, define an explicit coordinate transform before reuse in a new layout; normalized actuator commands and absolute target coordinates need different adapters.
### Example 2: Whole-sequence differential-drive control
Use this pattern when a complete movement plan can be proposed before motion starts.
| Boundary | Example setup |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| Task | Move a wheeled platform into a target bay across varied layouts |
| Observation | Fourteen simulator-state values, including target-relative position, heading, velocity, and current wheel speeds |
| Adapt-1 output | Thirty pairs of continuous left and right wheel-speed commands |
| Bounds | Each wheel is limited to plus or minus eight radians per second |
| Cadence | Each pair is held for 0.4 seconds, producing a twelve-second open-loop attempt |
| Supplied harness | Motor controller, rigid-body simulation, collision handling, and terminal checks |
| Consequence | Task progress and terminal outcome after the attempt |
Adapt-1 emits all sixty values before movement. The executor does not ask for another decision while the platform is moving.
This setup is useful when the intended unit of learning is a complete movement program. To make the controller reactive, shorten the plan into blocks and re-observe between them.
Use the [configuration guide](/docs/machina/configuration) to declare the fourteen state coordinates, two action coordinates, horizon of thirty, and goal mapping. The wheel-speed scale and 0.4-second duration belong to the executor.
### Example 3: Chunked continuous flight control
Use command blocks when a whole episode is too long for one open-loop proposal but a decision on every simulator tick is unnecessary.
| Boundary | Example setup |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| Task | Approach and land while position, altitude, speed, orientation, and descent conditions evolve |
| Observation | Current measured flight state relative to the landing target |
| Adapt-1 output | A block of continuous control commands |
| Cadence | Eight commands held for 0.5 seconds each, forming one four-second block |
| Supplied harness | Flight dynamics, actuator response, safety termination, and trajectory recording |
| Consequence | Measured runway proximity, altitude, sink rate, roll, heading, excess speed, and terminal state |
| State lifecycle | One stable episode across successive blocks; learning updates occur between blocks |
The loop is:
1. Observe the current flight state.
2. Request one four-second command block.
3. Execute the full block without replanning inside it.
4. Return the measured trajectory consequence.
5. Request another block if the episode remains active.
Use the [trajectory observation contract](/docs/machina/acquisition#align-the-observation-arrays) for numeric command blocks. With eight commands, return nine measured states and eight actually executed action rows. Re-observe before requesting the next block. Keep the same learner Domain and application episode identity across blocks; this alone does not add a separate episode-wide delayed-credit mechanism.
### Example 4: Retained base with contextual correction
Use this pattern when an acquired behavior mostly works and a measured change calls for a bounded adjustment.
| Boundary | Example setup |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| Preserved artifact | A learned action, controller parameter, or complete sequence kept immutable during correction |
| New observation | Changed geometry, actuator strength, braking response, payload, or another pre-action condition |
| Adapt-1 output | A bounded residual such as an offset, timing adjustment, or braking lead |
| Composition | Executed command equals preserved base plus learned residual |
| Consequence | Candidate comparison on actual changed-condition cases |
| State lifecycle | Parent remains frozen; correction state is learned and audited separately |
A correction loop can:
1. Confirm the preserved parent in its original condition.
2. Observe the changed condition before action.
3. Request a bounded residual.
4. Compose the parent and residual deterministically.
5. Execute the corrected behavior.
6. Return the measured consequence.
7. Retain the correction separately from the parent.
When old-condition preservation matters, include original conditions in the declared practice mix. For later frozen use, keep parent identity, correction identity, composition rule, and context representation fixed.
The correction should remain a residual. If it can silently replace the parent, the setup no longer isolates refinement around retained behavior.
Follow [Contextual refinement](/docs/machina/refinement) for the context matrix, candidate evaluation requests, complete comparison feedback, and base-plus-offset composition.
### Example 5: One-action persistent-world control
Use this pattern when the same world continues across decisions and every action changes the next observation.
| Boundary | Example setup |
| ---------------- | ------------------------------------------------------------------------------------------------ |
| Task | Progress through several objectives in one persistent environment |
| Observation | Current location, health, nearby entities, objective state, inventory, and legal actions |
| Adapt-1 output | One of seven primitives: four movement directions, strike, interact, or rest |
| Cadence | One action, one observed consequence, one acknowledged update, then the next action |
| Supplied harness | World transition rules, collision, combat resolution, interaction semantics, and terminal checks |
| Consequence | Objective completion, useful interaction, movement progress, blocked movement, damage, or death |
| State lifecycle | One learner and one world persist across the objective sequence |
Keep one episode identity until the real reset boundary. Every record should contain the ordered step, pre-action state, selected and executed action, next state, consequence, and terminal flag.
The action primitives are authored public capabilities. The successful route, action order, and objective strategy are not supplied.
Use [Sequential Discovery](/docs/neuroadapt/discovery-sequential) to configure this discrete decision workflow. Its action schema and feedback differ from the numeric trajectory API.
### Example 6: Staged repertoire and composition
Use separate stages when generating behavior, selecting among candidates, composing a sequence, and learning corrections should remain auditable.
| Stage | Receives | Produces |
| ------------------------- | ---------------------------------------------------------------- | --------------------------------------------------- |
| **Acquisition** | Empty task state, action bounds, contexts, and measured outcomes | Candidate executions or controller parameters |
| **Selection** | Actual acquired executions and matched comparison contexts | A native-selected execution |
| **Deletion** | Selected execution and measured comparison outcomes | A selected execution after testing command removals |
| **Ordering** | Retained execution and measured comparison outcomes | A selected command order |
| **Contextual refinement** | Preserved parent, pre-action context, and residual bounds | A corrected execution |
| **Frozen use** | Validated artifact and a new context | An executed result with no learner writes |
At every handoff, keep the source learner identity, state version, candidate identifier, complete structured output, decoder version, qualification cases, and deterministic import rule.
Not every task needs every stage. Skip selection when only one useful candidate exists. Skip ordering when one result already describes the complete action. Skip refinement when the parent does not have a bounded, measurable residual problem.
Follow [Structural stages](/docs/machina/structural-stages) for paginated record export, separate stage Domains, nomination and confirmation, and transferring `selected_execution` unchanged.
## Turn an example into your integration
### Choose the decision cadence
| Question | Choose |
| ------------------------------------------------------------------------------------ | ------------------------------- |
| Can the useful plan be proposed before execution and evaluated as one unit? | Whole-attempt sequence |
| Must the system re-observe during a longer episode? | Chunked observe–act control |
| Does every action change the state used by the next decision? | Stepwise persistent control |
| Does a retained behavior need a bounded adjustment? | Base plus contextual correction |
| Should acquisition, selection, ordering, and refinement remain separately auditable? | Staged pipeline |
### Define what Adapt-1 must learn
Write one sentence:
> Given observable state **X**, return action or sequence **Y** to improve measured consequence **Z** over horizon **H**.
Then list everything supplied by the harness. Sensor calibration, actuator mapping, inverse kinematics, motor control, safety rules, and physics may be valid infrastructure. A successful trajectory, correct route, target-derived oracle value, or hidden evaluator answer is not valid when it supplies the capability being tested.
### Preserve the application record
For every decision or attempt, keep:
* stable run, episode, step, trial, and event identifiers;
* the exact pre-action observation;
* the complete Adapt-1 response;
* whether Adapt-1, application logic, a controller, or a fallback selected the executed operation;
* the exact decoded operation sent to the environment;
* the measured after-state and native consequence;
* the feedback request and acknowledged response; and
* learner, adapter, executor, simulator, and outcome revisions.
See [Monitor adaptation](/docs/neuroadapt/measure-online-adaptation) for the complete interaction record.
### Choose the state boundary
Use [Choose a learning setup](/docs/neuroadapt/choose-a-learning-setup) to distinguish:
* empty-state acquisition during the run;
* a separate acquisition phase followed by frozen use;
* a separately acquired state that continues adapting; and
* a frozen read of retained state.
A new simulator episode does not automatically mean a new learning run. Keep the same learner scope across compatible episodes when accumulated state is intended to carry forward.
### Freeze before evaluation
Reserve new contexts before acquisition. During frozen use, stop learner writes and exploration, use unseen episode IDs, preserve abstentions, and verify that task-specific state remains unchanged. Keep any application fallback separate from the Adapt-1 result.
## Continue into the API guides
Distinguish zero-start acquisition, separate acquisition, frozen use, and continued adaptation.
Set the mechanism and numeric schema before requesting actions.
Learn state-dependent action values and delayed credit from ordered interaction.
Transfer acquired executions and compare selection, deletion, and ordering candidates.
Learn and apply measured corrections around a retained base.
Reconnect to the same Domains and reconcile interrupted trajectory requests.