Notebook Module

Read and edit Jupyter notebooks (.ipynb). Parses the JSON structure directly -- no kernel needed for read/edit operations. Zero external dependencies.

Configuration

modules:
  notebook: {}   # No config required

Actions (4)

read

Read a notebook with all cells, source code, and outputs.

read(path="analysis.ipynb")
read(path="analysis.ipynb", cell_range="0-5")   # cells 0 to 5 only
read(path="analysis.ipynb", cell_range="3")      # cell 3 only

Response:

{
  "path": "analysis.ipynb",
  "kernel": "Python 3",
  "language": "python",
  "total_cells": 15,
  "showing": "0-5",
  "cells": [
    {
      "index": 0,
      "type": "markdown",
      "source": "# Data Analysis\n\nThis notebook..."
    },
    {
      "index": 1,
      "type": "code",
      "source": "import pandas as pd\ndf = pd.read_csv('data.csv')",
      "execution_count": 1,
      "output": "   col1  col2\n0     1     2\n1     3     4"
    }
  ]
}

edit_cell

Replace the content of a cell.

edit_cell(path="analysis.ipynb", cell_index=3, content="print('hello')")
edit_cell(path="analysis.ipynb", cell_index=0, content="# Updated Title", cell_type="markdown")

add_cell

Add a new cell at a specific position or at the end.

add_cell(path="analysis.ipynb", content="plt.show()", cell_type="code")
add_cell(path="analysis.ipynb", content="## Results", cell_type="markdown", position=5)

delete_cell

Delete a cell by index.

delete_cell(path="analysis.ipynb", cell_index=7)

Output Types

The module extracts and formats cell outputs:

Output type	Display
Stream (stdout/stderr)	Raw text
Execute result (text/plain)	Formatted text
Display data (text/html)	[HTML output] placeholder
Display data (image/png)	[Image output] placeholder
Error	[Error: ExceptionName: message]

Example

# A data science assistant
modules:
  notebook: {}
  filesystem: {}

agents:
  - id: analyst
    brain:
      provider: deepseek
      model: deepseek-chat
    system_prompt: |
      You are a data science assistant.
      Read notebooks to understand the analysis, suggest improvements,
      and edit cells to fix issues.