debug-retriever 0.1.4

Retriever: Building Modular Robot Agents with Causal Functional Composition

🐕 Retriever

Building Modular Closed-loop Robot Agents with Causal Functional Composition

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:

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:

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:

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.