Retriever

Retriever runtime

Build robot agents whose perception, reasoning, and control run at their own clocks.

Retriever is a programming model and runtime for closed-loop, asynchronous robot agents. Compose typed Flows on explicit clocks, and let each edge declare how it samples its inputs. The same timestamped inputs produce the same outputs no matter how the runtime schedules them — so you can step, record, and replay the whole agent.

Run the visual demoStart with mock color detection, then switch to webcam and Rerun.Follow the notebook pathCommands paired with expected output and what each graph teaches.Debug deliberatelyRender graphs, step locally, record events, and replay the run.

Mental model: PyTorch composes nn.Modules that run immediately; Retriever composes typed Flows that run in explicit time. Each Flow owns local state, wakes on its own clock, consumes one synchronized input record, and can be stepped locally before it runs on a backend.

Quick Start

Run the source-checkout demo first. It proves the runtime graph without camera permission, GUI windows, Rerun, or robot hardware.

git clone https://github.com/openretriever/retriever.git
cd retriever
./scripts/retriever install --bootstrap-pixi
./scripts/retriever run webcam-mock

What does this do?

./scripts/retriever install –bootstrap-pixi prepares the source checkout. ./scripts/retriever run webcam-mock runs a small graph: synthetic camera frames feed a color detector, then detections are printed to stdout. Use the webcam/Rerun path only after this smoke works.

Use the source checkout for demos today: it includes examples, tutorial assets, graph rendering, and optional visualization. The runtime-only distribution name is retriever-core, and the Python import remains retriever; see Install for the package/source split.

Why Retriever For Robotics

Compositional Flow contracts. Perception, memory, planning, skills, monitors, and controllers stay as reusable typed modules instead of callback glue.

Explicit multi-rate time. Cameras, model calls, skills, and controllers do not need to pretend they share one global timestep.

Deterministic input handoff. Each edge declares how upstream event history becomes the one input record consumed by step(…).

Debuggable before deployment. Render the graph, step locally, use stdout/Rerun, record consumed inputs, and replay the same run.

Backend mapping when ready. Keep the graph semantics stable while moving from in-process stepping to multiprocessing or Dora-backed execution.

A representative Retriever pipeline: slow reasoning, medium-rate skills, and high-rate control live in one explicit graph.

How Retriever Compares

The full positioning matrix lives on Why Retriever. Keep the homepage short: Retriever is for closed-loop robot agents where typed modules, explicit time, local debugging, and replay matter together.

Guides

Visual quickstartRun mock color detection, then switch to webcam and Rerun/stdout.Examples and resultsCompare expected output before reading implementation details.Debug and visualizeRender, step, record, and replay a graph.GoldenRetriever Hub quickstartLoad maintained robot-facing payload exports through Retriever Hub after the core path works.

Common Patterns

Need	Start with
First reliable smoke	./scripts/retriever run webcam-mock
Live visual path	./scripts/retriever run webcam
Smallest Flow mental model	./scripts/retriever run basic-flow
Graph inspection	./scripts/retriever run graph
Record and replay	./scripts/retriever run record then ./scripts/retriever run replay
Hub ref inspection	retriever hub parse openretriever/hello-world:HelloFlow then retriever hub inspect openretriever/hello-world --json
Applied robot examples	GoldenRetriever first proof, then the example catalog

For checkpointable debugging, use the Python stepping API: Pipeline.step(...) or the top-level retriever.step(...) helper on the active pipeline. Saved IR/HTML is for inspection and reproducibility; Python remains the executable graph source.

The Four Objects

FlowA typed Python class with local state and a synchronous step(…) method.ClockEach Flow declares when it runs; there is no global robot timestep.Sync policyEach edge declares how upstream event history becomes one aligned input.PipelineThe graph that validates, visualizes, steps, replays, and runs.

For AI Agents

Agents should start from llms.txt, then follow the Visual Quickstart before changing code. Use Examples and Results for expected outputs and Debug and Visualize for graph/render/replay commands.