GoldenRetriever Hub Packs

GoldenRetriever publishes its applied payloads as a Retriever Hub module. Once the repository and Hub index are public, another project loads a robot payload by name without cloning GoldenRetriever or knowing its source tree:

from retriever import hub

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

What’s in the pack

The exported names live in [tool.retriever.module] in pyproject.toml, not in scattered import paths. This is the exact manifest Hub reads:

[tool.retriever.module]
module = "retriever_typing"
min_retriever_version = "0.0.1"

[tool.retriever.module.exports]
WorldState = "retriever_typing.robotics_types:WorldState"
Skill = "retriever_typing.robotics_types:Skill"
Plan = "retriever_typing.robotics_types:Plan"
convert_to_arrow = "retriever_typing.conversions:convert_to_arrow"
# ... full list on the export catalog page

The contract across versions is the registered schema, not class identity. Pin one ref per app. Standard types stay in retriever-core; GoldenRetriever’s exports compose them and never redefine one.

Check that it loads

hub.use(...) against the private repo will not resolve over the network yet, so the smoke demo loads this repo’s manifest directly through the runtime Hub loader (retriever.hub._loader.load_exports) — the same code path Hub uses, without network access.

retriever run demo-golden-hub-pack

Real output — exports load, WorldState is visible through the unified registry under the Hub namespace, and the Arrow helpers round-trip an Action:

GoldenRetriever pack exports: WorldState, BeliefGraph, Skill, Plan, Trajectory, convert_to_arrow, convert_from_arrow
Registry WorldState: _retriever_hub.golden_hub_pack_smoke__retriever_typing.robotics_types.WorldState
Constructed WorldState: ['cup']
Constructed Plan skills: ['pick']
Arrow round-trip: Action OK
Hub reference: hub.use("openretriever/golden-retriever:WorldState")
Graph proof: run `retriever run demo-pipeline-html-viz` to validate and render an IR HTML artifact.

The _retriever_hub.golden_hub_pack_smoke__... prefix is the loader isolating the pack in its own namespace — the same behavior a real hub.use gets, so importing a pack can never clobber another project’s registry.

See hub.use() resolve over the network today

While GoldenRetriever’s own repository is not public yet, the openretriever/hello-world pack already is (tagged v0.1.0), so you can watch the full network path — index lookup, tag resolution, fetch, load — work end to end right now:

from retriever import hub

HelloFlow = hub.use("openretriever/hello-world:HelloFlow")

GoldenRetriever’s exports resolve exactly the same way once the repository is public.

Pack Rules

Rule	Why it matters
Export through the manifest.	The public surface is explicit and reviewable.
Keep imports lightweight.	Loading a pack must not pull in camera, simulator, model, robot, or network deps.
Smoke every export.	demo-golden-hub-pack proves the boundary loads and round-trips.
Document expected output.	Users need to recognize success.

Related runtime docs

Loader mechanics, registry internals, and module packaging live in the core Retriever docs. GoldenRetriever only defines the applied robot-facing pack boundary.

Continue

• Export catalog — every exported name and its source path.
• Pack maturity guide — when a source example is ready to become a pack.
• GoldenRetriever Hub proof — the smallest command that validates the boundary.

Source: pyproject.toml [tool.retriever.module]; demo examples/advanced/core_composition/golden_hub_pack_smoke.py.