Metadata-Version: 2.4
Name: debug-retriever
Version: 0.1.4
Summary: Retriever: Building Modular Robot Agents with Causal Functional Composition
Project-URL: Homepage, https://github.com/linfeng-z/Retriever
Project-URL: Documentation, https://www.notion.so/retriever-dev/Retriever-Dev-Homepage-bfd5d802e1f346ac81a1ea773f6418e9
Project-URL: Bug Tracker, https://github.com/linfeng-z/Retriever/issues
Author-email: Linfeng Zhao <zlf0625@gmail.com>
License: Proprietary
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: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
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: typing-extensions; extra == 'dev'
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.21.0; extra == 'recording'
Provides-Extra: vision
Requires-Dist: openpi; extra == 'vision'
Requires-Dist: pillow; extra == 'vision'
Requires-Dist: timm; extra == 'vision'
Requires-Dist: torch>=2.0.0; extra == 'vision'
Requires-Dist: torchvision; extra == 'vision'
Requires-Dist: transformers; extra == 'vision'
Provides-Extra: web
Requires-Dist: fastapi; extra == 'web'
Requires-Dist: jinja2; extra == 'web'
Requires-Dist: pydantic; extra == 'web'
Requires-Dist: uvicorn[standard]; extra == 'web'
Description-Content-Type: text/markdown

<div align="center">
  <a href="https://github.com/linfeng-z/Retriever"><img width="400px" height="auto" src="assets/retriever-illustrative.jpeg"></a>
</div>



# 🐕 <span style="background: linear-gradient(45deg, #e96443 0%, #904e95 25%, #e65c00 50%, #f9d423 75%, #fc00ff 100%); -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text; font-weight: bold; font-size: 1.1em;">**Retriever**</span>

## **Building Modular Closed-loop Robot Agents with Causal Functional Composition**

<!-- **Retriever: a type-safe runtime for robotics dataflow pipelines** -->

This repository is the **Retriever core/runtime** package:

- Author pipelines as a typed graph (`Pipeline`)
- Verify/compile to a backend-agnostic IR (done automatically at runtime)
- Execute on a backend (`Pipeline.run(...)`): local multiprocessing or dora-rs
- Debug step-by-step in-process (`Pipeline.step(...)`)

System-level pipelines, robot/simulator integrations, and heavier model stacks belong in the companion **GoldenRetriever** repository or other external packages.

---


## Canonical Runtime Workflow

Critical ideas:

- `@io` defines typed message envelopes.
- `Flow[I, O]` defines node logic.
- `flow @ clock` decides when a node runs.
- `Pipeline.connect(..., sync=...)` wires nodes and declares sampling behavior.
- `pipe.run(...)` is for backend execution; `pipe.step(...)` is for in-process debugging.

Minimal example:

```py
from retriever.flow import Flow, Pipeline, Rate, Trigger, Latest, 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")
source = Source() @ Rate(hz=2)
double = Double() @ Trigger("value")
pipe.connect(source, double, sync=Latest())

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

Debugging:

```py
result = pipe.step(dt=0.5)
print(result.executed)
pipe.close_stepper()
```

Short docs path:

- Quickstart: `docs/quickstart.md`
- Handbook: `docs/handbook.md`
- Runtime guide: `docs/guide_runtime.md`

## Setup (overview)

Use Python 3.11 for the pinned runtime environment in this repo.

Quick start with [Pixi](https://pixi.sh):

```sh
curl -fsSL https://pixi.sh/install.sh | bash
pixi run demo-webcam-detection
```

`pixi.lock` is multi-platform (osx-arm64, linux-64). Commit it for reproducible installs; other platforms can re-lock after adding the platform to `pixi.toml` and running `pixi install`.

Pixi manages its own env. If you prefer `uv`/`pip`, use a separate conda/venv to avoid mixing managers. Pixi installs the PyPI portion using `uv` internally; you usually don't need to run `uv` yourself when using Pixi.

Full installation (Pixi/conda/uv), dora CLI notes, and troubleshooting: `docs/getting_started/install.md`.

Runtime/core manifests in this repo:

- `pyproject.toml`
- `pixi.toml`

## Development

- Development workflow, pre-commit hooks, and QA steps: `docs/contributing.md`

## Documentation

Docs live in `docs/`:

- Runtime handbook (canonical): `docs/handbook.md`
- Quickstart: `docs/quickstart.md`
- Architecture: `docs/architecture.md`
- Tutorials: `docs/tutorials/index.md`
- Install: `docs/getting_started/install.md`
- Runnable examples: `examples/tutorial/` and `examples/control_demo.py`

## Roadmap

Recent features:
- **Main Thread Flow** (`@gui_flow`): Run flows in main thread for native GUI support (MuJoCo viewers, Qt, etc.)
  - Public examples in this repo currently focus on the tutorial/runtime surface.
