Jupyter Notebooks

The keel-jupyter-kernel enables interactive Keel development in Jupyter notebooks and JupyterLab.

Features

Core Capabilities

Interactive Execution — Execute Keel code cells and see results immediately
Persistent State — Variables, functions, and imports persist across cells
Rich Output — DataFrames render as HTML tables with metadata, Records as JSON objects
Standard Library — All stdlib modules automatically available
Error Reporting — Rich error messages with type information and function signatures
Interrupt Support — Cancel long-running operations with the interrupt button

IDE Features

Code Completion — Tab completion for variables, functions, modules, and keywords
Dot Completion — Module member completion (e.g., List. → map, filter, foldl)
Hover Documentation — Press Shift+Tab to see function signatures and documentation

Installation

Prerequisites

Option 1 (Nix): Nix package manager with flakes enabled
Option 2 (Cargo): Rust (latest stable)
Jupyter (pip install jupyter)

Build and Install

With Nix (Recommended)

nix build git+https://codeberg.org/Keel/keel-jupyter-kernel
./result/bin/install-keel-kernel

With Cargo

cargo install --git https://codeberg.org/Keel/keel-jupyter-kernel
install-keel-kernel

Verify Installation

jupyter kernelspec list

You should see keel in the list of available kernels.

Usage

Jupyter Notebook

jupyter notebook

Create a new notebook and select Keel as the kernel.

JupyterLab

jupyter lab

Create a new notebook and select Keel as the kernel.

Example Cells

-- Cell 1: Basic arithmetic
1 + 2
-- Output: 3

-- Cell 2: Variables persist across cells
let x = 42
let y = 10

-- Cell 3: Use previous variables
x * y
-- Output: 420

-- Cell 4: List operations with module completion
-- Type "List." and press Tab to see available functions
List.map (|n| n * 2) [1, 2, 3, 4, 5]
-- Output: [2, 4, 6, 8, 10]

-- Cell 5: DataFrames with rich HTML output
DataFrame.readCsv "data.csv"
    |> DataFrame.filter (|row| row.amount > 1000.0)
    |> DataFrame.select ["date", "amount", "product"]
-- Output: Rich HTML table

Auto-Available Standard Library

All standard library modules are available in notebooks without explicit imports:

List — map, filter, foldl, foldr, length, head, tail, etc.
String — length, concat, toUpper, toLower, split, etc.
Math — abs, sqrt, pow, sin, cos, floor, ceil, pi, e, etc.
DateTime — now, parse, format, addDays, addHours, diffDays, weekday, etc.
IO — print, println, readFile, writeFile, etc.
Http — get, post, put, delete, etc.
Json — parse, stringify, etc.
DataFrame — readCsv, readParquet, writeCsv, select, filter, groupBy, join, etc.
Result — map, mapError, andThen, withDefault, toMaybe
Maybe — map, andThen, withDefault

JupyterLab Syntax Highlighting (Optional)

For syntax highlighting in JupyterLab, install the optional extension:

cd jupyterlab-keel
npm install
npm run build
jupyter labextension install .
jupyter lab build

Requires Node.js, npm, and JupyterLab >= 4.0.0.

VS Code / Positron Integration

Jupyter notebooks work in VS Code and Positron with the keel-vscode extension. Create or open .ipynb files, select the Keel kernel, and run cells with Shift+Enter.

Positron provides additional features:

Variable pane integration
Built-in data viewer for DataFrames
Side-by-side code and output

Troubleshooting

Kernel Not Found

# Reinstall the kernel
install-keel-kernel

# Verify installation
jupyter kernelspec list

Kernel Crashes on Startup

Check logs in the Jupyter terminal for error messages. Common issues:

Missing dependencies (rebuild with cargo build --release)
Port conflicts (restart Jupyter)

Code Doesn't Execute

Check for syntax errors in the cell
Look for error messages in the output
Check the Jupyter terminal for kernel logs

Enable debug logging:

RUST_LOG=debug jupyter notebook

Current Limitations

Stdin: Not yet implemented (no input() support)
Widgets: Comm protocol not yet implemented
Debugging: Debug protocol not yet implemented