# 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

```python
# 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

```python
# 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

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

### Delete Notebook

```python
# 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

```python
# 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

```bash
pip install hanzo-tools-jupyter
```

For notebook execution, also install:

```bash
pip install nbclient
```

## Dependencies

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

## Best Practices

### 1. Use Cell IDs for Stability

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

### 2. Validate Before Executing

```python
# 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

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

### 4. Use Markdown for Documentation

```python
# 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 |