IntegratedNotebookToolSet

IntegratedNotebookToolSet#

The IntegratedNotebookToolSet provides full Jupyter notebook operations with integrated kernel management, cell-based editing, and code execution.

Overview#

Key features:

  • Notebook Management: Create, open, and manage notebook files

  • Cell Operations: Add, update, delete, move cells with cell_id-based addressing

  • Code Execution: Execute Python, R (via %%R magic), and shell (via %%bash)

  • Kernel Management: Restart, interrupt, and monitor kernel state

  • Auto-Recovery: Automatic kernel recovery after crashes

Basic Usage#

from pantheon.agent import Agent
from pantheon.toolsets import IntegratedNotebookToolSet

# Create notebook toolset
notebook_tools = IntegratedNotebookToolSet(
    name="notebook",
    workdir="/path/to/notebooks"  # Optional
)

# Create agent and add toolset at runtime
agent = Agent(
    name="analyst",
    instructions="You are a data analyst. Use Jupyter notebooks for analysis."
)
await agent.toolset(notebook_tools)

await agent.chat()

Constructor Parameters#

Parameter

Type

Description

name

str

Name of the toolset

workdir

str | None

Working directory for notebooks. Defaults to current directory.

remote_backend

RemoteBackend | None

Optional backend for streaming execution output.

streaming_mode

“auto” | “remote” | “local”

IOPub streaming mode. Default: “auto”.

Tools Reference#

create_notebook#

Create or open a notebook file.

result = await notebook_tools.create_notebook(
    notebook_path="analysis.ipynb"
)
# Returns: {"success": True, "notebook_path": "...", "action": "created"|"opened"}

add_cell#

Add a new cell to the notebook.

result = await notebook_tools.add_cell(
    notebook_path="analysis.ipynb",
    cell_type="code",              # "code", "markdown", or "raw"
    content="import pandas as pd",
    cell_id="cell_1",              # Optional: auto-generated if not provided
    position=None,                  # Optional: index, cell_id, or None (append)
    execute=True                    # Execute after adding (recommended for code)
)

Position options:

  • None: Append to end (default)

  • "0", "1": Insert at index (0-based)

  • "cell_id": Insert after the cell with this ID

execute_cell#

Execute an existing cell’s content.

result = await notebook_tools.execute_cell(
    notebook_path="analysis.ipynb",
    cell_id="cell_1"
)
# Returns: {"success": True, "output": "...", "kernel_session_id": "..."}

Supported syntax:

  • Python code (default)

  • R language: %%R (cell magic) or %R (line magic)

  • Shell commands: %%bash or %%sh

  • Other magics: %%time, %%html, %matplotlib inline, etc.

update_cell#

Update cell content with optional execution.

# Full replacement
result = await notebook_tools.update_cell(
    notebook_path="analysis.ipynb",
    cell_id="cell_1",
    content="x = 10",
    execute=True
)

# Partial replacement
result = await notebook_tools.update_cell(
    notebook_path="analysis.ipynb",
    cell_id="cell_1",
    content="n_neighbors=30",
    old_content="n_neighbors=15",
    execute=True
)
# Returns: {"success": True, "replacements": 1, ...}

delete_cell#

Delete a cell from the notebook.

result = await notebook_tools.delete_cell(
    notebook_path="analysis.ipynb",
    cell_id="cell_1"
)

move_cell#

Move a cell to a different position.

result = await notebook_tools.move_cell(
    notebook_path="analysis.ipynb",
    cell_id="cell_3",
    below_cell_id="cell_1"  # Move after cell_1 (None = move to top)
)

read_cells#

Read cells with execution status and optional content.

# Get cell summaries
result = await notebook_tools.read_cells(
    notebook_path="analysis.ipynb"
)

# Get full cell content
result = await notebook_tools.read_cells(
    notebook_path="analysis.ipynb",
    include_details=True
)

# Read specific cells only
result = await notebook_tools.read_cells(
    notebook_path="analysis.ipynb",
    include_details=True,
    cell_ids=["cell_1", "cell_3"]
)

Returns:

{
    "success": True,
    "cells": [
        {
            "cell_id": "cell_1",
            "cell_index": 0,
            "cell_type": "code",
            "execution_count": 1,
            "execution_status": "success",  # or "error", "not_executed"
            "source_preview": "import pandas...",  # when include_details=False
            "source": "import pandas as pd",  # when include_details=True
            "outputs": [...]  # when include_details=True
        }
    ]
}

list_notebooks#

List running notebooks for the current session.

result = await notebook_tools.list_notebooks()
# Returns: {"success": True, "notebooks": [...], "count": 2}

manage_kernel#

Unified kernel management operations.

# Restart kernel (clears all state)
result = await notebook_tools.manage_kernel(
    notebook_path="analysis.ipynb",
    action="restart"
)

# Interrupt running execution
result = await notebook_tools.manage_kernel(
    notebook_path="analysis.ipynb",
    action="interrupt"
)

# Get kernel status
result = await notebook_tools.manage_kernel(
    notebook_path="analysis.ipynb",
    action="status"
)

# Get current kernel variables
result = await notebook_tools.manage_kernel(
    notebook_path="analysis.ipynb",
    action="variables"
)

# Shutdown kernel (context preserved)
result = await notebook_tools.manage_kernel(
    notebook_path="analysis.ipynb",
    action="shutdown"
)

# Delete context completely
result = await notebook_tools.manage_kernel(
    notebook_path="analysis.ipynb",
    action="delete"
)

R Language Support#

Use R via the %%R magic (requires rpy2):

await notebook_tools.add_cell(
    "analysis.ipynb",
    "code",
    content="""%%R
library(ggplot2)
data(mtcars)
ggplot(mtcars, aes(x=mpg, y=hp)) + geom_point()
""",
    execute=True
)

Pass data between Python and R:

# Python to R: %%R -i variable_name
# R to Python: %%R -o variable_name

Examples#

Data Analysis Workflow#

from pantheon.agent import Agent
from pantheon.toolsets import IntegratedNotebookToolSet

notebook_tools = IntegratedNotebookToolSet(name="notebook")

analyst = Agent(
    name="analyst",
    instructions="""You are a data analyst. When analyzing data:
    1. Create a notebook for the analysis
    2. Import required libraries
    3. Load and explore data
    4. Create visualizations
    5. Document findings in markdown cells"""
)
await analyst.toolset(notebook_tools)

# Agent creates notebook and performs analysis
result = await analyst.run(
    "Analyze the iris dataset and create visualizations"
)

Complete Example#

# Create notebook
await notebook_tools.create_notebook("demo.ipynb")

# Add import cell and execute
await notebook_tools.add_cell(
    "demo.ipynb",
    cell_type="code",
    content="import numpy as np\nimport matplotlib.pyplot as plt",
    execute=True
)

# Add markdown documentation
await notebook_tools.add_cell(
    "demo.ipynb",
    cell_type="markdown",
    content="# Sine Wave Plot\nGenerating a simple sine wave."
)

# Add visualization code
await notebook_tools.add_cell(
    "demo.ipynb",
    cell_type="code",
    content="""x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.plot(x, y)
plt.title('Sine Wave')
plt.show()""",
    execute=True
)

# Check cell status
cells = await notebook_tools.read_cells("demo.ipynb")

Best Practices#

  1. Use execute=True: Execute code cells immediately when adding/updating

  2. Use cell_id addressing: More stable than index-based addressing

  3. Document with markdown: Add markdown cells for documentation

  4. Check execution status: Use read_cells to verify cell execution

  5. Interrupt long operations: Use manage_kernel(action=”interrupt”)

  6. Split long operations: Break into multiple cells for better control