plainbook 0.1.6

Plain Language Notebooks

Plainbook: Natural Language Notebooks

Plainbooks allow users to create and communicate data analysis and science using natural language.

Plainbooks are notebooks that combine instructions and results, similarly to Jupyter notebooks. The difference is that in Plainbook, users view natural language, rather than code. The code is generated "under the hood" using AI. This allows you to share your data analysis and science with a much wider audience, including people who do not know how to code, and to make it easier for everyone to understand what you are doing.

When you share a plainbook, recipients can use AI to check that the "notebook does not lie", that is, that the code implementation is faithful to the natural language description, and they can also run tests, as a further check. Recipients can also edit the natural language description, and regenerate the code, to adapt the notebook to their needs.

In other words, the goal of the Plainbook project is to replicate in natural language what made Juptyter notebooks so successful: the ability to share together code and results, the ability to inspect how the results are obtained, and the ability to modify the notebook.

Installation and use

To install Plainbook, you might first want to create a Python environment:

python -m venv .venv
source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`

You can install Plainbook with pip:

pip install plainbook

To open a plainbook (which will be created if it does not exist):

plainbook notebook.nlb

You can use any file name you like, with any extension you like.

AI API Keys. You need a Gemini or Claude API key to use Plainbook. Click on the Settings button (the gear on the top right) and it will contain links where to get such keys. The lead developer is spending only about $2/month on Gemini and Claude together, so the cost should be very low.

Examples

• Introductory video.
• Plainbook on football matches: Download football.plb.

Resources

• GitHub Repository.
• Pypi package.

Plainbook Structure

Plainbooks consist of three types of cells:

• Action cells, where the user describes in natural language the action to be performed (e.g., "Load the dataset from file data.csv and display the first 10 rows"). The system converts the description to code, executes it, and displays the results below the cell.

• Comment cells, where the user can add comments, section headers, and so forth, using markdown syntax.

• Test cells, where the user can write properties that should hold at certain points of the notebook to check that everything is working as expected.

Differently from other notebook systems, Plainbooks are executed from start to end, so that the results follow the same order in which we humans read the cells. Plainbooks relies on a checkpointing kernel to remember the execution state after each cell, so that it can re-run a cell without having to start from the beginning.

AI Providers Plainbook is designed to work with multiple AI providers, and users can choose which provider to use for code generation and checking. The system is designed to allow users to easily switch between providers, so that users can cross-check that the implementation obtained from one provider is considered valid by another provider. This avoids over-reliance on a single class of AI models. Currently, Plainbook supports Gemini and Claude models. You will need an API key for at least one such provider to use Plainbook.

Contributors

• Luca de Alfaro, UC Santa Cruz.
• Mathis Aubert, UC Santa Cruz.
• Ranjit Jhala, UC San Diego.