Metadata-Version: 2.4
Name: ipygraph
Version: 0.1.2
Summary: Turn your Jupyter notebook into a branching graph of experiments — a JupyterLab extension with a plan-first AI copilot, branch isolation, and fork-join parallel execution.
Project-URL: Homepage, https://github.com/jupyterlab/jupyterlab-ipygb
Project-URL: Bug Tracker, https://github.com/jupyterlab/jupyterlab-ipygb/issues
Project-URL: Repository, https://github.com/jupyterlab/jupyterlab-ipygb.git
Author: ipycopilot
License: ipyGraph / Graphbook Community & Commercial License
        Version 1.0
        
        Copyright (c) 2026 Anish Chelliah CR
        All rights reserved.
        
        ============================================================================
        PLAIN-LANGUAGE SUMMARY (not the license — the terms below control)
        ----------------------------------------------------------------------------
        • Source-available, NOT OSI "open source": the source is public and you may
          read, modify, and self-host it, but commercial use is limited (see below).
        • Free, forever, 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).
        • You need a paid Commercial License (which carries a royalty) if you charge
          money for something built on this software, offer it as a hosted service,
          or exceed 20 internal Users.
        • This license covers only the original code of this project. Third-party
          components (JupyterLab, Lumino, React, and others) keep their own licenses
          — see the NOTICE file. Nothing here changes those.
        
        NOTE: This document is a template, not legal advice — have a lawyer review it
        before you rely on it. The royalty rate below (5%) is a starting figure the
        Licensor may change.
        ============================================================================
        
        
        1. DEFINITIONS
        
           "Software" means the original works of authorship in this repository that
           are owned by the Licensor, in source or object (including compiled or
           "prebuilt") form, together with associated documentation.
        
           "Licensor" means the copyright holder identified above.
        
           "You" (or "Your") means the individual or legal entity exercising rights
           under this license. For an entity, "You" includes all entities that
           control, are controlled by, or are under common control with You.
        
           "Use" means to install, run, access, copy, modify, or make derivative
           works of the Software, or to distribute or make it available to others.
        
           "User" (or "Seat") means each distinct individual who uses, or is
           authorized to use, the Software or any product or service that
           incorporates it, on Your behalf. Automated accounts serving a distinct
           individual count as that individual.
        
           "Internal Use" means Use by You solely for Your own operations, where the
           Software (or its outputs produced by the Software as such) is not sold,
           licensed, hosted for, or otherwise provided to any third party.
        
           "Commercial Use" means any Use that is NOT purely Internal Use within the
           free Seat allowance, including, without limitation:
             (a) charging any fee, subscription, or other consideration for a
                 product or service that includes, is built on, or is substantially
                 enabled by the Software;
             (b) offering the Software, or its functionality, to third parties as a
                 hosted, managed, SaaS, or "as-a-service" offering; or
             (c) Internal Use that exceeds the free Seat allowance in Section 3.
        
           "Commercial License" means a separate written agreement from the Licensor
           authorizing Commercial Use, as described in Section 4.
        
        
        2. GRANT (SOURCE-AVAILABLE)
        
           Subject to Your compliance with this license, the Licensor grants You a
           worldwide, non-exclusive, non-transferable, revocable license to Use the
           Software for the permitted purposes in Section 3, and to create and Use
           modifications and derivative works of the Software for those same
           purposes. All rights not expressly granted are reserved.
        
        
        3. FREE USE
        
           The following are permitted at no charge, with no Commercial License
           required:
        
           3.1 Individuals & Non-Commercial. Any Use by an individual, and any Use
               that is not Commercial Use, is free and unlimited. This expressly
               includes software development, testing, evaluation, personal
               projects, academic research, and classroom teaching.
        
           3.2 Enterprise Internal Use — up to 20 Seats. An organization may make
               Internal Use of the Software for free for up to twenty (20) Users in
               aggregate across the organization. Use by a 21st or additional User,
               or any Commercial Use, requires a Commercial License under Section 4.
        
           Free Use does not include the rights reserved to a Commercial License in
           Section 4.
        
        
        4. COMMERCIAL USE & ROYALTY
        
           4.1 Commercial License required. Commercial Use (as defined in Section 1)
               is permitted only under a Commercial License obtained from the
               Licensor in advance.
        
           4.2 Royalty. A Commercial License carries a royalty of 5%
               of the gross revenue reasonably attributable to the product or
               service that incorporates the Software, or such other fee as the
               Licensor and You agree in writing. Reporting, payment, audit, and
               minimum-fee terms are set out in the Commercial License.
        
           4.3 How to obtain one. Contact the Licensor at anishchelliah.cr@gmail.com to request a
               Commercial License. Until a Commercial License is executed, Commercial
               Use is not licensed and is prohibited.
        
           4.4 No implied grant. Nothing in Section 3 grants any right to Commercial
               Use.
        
        
        5. CONDITIONS ON ALL USE AND DISTRIBUTION
        
           5.1 Preserve notices. You must retain, in all copies and substantial
               portions of the Software (source and object), this license, the
               copyright notice above, and the NOTICE file, and must not remove or
               obscure any Licensor or third-party attribution.
        
           5.2 No misrepresentation. You must not represent the Software as
               "open source" under the Open Source Definition, remove these
               restrictions, or sublicense the Software except as expressly allowed.
        
           5.3 Modifications. You must clearly mark any files You change and not
               misattribute them to the Licensor.
        
           5.4 Trademarks. This license grants no rights to the Licensor's names,
               logos, or trademarks (including "ipyGraph" and "Graphbook") except as
               needed for reasonable and customary attribution.
        
        
        6. THIRD-PARTY COMPONENTS
        
           The Software is built for and with the Jupyter and JupyterLab ecosystem
           and other third-party components (including, without limitation,
           JupyterLab, Jupyter Server, Lumino, React, and various Python and
           JavaScript libraries). Those components are the property of their
           respective owners and are licensed to You under THEIR OWN licenses (for
           example, the BSD 3-Clause License for Jupyter/JupyterLab and Lumino, and
           the MIT License for React), not under this license. See the NOTICE file
           for details. Nothing in this license modifies, supersedes, or restricts
           Your rights or obligations under those third-party licenses, and to the
           extent of any conflict as to a third-party component, that component's
           own license governs it.
        
        
        7. CONTRIBUTIONS
        
           Unless You state otherwise in writing, any contribution You intentionally
           submit for inclusion in the Software is provided under the terms of this
           license, and You grant the Licensor a perpetual, worldwide,
           non-exclusive, royalty-free, irrevocable license to use, reproduce,
           modify, distribute, and relicense Your contribution as part of the
           Software (including under a Commercial License).
        
        
        8. TERM & TERMINATION
        
           This license applies for as long as You comply with it. It terminates
           automatically if You breach it and do not cure the breach within 30 days
           of becoming aware of it. On termination You must stop all Use and destroy
           copies in Your control, except that Section 6 (third-party components) and
           any separately executed Commercial License survive according to their own
           terms. Sections 5, 9, 10, and 11 survive termination.
        
        
        9. DISCLAIMER OF WARRANTY
        
           THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
           IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
           FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. YOU BEAR THE
           ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE.
        
        
        10. LIMITATION OF LIABILITY
        
           TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL THE LICENSOR BE
           LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
           CONSEQUENTIAL DAMAGES (INCLUDING LOSS OF PROFITS, DATA, OR GOODWILL)
           ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE SOFTWARE,
           WHETHER IN CONTRACT, TORT, OR OTHERWISE, EVEN IF ADVISED OF THE
           POSSIBILITY OF SUCH DAMAGES.
        
        
        11. GENERAL
        
           This license is the entire agreement regarding Free Use of the Software
           and supersedes prior understandings on that subject. If any provision is
           held unenforceable, it will be limited or severed to the minimum extent
           necessary so the rest remains in effect. Failure to enforce a provision is
           not a waiver. The governing law and venue are as stated in an applicable
           Commercial License or, absent one, the Licensor's principal place of
           business.
        
        ----------------------------------------------------------------------------
        For commercial licensing, contact: anishchelliah.cr@gmail.com
License-File: LICENSE
License-File: NOTICE
Keywords: ai,branching,dag,experiments,graph,graphbook,ipygraph,jupyter,jupyterlab,jupyterlab-extension,machine-learning,notebook
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: dill
Requires-Dist: jupyter-server<3,>=2.0.0
Description-Content-Type: text/markdown

<h1 align="center">ipyGraph</h1>

<p align="center"><b>Turn your Jupyter notebook into a branching graph of experiments.</b></p>

<p align="center">
  <img src="docs/images/plan-view-detail.png" alt="ipyGraph plan view — a chess evaluation model built as a branching graph of self-describing steps" width="850">
</p>

[![Build](https://github.com/jupyterlab/jupyterlab-ipygb/workflows/Build/badge.svg)](https://github.com/jupyterlab/jupyterlab-ipygb/actions/workflows/build.yml)
&nbsp;JupyterLab 4 extension&nbsp;·&nbsp;`.ipygb` format&nbsp;·&nbsp;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:**

<p align="center"><img src="docs/images/graph-plan-view.png" alt="Plan view: the full experiment graph" width="850"></p>

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

<p align="center"><img src="docs/images/graph-code-view.png" alt="Code view: the same graph as runnable cells" width="850"></p>

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

<p align="center"><img src="docs/images/graph-with-assistant.png" alt="ipyGraph assistant panel" width="850"></p>

---

## 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

```bash
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.

```bash
# 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:

```bash
jlpm watch
jupyter lab
```

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

---

## License

**ipyGraph / Graphbook** is **source-available**, not OSI open source. See [`LICENSE`](./LICENSE) for the full terms and [`NOTICE`](./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`](./NOTICE)); nothing here changes them.
