Robot Payload Types

Core Retriever gives you the runtime: Flow, Pipeline, clocks, sync, execution, IR, replay, and the Hub loader. GoldenRetriever adds the applied payload layer — the typed records robot examples hand each other so a perception, memory, planning, or control Flow can be swapped without renegotiating the data contract.

There are two tiers behind one import path. retriever_typing re-exports the standard spatial types from retriever.types.spatial (identity preserved — retriever_typing.PoseStamped is retriever.types.spatial.PoseStamped, never a copy) and adds the applied robot types that have no standard equivalent yet.

# Standard types, re-exported from retriever.types.spatial (same classes, @io-ready ports):
from retriever_typing import Header, Vector3, Quaternion, SE3Pose, PoseStamped, JointState

# Applied robot payloads GoldenRetriever owns (plain dataclasses carried as values):
from retriever_typing.robotics_types import WorldState, BeliefGraph, Skill, Plan, Trajectory, ExecutionStatus
from retriever_typing.core_types import Action, Command, Status

Construct one, resolve it through the registry

Every payload is a plain @dataclass. It carries no clock, buffer, or graph state — that isolation is what lets one Flow return it and another consume it. The same names resolve through the unified registry, so a manifest, replay reader, or Hub pack can look a type up without importing the module first.

from retriever_typing import Header, SE3Pose, Vector3, Quaternion, PoseStamped, get_type

pose = PoseStamped(
    header=Header(stamp_ns=1_726_000_000_000_000_000, frame_id="map", source="sim"),
    pose=SE3Pose(position=Vector3(1.0, 2.0, 0.5), orientation=Quaternion(0.0, 0.0, 0.0, 1.0)),
)

assert get_type("PoseStamped") is PoseStamped   # the registry name resolves to the class

pixi run demo-robotics-typing-catalog

Real output — the registry resolves the standard names, and the constructed payloads keep frame, position, and joint metadata intact:

Registry lookup: PoseStamped=PoseStamped SE3Pose=SE3Pose
Robotics typing catalog v1 demo
  pose.frame=map pos=Vector3(x=1.0, y=2.0, z=0.5)
  twist.frame=base_link linear=Vector3(x=0.2, y=0.0, z=0.0)
  wrench.frame=wrist force=Vector3(x=0.0, y=0.0, z=3.5)
  joint_count=6 aligned=True

The four questions this section answers

Page	Question	Runnable proof
Choose a payload	Which payload should this Flow use?	`demo-robotics-typing-catalog`
Flow contracts	How do `@io` typed ports form the I/O contract?	`demo-robotics-typing-contract`, `demo-robotics-typing-boundary`
Data and event streams	How does robot data stay replayable?	`demo-robotics-data-eventstream`, `demo-robotics-data-join`
LeRobot export	How do event records become dataset rows?	`demo-robotics-lerobot-bridge`

What GoldenRetriever Owns

A payload belongs in GoldenRetriever when it helps more than one applied example without importing an optional robot, simulator, camera, model, network, or private-dataset dependency. The WorldState, Skill, Plan, Trajectory, and ExecutionStatus types clear that bar and are the pack GoldenRetriever publishes through Retriever Hub. Lab-specific capture procedures, camera rigs, and one-off policy fields stay inside the example until the boundary is stable.

Runtime mechanics (Flow, Pipeline, clocks, sync, IR, replay, the loader) live in the core Retriever docs. This section only covers the applied payloads that ride on top of them.

Source: src/retriever_typing/ (v1.py, robotics_types.py, core_types.py, registry.py); demo examples/advanced/robotics_typing_standard/type_catalog_demo.py.