Skip to main content

BlobHub Python SDK

blobhub is the Python SDK for BlobHub, a platform for versioned blobs: ONNX models, graphs, workflows and more. It reads and writes blobs and their revisions, runs any blob type's data commands, and has typed modules for ONNX models, OrientDB graphs and workflows.

Install

pip install blobhub

Python 3.10 or newer. The only dependencies are httpx and PyYAML.

Connect

import blobhub

hub = blobhub.connect()
print(hub.identity)        # Identity(source='profile:work', api_url='https://api.blobhub.io/v1')

connect() makes no network call. It resolves each value from the first source that has it:

Value 1 2 3 4
profile name profile= BLOBHUB_PROFILE the file's default: none
API key api_key= BLOBHUB_API_KEY the profile's key an anonymous token
API URL api_url= BLOBHUB_API_URL the profile's url https://api.blobhub.io/v1
  • Profiles are the ones blobhub-cli's blobhub login stores in ~/.blobhub/credentials.yaml. The SDK reads that file and never writes it. A file readable by group or other is refused: chmod 600 ~/.blobhub/credentials.yaml.
  • blobhub.connect(profile="work") picks a profile; blobhub.connect(api_key="…") passes a key directly.
  • blobhub.connect(anonymous=True) reads public content with no credential at all, and ignores the profile file. Combined with api_key= or profile= it raises ValueError.
  • hub.identity says where the key came from. The key itself is never printed, logged or put in an error.

A short tour

blob = hub.blob("onnx-models", "super-resolution")    # org and blob, each an alias or an id
blob.type, blob.visibility, blob.default_revision_id

rev = blob.revision()                    # the default revision; blob.revision("<id>") for another
for r in blob.revisions():               # every revision, newest first
    print(r.id, r.phase, r.status)

rev.query("describe")                    # any read the blob's type supports
rev.command("<command>", key="value")    # any write; arguments set to None are left out

Revisions

draft = blob.create_revision("retrain")  # needs a committed default revision; waits until ready
draft.commit("v2")                       # waits until committed

ONNX models

from blobhub.types.onnx import Onnx

model = Onnx(rev)                        # or rev.typed()
model.artifacts()                        # [Artifact(path='model.onnx', size=…), …]
path = model.download()                  # model.onnx, cached under ~/.cache/blobhub
model.download("model.tar.gz", dest="./model.tar.gz")
model.topology()                         # the graph without its weights

operation = Onnx(draft).upload("super_resolution.onnx")   # packs, uploads, waits for processing

A committed revision's download is cached and reused; a draft's is fetched again each time. Large files move in parts over presigned URLs, and an upload that fails part-way is cancelled.

Graphs

from blobhub.types.orientdb import Graph

graph = Graph(rev)                       # or rev.typed() for a blobhub.graph.orientdb blob
result = graph.execute("SELECT FROM V WHERE name = :name", {"name": "fox"})
result.vertices, result.edges            # OrientDB records, each with its "@rid" and "@class"
graph.execute("CREATE VERTEX V SET name = 'fox'", write=True)

A read runs one SELECT, TRAVERSE or MATCH statement; anything else needs write=True, which a committed revision refuses with Conflict. Parameters are a dict for :name placeholders or a list for ?. A statement returns at most 50 records. When OrientDB rejects a statement, the CommandError message gives its reason.

Workflows

from blobhub.types.workflow import Workflow

question = {"type": "message", "message": {"role": "user", "content": [{"type": "text", "text": "Why?"}]}}
run = Workflow(rev).execute(             # or rev.typed() for a blobhub.compute.workflow blob
    "summarize",                         # a definition alias or id, or "<org>/<blob>/<revision>/<definition>"
    input_data={"question": question},   # component alias to value
    session="sdk-demo",                  # an alias, created when absent, or an id; None starts a fresh session
)
print(run.id, run.session_id, run.url)   # url opens the execution in blobhub.io's debugger
# run.stop()                            # while it runs, instead of waiting: only a running execution stops
status = run.wait(timeout=900, on_event=print)   # "completed", "failed" or "stopped"
for event in run.events():               # the execution's log, oldest first; `after=` resumes past an id
    print(event["type"], event.get("message"))

execute returns as soon as the execution exists. An input value reaches the workflow's data component whose alias port names it and whose persistence is execution. A session that is not open is refused with Conflict before anything is created. wait gives up with WaitTimeout and leaves the execution running. Writing and deploying definitions is blobhub-cli's job.

Session events and listeners

A session keeps an append-only stream of what happened in it: thread items, object writes, graph changes, and the start and end of its executions. Workflow.session gives a handle on a session that already exists.

from datetime import datetime, timezone

from blobhub.types.workflow import Workflow, boundary_id

workflow = Workflow(rev)
session = workflow.session("sdk-demo")                      # an id or an alias; never creates one
posted = {"types": ["thread.item_posted"], "aliases": ["missions/**"]}
for event in session.events(posted, limit=20):              # oldest first, paged for you
    print(event["id"], event["type"], event["object"]["alias"])

newest = session.latest()                                   # the newest event, or None for an empty stream
for event in session.events(posted, after=newest["id"] if newest else None, follow=True, timeout=60):
    print(event["type"])                                    # follow=True keeps reading until `timeout`

nine = datetime(2026, 11, 10, 9, 0, tzinfo=timezone.utc)
since_nine = session.events(after=boundary_id(nine))        # every event from 09:00 on

An event's id is minted just before its row is written, so a row can commit after a row with a larger id. A followed read re-reads a minute back and drops what it already delivered, so it finds such a row; a plain after= read does not. session.latest() followed by follow=True starts a read from now. A followed read never goes below its after, so a caller that must not miss a late row starts from boundary_id(time.time() - 60) instead.

A listener is a filter on the stream that does something with each match. A declared listener is a definition of category listener; Session reads and switches them, and lists the executions they started.

for entry in session.listeners(binding="declared"):         # alias, enabled, counts, last_outcome, ...
    print(entry["alias"], entry["enabled"], entry["counts"])

session.set_listener("on_posted", False)                    # off for this session; an alias or a definition id
session.set_listener("on_posted", True)

for run in session.executions(listener="on_posted"):        # the executions this listener started, newest first
    print(run.id, run.status, run.source["kind"])           # source: what started it, e.g. "listener" or "api"

run = next(session.executions())
ended = next(run.session.events({"types": ["execution.ended"], "executions": [run.id]}), None)
print(ended["execution"]["status"] if ended else None)      # the status `wait` returns, as the stream recorded it

wait returns once the execution record is terminal. With on_event, it first makes one last read of the execution log, with no settle wait, so a row another writer commits late can appear only afterwards. flow.* and processor.* rows live only in the execution log, never on the session stream: read such a row with run.events(after=...) at least 60 s after wait returns.

A listener is written as a definition and deployed with blobhub-cli; the SDK does not write definitions. Two patterns on the invocation_target of a workflow target:

# the batch of events, as messages, into an input named "events"
invocation_target:
  workflow: {definition: orchestrator}
  input_data:
    - {alias: events, value: "{{ batch.messages }}"}
---
# the thread item the last event posted, as one message, into an input named "question"
invocation_target:
  workflow: {definition: reply}
  input_data:
    - {alias: question, value: "{{ item.message }}"}

Errors

Every error is a blobhub.BlobHubError carrying the server's error code, a message and the HTTP status: AuthError (401), PermissionDenied (403, also answered for many missing resources), NotFound (404), Conflict (409, e.g. revision_not_writable), RateLimited (429), ServerError (5xx), NetworkError and its subclass RequestNotSent, CommandError, ConfigError, TypeMismatch, OperationFailed and WaitTimeout. When the client found no key and fell back to an anonymous token, an AuthError or PermissionDenied message says so. When the server's failure carries a details list, the error keeps it in details.

Reads are retried on throttling, server errors and network failures. Writes are retried only when the failure proves the request never ran, so a retry can never repeat a write.

Raw requests

hub.request("GET", f"revisions/{rev.id}/metadata/readme")

Migrating from 0.1.x

0.1.x cannot talk to the current API, so there is no compatibility layer.

0.1.x 0.2
Blob(org_id, blob_id, api_key=…) from blobhub.blob blobhub.connect(api_key=…).blob(org, blob)
blob.revisions.latest() blob.revision() (the default revision)
revision["status"], revision[Revision.FIELD_PHASE] revision.status, revision.phase
from blobhub.presets.onnx import Onnx, Model from blobhub.types.onnx import Onnx
onnx.upload(Model.from_local_file(onnx, path)) returns True onnx.upload(path) returns an Operation
onnx.download() returns a Model; model.path onnx.download() returns a Path
models stored under ~/.blobhub/ models cached under ~/.cache/blobhub/revisions/<revision>/
CallFailure, BadRequest, Forbidden the classes in blobhub.errors

License

MIT

Metadata

Release files for blobhub 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for blobhub 0.4.0
File Size Uploaded Provenance Actions
blobhub-0.4.0.tar.gz 31.9 kB With provenance Details for blobhub-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for blobhub 0.4.0
File Interpreter ABI Platform Actions
blobhub-0.4.0-py3-none-any.whl Python 3 none any Details for blobhub-0.4.0-py3-none-any.whl

Total release size: 76.7 kB

Release files / blobhub-0.4.0.tar.gz

Download URL blobhub-0.4.0.tar.gz
Size 31.9 kB
Tags Source
SHA-256 checksum
How to use checksums
b9e00550e18a958136428ed74d9616fe462ea2aac403e890bec51f96dead5b92
BLAKE2b-256 checksum
How to use checksums
176a1302c1b3b191db8b624e6b56ea2896a83eb2b3166d55f6c4bd18c62f59bc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / blobhub-0.4.0-py3-none-any.whl

Download URL blobhub-0.4.0-py3-none-any.whl
Size 44.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
428776b913b832c1c9ee2c5addbdca4e6bf1112b241953cb829e934cea95bcc7
BLAKE2b-256 checksum
How to use checksums
32a3885328a65b5ce7f2f30d12b673ffe5380e185dc6f6f4672ce0869b1df80f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for blobhub 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for blobhub-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page