swarmauri_tool_jupyterreadnotebook 0.11.0.dev1

Swarmauri notebook-ingestion tool for reading and validating Jupyter notebooks with nbformat.

Swarmauri Jupyter Read Notebook Tool

swarmauri_tool_jupyterreadnotebook reads a Jupyter .ipynb file from disk, parses it with nbformat, validates the notebook schema, and returns the resulting NotebookNode inside a Swarmauri tool response.

Why

• Load notebooks into Swarmauri pipelines before execution, export, or cleanup steps.
• Normalize notebook ingestion around a simple tool contract.
• Catch missing files and notebook schema issues before later notebook-processing stages.

Features

• Reads .ipynb files with nbformat.read.
• Validates the parsed notebook with nbformat.validate.
• Returns {"notebook_node": ...} on success.
• Returns {"error": ...} on file and validation failures.
• Supports an as_version argument for controlled notebook parsing.

FAQ

What does this tool return?

It returns a dictionary with either notebook_node containing the parsed notebook or error containing a failure message.

Does this tool execute the notebook?

No. It only reads and validates notebook content. Pair it with execution tools when you need code-cell outputs.

When should I change as_version?

Use as_version when you need to coerce notebook parsing to a specific nbformat version for compatibility with downstream tooling.

Installation

uv add swarmauri_tool_jupyterreadnotebook

pip install swarmauri_tool_jupyterreadnotebook

Usage

from swarmauri_tool_jupyterreadnotebook import JupyterReadNotebookTool

tool = JupyterReadNotebookTool()
result = tool(
    notebook_file_path="notebooks/example.ipynb",
    as_version=4,
)

if "notebook_node" in result:
    notebook = result["notebook_node"]
    print(len(notebook.cells))
else:
    print(result["error"])

Examples

Read a notebook before execution

from swarmauri_tool_jupyterreadnotebook import JupyterReadNotebookTool

reader = JupyterReadNotebookTool()
payload = reader("reports/daily_report.ipynb")

if "notebook_node" in payload:
    metadata = payload["notebook_node"].metadata
    print(metadata)

Guard against invalid notebook files

response = JupyterReadNotebookTool()("broken.ipynb")

if "error" in response:
    print("Notebook ingestion failed:", response["error"])

Related Packages

• swarmauri_tool_jupyterwritenotebook
• swarmauri_tool_jupyterexecutenotebook
• swarmauri_tool_jupyterexecutenotebookwithparameters
• swarmauri_tool_jupyterexecuteandconvert
• swarmauri_tool_jupyterclearoutput

Foundational Swarmauri Packages

• swarmauri
• swarmauri_core
• swarmauri_base
• swarmauri_standard

More Documentation

• Swarmauri SDK repository
• nbformat documentation
• Jupyter notebook format docs