GoldenRetriever Example Catalog

GoldenRetriever examples are the applied continuation of the core Retriever quickstart. Each one is a real Pipeline of typed Flows you can run, step in-process, and render. Start with the mock-safe commands below, confirm the output, then opt into camera, simulator, or model-backed lanes.

Try it first

Set up once with pip install retriever-core (gives you the retriever command), then git clone this repo and run retriever install. After that:

• retriever run <demo> runs an example in the default environment.
• pixi run -e golden-retriever <demo> runs the heavier perception, memory, and language examples, which pull in extra model dependencies. GoldenRetriever uses Pixi as its environment manager; retriever run wraps it for the default set.

Every command below runs with no robot, camera, model, or network. Run one, match the first line of output, then open its page for the code and the full run.

retriever run demo-golden-hub-pack
# GoldenRetriever pack exports: WorldState, BeliefGraph, Skill, Plan, Trajectory, convert_to_arrow, convert_from_arrow

pixi run -e golden-retriever demo-composable-pipelines
# policy output after replacement: ProcOut(value=104)

retriever run demo-robosuite-mock
# [mock step=002] object_z=0.820 gripper_z=0.940 reward=0.000 done=False

retriever run demo-pipeline-html-viz
# Pipeline: visualization_demo  ->  writes out/golden_retriever_closed_loop_viz.html

Command	What it proves	Page
demo-golden-hub-pack	GoldenRetriever extends Retriever through a Hub manifest: exports load, registry resolves, Arrow round-trips.	Hub proof
demo-composable-pipelines	A registered pipeline can be extended and wrapped as a Flow, payloads staying typed.	Composition
demo-robosuite-mock	Environment-as-Flow and policy-as-Flow close a feedback loop with no simulator install.	Simulation
demo-pipeline-html-viz	The runtime IR validates and renders to ASCII plus an inspectable HTML graph.	Visualization

Find an example

Once a proof runs, walk the perception → memory → language → composition ladder on deterministic payloads before adding heavier inputs.

pixi run -e golden-retriever demo-perception-detection-flow   # pixels -> typed Detection2D
pixi run -e golden-retriever demo-memory-belief-flow          # detections -> remembered SceneBelief
pixi run -e golden-retriever demo-language-caption-plan       # caption -> primitive PlanText

• Perception and memory — synthetic detections, belief tracking, and pointing over standard retriever.types.perception payloads.
• Language and grounding — captions and grounded references turned into primitive plans, no LLM required.
• Pipeline composition — registry-backed graphs you can extend and nest.
• Simulation and visualization — mock-safe robosuite, optional Rerun lanes, and HTML graph rendering.
• Robot payloads — world state, belief, plans, trajectories, and dataset/export profiles reused across examples.

Suggested order

1. Run the Hub proof so you know GoldenRetriever loads without optional robot dependencies.
2. Run one deterministic perception or memory demo and recognize its typed output before adding heavier inputs.
3. Render the graph with demo-pipeline-html-viz when wiring is unclear — inspect ports, clocks, and feedback edges first.
4. Only then opt into camera, model-backed perception, real simulator, or dataset-export lanes.

Related runtime docs

These pages assume the Flow, Pipeline, clock, and sync mental model from the core Retriever docs. GoldenRetriever focuses on robot-facing examples, typed payloads, and Hub pack candidates built on that runtime.

How mature each example is

Level	Meaning	User expectation
Hub-loadable pack	Declared by the Hub manifest and loaded by Retriever Hub.	Safe to import and reuse as a pack boundary.
Promoted demo	Named Pixi task, docs page, expected output, and smoke coverage.	Safe for first-run docs and CI checks.
Source reference	Useful implementation pattern, not yet a public launch point.	Read the source after the promoted path works.
Optional integration	Requires camera, model, simulator, GPU, robot, or external service.	Use only when the dependency story is explicit.