Skip to content

feat: notebook_run — execute notebook cells via Jupyter kernel #41

Description

@EngineerProjects

Summary

Add a `notebook_run` tool that executes cells in a Jupyter notebook and returns their outputs (stdout, stderr, display data, errors).

Motivation

`notebook_edit` and `notebook_write` let the model write notebooks, but there is no way to actually run them and observe results. `notebook_run` closes that loop: write code → run it → read outputs → iterate.

Proposed API

```
notebook_run:
notebook_path: /path/to/analysis.ipynb # required
cell_ids: ["cell-0", "cell-1"] # optional — run specific cells only
timeout: 60 # seconds per cell (default 60)
restart_kernel: false # restart before running (default false)
```

Returns per-cell output (stdout, display_data, error tracebacks) and execution counts.

Architecture

This is a non-trivial sub-system:

  • Kernel manager (Go) — starts `jupyter kernel` via `uv run` in the Nexus-managed venv (`~/.config/nexus-cli/.venv`), one kernel per notebook path (pooled).
  • ZMQ client (Go) — communicates with the kernel over the Jupyter wire protocol (execute_request / execute_reply / iopub stream).
  • Output capture — streams stdout/stderr/display_data/error back from iopub channel; respects per-cell timeout.
  • Lifecycle — kernels are kept alive between calls (fast subsequent runs) and cleaned up on TUI exit alongside the docling manager.

Dependencies

  • `jupyter_client` Python package (installed via the managed venv — see `make install-python`).
  • ZMQ bindings: either `go-zeromq/zmq4` (pure Go) or `pebbe/zmq4` (cgo, requires libzmq).
    • Prefer pure-Go `go-zeromq/zmq4` to avoid the libzmq system dependency.

Implementation phases

  1. Install `jupyter_client` and `ipykernel` in `scripts/install-python-env.sh`.
  2. Implement `internal/python/kernel.go` — `KernelManager` struct (start / execute / shutdown).
  3. Implement `internal/tools/files/notebook/run.go` — `RunTool` following the same pattern as `EditTool` / `WriteTool`.
  4. Register in `builtin.go` + add TUI renderer in `notebook.go`.

Notes

  • This is the highest-value notebook feature but also the most complex. Estimated effort: 2–3 days.
  • Blocked on `go-zeromq/zmq4` compatibility check (pure-Go ZMQ). If that proves difficult, fall back to shelling out to a small Python script via `uv run`.
  • Related: [[notebook_create]], [[notebook_write]] (already implemented in `internal/tools/files/notebook/`).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions