> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Notebooks

> Four example notebooks ship inside the blobhub package; python -m blobhub.notebooks copies one out

Four Jupyter notebooks ship inside the `blobhub` package, written against this SDK. Three download a public ONNX
model and run it with ONNX Runtime, with no account. The fourth exports a model with PyTorch and uploads it to an
ONNX blob of yours. `blobhub.notebooks` lists them and copies one out of the package.

## Run one

```bash theme={null}
pip install blobhub
python -m blobhub.notebooks list
python -m blobhub.notebooks copy onnx/super-resolution      # writes ./super-resolution.ipynb
```

Open `super-resolution.ipynb` in JupyterLab, VS Code or any other Jupyter environment, and run it from the top. Its
first cell installs what it needs. To run it without opening it:

```bash theme={null}
pip install nbclient ipykernel
jupyter execute super-resolution.ipynb
```

## The notebooks

| Id | What it does | Credential |
| :- | :- | :- |
| `onnx/bi-att-flow` | Downloads the BiDAF model and answers questions about short passages. | none |
| `onnx/super-resolution` | Downloads a super-resolution model and triples the resolution of a photo. | none |
| `onnx/super-resolution-end-to-end` | Exports that model with PyTorch, uploads, downloads, runs it. | a writable key |
| `onnx/object-detection` | Downloads an SSD detector trained on COCO and draws what it finds in a photo. | none |

The three without a credential read the public blobs
[onnx-text-models/bi-att-flow](https://blobhub.io/onnx-text-models/bi-att-flow),
[onnx-vision-models/super-resolution](https://blobhub.io/onnx-vision-models/super-resolution) and
[onnx-vision-models/object-detection](https://blobhub.io/onnx-vision-models/object-detection). The two vision
notebooks fetch their input photo, and object detection its class labels, from `static.blobhub.io`. BiDAF's
passages and questions are written in the notebook, and NLTK downloads its tokenizer data.

Each notebook's first cell is its only `%pip install`:

| Id | Installs |
| :- | :- |
| `onnx/bi-att-flow` | `blobhub onnx onnxruntime nltk numpy` |
| `onnx/super-resolution` | `blobhub onnx onnxruntime Pillow numpy` |
| `onnx/super-resolution-end-to-end` | `blobhub "torch>=2.5" onnx onnxruntime Pillow numpy` |
| `onnx/object-detection` | `blobhub onnx onnxruntime Pillow numpy matplotlib` |

### Public models need no account

The three public notebooks connect with `blobhub.connect(anonymous=True)`. That ignores any profile stored on the
machine, so a stale, revoked or foreign profile cannot break them, and no sign-in is needed. Their downloads are
cached under `~/.cache/blobhub`, so a second run fetches nothing. See
[Credentials and profiles](/sdk/credentials#anonymous-reading).

### The end-to-end notebook needs your blob

`onnx/super-resolution-end-to-end` uploads to an ONNX blob you can write to:

1. Create an ONNX blob on [blobhub.io](https://blobhub.io/), or pick one you have.
2. Store a credential that can write to it, with `blobhub login` or by exporting `BLOBHUB_API_KEY`. The notebook
   calls `blobhub.connect()`, which finds either.
3. Set `ORG` and `BLOB` in the notebook's "Your blob" cell, each an alias or an id.

When the blob's default revision is already committed, the notebook creates a new draft to upload to. It never
commits that draft; its last cell shows how to, with `revision.commit()`. It needs PyTorch 2.5 or newer.

## From Python

```python theme={null}
import blobhub.notebooks

for notebook in blobhub.notebooks.list():
    print(notebook.id, notebook.title)

path = blobhub.notebooks.copy("onnx/super-resolution", dest="notebooks/")
```

* `blobhub.notebooks.list()` returns a `Notebook(id, title)` for each, in the order above.
* `blobhub.notebooks.copy(notebook_id, dest=".")` copies one and returns the new file's `Path`. An existing folder,
  or a string ending in `/`, receives `<last part of the id>.ipynb`, and the folder is created if missing. Anything
  else is the file path to write.
* `copy` never overwrites: an existing target raises `FileExistsError`. An unknown id raises `ValueError`.

## The command line

`python -m blobhub.notebooks` is the SDK's only command-line surface.

| Command | Does | Exit status |
| :- | :- | :- |
| `list` | Prints one `<id>  <title>` line per notebook. | `0` |
| `copy <id> [dest]` | Copies one notebook and prints its path. `dest` defaults to the current folder. | `0` |

An unknown id exits `2`, as does a usage error. A target that exists, or a folder that cannot be written, exits `1`.
Each error is one `error: …` line on stderr.

## See also

* [ONNX](/sdk/onnx) — the typed module every notebook uses.
* [Credentials and profiles](/sdk/credentials) — what `connect()` and `connect(anonymous=True)` read.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.