GoldenRetriever Pack Boundary

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 A Pack Contains

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.

Prove the boundary 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.

pixi 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 `pixi 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.

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.

Runtime Bridge

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.