# Retriever

> Retriever (PyPI target `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
pixi install
pixi run demo-webcam-detection-mock
pixi run demo-stepper
pixi run docs-tutorial-perception-html
```

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 still the canonical path for demos, examples, Rerun visualization, and repository tests.
- 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, type packs, simulator/visualization lanes, and Hub-pack candidates.

## Canonical Commands

```bash
pixi run demo-basic-flow
pixi run demo-stepper
pixi run demo-perception-stepper
pixi run demo-webcam-detection-mock
pixi run demo-webcam-detection
pixi run docs-tutorial-perception-html
pixi run demo-webcam-record
pixi run demo-webcam-replay-rrd
```

## Docs

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

## Companion Sites

- [Core Source](https://github.com/openretriever/retriever): runtime implementation and source-checkout demos.
- [Golden Source](https://github.com/openretriever/golden-retriever): robot-facing examples, type packs, simulator lanes, and public-surface checks.
- [Landing page](https://openretriever.org/): compact public front door.
- [GoldenRetriever](https://retriever-space.pages.dev/): robot-facing reference examples, type packs, simulator/visualization lanes, and Hub-pack candidates.