Metadata-Version: 2.4
Name: ipygraph
Version: 1.14.1
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
Requires-Dist: jupyterlab<5,>=4.0.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/anishchelliahcr/ipygraph-assets/main/logo-banner.png" alt="ipyGraph — Notebooks that branch" width="620">
</p>

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

<p align="center">
  <img src="https://raw.githubusercontent.com/anishchelliahcr/ipygraph-assets/main/plan-view-detail.png" alt="ipyGraph plan view — a chess evaluation model built as a branching graph of self-describing steps" width="820">
</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 · `.ipygb` file format · runs at `/graph` · 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*) 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**.

You launch it with its own command and it opens at `/graph`:

```bash
pip install ipygraph
jupytergraph          # opens JupyterLab at http://localhost:8888/graph
```

## The `.ipygb` file format

ipyGraph adds a new document type: **`.ipygb`** (a "Graphbook"). It's a **superset of the Jupyter notebook format** — the same `nbformat` JSON with cells, outputs, and metadata — with a little extra per-cell `ipygb` metadata that records the graph:

```jsonc
"metadata": {
  "ipygb": {
    "parent_id": "root-1",        // which cell's outputs this one builds on
    "branch_name": "encode-nn",   // the branch this cell starts (optional)
    "parent_ids": ["a", "b"],     // 2+ parents = a merge cell
    "description": "…",           // shown in Plan view
    "inputs": { … }               // explicit variables a merge consumes
  }
}
```

Because it's a superset, the kernel, outputs, and rendering are ordinary Jupyter — nothing proprietary about how your code runs. And you can always **export any root→tip path back to a plain `.ipynb`** to share or hand off.

---

## 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="https://raw.githubusercontent.com/anishchelliahcr/ipygraph-assets/main/graph-plan-view.png" alt="Plan view: the full experiment graph" width="820"></p>

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

<p align="center"><img src="https://raw.githubusercontent.com/anishchelliahcr/ipygraph-assets/main/graph-code-view.png" alt="Code view: the same graph as runnable cells" width="820"></p>

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

<p align="center"><img src="https://raw.githubusercontent.com/anishchelliahcr/ipygraph-assets/main/graph-with-assistant.png" alt="ipyGraph assistant panel with a live conversation" width="820"></p>

---

## Parallel execution

Branches are independent, so ipyGraph runs them like an experiment *should* run: **shared prep once, models concurrently.**

<p align="center"><img src="https://raw.githubusercontent.com/anishchelliahcr/ipygraph-assets/main/parallelism.png" alt="Fork-join parallelism: shared prep runs once, branches train in parallel on separate kernels, a merge compares them" width="820"></p>

- **Fork-join, not replay.** *Run Parallel* on a 1-prep → 3-model graph runs the prep **once**, then trains the three models **at the same time**, each on its own fresh kernel. A 10-model bake-off pays for data loading once, not ten times.
- **Fork-point kernel snapshots.** The kernel's state is saved at each branch point, so a sibling branch **resumes from a saved copy** instead of re-running the whole path — and the copy rolls forward as you iterate down a branch. Tweaking the deepest cell costs one cell's runtime plus a state restore.
- **True isolation.** A branch's variables come only from its own path. One branch can never be polluted by code you ran on another — proven by identical results whether a branch runs alone or beside others.
- **▶ Run** a single cell or **⇥ Run to here** to rebuild a path from scratch on a clean isolated kernel.

---

## More features

- 🕸️ **The graph is the interface.** Graph View is the default; flip any card between **Plan view** (titles + prose) and **Code view** (editors + outputs). Edit code, rename branches, and click-to-edit descriptions in place. Arrow-key navigation; a **👁 Watch agent** button pans to whatever the agent is touching.
- 🤖 **Plan-first AI copilot.** Describe a goal → it drafts the plan on the graph, you approve, then it builds and iterates. Multi-agent: an architect-vs-critic debate picks the model shortlist; parallel coder sub-agents fill the branches. Finds data for you via a full-screen Kaggle dataset picker. Uses your Claude subscription (Claude Agent SDK, no API key) or an Anthropic/OpenAI/Gemini key.
- 🔀 **Visual merge contracts.** Combine branches by **clicking the variables you want** in each branch's code — hover to trace every occurrence, click to add it to the merge. No copy-paste, no name clashes.
- 🩺 **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.
- 📓 **Still Jupyter.** Real kernels, outputs, MathJax. Open the linear notebook side-by-side, and export any path to a plain `.ipynb`.

## Why it's useful

- **You never lose an experiment** — every model you try is a branch you can see, re-run, and compare.
- **Results are actually reproducible** — path isolation + "Run to here" means a number came from *that branch's code and nothing else*.
- **Iteration is cheap** — fork snapshots + fork-join mean expensive prep is paid for once and deep edits re-run one cell.
- **The graph is self-documenting** — Plan view turns a notebook into something a teammate (or future you) can read top to bottom.
- **AI does the busywork, you keep control** — it 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 & run

```bash
pip install ipygraph
jupytergraph                 # launches JupyterLab at /graph
```

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

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

> `jupytergraph` is JupyterLab mounted at `/graph` with ipyGraph branding. Everything else — kernels, terminals, other extensions — works exactly as in JupyterLab.

## Quick start

1. Run `jupytergraph`, then Launcher → **Graphbook (.ipygb)**.
2. Open the **Assistant** and describe what 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

You will need NodeJS to build the extension. `jlpm` is JupyterLab's pinned yarn.

```bash
python -m venv .venv && source .venv/bin/activate
pip install --editable "."
jupyter labextension develop . --overwrite
jlpm build          # rebuild the TypeScript after changes
```

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

```bash
jlpm watch
jupytergraph
```

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.
