hypernote 0.3.0

Thin control plane for Jupyter notebook execution with jobs, attribution, and runtime lifecycle

Hypernote

• JupyterLab-first - Hypernote is a thin execution control plane for a Hypernote-enabled JupyterLab server.
• One notebook truth - notebook edits, execution, and late-open JupyterLab views all operate on the same logical document.
• Agent-first surface - the Python SDK is primary, and the CLI is a thin shell over it.
• Ephemeral control plane - Jupyter owns durable .ipynb contents and outputs; Hypernote owns in-memory runtimes, jobs, and attribution.

What it ships

• notebook-first SDK in src/hypernote/sdk.py
• agent-first CLI in src/hypernote/cli/main.py
• Jupyter server extension for execution and runtime control
• subshell-routed execute, interrupt, and restart so JupyterLab stays usable while Hypernote is running cells
• notebook-scoped runtime lifecycle with attach, detach, recovery, and stop
• job polling and input() round-trips for agent automation without requiring an open Lab tab
• live-server and browser regression coverage for shared-document behavior

Quick start

uv sync
uv run hypernote --help
uv run hypernote setup serve
uv run hypernote setup doctor
uv run hypernote create tmp/demo.ipynb
uv run hypernote ix tmp/demo.ipynb -s 'value = 20 + 22\nprint(value)'
uv run hypernote status tmp/demo.ipynb --full

For another repo's environment, install Hypernote there (uv add hypernote --dev) and run the same bootstrap command from that repo.

Install

The default install includes the JupyterLab integration stack Hypernote needs: JupyterLab, shared-document support, server-side notebook execution, and the collaboration/docprovider frontend packages.

Use hypernote[dev] only for local development and CI tooling.

Examples:

uv sync
uv sync --extra dev

Mental model

Jupyter owns:

• notebook persistence
• shared YDoc document state
• kernel and session primitives
• notebook rendering in JupyterLab

Hypernote owns:

• runtime lifecycle around a notebook
• job coordination and stdin round-trips
• actor attribution
• SDK, CLI, and thin REST handlers

Design discipline

• shared behavior should have one owner, usually the SDK for agent-facing observation rules
• command and payload variants should preserve one contract unless a difference is explicit and documented
• adapters should normalize valid upstream shape differences at the boundary
• tests should cover invariants across variants, not only the main workflow

Documentation

• Getting Started
• CLI Reference
• SDK Reference
• Runtime Model
• Browser Regression Spec

Verification

For local development and CI, install the dev tier first:

uv sync --extra dev

uv run ruff check src/hypernote tests
uv run python -m pytest -q