A Python programming model and runtime for robot agents whose perception, planning, and control run at different rates. You write down how often each part runs and how it handles data that arrives out of sync, so the timing lives in the graph instead of in hand-written glue code — and recorded input traces can be replayed through the same graph.
Robot systems rarely run as one neat synchronous loop: cameras, estimators, planners, VLMs, VLAs, and controllers all update at different rates. Retriever lets you declare how often each Flow runs and how each edge samples data — so the timing lives in the graph, not in glue code. Step the graph in-process to debug it, then run the same graph on a backend; record the consumed input trace when you need an exact replay.
One line, on any laptop with a webcam:
pip install "retriever-core[demo]" rerun-sdk
retriever demo webcam --visualize rerunThis pulls the openretriever/webcam-demo Hub pack (no clone) and drives a live Camera → ColorDetector → Rerun closed loop with bounding-box overlays. Full walkthrough: retriever.build.
python -m pip install retriever-core # runtime + `retriever` CLI; imports as `retriever`Python 3.11+. For the bundled demos, renderers, and tests, use a source checkout: git clone https://github.com/openretriever/retriever && cd retriever && retriever install.
from retriever import Flow, Latest, Pipeline, Rate, Trigger, io
@io
class Number:
value: int
@io
class Doubled:
value: int
class Source(Flow[None, Number]):
def __init__(self) -> None:
super().__init__()
self.count = 0
def step(self, _):
self.count += 1
return Number(value=self.count)
class Double(Flow[Number, Doubled]):
def step(self, input: Number) -> Doubled:
return Doubled(value=input.value * 2)
pipe = Pipeline("quickstart")
with pipe:
source = Source() @ Rate(hz=2) # runs at 2 Hz
double = Double() @ Trigger("value") # wakes on each Number
source.then(double, sync=Latest()) # edge samples the latest value
pipe.run(backend="multiprocessing", duration=1.0) # deploy
# result = pipe.step(dt=0.1) # ...or step in-process to debug + replay@io typed message · Flow[I, O] node logic · flow @ clock when it runs · .then(…, sync=…) how the edge samples · pipe.run() to deploy, pipe.step() to debug and replay.
| Guide | What's there |
|---|---|
| Docs home | install, visual quickstart, tutorials |
| Concepts | Flow, clocks, sync policies, IR, record/replay |
| Retriever Hub | load packs by name from any repo — no clone |
| GoldenRetriever | applied robot examples: perception, memory, language, sim |
| Discord | questions, help, and community |
In-process stepping, record & replay
Retriever has two execution modes on purpose. Backend execution is for realistic scheduling and deployment; in-process stepping is for debugging logic, replaying incidents, and making timing bugs inspectable with normal Python tools.
# Backend execution — realistic scheduling, process boundaries, deployment
pipe.run(backend="multiprocessing", duration=3.0)
pipe.run(backend="dora", duration=3.0)
# In-process debugging — step the graph, inspect, checkpoint, replay
result = pipe.step(dt=0.1)
print(result.executed)
pipe.close_stepper()Given the same ordered timestamped input history — including a fixed order for equal timestamps — deterministic Flows produce the same discrete-event output trace. Live backend timing decides which history is captured; replay drives the graph from that captured history. See Runtime for the precise contract and Debug and Visualize for the workflow.
Ecosystem boundary
- Core runtime — this repo, published as
retriever-core, imported asretriever. Stays focused on the runtime. - GoldenRetriever — the applied examples + Hub-pack layer (robot payloads, simulator/visualization lanes). Built on the runtime, not a second one.
- Retriever Hub — the manifest + index protocol that turns any repo into a loadable pack of Flows, types, and pipelines.
- openretriever.org — the project home.
Contributing & development
Contributor tasks run through the same retriever command from a source checkout:
retriever install # set up the environment
retriever run test # full test suite
retriever run p0-release-readiness
retriever run public-surface-check # external launch checkThe source checkout uses Pixi as its environment/task backend, and retriever run <task> wraps it. main is canonical — a fresh clone and ordinary git pull fast-forward. See docs/contributing.md.
Questions and help: Discord. Licensed under Apache-2.0 — see LICENSE and THIRD_PARTY_NOTICES.md.