Skip to content

API reference

The classes exported from strands_robots, and the subpackages that hold the rest of the API.

from strands_robots import Robot, Simulation, Policy, Body, Description, Observation, Action, JointState, Pose

These are the main classes. Import the rest from their subpackages:

Subpackage Holds
strands_robots.mesh Mesh, authority
strands_robots.robot.safety RequestRefused
strands_robots.recording Dataset recording
strands_robots.dashboard Dashboard
strands_robots.policy Perturb, LeRobot policies

Robot

Bases: DeviceVerbs

A body in a world (sim=, or Simulation.default()) or on a bus (port=/driver=): same verbs.

description instance-attribute

description: Description = Description.load(name)

name instance-attribute

name = self.description.name

is_real instance-attribute

is_real = port is not None or driver is not None or 'host' in driver_options

operator instance-attribute

operator = operator

sim instance-attribute

sim: Simulation | None = None

twin instance-attribute

twin: Robot | None = None

twin_of instance-attribute

twin_of: Robot | None = None

clock instance-attribute

clock: Clock = checked(clock)

validators instance-attribute

validators: list[Validator] = []

interlocks instance-attribute

interlocks: list[Validator] = []

drives_here instance-attribute

drives_here = bool(getattr(driver, 'drives_here', True))

id instance-attribute

id = id or default_id(name)

supports_position_hold instance-attribute

supports_position_hold = position_hold_of(self.description, self._body)

body property

body: Body

action_keys property

action_keys: tuple[str, ...]

pose property

pose: Pose

confirm_act class-attribute instance-attribute

confirm_act = _gate.act_through_gate

run class-attribute instance-attribute

run = _run.run

start class-attribute instance-attribute

start = _run.start

tool property

tool: Any

This robot as a strands agent tool, generated from its rpcs (imports strands on first use).

detached

detached() -> None

set_pose

set_pose(position: Any = None, orientation: Any = None) -> None

Teleport (sim only). A hardware robot raises; its twin can still be teleported.

set_gains

set_gains(kp: Any, kd: Any) -> None

PD gains of this body's actuators, action_keys order (sim, or a driver that sends gains per command).

observe

observe(*, images: bool = True) -> Observation

One read of the body; t is the capture time on the robot's clock.

gate

gate(action: Action, *, confirmed: bool = False, approved_run: bool = False, **kw: Any) -> np.ndarray

The operator gate for commands from an agent tool or dashboard (robot.gate; measured/source).

act

act(action: Action, *, steps: int | None = None, seconds: float | None = None) -> Observation

Write targets for THIS body and advance its world (a real body: its twin's) one control step.

seconds: reach the pose instead, ramping there from the measured one over that long (robot.reach). Returns what the body reports after (one read); a run loop calls command instead.

command

command(targets: ndarray, *, steps: int | None = None, stops0: int | None = None) -> None

The run loop's write, no read: full targets checked as act checks them (NaN/inf or a wrong length refused, clipped into the limits) before the body, then the world advances.

calibrate

calibrate(*, interactive: bool = True) -> Calibration

Read (or, at the arm, record) the bus calibration: LeRobot's calibration JSON, unchanged.

coerce

coerce(action: Action, *, clip: bool = True, measured: ndarray | None = None) -> np.ndarray

Any accepted Action -> full targets in action_keys order (see robot.targets.coerce).

stop

stop(timeout: float | None = None) -> RunResult | None

End the background run: its result, or its error raised once; None when nothing runs.

close

close() -> None

Simulation

Bases: _SceneOps

One world. Owns time. Holds many robots. Simulation() is MuJoCo, headless; Simulation.default() is the process-wide world every Robot joins when it is given none.

scene instance-attribute

scene = Scene(gravity=gravity, timestep=timestep, ground=ground)

revision instance-attribute

revision = 0

lock instance-attribute

lock = WorldLock()

backend instance-attribute

backend: Backend = cls(physics=physics, headless=headless, device=device, num_envs=num_envs, render_size=render_size)

is_default property

is_default: bool

time_is_manual property

time_is_manual: bool

time property

time: float

physics property

physics: Physics

robots property

robots: Mapping[str, Member]

envs property

envs: int

tool property

tool: Any

This world as a strands agent tool, generated from its public verbs (imports strands on first use).

default classmethod

default() -> Simulation

The world a Robot attaches to when none is given: MuJoCo, headless, created on first use.

step

step(n: int = 1) -> None

Advance n physics steps (timestep each).

control_step

control_step() -> None

Advance exactly one control step (physics.substeps physics steps) unless time is manual.

manual_time

manual_time() -> Iterator[Simulation]

Inside: robot.act() only writes targets; the caller steps the world.

editing

editing() -> Iterator[Simulation]

Batch scene edits into one rebuild on exit (on newton a new scene shape compiles kernels). A block that fails, in its body or in its rebuild, restores the scene and robots as they were; step, render and set_pose outside a block flush pending edits first.

reset

reset(*, keyframe: str | None = None) -> None

Every body back to its spawn state, or to keyframe where a robot has one.

run

run(policies: Mapping[str | Robot, PolicyLike | Callable[[Observation], Any]], *, hz: float | None = None, seconds: float | None = None, steps: int | None = None, instruction: str | None = None, units: str | None = 'auto') -> dict[str, RunResult]

Drive N robots in lock-step (robot id -> policy spec): each observes and acts, then the world steps once.

pose

pose(body: str) -> Pose

Where a robot base, an object or a robot link ("so101/gripper") is now: position m, quat w,x,y,z.

describe

describe() -> dict[str, Any]

Robots (spawn frame, live pose, links), objects where they are now, cameras, physics, time; JSON-safe.

close

close() -> None

Policy

Base class: override act; units and requirements say what the policy speaks and needs.

Optional hooks the run loop honours: attach(robot) before step one (connect, admit, load), detach() after the last step, realtime (pace in wall time even in a sim), hz and needs_observation (the loop renders the cameras only for a step that answers True), gains (kp, kd), start_pose (where its episodes begin, in the policy's units — a mapping or a full vector — reached over start_seconds, default 3, before step one). The loop reads them once before step one; a hook of the wrong type is a TypeError.

units class-attribute instance-attribute

units: str | None = None

act

act(obs: Observation, *, instruction: str | None = None) -> Action | None

The action for this observation, or None to hold: the run loop writes nothing that tick, the body keeps its last target, and the tick is a RunResult.holds entry — never a deadline miss.

reset

reset() -> None

needs_observation

needs_observation(*, instruction: str | None = None) -> bool

Whether the next act looks at the observation's images; the default looks on every step.

requirements

requirements() -> Requirements

Cameras/state this policy needs; the default needs nothing specific.

Description

A robot model resolved to a file plus the facts a world or a bus needs about it.

name instance-attribute

name: str

model_path instance-attribute

model_path: Path

format instance-attribute

format: str

category class-attribute instance-attribute

category: str = 'unknown'

device_type class-attribute instance-attribute

device_type: str | None = None

joints class-attribute instance-attribute

joints: tuple[str, ...] = ()

actuators class-attribute instance-attribute

actuators: tuple[str, ...] = ()

action_keys class-attribute instance-attribute

action_keys: tuple[str, ...] = ()

limits class-attribute instance-attribute

limits: Mapping[str, tuple[float, float]] = field(default_factory=dict)

keyframes class-attribute instance-attribute

keyframes: tuple[str, ...] = ()

floating class-attribute instance-attribute

floating: bool = False

joint_labels class-attribute instance-attribute

joint_labels: Mapping[str, str] = field(default_factory=dict)

spawn_position class-attribute instance-attribute

spawn_position: tuple[float, float, float] = (0.0, 0.0, 0.0)

hardware class-attribute instance-attribute

hardware: Hardware = field(default_factory=Hardware)

gripper class-attribute instance-attribute

gripper: Gripper | None = None

scene_path class-attribute instance-attribute

scene_path: Path | None = None

package_dir property

package_dir: Path

dof property

dof: int

label

label(model_joint: str) -> str

unlabel

unlabel(label: str) -> str

describe

describe() -> dict[str, Any]

JSON-safe summary (what an agent tool and the dashboard read).

load classmethod

load(name: str | Path) -> Description

Resolve a registry name, alias, robot_descriptions name or MJCF/URDF path.

Observation, JointState, Pose

What a body reports at time t: joints, base pose, camera images and per-body extras.

== compares every field by value (images and extras too); hash reads t, joints and pose.

t instance-attribute

t: float

joints instance-attribute

joints: JointState

pose class-attribute instance-attribute

pose: Pose | None = None

images class-attribute instance-attribute

images: Mapping[str, ndarray] = field(default_factory=dict)

extras class-attribute instance-attribute

extras: Mapping[str, Any] = field(default_factory=dict)

with_joints

with_joints(positions: ndarray) -> Observation

The same observation with joint positions replaced (used for unit conversion before a policy).

to_lerobot

to_lerobot() -> dict[str, Any]

observation.state (float32 vector) + observation.images.<cam> (HxWx3 uint8).

Positions/velocities/efforts for a named set of joints (SI: rad, rad/s, N·m). A value: ==, hash.

names instance-attribute

names: tuple[str, ...]

positions instance-attribute

positions: ndarray

velocities instance-attribute

velocities: ndarray

efforts instance-attribute

efforts: ndarray

as_dict

as_dict() -> dict[str, float]

zeros classmethod

zeros(names: tuple[str, ...] | list[str]) -> JointState

A rigid pose in the world frame: position (m) and orientation as a unit quaternion (w, x, y, z).

A floating body also reports its twist: linear_velocity (world frame, m/s) and angular_velocity (body frame, rad/s — what a gyro mounted on the base reads). Fixed bases and drivers leave both None.

position instance-attribute

position: ndarray

orientation instance-attribute

orientation: ndarray

linear_velocity class-attribute instance-attribute

linear_velocity: ndarray | None = None

angular_velocity class-attribute instance-attribute

angular_velocity: ndarray | None = None

identity classmethod

identity(position: Any = (0.0, 0.0, 0.0)) -> Pose
Edit page