retriever-core 0.0.4

A Python programming model and runtime for closed-loop robot agents whose perception, planning, and control run at different rates.

Programming Closed-Loop Modular Robot Agents

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.

See it run

One line, on any laptop with a webcam:

pip install "retriever-core[demo]" rerun-sdk
retriever demo webcam --visualize rerun

This 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.

Install

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.

Quickstart

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.

Learn more

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 as retriever. 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 check

The 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.

Community & license

Questions and help: Discord. Licensed under Apache-2.0 — see LICENSE and THIRD_PARTY_NOTICES.md.