Jupyter Tools¶

The Jupyter tools (hanzo-tools-jupyter) provide comprehensive Jupyter notebook operations including reading, editing, creating, and executing notebooks.

Overview¶

Work with .ipynb files programmatically - read cell contents, modify cells, create new notebooks, and execute code cells.

jupyter - Unified Notebook Tool¶

The unified jupyter tool handles all notebook operations through an action parameter.

Read Notebook¶

# Read entire notebook
jupyter(notebook_path="analysis.ipynb")

# Read specific cell by index
jupyter(notebook_path="analysis.ipynb", cell_index=2)

# Read specific cell by ID
jupyter(notebook_path="analysis.ipynb", cell_id="abc123")

Edit Notebook¶

# Replace cell content
jupyter(
    action="edit",
    notebook_path="analysis.ipynb",
    cell_index=0,
    source="print('Hello, World!')"
)

# Insert new cell
jupyter(
    action="edit",
    notebook_path="analysis.ipynb",
    edit_mode="insert",
    cell_index=2,
    cell_type="code",
    source="import pandas as pd"
)

# Delete cell
jupyter(
    action="edit",
    notebook_path="analysis.ipynb",
    edit_mode="delete",
    cell_index=3
)

# Change cell type
jupyter(
    action="edit",
    notebook_path="analysis.ipynb",
    cell_index=0,
    cell_type="markdown",
    source="# Analysis Results"
)

Create Notebook¶

# Create empty notebook
jupyter(action="create", notebook_path="new_analysis.ipynb")

Delete Notebook¶

# Delete entire notebook
jupyter(action="delete", notebook_path="old.ipynb")

# Delete specific cell
jupyter(action="delete", notebook_path="analysis.ipynb", cell_index=5)

Execute Notebook¶

# Execute all cells
jupyter(action="execute", notebook_path="analysis.ipynb")

# Execute with custom timeout
jupyter(action="execute", notebook_path="analysis.ipynb", timeout=600)

# Execute with specific kernel
jupyter(action="execute", notebook_path="analysis.ipynb", kernel_name="python3")

Parameters¶

Parameter	Type	Default	Description
`action`	str	`read`	`read`, `edit`, `create`, `delete`, `execute`
`notebook_path`	str	required	Path to .ipynb file
`cell_id`	str	-	Cell ID for targeted operations
`cell_index`	int	-	Cell index (0-based)
`cell_type`	str	-	`code` or `markdown`
`source`	str	-	New cell content
`edit_mode`	str	`replace`	`replace`, `insert`, `delete`
`timeout`	int	`600`	Execution timeout (seconds)
`kernel_name`	str	`python3`	Jupyter kernel to use

Edit Modes¶

Mode	Description
`replace`	Replace existing cell content
`insert`	Insert new cell at index
`delete`	Delete cell at index

Cell Types¶

Type	Description
`code`	Executable Python code
`markdown`	Markdown text/documentation

Output Format¶

When reading notebooks, output includes:

Notebook with 5 cells
==================================================

Cell 0 (code)
ID: abc123
----------------------------------------
import pandas as pd
import numpy as np

Outputs:
[Out 1]: <module 'pandas'>

Cell 1 (markdown)
----------------------------------------
# Data Analysis
This notebook analyzes...

Installation¶

pip install hanzo-tools-jupyter

For notebook execution, also install:

pip install nbclient

Dependencies¶

nbformat - Notebook file format handling
nbclient (optional) - For notebook execution

Best Practices¶

1. Use Cell IDs for Stability¶

# Prefer cell IDs over indices when available
jupyter(action="edit", notebook_path="nb.ipynb", cell_id="stable-id", source="...")

2. Validate Before Executing¶

# Read first to check cell contents
result = jupyter(notebook_path="analysis.ipynb")
print(result)

# Then execute
jupyter(action="execute", notebook_path="analysis.ipynb")

3. Set Appropriate Timeouts¶

# Long-running analysis
jupyter(action="execute", notebook_path="ml_training.ipynb", timeout=3600)

4. Use Markdown for Documentation¶

# Add documentation cells
jupyter(
    action="edit",
    notebook_path="analysis.ipynb",
    edit_mode="insert",
    cell_index=0,
    cell_type="markdown",
    source="# Analysis Report\n\nGenerated by automated pipeline."
)

Error Handling¶

Common errors and solutions:

Error	Cause	Solution
`nbclient not installed`	Missing execution dependency	`pip install nbclient`
`Cell index out of range`	Invalid cell index	Check notebook length first
`Kernel not found`	Invalid kernel name	Use `python3` or check available kernels