Using the Hub (Notebook)

The notebook companion to Hub Packs and Modules: hub.use("org/name:Export") fetches a module from its git repo and hands back the exported object itself. The public module openretriever/hello-world is live right now, so every output block below is captured from a real, networked run — the only requirement beyond retriever-core is a network connection.

⬇ Download .ipynb ▶ Open in Colab

Load one export by its ref

A ref is {org}/{name}:{Export}. Here openretriever/hello-world is the module and HelloFlow is one name from its export table. hub.use fetches the repo, imports it under a private namespace, and returns the class itself — so you construct it and call step() exactly like a local Flow.

from retriever import hub

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

flow = HelloFlow()
print("returned:", HelloFlow.__name__)
print("step:", flow.step(None).text)

Output

returned: HelloFlow
step: hello, world

Takeaway: the return value is the real class, not a wrapper — HelloFlow() builds an instance and step(None) runs it in-process, with no backend or clock involved.

An export can be any Python object

The export table is not limited to Flows. A module can publish plain functions, types, or values under the same ref shape. greet is a function export — load it and call it directly.

greet = hub.use("openretriever/hello-world:greet")
print(greet("retriever"))

Output

hello, retriever

Takeaway: hub.use(“org/name:Export”) returns whatever the manifest maps that name to — a class, a function, a type, a value — never a generic proxy.

Load the whole module as a proxy

Drop the :attribute and hub.use returns a ModuleProxy over the declared export table. dir(proxy) lists the exports and its repr names them.

mod = hub.use("openretriever/hello-world")
print("repr:", repr(mod))
print("exports:", dir(mod))
print("via proxy:", mod.HelloFlow().step(None).text)

Output

repr: <HubModule 'openretriever/hello-world' exports=['HelloFlow', 'greet']>
exports: ['HelloFlow', 'greet']
via proxy: hello, world

Takeaway: the proxy is a convenient handle when you want several exports from one module without repeating the ref.

The manifest is the public surface

A proxy exposes only declared exports. Reaching for a name that is not in the manifest raises AttributeError listing what is actually available — so the [tool.retriever.module] table, not the file tree, defines what consumers see.

try:
    mod.SecretFlow
except AttributeError as exc:
    print("AttributeError:", exc)

Output

AttributeError: Module 'openretriever/hello-world' has no export 'SecretFlow'. Available exports: ['HelloFlow', 'greet']

Takeaway: undeclared names are invisible, so a module author can refactor internals freely as long as the export table stays stable.

The resolution chain, once

Given a ref, the loader walks a fixed chain: parse {org}/{name}[:attribute][@version], look {org}/{name} up in the Hub index to get the git repo URL, resolve the version to a commit (newest semver tag, or the tag you pinned), download and cache that commit under ~/.retriever/hub/cache/, read [tool.retriever.module] from the repo’s pyproject.toml for the export table, then import the package under a private, commit-scoped namespace and return the export. The result is cached in-process, so a second hub.use of the same ref returns the same object without re-fetching.

first = hub.use("openretriever/hello-world:HelloFlow")
second = hub.use("openretriever/hello-world:HelloFlow")
print("same object cached in-process:", first is second)

from retriever.hub._ref import parse_ref

ref = parse_ref("openretriever/hello-world:HelloFlow")
print("parsed ->", f"org={ref.org} name={ref.name} attr={ref.attribute} version={ref.version}")

Output

same object cached in-process: True
parsed -> org=openretriever name=hello-world attr=HelloFlow version=None

Takeaway: index → repo → commit → [tool.retriever.module] exports is the whole chain; add @version to pin a tag and refresh=True to bypass the cache. Next: Publishing makes your own repo hub-loadable through the same loader.

This page is generated from notebooks/src/using_the_hub.py (jupytext py:percent source). Grab the runnable notebook and run every cell yourself.