GoldenRetriever

Applied Retriever reference

GoldenRetriever examples start where the core quickstart ends.

Run robot-facing examples, inspect visual artifacts, and reuse robot payload types on top of the core Retriever runtime.

Run the first GoldenRetriever proofLoad GoldenRetriever robot payloads through Retriever Hub with no robot, camera, model, simulator, or network dependency.Browse example resultsPick an applied lane by expected output, artifact type, and dependency level.Open visual artifactsInspect generated HTML graphs, mock simulator traces, and optional Rerun lanes.

First GoldenRetriever proofExample catalogVisual artifactsReusable packsRobot payloads

GoldenRetriever is not a second runtime. Core Retriever owns Flow, Pipeline, clocks, sync, IR, replay, execution, and Hub mechanics. GoldenRetriever owns applied robot examples, robot payload types, visualization lanes, and Hub pack candidates. Need runtime concepts first? Use the core Retriever docs.

Quick Start

Start here after the core Retriever visual quickstart works. GoldenRetriever runs on the same retriever CLI; it is a separate source checkout of the examples:

pip install retriever-core           # if you don't already have the `retriever` command
git clone https://github.com/openretriever/golden-retriever.git
cd golden-retriever
retriever install                    # sets up the example environment (wraps Pixi)
retriever run demo-golden-hub-pack   # payload exports + Arrow round-trip

Perception, memory, and language examples need extra model dependencies, so they run in the golden-retriever Pixi environment (pixi run -e golden-retriever demo-...). Everything else runs through retriever run.

What does this do?

The command loads the GoldenRetriever Hub exports through Retriever Hub, constructs representative payloads, and round-trips a command through Arrow helpers. It requires no robot, camera, simulator, model, network service, or GUI.

What you should see

Hub proofTerminal export summary

retriever run demo-golden-hub-pack
# GoldenRetriever pack exports: WorldState, BeliefGraph, Skill, Plan, ...
# Arrow round-trip: Action OK

Example proofDeterministic perception flow

pixi run -e golden-retriever demo-perception-detection-flow
# synthetic scene -> typed detections
# steps complete

Graph proofSelf-contained HTML graph

retriever run demo-pipeline-html-viz
# writes out/golden_retriever_closed_loop_viz.html
# prints a compact ASCII graph

Where to go next

01First proof

Validate the Hub extension boundary and payload exports.

02Example catalog

Choose a runnable lane by output, artifact, and dependency level.

03Visual artifacts

Inspect HTML graphs and mock-safe simulator traces before heavier integrations.

04Promote to Hub

Promote stable payloads and helpers only after the boundary is lightweight and smoke-tested.

How the pieces fit

Surface	Owns	Start here when…
Core Retriever	Flow, Pipeline, clocks, sync policies, IR, execution, replay, graph rendering, and Hub loading mechanics.	You need to understand or debug the runtime model.
GoldenRetriever	Applied robot examples, robot payload types, simulator lanes, visualization demos, and Hub pack candidates.	You want runnable robot-facing examples after the core quickstart.
Retriever Hub	The packaging boundary for stable Flows, robot payload types, and conversion helpers.	You want reuse without depending on source-tree layout.

Common Patterns

Need	Start with	Avoid first
Safe GoldenRetriever smoke	retriever run demo-golden-hub-pack	Camera, simulator, model, or network setup.
Example behavior	pixi run -e golden-retriever demo-perception-detection-flow	Optional model-backed lanes.
Simulator integration	retriever run demo-robosuite-mock	Real robosuite before the mock trace works.
Graph visualization	retriever run demo-pipeline-html-viz	Screenshots or stale generated HTML.
Robot payload reuse	retriever run demo-robotics-typing-catalog	Ad hoc dict payloads or source-only imports.

Continue

First GoldenRetriever proofLoad the GoldenRetriever Hub exports through Retriever Hub.Example catalogPick a lane by expected artifact and dependency level.Robot payload typesChoose payloads for world state, belief, plans, trajectories, and events.Visualization lanesInspect HTML graphs, mock simulator traces, and optional Rerun streams.

For AI agents: llms.txt mirrors the same GoldenRetriever path for agents and audits.