ipyGraph

Turn your Jupyter notebook into a branching graph of experiments.

 JupyterLab 4 extension · .ipygb format · source-available

---

The problem

Every ML notebook starts clean and ends as a 2,000-line scroll of dead cells, half-tried models, and "wait — which run produced this number?" You try five approaches, comment out four, lose track of which features fed which model, and can never reproduce the good result. AI can write the code for you now — but your experiments are still a linear mess.

Notebooks are linear. Experimentation isn't.

What ipyGraph is

ipyGraph (a.k.a. Graphbook, file extension .ipygb) is a JupyterLab 4 extension that turns a notebook into a branching DAG of cells. Every experiment is a branch on a living graph instead of a copy-pasted block you'll never find again. A shared data-prep step forks into competing models; each branch keeps its own state; you compare tips and keep the winner.

It ships with a plan-first AI copilot that designs the experiment graph, writes the code, runs it, and iterates — and an execution engine where one branch can never silently contaminate another.

The cells are real, runnable Jupyter cells — so outputs, plots, and the kernel all work exactly as you expect. When you're done, export any path as a plain .ipynb.

---

See it

The screenshots below are a real ipyGraph project: predicting a chess engine's position evaluation from the board. A shared prep step splits into two feature representations (tabular vs. board-planes), which feed different model families.

Plan view — the whole experiment reads like a flowchart, and every step documents itself:

Code view — those same nodes are real, runnable Jupyter cells with live outputs:

The AI copilot builds and iterates on the graph beside you (Autopilot is on by default):

---

Features

🕸️ The graph is the interface

• Graph View is the default view. Cells are laid out as a 2D flow — column = branch, row = depth — with parents centered over their children.
• Two views of one graph. Flip between Plan view (titles + prose descriptions — read the whole experiment at a glance) and Code view (the real editors and outputs). The agent can switch views for you to show you what matters.
• Branch anywhere. Fork a new branch from any cell with one click; extend a tip with + Cell.
• Edit in place. Type directly into cells on the graph, rename branches, and click-to-edit descriptions — no round-trip to a separate editor.
• Arrow-key navigation and a 👁 Watch agent button that pans the graph to whatever cell is being worked on, live.

🤖 Plan-first AI copilot

• Describe a goal, get a plan on the graph. The agent drafts the experiment as plan cells first — you approve, then it builds. It thinks in dataflow: shared prep on the trunk, a separate encoder per model family, models under their encoder.
• Multi-agent under the hood. An architect-vs-critic design debate picks the model shortlist; parallel coder sub-agents fill in the branches concurrently.
• Finds data for you. A full-screen dataset picker searches Kaggle and profiles candidates so you can choose the right one.
• Uses your Claude subscription via the Claude Agent SDK (no API key needed), or bring an API key for Anthropic / OpenAI / Gemini.
• Minimal questions, fast turns — it infers sensible defaults, asks only when a choice genuinely matters, and shows a live progress spinner while it works.

🔒 Reproducible, isolated execution

• A cell's variables come only from its own path. One branch can never be polluted by code you ran on another branch.
• ▶ Run a single cell, or ⇥ Run to here to rebuild a path from the start on a clean, isolated kernel.
• Fork-point kernel snapshots. State is saved at each branch point (fast, on-disk), so a sibling branch resumes from a saved copy instead of replaying the whole path — and the copy rolls forward as you iterate down a branch.
• True fork-join parallelism. "Run Parallel" on a 1-prep → 3-model graph runs the prep once and trains the three models concurrently on separate kernels.
• Staleness badges. A cell warns you — "changed after last run" / "upstream changed" — when an edit made its last result stale, naming the variables that drifted.

🔀 Merge & compare

• Visual merge contracts. Combine branches by clicking the variables you want right in each branch's code — hover to trace every occurrence, click to add it to the merge. No copy-paste, no name clashes.
• Merge cells receive their inputs across kernels via an explicit, editable contract.

📓 Fits your existing workflow

• It's still Jupyter. Real kernels, real outputs, MathJax, the works.
• Notebook side-view. Open the linear notebook beside the graph any time.
• Export a path → .ipynb. Pick a root-to-tip path and save it as an ordinary notebook to share or hand off.

---

Why it's useful

• You never lose an experiment. Every model you try is a branch you can see, re-run, and compare — not a commented-out block.
• Your results are actually reproducible. Path isolation + "Run to here" means a number on a branch was produced by that branch's code and nothing else.
• Iteration is cheap. Fork snapshots mean tweaking the deepest cell costs one cell's runtime plus a state restore — not a full re-run of the pipeline. Expensive data prep is paid for once, even across parallel model trainings.
• The graph is self-documenting. Plan view + descriptions turn a notebook into something a teammate (or future you) can read top to bottom.
• AI does the busywork, you keep control. The agent plans, codes, runs, and compares; you approve the plan and own the graph.

Great for ML engineers and researchers running model bake-offs, feature-engineering sweeps, and architecture searches — anyone whose "quick experiment" notebook always spirals.

---

Install

pip install ipygraph

Then start JupyterLab and create a new Graphbook (.ipygb) from the launcher, or open an existing .ipygb file — it opens in Graph View by default.

Requirements: JupyterLab >= 4.0.0, Python >= 3.10. For the AI copilot, either the claude CLI (subscription login) or an API key for your provider of choice. Kaggle dataset search needs Kaggle credentials (entered once, stored server-side).

Quick start

1. Launcher → Graphbook (.ipygb).
2. Open the Assistant panel and describe what you want to build — e.g. "train tree and neural models to predict chess move quality, and iterate."
3. Approve the plan it draws on the graph → it builds, runs, and compares the branches.
4. Fork your own branches, Run Parallel, and Save a path as .ipynb when you're happy.

---

Development

Note: You will need NodeJS to build the extension package. jlpm is JupyterLab's pinned version of yarn.

# From the repo root: set up a dev environment
python -m venv .venv
source .venv/bin/activate
pip install --editable "."

# Link the dev build into JupyterLab
jupyter labextension develop . --overwrite

# Rebuild the TypeScript after changes
jlpm build

Watch mode (rebuild on save) in one terminal, JupyterLab in another:

jlpm watch
jupyter lab

Tests: jlpm test (Jest) and Playwright/Galata integration tests under ui-tests. Packaging: see RELEASE.

---

License

ipyGraph / Graphbook is source-available, not OSI open source. See LICENSE for the full terms and NOTICE for third-party components.

• Free for individuals and any non-commercial use — development, evaluation, personal projects, academic research, and teaching.
• Free for an organization's internal use up to 20 users (seats).
• A paid commercial license (with a 5% royalty) is required to charge for something built on it, offer it as a hosted/SaaS service, or exceed 20 internal users. Contact anishchelliah.cr@gmail.com to arrange one.

This license covers only this project's own code. JupyterLab, Lumino, React, and other dependencies keep their own licenses (see NOTICE); nothing here changes them.