debug-retriever 0.1.2

Retriever: Building Modular Robot Agents with Causal Functional Composition

🐕 Retriever

Building Modular Closed-loop Robot Agents with Causal Functional Composition

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):

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:

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