Skip to content
RetrieverRetriever

Install

Install from source. Retriever ships a repository of runnable demos, graph-rendering scripts, Rerun visualization, and tests — none of which are useful without the source tree. Pixi builds the environment and runs every demo through one command.

What you’ll get: a Python 3.11 environment with retriever-core installed editable, plus a working first demo you can run in under a minute — no camera, no GUI, no robot hardware.

1. Clone and build the environment

Section titled “1. Clone and build the environment”
git clone https://github.com/openretriever/retriever.git
cd retriever
pixi install

pixi install reads pixi.toml, resolves conda and PyPI dependencies, pins Python to 3.11, and installs retriever-core as an editable package. Every demo is a Pixi task, so you never manage a virtualenv by hand.

2. Run the first demo

Section titled “2. Run the first demo”
pixi run demo-webcam-detection-mock

This is the deterministic first smoke: synthetic camera frames, stdout output, no camera permission, no GUI, no backend to configure. Stripped of INFO log lines, it prints:

============================================================
Perception Demo - Live or Mock Camera to Detection

Building perception pipeline:
  Camera @ Rate(20Hz) -> ColorDetector @ Trigger -> Display @ Rate

✓ Graph created: 3 nodes, 5 edges

Running for 0.1 seconds...
Tip: This run is using mock frames. Use --camera-mode real to require a live webcam path.
------------------------------------------------------------
  Frame 1: 2 objects - [('red_object', '0.95'), ('blue_object', '0.95')]
------------------------------------------------------------

A camera Flow emitted a frame, a color detector sampled it, and a display Flow printed the detections. The graph ran to a fixed duration and stopped. If you see this, the runtime works.

Visual quickstartThe fastest first success, then the live webcam and Rerun path. Examples and resultsSeveral demos, each paired with its real output. Tutorial pathThe ordered route from first demo to robot examples.

The runtime API

Section titled “The runtime API”

The distribution name is retriever-core; the import package is retriever:

from retriever.flow import Flow, Pipeline, Rate, io

A Flow is a stateful stream function. You declare typed IO with @io, subclass Flow, and override step():

@io
class NumberInput:
    value: int

@io
class NumberOutput:
    result: int

class DoubleFlow(Flow[NumberInput, NumberOutput]):
    def step(self, input: NumberInput):
        return NumberOutput(result=input.value * 2)

You compose Flows into a Pipeline, giving each edge an explicit sync= policy, then debug in-process before deploying async:

pipe.step(dt=0.1)              # advance the graph in-process, deterministically
pipe.run(backend="dora")       # deploy async; also "multiprocessing" or "in-process"

The same timestamped input trace yields the same output trace regardless of backend scheduling. That functional determinism is what makes local stepping, record, and replay well-defined.

Runtime-only package (target track)

Section titled “Runtime-only package (target track)”

Once retriever-core is published to PyPI, users who only need the API — not the demos, graph renderer, or tutorial assets — will install it directly:

python -m pip install retriever-core   # planned; not yet on PyPI

Until then, the source checkout above is the supported path, and it is the only path that includes the repository demos, docs-tutorial-* graph renderers, Rerun examples, and tests.

First-command reference

Section titled “First-command reference”
Situation Command
Reliable first smoke, no camera, no GUI pixi run demo-webcam-detection-mock
Live webcam with automatic Rerun/stdout fallback pixi run demo-webcam-detection
Understand the smallest Flow first pixi run demo-basic-flow
Render an interactive HTML graph pixi run docs-tutorial-perception-html
Record a run, then replay it pixi run demo-webcam-record then pixi run demo-webcam-replay-rrd

demo-webcam-detection needs a real webcam and uses --visualize auto (Rerun when available, stdout otherwise). If you have no camera or a permission prompt blocks it, stay on -mock.

If something fails

Section titled “If something fails”
Symptom Try first Why
Camera permission or hardware fails pixi run demo-webcam-detection-mock Proves the runtime graph with no local devices.
Rerun viewer does not open pixi run demo-perception-stepper Separates viewer setup from runtime correctness.
A graph behaves unexpectedly pixi run docs-tutorial-perception-html Inspect nodes, ports, clocks, and sync policies first.
A result is hard to reproduce pixi run demo-webcam-record then replay Turns timing-sensitive input into a stable artifact.

Next steps

Section titled “Next steps”