nbaide

The agent-readability standard for Jupyter notebooks. Ruff makes your code clean — nbaide makes your notebooks intelligent.

AI coding agents (Claude Code, Cursor, Codex) struggle with Jupyter notebooks because outputs are stored as HTML tables, base64 images, and opaque blobs. nbaide solves this with three layers:

1. Formatters — embed structured JSON in notebook outputs so agents can read them. Humans see exactly what they've always seen.
2. CLI — nbaide manifest, nbaide read, and nbaide lint give agents structured access to any notebook.
3. Linter — score notebooks 0-100 for agent readability and auto-fix common issues.

Quick Start

pip install nbaide

import nbaide
nbaide.install()  # one line — all displays are now dual-rendered

import pandas as pd
df = pd.read_csv("data.csv")
df  # humans see the HTML table; agents see structured JSON with schema + stats

Lint Your Notebooks

$ nbaide lint notebook.ipynb

notebook.ipynb

  cell  1: AIR001 Output size 292KB exceeds 256KB
  cell  3: AIR003 Error output: ZeroDivisionError
  cell  5: AIM001 Chart missing title
  notebook: AIN003 No nbaide.install() call found

  4 issue(s) (1 error, 2 warning, 1 info)
  Agent readability score: 64/100 (Fair)

$ nbaide lint notebook.ipynb --fix

  Fixed:
    [AIR001] cell 1: Auto-fixed
    [AIR003] cell 3: Auto-fixed
    [AIN003] notebook: Auto-fixed

  cell  5: AIM001 Chart missing title

  1 issue(s) (0 error, 1 warning, 0 info)
  Agent readability score: 95/100 (Excellent)

Lint Rules

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/igerber/nbaide
    rev: v0.2.0
    hooks:
      - id: nbaide-lint
        args: [--check, --min, "70"]

Blocks commits if any .ipynb file scores below the threshold.

CI Integration

# Fail CI if agent readability score drops below 80
nbaide lint notebook.ipynb --check --min 80

What Agents See

When an agent reads a notebook with nbaide installed, each output includes structured JSON:

---nbaide---
{"type": "dataframe", "shape": [200, 9], "columns": [{"name": "price", "dtype": "float64", "nulls": 10, "stats": {"mean": 151.97, "min": 8.58, "max": 299.91}}, ...], "sample_rows": [...]}

For charts, agents get chart type, axis labels, trend detection, and sampled data:

---nbaide---
{"type": "figure", "axes": [{"title": "Monthly Revenue", "series": [{"plot_type": "line", "data_points": 12, "trend": {"direction": "increasing", "slope": 2280.0, "r_squared": 0.97}}]}]}

Humans see exactly what they've always seen. The structured JSON is invisible in Jupyter (HTML takes priority over text/plain).

Supported Types

Custom Type Registration

import nbaide

def format_experiment(exp):
    return {
        "type": "experiment",
        "name": exp.name,
        "params": exp.params,
        "metrics": exp.metrics,
    }

nbaide.register(Experiment, format_experiment)

Works even after install() has been called (late registration).

CLI Tools

# Structured summary of an entire notebook
nbaide manifest notebook.ipynb

# Extract structured data from all cell outputs
nbaide read notebook.ipynb

# Get data for a specific cell
nbaide read notebook.ipynb --cell 7

# Filter by type
nbaide read notebook.ipynb --type dataframe

# Lint for agent readability
nbaide lint notebook.ipynb
nbaide lint notebook.ipynb --fix
nbaide lint notebook.ipynb --check --min 80
nbaide lint notebook.ipynb --json

Installation

# Core (pandas + numpy)
pip install nbaide

# With matplotlib support
pip install nbaide[matplotlib]

# With plotly support
pip install nbaide[plotly]

# Everything
pip install nbaide[all]

How It Works

Jupyter stores multiple MIME representations per output. The frontend picks the richest one (HTML, PNG) for display, but text/plain is also stored. nbaide embeds structured JSON in text/plain — invisible to humans in Jupyter, but readable by any agent that opens the .ipynb file.

The linter statically analyzes .ipynb files for agent-hostile patterns (oversized outputs, missing metadata, error tracebacks) and can auto-fix most issues without a running kernel.

Status

v0.2.0 — 253 tests. The agent-readability standard for Jupyter notebooks.

• Formatters: pandas, matplotlib, numpy, plotly, custom types via plugin system
• CLI: manifest, read, lint with scoring, rules, and auto-fix
• Linter: 10 rules, 0-100 scoring, CI integration via --check
• See CLAUDE.md for the full roadmap and technical design