# Golden Retriever

GoldenRetriever is the maintained applied reference layer for Retriever: robot-facing examples, reusable robot payload references, simulator and visualization lanes, expected artifacts, and Retriever Hub pack candidates. Use it after the core Retriever visual quickstart when you want runnable robot-facing examples rather than runtime concepts alone.

## Public Surfaces

- Retriever core docs: https://retriever.build/
- Golden overview: https://golden.retriever.build/
- Golden Hub proof: https://golden.retriever.build/examples/golden-hub-proof/
- Golden example catalog: https://golden.retriever.build/examples/
- Golden simulation and visualization guide: https://golden.retriever.build/examples/simulation-visualization/
- Golden Hub reference: https://golden.retriever.build/hub/
- Golden export catalog: https://golden.retriever.build/hub/export-catalog/
- Golden pack roadmap: https://golden.retriever.build/hub/pack-roadmap/
- Golden robot payload reference: https://golden.retriever.build/robot-payloads/

## Boundary

GoldenRetriever is not a second runtime package. Golden maintains robot-facing examples, reusable robot payload references, simulator/visualization lanes, notebooks, and Hub pack candidates on top of the core `retriever` runtime.

## Canonical Path

1. Run `pixi run demo-golden-hub-pack` to prove the Golden Hub extension boundary.
2. Continue to the example catalog for perception, memory, language, composition, simulation, visualization, and robot payload and Hub pack examples.
3. Use the core Retriever docs only when Flow, Pipeline, clocks, sync, replay, or Hub-loader mechanics are the question.
4. Promote source examples into Hub packs only when they are import-safe, versioned, smoke-tested, documented, and useful outside this repository.

## Current Retriever Hub Pack Surface

The current manifest-declared Golden pack surface is the robot-facing payload pack declared by the Hub manifest: `WorldState`, `RobotState`, `BeliefGraph`, `Skill`, `Plan`, `StructuredPlan`, `TaskGoal`, `Trajectory`, `ExecutionStatus`, `Action`, `Command`, `Status`, `convert_to_arrow`, and `convert_from_arrow`.

```python
from retriever import hub

WorldState = hub.use("openretriever/golden-retriever:WorldState")
```

## Agent First Path

Run this sequence from a GoldenRetriever source checkout when you need a safe public smoke pass:

```bash
pixi run demo-golden-hub-pack
pixi run -e golden-retriever demo-perception-detection-flow
pixi run demo-robosuite-mock
pixi run demo-pipeline-html-viz
pixi run demo-robotics-typing-catalog
```

Expected artifacts: Hub export/registry/Arrow terminal proof, exit-zero synthetic perception flow, `[mock step=...]` robosuite trace lines, `out/golden_retriever_closed_loop_viz.html`, and robot payload catalog output.

## Agent Decision Table

| If the user asks for... | Start with | Do not start with |
| --- | --- | --- |
| A safe Golden smoke | `pixi 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 | `pixi run demo-robosuite-mock` | real robosuite until the mock trace works |
| Graph visualization | `pixi run demo-pipeline-html-viz` | screenshots or stale generated HTML |
| Robot payload reuse | `pixi run demo-robotics-typing-catalog` | ad hoc dict payloads or source-only imports |

If a safe command fails, keep the example, task, docs, and expected output aligned before promoting a new command.

## Optional Lanes

Only start these when the user explicitly asks for the relevant environment:

- Webcam/Rerun: `pixi run -e torch demo-webcam-rerun`
- TWIST2/MuJoCo: `pixi run -e twist2 demo-twist2-rerun`
- Robosuite mock + HTML graph visualization: use the Golden simulation and visualization guide.
- Real robosuite Lift: install the optional robosuite dependency first, then run `pixi run demo-robosuite-lift`
- Model-backed perception/memory: use the documented optional model-backed examples after the mock path is green.

## Agent Guidance

- Start from the repository guidance, then verify against the hosted docs and safe smoke commands.
- Use hosted docs for public behavior and the source checkout for runnable examples.
- Do not treat source examples as Retriever Hub packs unless the Hub manifest exports them.
- Keep public docs limited to public source paths, hosted docs, and public URLs.
- Prefer mock/smoke commands before optional hardware, simulator, model, GPU, or network dependencies.
- When editing examples, update the matching Pixi task, docs page, and expected output in the same change.