# Retriever

> Retriever (distribution `retriever-core`, import package `retriever`) is a typed dataflow runtime for closed-loop robot systems. It lets users author typed Flow graphs with explicit clocks and per-edge sync policies, inspect them as graphs, debug them in-process with `pipe.step()`, then run the same graph on multiprocessing or dora backends with recording and replay.

## Agent First Path

If you are an AI agent working in the source repo, do this before editing code:

```bash
retriever install --bootstrap-pixi
retriever run webcam-mock
retriever run stepper
retriever run graph

# Installed-package no-clone visual demo:
python -m pip install "retriever-core[demo]" rerun-sdk
retriever demo webcam --seconds 60 --visualize rerun --refresh
```

Use the mock visual smoke first. Do not start with live camera, dora, or multiprocessing unless the user specifically asks for that backend.

## Critical Facts

- Python 3.11+.
- PyPI distribution target: `retriever-core`.
- Import package: `retriever`.
- The source checkout is canonical for repository demos, examples, and tests. The installed package supports the no-clone `retriever demo webcam` Rerun path.
- Define payloads with `@io` from `retriever.flow`.
- Override `Flow.step(...)`; do not invent `run(...)` methods for Flow logic.
- Edge sync should be explicit with `connect(..., sync=...)` unless a default sync policy is intentionally configured.
- Common backends are `in-process`, `multiprocessing`, and `dora`.
- Use record/replay when behavior depends on live sensor timing.
- GoldenRetriever is the maintained reference examples layer: maintained robot-facing examples, payload packs, simulator/visualization lanes, and Hub-pack candidates.

## Canonical Commands

```bash
retriever demo webcam --seconds 60 --visualize rerun --refresh
retriever run basic-flow
retriever run stepper
retriever run perception-stepper
retriever run webcam-mock
retriever run webcam
retriever run graph
retriever run record
retriever run replay
retriever hub parse openretriever/hello-world:HelloFlow
retriever hub inspect openretriever/hello-world --json
```

## Docs

- [Overview](https://retriever.build/): recommended path and conceptual map.
- [Install](https://retriever.build/getting-started/install/): source checkout setup today, plus the runtime-only package/source split.
- [Visual Quickstart](https://retriever.build/getting-started/visual-quickstart/): deterministic mock color-detection smoke, then live webcam/Rerun.
- [Examples and Results](https://retriever.build/tutorials/examples-and-results/): commands paired with expected output.
- [Debug and Visualize](https://retriever.build/tutorials/debug-and-visualize/): graph render, local stepping, Rerun, record, replay.
- [Flow](https://retriever.build/concepts/flow/): typed Flow authoring.
- [Time and Sync](https://retriever.build/concepts/time-and-sync/): clocks, event streams, and sync policies.
- [Runtime](https://retriever.build/concepts/runtime/): validate -> IR -> backends, stepping, recording, and replay.
- [Standard Types](https://retriever.build/concepts/standard-types/): runtime-owned type primitives and what belongs outside core.
- [Concepts and Lineage](https://retriever.build/concepts/lineage/): relation to FRP and synchronous dataflow.
- [GoldenRetriever examples bridge](https://retriever.build/ecosystem/golden-packs/): how GoldenRetriever extends core Retriever through a manifest-declared payload pack.
- [GoldenRetriever first proof](https://golden.retriever.build/examples/golden-hub-proof/): runnable GoldenRetriever command path from the separate `openretriever/golden-retriever` source checkout.
- [Modules](https://retriever.build/ecosystem/modules/): Retriever Hub module loading with `hub.use("org/name:Export")` plus `retriever hub parse/inspect` for command-line checks.
- [Composable Pipelines](https://retriever.build/ecosystem/composable-pipelines/): reusable pipelines as inspectable graphs or Flow stages.
- [Publishing](https://retriever.build/ecosystem/publishing/): make a repo hub-loadable with `[tool.retriever.module]`.

## Companion Sites

- Core source target: `openretriever/retriever` for runtime implementation and source checkout demos. Use hosted docs for stable public instructions.
- GoldenRetriever source target: `openretriever/golden-retriever` for robot-facing examples, payload packs, simulator lanes, and public-surface checks. Use the GoldenRetriever first proof before heavier examples.
- [Landing page](https://openretriever.org/): compact public front door.
- [GoldenRetriever](https://golden.retriever.build/): robot-facing reference examples, payload packs, simulator/visualization lanes, and Hub-pack candidates. Start with [First GoldenRetriever Proof](https://golden.retriever.build/examples/golden-hub-proof/).