Whybook

Whybook / Roadmap

The path to v1

Whybook is a research prototype. Three releases lead to v1: an alpha for friendly users outside the project, a beta that anyone can install, and v1 for organisations that deploy it. No release has a date yet: the dates depend on who joins the work. This page lists the work that each release needs, with a ticked box on what is built, and what waits for v2. What runs today is on the website.

§1 The path

Three releases to v1

Each release is defined by what an outside user gets. The features come in the alpha and the beta, and v1 adds the work that needs people: research with analysts, reviews, an audit and maintainers.

Alpha

For five to ten friendly users: analysts outside the project. They install whybook from PyPI into their own JupyterLab, open their own notebooks and get the questions from templates at once, and the questions that need AI from the model they connect. To be one of them, open an issue on GitHub with your field and the kind of notebooks you work on.

  • On PyPI. pip install whybook installs Whybook into the analyst's own JupyterLab.
  • In the open. The code is public on GitHub, where an alpha user reports a problem.
  • Jupyter Notebook 7. Whybook and its questions are tested in Notebook 7, as they are in JupyterLab. A first version is built: a switch on a notebook's page shows Whybook in place of the notebook editor, and a browser script checks it.
  • Databases beyond SQLite. PostgreSQL, MySQL and others through an existing explorer extension, likely a fork of jupyterlab-db-explorer, with a way for the kernel to open the same connections. The part that joins it to Whybook could become a package of its own, as the sandbox will; that is less clear here, since two explorers exist upstream.
  • AI answers tested with real models. The alpha will run every question that needs AI against a real connected model, and will grade the agent's answers: whether they are right, how many cells they take and what they cost. Today the tests answer the model's requests themselves.
  • A choice on the first run of where labels are written. Today the remote model writes the labels of tables, the summaries of frames and the titles of cells by default. On the first run, Whybook asks whether a model on the analyst's machine or the remote model writes them, and shows what each choice sends out and what it needs. A local model by default would give analysts with a weaker machine a slow start, and could put them off. Where an administrator set Whybook up, the server's configuration decides, and Whybook does not ask.
  • Real notebooks. Whybook runs on 20 to 50 real notebooks from the target fields, public ones first, without a crash or a hang, with polars frames and with 100 cells or more.
  • A security pass over the server routes, the kernel code, the keys and the text of a model shown as Markdown, and a version number in the notebook's metadata, so that later releases can migrate it.
  • Installs that work everywhere. Whybook's tests run on Linux, and the sandbox tests also on macOS. The alpha will test clean installs on Linux, macOS and Windows, and will add a page of known gaps and a link that reports a problem.

Beta

For anyone. Notebooks written with it keep working in later versions, and code that a model wrote runs only after a review, by the analyst or by a guard, or in a sandbox.

  • The cost of each answer. With its setting on, Whybook shows what the answers of a notebook cost and caps the notebook, and the server caps each call and each agent's run.
  • The sandboxed kernel on Linux and macOS. A kernel to choose, with access to the notebook's folder only, and to no network.
  • A review guard. Code that a model wrote is checked before it runs, more strictly outside the sandbox. Every prompt is checked before it goes to a model on another machine. The rules check first, and a guard model on this machine reads beside them when the analyst turns one on, with a policy in the analyst's words. It asks, or holds back so that the work does not wait.
  • On-demand package installation in the sandbox. The sandboxed kernel uses the packages installed in its Python environment beforehand, with read-only access. It has no network and cannot write to the environment, so %pip install fails. The beta will install a package when the analyst asks for one, and will show in Whybook's toolbar which kernel is sandboxed, as the AI models panel does today.
  • Better local models. Small classifiers give the type and the place of a user question, trained on the remote model's answers. Larger local models are tested on writing the cells, on a 16 or 32 GB GPU, 128 GB of unified memory and an 80 GB GPU, for analysts who send no data out.
  • Sign in with ChatGPT. An analyst with a ChatGPT Plus or Pro plan pays for the model calls with the plan, and needs no API key. OpenAI's flow for open-source apps registers the app at the first sign-in, so Whybook needs no client id from OpenAI. It works on the analyst's own machine. OpenAI's terms keep the tokens off managed servers, so JupyterHub and Nebari would need OpenAI's approval, through its form for hosted apps. The terms also ask for the analyst's consent before calls that the app makes on its own, such as the labels of tables.
  • Answer time, and models without a price. Research on fast replies, then a limit on the time of an answer. The waits of the demo's questions, cells, labels and titles are measured through OpenRouter, and each task can take a faster model. In the beta, the cost caps will also count the answers of a model with no known price, which they leave out today.
  • Metadata format v1, with a published schema and validation.
  • Accessibility. Every action from the keyboard and with a screen reader, contrast that meets WCAG 2.2 AA, and automated checks of both in the tests.
  • Scale. Notebooks of 300 cells and frames of 10,000 columns, restarts while branches run, and the classic view of the same file open beside Whybook.
  • JupyterLite. Whybook opens stored notebooks in JupyterLite, with the questions turned off, and its UI tests run there.
  • User documentation. Install, a tutorial on each demo, the settings, what leaves the machine, and what to do when something fails.

v1

For organisations. They deploy it on JupyterHub or Nebari and plan around it: its numbers checked by people, its design tested with analysts, an external audit, supported versions, and maintainers who answer issues.

  • Research with analysts. Five to eight analysts try the beta. They ask the same five questions of the demo in Whybook, by dragging and by clicking, in a chat assistant in JupyterLab, and by hand, and the study records the time to each answer, the errors, and which offered questions they pick. The design will change after it, and a second round will try the new version. Release candidates go to the beta's users.
  • People check the numbers. A person labels a sample behind each number on the website: question types, user questions, synthetic examples of a column dragged onto a cell, table labels, and the review guard's cases. One model wrote those labels.
  • A statistics review. Statisticians and epidemiologists review the templates, the tests that Whybook offers, how Whybook joins a column from another table, averaged per key first, and the prompts.
  • An external security audit, with its findings fixed and advisories published.
  • An accessibility review with people who use a screen reader or only the keyboard, and a statement of what Whybook meets.
  • Commitments. Supported versions, a deprecation policy, the metadata format frozen with migrations tested on alpha and beta notebooks, a plan for JupyterLab 5, a deployment guide for JupyterHub and Nebari, and a release process with security advisories.

§2 After v1

What waits for v2

Each item adds a feature or a platform, where v1 hardens what exists. None of them blocks an organisation from deploying v1.

  • Questions in JupyterLite. The templates rewritten in TypeScript, and a model that runs in the browser.
  • The sandbox by default, on Windows through WSL2, and in containers or microVMs for users who have them.
  • A model that chooses where an answer goes, fitted to each analyst's corrections, in place of the rules. Today the rules choose by default, and Jev can choose for a user question that no rule matches.
  • Full feature parity for R: question and answer templates written for R, questions about plots, and branches that run at the same time. An R kernel has the Variables panel, chips on the cells and questions today, and a model writes the code of each answer in R.
  • Full support for other languages, such as Julia, each with its own templates and kernel code.
  • Several notebooks of one project on one map.
  • A standalone app: first a check in JupyterLab Desktop, then an app of its own.
  • A causal diagram and a list of assumptions. The analyst draws the diagram, and rules check each model against it. The list holds the notebook's assumptions, grouped by who set each. Today an agent can draw a diagram in a cell with the jupyterlab-dagitty extension, as in the video on teens and social media. Whybook's own diagram and list are designed, and neither is built.
  • Spoken questions measured with real voices. Until then they stay an experimental setting.
  • A full accessibility audit by an outside firm, after the review with users in v1.

§3 Upstream

What goes to Jupyter and other projects

What Whybook needs from other packages goes to those packages, as the website's Designed to last sets out, and each change is useful without Whybook.

Kernel sandboxing

The sandbox's kernel provisioner as a package that any Jupyter server can use: it ships inside whybook for now, and later moves to a package of its own, possibly in its own repository, so that it is easy to take upstream. Then a pre-JEP, the issue that opens a Jupyter Enhancement Proposal, for a sandbox policy in the kernelspec, apart from the pre-JEP on sandboxed server extensions (jupyter/enhancement-proposals#152).

What a model reads

_ai_repr_ in libraries, the method of JEP 129: what a model should read about an object, as text or a picture, as _repr_html_ is for display.

JupyterLab

Public interfaces for the parts of JupyterLab that Whybook copies today, and the fixes it needs, such as the tab that a reload makes current.

The Jupyter AI ecosystem

A diff in any editor in jupyterlab-diff, now an open pull request, calls with a JSON schema in JupyterLite AI, and keys kept out of kernels in Jupyternaut's key store.

Build it with us

Whybook is a research prototype, open source under the Apache-2.0 licence. Taking it to v1, along this roadmap, needs people as much as code: research with analysts, reviews of its statistics and its security, and maintainers. We are looking for partners:

  • Organisations whose analysts would try the beta on their own notebooks.
  • Funders and sponsors who would carry it to v1.
  • Developers who would contribute to the extension and to Jupyter.
Talk to OpenTeams Contribute on GitHub