Retriever Hub

Retriever Hub loads reusable robot code straight from a git repository. Point it at org/name:Export and it returns the object — a Flow class, a type, a transform, or a pipeline builder — with no PyPI wheel and no copied source.

from retriever import hub
from retriever.flow import Rate

LidarSlam = hub.use("your-org/lidar-slam:LidarSlamFlow")
slam = LidarSlam(resolution=0.05) @ Rate(hz=10)

A module declares its public surface in one [tool.retriever.module] manifest section. hub.use reads that manifest from the repo, imports the declared package under a private commit-scoped namespace, and hands back the requested export.

Three surfaces, one distribution path

• Core runtime — retriever-core, imported as retriever. Flow, Clock, sync policies, Pipeline, stepping, replay, IR, backends, and the standard types in retriever.types.*.
• Retriever Hub — the manifest + index protocol that turns any repo into a loadable pack of Flows, types, transforms, and composed pipelines.
• GoldenRetriever — the maintained applied catalog: a real Hub type pack of robot-facing payloads, plus example lanes. Built on the runtime, not a second one.

Reach for Hub when a robot system should reuse a stable boundary instead of copying code.

One runnable proof

The primitive Hub distributes is a composable pipeline. Prove it composes locally — this runs in the core checkout:

pixi run demo-composable-pipelines

=== Extend Declared Pipeline ===
internal flows: ['counter', 'policy']
policy output after replacement: ProcOut(value=104)

=== Compose Pipeline As Flow ===
[outer] value=5 aux=99
wrapped stage output: Tutorial_Composable_CounterOutput(aux=99, value=5)

A registered pipeline can be extended in place or dropped in as a single Flow stage — the two surfaces a Hub module exports. For the loader running against a real manifest, see the GoldenRetriever pack proof.

Hub packs and modulesHow hub.use(…) resolves a ref: index, git tag, cache, and the return contract.PublishingMake your repo hub-loadable: the real [tool.retriever.module] manifest and import-safety rules.Composable pipelinesExport a pipeline builder, then reuse it as a live graph or one Flow stage.GoldenRetriever packsGoldenRetriever as a Hub type pack, with a runnable manifest-load proof.First GoldenRetriever proofThe applied Hub-pack path, then perception, memory, simulation, and visualization lanes.

Recommended route

1. Run the core visual quickstart.
2. Read Hub packs and modules for refs, exports, and loading semantics.
3. Run the GoldenRetriever pack proof to watch a real manifest load through the Hub loader.
4. Read Publishing when you want to expose your own repo the same way.

The boundary to keep straight: GoldenRetriever is not a second runtime package. The runtime is retriever-core (imports as retriever); GoldenRetriever is the maintained examples and pack surface on top of it.