Metadata-Version: 2.4
Name: retriever-core
Version: 0.0.1
Summary: A Python programming model and runtime for closed-loop robot agents whose perception, planning, and control run at different rates.
Project-URL: Homepage, https://github.com/openretriever/retriever
Project-URL: Documentation, https://retriever.build/
Project-URL: Bug Tracker, https://github.com/openretriever/retriever/issues
Author: Linfeng Zhao
License: Apache-2.0
License-File: LICENSE
Keywords: bilevel-planning,foundation-models,planning,robotics,skill-learning,task-and-motion-planning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: packaging>=23
Provides-Extra: demo
Requires-Dist: matplotlib; extra == 'demo'
Requires-Dist: numpy; extra == 'demo'
Requires-Dist: opencv-python>=4.10; extra == 'demo'
Requires-Dist: pandas; extra == 'demo'
Requires-Dist: pynput; extra == 'demo'
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: lark; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pygments; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.2.2; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Requires-Dist: typing-extensions; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: pymdown-extensions>=10; extra == 'docs'
Provides-Extra: dora
Requires-Dist: dora-rs-cli>=0.3.12; extra == 'dora'
Requires-Dist: dora-rs>=0.3.12; extra == 'dora'
Requires-Dist: psutil; extra == 'dora'
Requires-Dist: pyarrow; extra == 'dora'
Requires-Dist: pyyaml; extra == 'dora'
Provides-Extra: jax
Requires-Dist: flax; extra == 'jax'
Requires-Dist: jax; extra == 'jax'
Requires-Dist: jaxlib; extra == 'jax'
Requires-Dist: optax; extra == 'jax'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.25.0; extra == 'mcp'
Provides-Extra: otel
Requires-Dist: opentelemetry-api; extra == 'otel'
Requires-Dist: opentelemetry-sdk; extra == 'otel'
Requires-Dist: uptrace; extra == 'otel'
Provides-Extra: recording
Requires-Dist: mcap>=1.0.0; extra == 'recording'
Requires-Dist: numpy; extra == 'recording'
Requires-Dist: rerun-sdk<0.24,>=0.21.0; extra == 'recording'
Provides-Extra: vision
Requires-Dist: pillow; extra == 'vision'
Requires-Dist: torch>=2.0.0; extra == 'vision'
Requires-Dist: transformers; extra == 'vision'
Provides-Extra: web
Requires-Dist: fastapi; extra == 'web'
Requires-Dist: uvicorn[standard]; extra == 'web'
Description-Content-Type: text/markdown

<div align="center">

<a href="https://openretriever.org/"><img width="200" height="auto" src="assets/retriever-illustrative.jpeg" alt="Retriever logo"></a>

<br>

<a href="https://openretriever.org/"><img src="assets/retriever-wordmark.svg" alt="Retriever" width="300"></a>

### Programming Closed-Loop Modular Robot Agents

<p>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 any run can be recorded and replayed exactly.</p>

<p>
  <a href="https://retriever.build/"><img alt="Docs" src="https://img.shields.io/badge/Docs-open-0f766e?style=for-the-badge"></a>
  <a href="https://openretriever.org/"><img alt="Website" src="https://img.shields.io/badge/Website-openretriever.org-111827?style=for-the-badge"></a>
  <a href="https://github.com/openretriever/retriever"><img alt="Source" src="https://img.shields.io/badge/Source-GitHub-111827?style=for-the-badge&logo=github"></a>
  <br>
  <a href="https://golden.retriever.build/examples/"><img alt="GoldenRetriever examples" src="https://img.shields.io/badge/GoldenRetriever-examples-f97316?style=for-the-badge"></a>
  <a href="https://golden.retriever.build/hub/"><img alt="Hub packs" src="https://img.shields.io/badge/Hub-packs-9333ea?style=for-the-badge"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/License-Apache_2.0-3b82f6?style=for-the-badge"></a>
</p>

</div>

---

Retriever is the **core/runtime** package for typed, multi-rate robot pipelines. Robot applications rarely run as one neat synchronous loop: cameras, state estimators, planners, VLMs, VLAs, controllers, operators, and logs all update at different rates. Retriever makes those timing boundaries explicit while keeping the authoring model close to normal Python.

Use Retriever when a robot system needs:

- **Closed loops**: perception, memory, planning, control, monitoring, and even environment wrappers can live in one cyclic graph.
- **Explicit timing**: each `Flow` declares when it runs, and each edge declares how data is sampled before `step(...)` executes.
- **Debuggable execution**: run the graph on a backend, or step it in-process with normal Python breakpoints.
- **Portable backends**: author one typed graph, then run it in-process, with multiprocessing, or on a distributed backend.
- **Reusable components**: typed payloads, registries, and Hub surfaces make robot software easier to publish and compose.

System-level robot integrations, simulator stacks, and heavier model packages belong in the maintained reference examples layer: [GoldenRetriever](https://golden.retriever.build/examples/) and Retriever Hub packs. This repository stays focused on the runtime core.

The authoring style is intentionally close to functional reactive programming: compose small stateful stream functions, make time explicit, and put the sampling rule on the edge. In day-to-day code, `.then(...)` is the fluent composition surface; `retriever.connect(...)` is the same edge written as a standalone function.

## Canonical Runtime Workflow

```python
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, _):  # type: ignore[override]
        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)
    double = Double() @ Trigger("value")
    source.then(double, sync=Latest())

pipe.run(backend="multiprocessing", duration=1.0)
```

The important pieces are small:

- `@io` defines typed message envelopes.
- `Flow[I, O]` defines node logic.
- `flow @ clock` declares when a node runs.
- `source.then(target, sync=...)` wires a Flow-to-Flow edge in the fluent style.
- `retriever.connect(source, target, sync=...)` is the explicit equivalent when chaining is not the clearest shape.
- `Pipeline.run(...)` executes on a backend.
- `Pipeline.step(...)` runs in-process for debugging and replay.

## Install

Use Python 3.11 or newer.

The public package target is `retriever-core`; the Python import package and executable command are both `retriever`:

```bash
python -m pip install retriever-core
retriever --version
retriever init my-retriever-app --bootstrap-pixi
cd my-retriever-app
retriever run hello
```

For repository demos, clone the source checkout because the example files, graph renderers, and visualization assets live in the repository. With `retriever-core` installed, run everything through the `retriever` command:

```bash
git clone https://github.com/openretriever/retriever
cd retriever
retriever install --bootstrap-pixi
retriever run webcam-mock
retriever run webcam
```

`retriever run webcam-mock` runs `camera -> color detector -> display` with
synthetic frames and stdout, so it works on headless machines and in agent
runs. `retriever run webcam` requests a real webcam and uses `--visualize auto`
so Rerun is used when available and stdout is used otherwise. Hold red or blue
paper/objects in front of the camera to see detections.

Useful follow-up commands from the source checkout:

```bash
retriever run basic-flow
retriever run rt-execution
retriever run stepper
retriever run record
retriever tasks
```

`retriever run <name>` is the stable command surface for examples and diagnostics. Curated names (`webcam-mock`, `stepper`, `record`, …) are the public path; raw repository task names still work with `retriever run <task>` as a source-checkout escape hatch.

## Step And Checkpoint Graphs

Checkpointable graph debugging is a Python API, not a separate CLI namespace. Define the graph in Python, inspect or render its IR, then step it in-process with normal breakpoints and your own checkpoint artifact:

```python
import json
from pathlib import Path

pipe.validate()

for i in range(10):
    result = pipe.step(dt=0.1)
    checkpoint = {"now": result.now, "executed": result.executed}
    Path(f"checkpoint-{i:03d}.json").write_text(json.dumps(checkpoint, indent=2))

pipe.close_stepper()
```

Python is the executable source of truth. Saved IR/HTML is the portable graph description for inspection and reproducibility; executing directly from saved IR should remain a future, versioned contract rather than the default promise.

## Retriever Hub

Hub loads a module by name from a public repo — no clone, no checkout. Install the
runtime package plus Rerun, then run a 60-second live webcam demo in one line:

```bash
python -m pip install "retriever-core[demo]" rerun-sdk && retriever demo webcam --seconds 60 --visualize rerun --refresh
```

`hub.use(...)` fetches the [`openretriever/webcam-demo`](https://github.com/openretriever/webcam-demo)
pack, checks its dependencies, and drives a `Camera -> ColorDetector -> Rerun`
closed loop over your webcam with image and bounding-box overlays. Use
`--visualize stdout` for terminal-only output or `--visualize both` for Rerun plus
stdout.

Hub refs are ordinary strings: `{org}/{name}[:Export][@version]`. Use the CLI to validate the ref shape offline, inspect a module through the same loader as `hub.use(...)`, and locate the local cache:

```bash
retriever hub parse openretriever/hello-world:HelloFlow
retriever hub inspect openretriever/hello-world --json
retriever hub cache-dir
```

`hub inspect` may fetch from the Hub index and GitHub unless the module is already cached. Use `retriever --dry-run hub inspect <ref>` when you only want to check the ref shape without network access. In Python, load the same export with `from retriever import hub; hub.use("openretriever/hello-world:HelloFlow")`.

## Documentation Path

The hosted Starlight docs are the public docs front door:

- [Overview](https://retriever.build/) — recommended path.
- [Install](https://retriever.build/getting-started/install/) — package target and source-checkout commands.
- [Visual Quickstart](https://retriever.build/getting-started/visual-quickstart/) — mock smoke, webcam color detection, and 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, stepper, record, and replay.
- [GoldenRetriever Overview](https://golden.retriever.build/) — GoldenRetriever as the applied examples and reference-pack layer.
- [GoldenRetriever Example Catalog](https://golden.retriever.build/examples/) — applied perception, memory, language, composition, simulation, visualization, and typing guides.

The repository `docs/` tree remains available for deeper source-local reference
and release maintenance.

Source code lives at [github.com/openretriever/retriever](https://github.com/openretriever/retriever). GoldenRetriever source lives at [github.com/openretriever/golden-retriever](https://github.com/openretriever/golden-retriever), but most users should start from the hosted [GoldenRetriever example catalog](https://golden.retriever.build/examples/).

## Runtime Surfaces

Retriever has two execution modes on purpose:

```python
# Backend execution
pipe.run(backend="multiprocessing", duration=3.0)
pipe.run(backend="dora", duration=3.0)

# In-process debugging
result = pipe.step(dt=0.1)
print(result.executed)
pipe.close_stepper()
```

Backend execution is for realistic scheduling, process boundaries, and deployment behavior. In-process stepping is for debugging logic, replaying incidents, and making timing bugs inspectable with normal Python tools.

## Ecosystem Boundary

The intended public split is:

- **Core runtime**: this repository, published as `retriever-core` and imported as `retriever`.
- **GoldenRetriever examples**: [GoldenRetriever](https://golden.retriever.build/examples/) for robot-facing examples and pack candidates.
- **Project website**: [openretriever.org](https://openretriever.org/).

## Development

Contributor tasks run through the same `retriever` command from a source
checkout:

```bash
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 before announcing
```

The source checkout uses [Pixi](https://pixi.sh) as its environment and task
backend, and `retriever run <task>` wraps it. For focused test subsets, run
pytest in the environment directly:

```bash
pixi run python -m pytest tests/core/test_public_surface_rt.py -q
pixi run python -m pytest tests/core/test_hub_ref_rt.py tests/core/test_hub_check_rt.py tests/core/test_hub_loader_rt.py tests/core/test_hub_use_rt.py -q
```

See [docs/contributing.md](docs/contributing.md) for the full development workflow.

## Clone and Stay in Sync

```bash
git clone https://github.com/openretriever/retriever
cd retriever
git pull   # normal pulls fast-forward
```

`main` is the canonical branch; a fresh clone and ordinary `git pull` are all you need.

## License

Retriever is licensed under the Apache License 2.0 (`Apache-2.0`). See [LICENSE](LICENSE) for the full license text and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for bundled third-party JavaScript notices.
