Swarmauri Tool · Jupyter Validate Notebook
A Swarmauri tool that validates Jupyter notebooks (NotebookNode objects) against the official nbformat JSON schema. Use it to gate notebook submissions, enforce structural best practices, or wire schema checks into automated notebook pipelines.
- Accepts in-memory
NotebookNodeinstances and produces structured success/error payloads. - Surfaces detailed schema violations coming from nbformat/jsonschema.
- Integrates with Swarmauri agents via the standard tool registration workflow.
Requirements
- Python 3.10 – 3.13.
nbformat(installed automatically) with access to the notebook JSON schema.- Dependencies (
jsonschema,swarmauri_base,swarmauri_standard,pydantic,typing_extensions).
Installation
Pick the installer that matches your workflow; each command resolves transitive packages.
pip
pip install swarmauri_tool_jupytervalidatenotebook
Poetry
poetry add swarmauri_tool_jupytervalidatenotebook
uv
# Add to the current project and update uv.lock
uv add swarmauri_tool_jupytervalidatenotebook
# or install into the active environment without touching pyproject.toml
uv pip install swarmauri_tool_jupytervalidatenotebook
Tip: When using uv inside this repo, run uv commands from the repository root so it can locate the shared
pyproject.toml.
Quick Start
Load a notebook with nbformat, then pass the resulting NotebookNode to the tool. The response dictionary contains string values for valid ("True" or "False") and a human-readable report.
import nbformat
from swarmauri_tool_jupytervalidatenotebook import JupyterValidateNotebookTool
notebook = nbformat.read("analysis.ipynb", as_version=4)
validate = JupyterValidateNotebookTool()
result = validate(notebook)
if result["valid"] == "True":
print("Notebook passes schema validation")
else:
raise ValueError(result["report"])
Usage Scenarios
Batch Validate an Entire Notebook Directory
import nbformat
from pathlib import Path
from swarmauri_tool_jupytervalidatenotebook import JupyterValidateNotebookTool
validator = JupyterValidateNotebookTool()
notebook_dir = Path("notebooks")
for path in notebook_dir.glob("**/*.ipynb"):
nb = nbformat.read(path, as_version=4)
result = validator(nb)
status = "PASS" if result["valid"] == "True" else "FAIL"
print(f"[{status}] {path}: {result['report']}")
Drop this snippet into CI to stop merges when any notebook violates the schema.
Fail a Build When Validation Fails
import sys
import nbformat
from swarmauri_tool_jupytervalidatenotebook import JupyterValidateNotebookTool
validator = JupyterValidateNotebookTool()
notebook = nbformat.read(sys.argv[1], as_version=4)
result = validator(notebook)
print(result["report"])
if result["valid"] != "True":
sys.exit(1)
Wire the script into a pre-commit hook or build step (python validate.py path/to/notebook.ipynb).
Combine With Other Swarmauri Tools
from swarmauri_tool_jupyterstartkernel import JupyterStartKernelTool
from swarmauri_tool_jupytervalidatenotebook import JupyterValidateNotebookTool
start_kernel = JupyterStartKernelTool()
validate_notebook = JupyterValidateNotebookTool()
launch = start_kernel()
print(f"Launched kernel: {launch['kernel_id']}")
# After generating a notebook programmatically, load and validate it
import nbformat
nb = nbformat.read("generated.ipynb", as_version=4)
validation = validate_notebook(nb)
print(validation)
Use the validation step after automated notebook generation/execution to ensure outputs remain schema-compliant.
Troubleshooting
Invalid nbformat version– The tool enforces nbformat version 4. Upgrade the notebook (nbformat.convert) or save it with a modern Jupyter client.Validation error– Inspect thereportfield for the jsonschema path causing the failure. Missing metadata or malformed cells are common culprits.Unexpected error– Log the exception and confirm the input is an nbformatNotebookNode, not a raw dict or path string.
License
swarmauri_tool_jupytervalidatenotebook is released under the Apache 2.0 License. See LICENSE for full text.
1 maintainer
Metadata
1 maintainer
Release files for swarmauri_tool_jupytervalidatenotebook 0.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| swarmauri_tool_jupytervalidatenotebook-0.10.0.tar.gz | 8.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| swarmauri_tool_jupytervalidatenotebook-0.10.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 18.5 kB
Release files / swarmauri_tool_jupytervalidatenotebook-0.10.0.tar.gz
| Download URL | swarmauri_tool_jupytervalidatenotebook-0.10.0.tar.gz |
|---|---|
| Size | 8.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
13ed7276120b1b9b9f18e47e42b05477e3fa85041dc5b8fcd0e950803ff74d58
|
|
BLAKE2b-256 checksum How to use checksums |
052e6200453ff04cd27a0b534b8fc0259fed102834b6bb02f64f7eb4091fe2c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.0 {"installer":{"name":"uv","version":"0.11.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / swarmauri_tool_jupytervalidatenotebook-0.10.0-py3-none-any.whl
| Download URL | swarmauri_tool_jupytervalidatenotebook-0.10.0-py3-none-any.whl |
|---|---|
| Size | 9.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
88443c42dcc63074b038d18ee94304c5887fb73cceb33b34d85deccaf33aa453
|
|
BLAKE2b-256 checksum How to use checksums |
35438d0bf84a81b7e0acaee8fa478f3219a68e21a88307af20f85ebd58a04fdb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.0 {"installer":{"name":"uv","version":"0.11.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
