Skip to main content

BlobHub Python SDK

BlobHub is the one-stop shop for agentic development. It is a new set of primitives to build against, which makes agents, copilots and the apps that use them easy to design and build — and inherently compatible, because they are all made of the same parts. Agents live and work inside BlobHub, so it is the system of record and action for them: every agent runs inside guardrails the company sets, and everything it does is on the record, written by the work itself. Under the hood, BlobHub is a serverless platform for versioned blob storage with workflow automation: a workflow, a schedule or a model is a typed, versioned blob behind one REST API.

The BlobHub Python SDK, blobhub, runs workflows and reads their record from Python and notebooks. Its workflow module runs a definition that is already deployed, follows a session's events and waits for a run; a generic layer reaches blobs, revisions and any blob type's data commands, and typed modules cover ONNX models and OrientDB graphs. It is a synchronous client of the public REST API, and finds its key the way the CLI does, from an argument, the environment or a shared profile, falling back to an anonymous token that reads public content.

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

Documentation

The full guide and reference are at docs.blobhub.io.

License

MIT

Metadata

Release files for blobhub 0.4.1

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.1
File Size Uploaded Provenance Actions
blobhub-0.4.1.tar.gz 32.4 kB With provenance Details for blobhub-0.4.1.tar.gz

Built distribution (wheel)

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

Total release size: 77.7 kB

Release files / blobhub-0.4.1.tar.gz

Download URL blobhub-0.4.1.tar.gz
Size 32.4 kB
Tags Source
SHA-256 checksum
How to use checksums
d42828a1ad7f6f4de2563f095bfb41c59f658943137b8205c72067183833b5f9
BLAKE2b-256 checksum
How to use checksums
510a194840479b7de68172c592ba04b7eaf05189a2cb753a962acda14712a9cc
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 15, 2026.

Transparency log

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

Download URL blobhub-0.4.1-py3-none-any.whl
Size 45.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
45e184d57c31985369adf52f59715c23739184909bff6ca1128d6ddc22d221af
BLAKE2b-256 checksum
How to use checksums
d0853d5ac776ef85d94b3e56d316aa352a2df04ea408d6d2e7f0627faf8ba1e5
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 15, 2026.

Transparency log

Security for blobhub 0.4.1

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.1.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 15, 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