Metadata-Version: 2.4
Name: debug-retriever
Version: 0.1.2
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.11
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: 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'
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 evolving to focus on the **Retriever core/runtime**:

- Author pipelines as a typed graph (`Pipeline` / `FlowContext`)
- 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, integrations (robots/sim), and heavy model stacks will live in a separate **Golden Retriever** (reference system) repository as part of an ongoing split.

---


## Canonical Runtime Workflow

**Unified API (Recommended)**: `retriever.connect(...)` → `retriever.run(...)` (Implicitly handles validation/IR).

**Low-Level API**: `Pipeline (or FlowContext) → validate() → IRStruct → (optional) build_execution() → execute_ir()`

Minimal example (Typed Flows + Unified DSL):

```py
from dataclasses import dataclass
from retriever.flow import Flow, flow_io
import retriever

@flow_io
@dataclass
class SrcOut:
    value: int

@flow_io
@dataclass
class AddOut:
    value: int

class Source(Flow[None, SrcOut]):
    def run(self, _):  # type: ignore[override]
        return SrcOut(value=1)

class AddOne(Flow[SrcOut, AddOut]):
    def run(self, input: SrcOut) -> AddOut:
        return AddOut(value=input.value + 1)

# 1. Instantiate & Clock
src = Source() @ retriever.Rate(hz=10)
add = AddOne() @ retriever.Rate(hz=10)

# 2. Connect (Unified DSL)
retriever.connect(src, add)

# 3. Debug (Sync, In-Process)
retriever.step(dt=0.1)

# 4. Run (Async)
retriever.run(backend="multiprocessing", duration=1.0)
```

**Note**: For standard libraries (PyTorch, Gym), you can use the `retriever.lib.Wrapper` factory (see handbook).

More details: `docs/handbook.md`

## Setup (overview)

Use Python 3.10–3.12 (avoid 3.14; some deps lack wheels).

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`.

Golden/system split prep:

- Runtime/core manifests: `pyproject.toml`, `pixi.toml`
- Golden/system templates (to be moved to a separate repo): `pyproject-golden.toml`, `pixi-golden.toml`

## Development

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

## Documentation

Docs live in `docs/`:

- Runtime handbook (canonical): `docs/handbook.md`
- Architecture: `docs/architecture.md`
- Tutorials: `docs/tutorials/index.md`
- Install: `docs/getting_started/install.md`
- Advanced Examples: `examples/advanced/`
  - **Skill Switching**: Dynamic behavior switching pattern with **Fan-in** support (`examples/advanced/skill_switching/`)
  - **Native Controller**: Rust/C++ native extension bindings (`examples/advanced/native_controller/`)
  - **TWIST2 Simulation**: MuJoCo humanoid robot at 1000Hz physics + 50Hz policy (`examples/advanced/twist2_simulation/`)

## Roadmap

Recent features:
- **Main Thread Flow** (`@gui_flow`): Run flows in main thread for native GUI support (MuJoCo viewers, Qt, etc.)
  - See: `examples/advanced/twist2_simulation/` for usage example

