hypernote 0.1.0__tar.gz

hypernote-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  build-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Verify tag matches package version
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          tag = os.environ["GITHUB_REF_NAME"]
+          expected = f"v{version}"
+          if tag != expected:
+              raise SystemExit(f"Tag {tag!r} does not match package version {expected!r}")
+          print(f"Releasing hypernote {version}")
+          PY
+
+      - run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - run: uv run --extra dev playwright install --with-deps chromium
+
+      - run: uv run --extra dev python -m pytest -q
+
+  release:
+    needs: [build-package, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: artifacts/
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: artifacts/*
+
+  publish-pypi:
+    needs: [release]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: uv publish

hypernote-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.env
+*.db
+*.db-shm
+*.db-wal
+.ipynb_checkpoints/
+node_modules/
+lib/
+*.tsbuildinfo
+.jupyter/
+.agent-repl/
+tmp/

hypernote-0.1.0/AGENTS.md

@@ -0,0 +1,134 @@
+# Hypernote
+
+Notebook-first execution system built on top of Jupyter shared documents
+
+## Quick Start
+
+```bash
+uv run hypernote --help
+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
+uv run python -m pytest -q
+uv run ruff check hypernote tests
+```
+
+## Architecture
+
+Jupyter owns notebook truth:
+
+- `.ipynb` persistence
+- shared YDoc document state
+- kernel and session primitives
+- notebook rendering in JupyterLab
+
+Hypernote owns a thin control plane:
+
+- public SDK in [hypernote/sdk.py](/Users/giladrubin/python_workspace/hypernote/hypernote/sdk.py)
+- public errors in [hypernote/errors.py](/Users/giladrubin/python_workspace/hypernote/hypernote/errors.py)
+- agent-first CLI in [hypernote/cli/main.py](/Users/giladrubin/python_workspace/hypernote/hypernote/cli/main.py)
+- execution orchestration and shared-document mutation in [hypernote/execution_orchestrator.py](/Users/giladrubin/python_workspace/hypernote/hypernote/execution_orchestrator.py)
+- runtime ownership in [hypernote/runtime_manager.py](/Users/giladrubin/python_workspace/hypernote/hypernote/runtime_manager.py)
+- HTTP handlers in [hypernote/server/handlers.py](/Users/giladrubin/python_workspace/hypernote/hypernote/server/handlers.py)
+- Jupyter extension wiring in [hypernote/server/extension.py](/Users/giladrubin/python_workspace/hypernote/hypernote/server/extension.py)
+- ephemeral job and attribution ledger in [hypernote/actor_ledger.py](/Users/giladrubin/python_workspace/hypernote/hypernote/actor_ledger.py)
+
+Core rule: notebook edits and execution must operate on one logical document truth whether JupyterLab is closed, already open, or opened mid-run.
+
+Lifecycle rule: notebook contents and outputs persist through Jupyter's `.ipynb` model, but Hypernote's runtime state, job records, and cell attribution are intentionally in-memory and notebook-scoped.
+
+## Shipped Surface
+
+### SDK
+
+- `hypernote.connect(path, create=False)`
+- `Notebook`, `CellCollection`, `CellHandle`, `Runtime`, `Job`
+- `nb.run(...)`, `nb.run_all()`, `nb.restart()`, `nb.interrupt()`
+- `nb.snapshot()`, `nb.status()`, `nb.diff(...)`
+
+### CLI
+
+- `create`
+- `ix`
+- `exec`
+- `edit`
+- `run-all`
+- `restart`
+- `restart-run-all`
+- `interrupt`
+- `status`
+- `diff`
+- `cat`
+- `job ...`
+- `runtime ...`
+- `setup doctor`
+
+Default CLI contract:
+
+- TTY: concise human-readable progress
+- non-TTY: one compact final JSON result
+- explicit streaming only through `--watch` or `--stream-json`
+
+## Rules
+
+- Terminology: when the user says "our system", treat that as the maintained project-operating surface, including `AGENTS.md`, `SKILL.md`, `docs/`, `dev/`, tests, and other shared guidance or verification artifacts around the code.
+- SDK first. CLI behavior should come from the SDK, not duplicate raw HTTP semantics.
+- One truth. Do not reintroduce a contents-vs-YDoc split for notebook reads or writes.
+- Keep control-plane state ephemeral. Do not add durable job history unless the product explicitly needs it.
+- Our system is part of done. After every meaningful change, update the relevant parts of `AGENTS.md`, `SKILL.md`, `docs/`, `dev/`, tests, and adjacent shared project guidance so they stay in sync with implementation.
+- Keep adapters thin. CLI, JupyterLab, and tests should reuse shared contracts instead of re-encoding notebook behavior.
+- Prefer unique notebook paths in tests and demos. Browser tests must also use unique JupyterLab workspace URLs.
+- Keep `tmp/` disposable. Durable notes belong in `docs/` or `dev/`, not `tmp/`.
+
+## Read These First
+
+- [SKILL.md](/Users/giladrubin/python_workspace/hypernote/SKILL.md)
+- [docs/README.md](/Users/giladrubin/python_workspace/hypernote/docs/README.md)
+- [dev/README.md](/Users/giladrubin/python_workspace/hypernote/dev/README.md)
+
+## If You Are Editing...
+
+### `hypernote/sdk.py` or `hypernote/errors.py`
+
+- preserve the notebook-first public object model
+- keep public enums and errors stable
+- update [docs/sdk.md](/Users/giladrubin/python_workspace/hypernote/docs/sdk.md)
+
+### `hypernote/cli/main.py`
+
+- keep non-TTY output compact by default
+- preserve `ix` as the happy-path command
+- keep streaming explicit in non-TTY mode
+- update [docs/cli.md](/Users/giladrubin/python_workspace/hypernote/docs/cli.md)
+
+### `hypernote/execution_orchestrator.py`, `hypernote/runtime_manager.py`, or `hypernote/server/*`
+
+- preserve the single-truth shared-document path
+- verify open-tab and late-open behavior still hold
+- update [dev/current-architecture.md](/Users/giladrubin/python_workspace/hypernote/dev/current-architecture.md)
+- if browser-visible behavior changes, update [docs/browser-regression-spec.md](/Users/giladrubin/python_workspace/hypernote/docs/browser-regression-spec.md)
+
+### `tests/*`
+
+- prefer the narrowest test that proves the behavior
+- preserve coverage for:
+  - SDK shape
+  - CLI output contract
+  - live server behavior
+  - browser regression for streaming and late-open correctness
+
+## Verification
+
+Minimum checks for most changes:
+
+```bash
+uv run ruff check hypernote tests
+uv run python -m pytest -q
+```
+
+When browser or live-server behavior changes, also use:
+
+```bash
+HYPERNOTE_INTEGRATION=1 uv run python -m pytest -q tests/test_live_server.py
+uv run python -m pytest -q tests/test_browser_regression.py
+```

hypernote-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 - 2026-04-02
+
+Initial public release.
+
+### Added
+
+- notebook-first Python SDK built around `Notebook`, `CellCollection`, `CellHandle`, `Runtime`, and `Job`
+- agent-first CLI with `create`, `ix`, `exec`, `edit`, `run-all`, `restart`, `interrupt`, `status`, `diff`, `cat`, `job`, and `runtime` flows
+- Jupyter server extension with narrow Hypernote REST handlers
+- notebook-scoped runtime lifecycle with attach, detach, recovery, stop, and GC
+- headless execution flow over Jupyter shared documents and `jupyter-server-nbmodel`
+- job polling and `input()` round-trip support for long-running or interactive execution
+- live-server and browser regression tests for late-open, persistence, and shared-document correctness
+- project and developer docs for the runtime model, SDK, CLI, and release workflow
+
+### Changed
+
+- aligned the control plane around an explicitly ephemeral lifecycle
+- moved job tracking and cell attribution to an in-memory notebook-scoped ledger
+- removed the SQLite dependency and any implied durable job history
+
+### Notes
+
+- Jupyter owns durable notebook contents and outputs in `.ipynb`
+- Hypernote owns ephemeral runtime state, jobs, and attribution

hypernote-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

hypernote-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: hypernote
+Version: 0.1.0
+Summary: Thin control plane for Jupyter notebook execution with jobs, attribution, and runtime lifecycle
+Project-URL: Homepage, https://github.com/gilad-rubin/hypernote
+Project-URL: Repository, https://github.com/gilad-rubin/hypernote
+Project-URL: Issues, https://github.com/gilad-rubin/hypernote/issues
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: jupyter-collaboration>=3.0
+Requires-Dist: jupyter-server-nbmodel>=0.1
+Requires-Dist: jupyter-server>=2.0
+Requires-Dist: jupyter-ydoc>=2.0
+Requires-Dist: pycrdt-websocket>=0.15
+Requires-Dist: pycrdt>=0.12
+Provides-Extra: dev
+Requires-Dist: playwright>=1.40; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Hypernote
+
+- **Notebook-first** - Hypernote is a thin execution control plane on top of Jupyter shared documents.
+- **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 `hypernote/sdk.py`
+- agent-first CLI in `hypernote/cli/main.py`
+- Jupyter server extension for execution and runtime control
+- notebook-scoped runtime lifecycle with attach, detach, recovery, and stop
+- job polling and `input()` round-trips for headless execution
+- live-server and browser regression coverage for shared-document behavior
+
+## Quick start
+
+```bash
+uv sync --all-extras
+uv run hypernote --help
+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
+```
+
+## 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
+
+## Documentation
+
+- [Getting Started](/Users/giladrubin/python_workspace/hypernote/docs/getting-started.md)
+- [CLI Reference](/Users/giladrubin/python_workspace/hypernote/docs/cli.md)
+- [SDK Reference](/Users/giladrubin/python_workspace/hypernote/docs/sdk.md)
+- [Runtime Model](/Users/giladrubin/python_workspace/hypernote/docs/runtime-model.md)
+
+## Verification
+
+```bash
+uv run ruff check hypernote tests
+uv run python -m pytest -q
+```

hypernote-0.1.0/README.md

@@ -0,0 +1,55 @@
+# Hypernote
+
+- **Notebook-first** - Hypernote is a thin execution control plane on top of Jupyter shared documents.
+- **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 `hypernote/sdk.py`
+- agent-first CLI in `hypernote/cli/main.py`
+- Jupyter server extension for execution and runtime control
+- notebook-scoped runtime lifecycle with attach, detach, recovery, and stop
+- job polling and `input()` round-trips for headless execution
+- live-server and browser regression coverage for shared-document behavior
+
+## Quick start
+
+```bash
+uv sync --all-extras
+uv run hypernote --help
+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
+```
+
+## 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
+
+## Documentation
+
+- [Getting Started](/Users/giladrubin/python_workspace/hypernote/docs/getting-started.md)
+- [CLI Reference](/Users/giladrubin/python_workspace/hypernote/docs/cli.md)
+- [SDK Reference](/Users/giladrubin/python_workspace/hypernote/docs/sdk.md)
+- [Runtime Model](/Users/giladrubin/python_workspace/hypernote/docs/runtime-model.md)
+
+## Verification
+
+```bash
+uv run ruff check hypernote tests
+uv run python -m pytest -q
+```

hypernote-0.1.0/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: hypernote
+description: Work against Hypernote's notebook-first SDK and agent-first CLI. Use this when an agent needs to create notebooks, insert or edit cells, run code headlessly, inspect notebook status or diffs, or verify JupyterLab attach/streaming behavior.
+---
+
+# hypernote
+
+`hypernote` is the notebook runtime surface. The SDK is the core API. The CLI is a thin shell over that SDK.
+
+Run `uv run hypernote --help` for the current command list, and `uv run hypernote <command> --help` for exact syntax.
+
+## Quick Start
+
+```bash
+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
+```
+
+## Use This Surface
+
+- `ix` — insert a new cell and run it; this is the default happy path
+- `exec` — run existing cell ids only
+- `edit` — mutate notebook cells without executing
+- `run-all` / `restart` / `restart-run-all` — notebook-wide control
+- `status` / `diff` — observe current notebook state and changes
+- `cat` — inspect cells and outputs directly
+
+## Best Practices
+
+1. Prefer `ix` over separate insert + execute steps.
+2. Prefer the SDK and CLI over raw HTTP unless you are explicitly working on server routes.
+3. Treat Jupyter shared documents as the source of truth. Open or closed JupyterLab tabs must not change correctness.
+4. For agents, prefer default non-TTY JSON output unless you intentionally want background streaming.
+5. Use `--stream-json` only when you plan to watch the process; otherwise it wastes context.
+6. Use unique notebook paths in tests and demos.
+7. Move durable notes into `docs/` or `dev/`; keep `tmp/` disposable.
+8. Treat Hypernote jobs, runtime state, and cell attribution as ephemeral coordination state, not durable history.
+
+## Before You Change Behavior
+
+1. Read [AGENTS.md](/Users/giladrubin/python_workspace/hypernote/AGENTS.md).
+2. Check the current public surface in [docs/cli.md](/Users/giladrubin/python_workspace/hypernote/docs/cli.md) and [docs/sdk.md](/Users/giladrubin/python_workspace/hypernote/docs/sdk.md).
+3. If browser-visible execution behavior changes, check [docs/browser-regression-spec.md](/Users/giladrubin/python_workspace/hypernote/docs/browser-regression-spec.md).
+
+## Verification
+
+```bash
+uv run ruff check hypernote tests
+uv run python -m pytest -q
+```

hypernote-0.1.0/dev/README.md

@@ -0,0 +1,23 @@
+# Development Docs
+
+This folder is internal reference for the shipped Hypernote architecture.
+
+Public workflow docs live in `docs/`. This folder is for implementation-facing notes only.
+
+Read these first:
+
+- [Current Architecture](/Users/giladrubin/python_workspace/hypernote/dev/current-architecture.md)
+- [Module Map](/Users/giladrubin/python_workspace/hypernote/dev/module-map.md)
+- [Testing and Verification](/Users/giladrubin/python_workspace/hypernote/dev/testing-and-verification.md)
+
+Release path:
+
+- pushing a tag like `v0.1.0` runs [release.yml](/Users/giladrubin/python_workspace/hypernote/.github/workflows/release.yml)
+- the workflow verifies the tag matches `pyproject.toml`, builds `dist/`, creates a GitHub release, and publishes to PyPI as `hypernote`
+- PyPI auth comes from the GitHub Actions secret `PYPI_API_TOKEN`
+
+Rules:
+
+- keep this folder small
+- document shipped behavior, not aspirational redesigns
+- when behavior changes, update `AGENTS.md`, `SKILL.md`, `docs/`, and `dev/` together

hypernote-0.1.0/dev/current-architecture.md

@@ -0,0 +1,30 @@
+# Current Architecture
+
+Hypernote is a notebook-first layer over Jupyter shared documents.
+
+## Topology
+
+```text
+Agent or Human
+    ↕
+CLI / SDK / JupyterLab
+    ↕
+Hypernote HTTP handlers + execution orchestration
+    ↕
+Jupyter shared document + kernel/session primitives
+```
+
+## Current design
+
+- The SDK is the public semantic center.
+- The CLI is a thin shell over the SDK.
+- Notebook reads and writes must go through the shared-document path.
+- Execution must resolve cell source from the same document model the UI sees.
+- JupyterLab is an optional viewer/actor, not a second source of truth.
+
+## Important consequences
+
+- a newly inserted cell must be immediately executable
+- open-tab and closed-tab behavior must match
+- opening a notebook mid-run must show prior output and continue streaming
+- persisted `.ipynb` output must converge with the live shared document

hypernote-0.1.0/dev/module-map.md

@@ -0,0 +1,27 @@
+# Module Map
+
+## Python package
+
+- [hypernote/sdk.py](/Users/giladrubin/python_workspace/hypernote/hypernote/sdk.py)
+  - public notebook-first SDK
+- [hypernote/errors.py](/Users/giladrubin/python_workspace/hypernote/hypernote/errors.py)
+  - public exceptions
+- [hypernote/cli/main.py](/Users/giladrubin/python_workspace/hypernote/hypernote/cli/main.py)
+  - agent-first CLI over the SDK
+- [hypernote/execution_orchestrator.py](/Users/giladrubin/python_workspace/hypernote/hypernote/execution_orchestrator.py)
+  - shared-document access, job orchestration, execution integration
+- [hypernote/runtime_manager.py](/Users/giladrubin/python_workspace/hypernote/hypernote/runtime_manager.py)
+  - notebook runtime lifecycle and room state
+- [hypernote/server/handlers.py](/Users/giladrubin/python_workspace/hypernote/hypernote/server/handlers.py)
+  - HTTP handlers
+- [hypernote/server/extension.py](/Users/giladrubin/python_workspace/hypernote/hypernote/server/extension.py)
+  - Jupyter server extension wiring
+- [hypernote/actor_ledger.py](/Users/giladrubin/python_workspace/hypernote/hypernote/actor_ledger.py)
+  - actor attribution
+
+## Release automation
+
+- [.github/workflows/release.yml](/Users/giladrubin/python_workspace/hypernote/.github/workflows/release.yml)
+  - tag-driven build, GitHub release, and PyPI publish workflow for the `hypernote` package
+
+There is no separate JupyterLab-side package that owns notebook semantics. JupyterLab is treated as an external notebook surface attached to the same shared-document and execution path.

hypernote-0.1.0/dev/testing-and-verification.md

@@ -0,0 +1,30 @@
+# Testing and Verification
+
+## Fast checks
+
+```bash
+uv run ruff check hypernote tests
+uv run python -m pytest -q
+```
+
+## Test layers
+
+- unit and contract tests
+  - SDK shape
+  - CLI output contract
+  - runtime and attribution helpers
+- live integration tests
+  - server-backed notebook creation, execution, persistence, and diff behavior
+- browser regression tests
+  - open-tab cell appearance
+  - streaming output while running
+  - late-open visibility of already-produced output
+
+## Rules
+
+- use unique notebook paths per test
+- browser tests should also use unique JupyterLab workspace URLs
+- assert semantic progress, not fragile timestamps
+- when browser-visible execution behavior changes, verify both:
+  - job state
+  - rendered notebook state

hypernote-0.1.0/docs/README.md

@@ -0,0 +1,15 @@
+# Hypernote Docs
+
+Hypernote is a notebook-first execution layer on top of Jupyter shared documents.
+
+Jupyter owns durable notebook contents and outputs. Hypernote owns an ephemeral control plane for runtimes, jobs, and attribution.
+
+Start here:
+
+- [Getting Started](/Users/giladrubin/python_workspace/hypernote/docs/getting-started.md)
+- [CLI Reference](/Users/giladrubin/python_workspace/hypernote/docs/cli.md)
+- [SDK Reference](/Users/giladrubin/python_workspace/hypernote/docs/sdk.md)
+- [Runtime Model](/Users/giladrubin/python_workspace/hypernote/docs/runtime-model.md)
+- [Browser Regression Spec](/Users/giladrubin/python_workspace/hypernote/docs/browser-regression-spec.md)
+
+Public docs should describe shipped behavior only. Internal implementation notes belong in `dev/`.