Choose a Robot Payload

Robot payload selection

Choose by the handoff, not by the ontology.

Golden payloads are for reusable robot examples. Start from the boundary you need to preserve: a local spatial value, a stamped graph handoff, scene memory, planner intent, motion output, execution status, or replayable event record.

Run first

pixi run demo-robotics-typing-catalog

Expected result: representative spatial and robot-facing payloads are constructed, registry lookup succeeds, and validation prints a compact summary.

Use the smallest reusable payload.

Prefer a narrow type that preserves the boundary instead of a broad object that silently becomes a project-specific blob.

Stamp values before they cross boundaries.

Add frame, event time, and source metadata before values enter replay, planning, control, export, or another process.

Keep optional integrations outside the base layer.

Camera, simulator, model, robot, network, and private dataset details should not be required to import these payloads.

Quick Decision Table

Boundary	Start with	Use when	Avoid first
Local spatial math	Vector3, Quaternion, SE3Pose	The frame, unit, and source are already local context.	Stamped wrappers for values that never leave the local computation.
Graph or process handoff	PoseStamped, TwistStamped, WrenchStamped	The value crosses a Flow, process, replay, dataset, or robot boundary.	Dropping frame_id, stamp_ns, or source before replay.
Robot state	RobotState, JointState	A wrapper, monitor, policy, or simulator needs current robot configuration.	Unnamed joint arrays or opaque status strings.
Scene and memory	WorldState, BeliefGraph	Perception, memory, grounding, and planning need a shared scene description.	Mixing geometric state, confidence, and task memory in one ad hoc dict.
Planner handoff	TaskGoal, Skill, Plan, StructuredPlan	A planner or language module hands intent to a controller or monitor.	Passing natural-language instructions directly to control code.
Motion and progress	Trajectory, ExecutionStatus	A controller or monitor reports timed motion, progress, terminal state, or errors.	Boolean-only success/failure with no progress or error context.
Lightweight exchange	Action, Command, Status	A smoke demo, Hub export, or dataset bridge needs compact exchange records.	Embedding simulator/model-specific payloads in the public pack.

Common Choices

GeometryPose, velocity, force

Use Vector3, Quaternion, SE3Pose, Twist, and Wrench when a Flow only needs spatial values.

Stamped boundaryFrame + time + source

Use stamped wrappers when a value crosses a graph, process, dataset, or robot boundary.

World modelCurrent robot and scene

Use RobotState, WorldState, and BeliefGraph for perception, memory, planning, and monitoring examples.

Action layerGoal, skill, plan, trajectory

Use TaskGoal, Skill, Plan, StructuredPlan, Trajectory, and ExecutionStatus for planner-to-controller handoff.

Authoring Pattern

Use direct imports inside example code. Use registry lookup at package boundaries: manifests, Hub packs, validation tools, replay readers, and dataset readers.

from retriever_typing import PoseStamped, SE3Pose, get_type
from retriever_typing.robotics_types import WorldState, Plan, ExecutionStatus

pose_cls = get_type("PoseStamped")
assert pose_cls is PoseStamped

AuthoringPrefer direct imports

Code should be readable without asking the registry what every payload means.

ManifestUse registry lookup

Hub packs and dataset readers can resolve names without importing optional robot integrations.

BoundaryValidate before reuse

Normalize frames, timestamps, quaternion norms, joint-array lengths, and progress ranges at graph edges.

Validation Checklist

FramesKeep frame IDs explicit

Use non-empty frame_id when world, camera, robot, or object frames can be confused.

TimePreserve event time

Keep stamp_ns monotonic per source when replay or event-time joins depend on ordering.

MotionNormalize rotations

Check quaternion norms before a pose crosses into planners, controllers, or datasets.

StatusMake progress comparable

Keep ExecutionStatus.progress in [0, 1] so monitors and UI surfaces agree.

Detailed field reference for implementers

Vector33D value

x, y, z. Use for positions, directions, velocities, forces, and offsets when the unit is declared by context.

QuaternionOrientation

x, y, z, w. Normalize at boundaries; keep frame conventions outside the raw quaternion.

SE3PoseRigid pose

position plus orientation. Prefer this for object, end-effector, and robot poses.

TwistSpatial velocity

linear plus angular. Use for velocity estimates or velocity commands.

WrenchForce and torque

force plus torque. Use at contact, manipulation, or controller boundaries.

JointStateJoint arrays

names, positions, velocities, efforts. Arrays are aligned by index.

HeaderBoundary metadata

stamp_ns, frame_id, source. Attach this before values leave a local Flow boundary.

WorldStateScene state

Current robot and object facts that perception, memory, and planning can share.

BeliefGraphProbabilistic memory

Symbolic scene memory and confidence values for grounding and planning.

Skill / PlanAction vocabulary

Named capabilities, parameters, and step sequences for planner-controller handoff.

TrajectoryTimed motion

A time-indexed pose sequence for motion planning or control examples.

ExecutionStatusProgress and terminal state

Progress, status, and error text for monitors, controllers, and logs.

Keep the base catalog small. Add covariance-bearing poses, richer frame graphs, or domain-specific schemas as separate Hub packs only after these base payloads are not enough.