Retriever Hub Packs¶
GoldenRetriever is the maintained reference layer and proving ground for Retriever Hub packs. It shows how a repository outside the runtime exposes reusable robot-facing payloads through Retriever Hub while keeping heavier examples as source-level reference lanes until they are ready for stable pack contracts.
Mental model¶
retriever-core
Flow, Pipeline, clocks, sync policies, IR, runtime, Hub loader
GoldenRetriever
applied robotics payloads, example pipelines, simulator wrappers,
visualization demos, notebooks, and promotion candidates for future Retriever Hub packs
The current v1 Golden Hub contract is intentionally small and stable: applied robotics types plus conversion helpers. That gives downstream examples a common vocabulary without turning Golden into a second runtime package or forcing users to copy example code.
Pack lifecycle¶
A source example can be useful before it is a pack. A Hub-loadable pack needs a tighter contract: no heavyweight import side effects, versioned exports, a named smoke command, documented expected output, and a clear dependency level.
Load a Golden pack through Retriever Hub¶
The Retriever Hub reference shape is:
from retriever import hub
WorldState = hub.use("openretriever/golden-retriever:WorldState")
Plan = hub.use("openretriever/golden-retriever:Plan")
convert_to_arrow = hub.use("openretriever/golden-retriever:convert_to_arrow")
During local development and when working from source, pixi run demo-golden-hub-pack exercises the same manifest without network access.
What is pack-loadable today¶
See Export Catalog for the exact exports declared in pyproject.toml.
Promotion candidates¶
See Pack Roadmap. The short version: promote source examples into Hub packs only when they are import-safe, have serializable construction config, and have a documented smoke command.
What stays source-only¶
Golden source examples are useful before they become Hub packs. Keep camera, model-backed, simulator-heavy, hardware-bound, or operator-facing lanes as source-checkout examples until they have a documented dependency level, an import-safe construction path, and a smoke command.