swarmauri_tool_jupyterruncell 0.11.0.dev1

Swarmauri IPython-execution tool for running code cells in an active interactive shell with captured output.

Swarmauri Tool Jupyter Run Cell

swarmauri_tool_jupyterruncell is a Swarmauri IPython-execution tool for running code inside the active interactive shell and capturing cell output, error output, and success state. It is useful for notebook-style automation, interactive assistants, teaching flows, and environments that already host an IPython shell.

Why Use Swarmauri Tool Jupyter Run Cell

• Execute code directly inside the active IPython shell.
• Capture both successful output and exception traces in a consistent shape.
• Apply optional signal-based timeouts to interactive cell execution.
• Reuse an execution primitive across notebook and agent workflows.

FAQ

What inputs does the tool accept?
A code string and an optional timeout.

What does the tool return?
A dictionary with cell_output, error_output, and success.

What happens if no IPython shell is active?
The tool returns a failed result with an explanatory error message.

How is this different from jupyterexecutecell?
This tool is explicitly oriented around an already-running interactive IPython shell and returns a success flag plus separated output fields.

Features

• Swarmauri ToolBase implementation registered as JupyterRunCellTool.
• Executes Python code in the active IPython shell.
• Captures stdout and stderr-like error output into separate fields.
• Supports optional timeout-based interruption.
• Supports Python 3.10, 3.11, 3.12, 3.13, and 3.14.

Installation

uv add swarmauri_tool_jupyterruncell

pip install swarmauri_tool_jupyterruncell

Usage

from swarmauri_tool_jupyterruncell import JupyterRunCellTool

tool = JupyterRunCellTool()
result = tool(code="print('hello')", timeout=5)

print(result)

Examples

Run a simple expression

from swarmauri_tool_jupyterruncell import JupyterRunCellTool

tool = JupyterRunCellTool()
result = tool("print(3 * 7)")

print(result["cell_output"])

Capture an exception

from swarmauri_tool_jupyterruncell import JupyterRunCellTool

tool = JupyterRunCellTool()
result = tool("1 / 0")

print(result["success"], result["error_output"])

Register the tool in a Swarmauri collection

from swarmauri_standard.tools.ToolCollection import ToolCollection
from swarmauri_tool_jupyterruncell import JupyterRunCellTool

tools = ToolCollection(tools=[JupyterRunCellTool()])
print(tools)

Related Packages

• swarmauri_tool_jupyterexecutecell
• swarmauri_tool_jupyterstartkernel
• swarmauri_tool_jupytershutdownkernel
• swarmauri_tool_jupyterclearoutput

Swarmauri Foundations

• swarmauri
• swarmauri_core
• swarmauri_base
• swarmauri_standard

More Documentation

• IPython documentation
• Python signal documentation
• Swarmauri SDK repository

Best Practices

• Use short timeouts only for code you expect to complete quickly.
• Inspect success before trusting cell_output.
• Prefer controlled code snippets when exposing this tool to agents.
• Use this tool when you already have an active IPython shell rather than a separately managed Jupyter kernel session.

License

This project is licensed under the Apache-2.0 License.