swarmauri_tool_jupyterexecutecell 0.11.0.dev1

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

Swarmauri Tool Jupyter Execute Cell

swarmauri_tool_jupyterexecutecell is a Swarmauri code-execution tool for running a single code cell inside the active IPython or Jupyter environment and capturing stdout, stderr, and error information. It is useful for notebook automation, agent-directed code execution, validation workflows, and interactive runtime tooling.

Why Use Swarmauri Tool Jupyter Execute Cell

• Execute code snippets from Swarmauri workflows in a live notebook context.
• Capture stdout, stderr, and tracebacks in a structured response.
• Apply timeouts to code execution to avoid hanging runs.
• Reuse the same callable surface across automation, agents, and testing flows.

FAQ

What inputs does the tool accept?
A code string plus an optional timeout in seconds.

What does the tool return?
A dictionary containing stdout, stderr, and error.

What happens when no active IPython kernel is available?
The tool returns an error payload indicating the kernel could not be found.

Does the tool execute asynchronously?
No. It executes synchronously and uses a thread-backed timeout guard.

Features

• Swarmauri ToolBase implementation registered as JupyterExecuteCellTool.
• Runs code in the active IPython/Jupyter environment.
• Captures stdout, stderr, and traceback information.
• Supports timeout-based interruption of long-running tasks.
• Supports Python 3.10, 3.11, 3.12, 3.13, and 3.14.

Installation

uv add swarmauri_tool_jupyterexecutecell

pip install swarmauri_tool_jupyterexecutecell

Usage

from swarmauri_tool_jupyterexecutecell import JupyterExecuteCellTool

tool = JupyterExecuteCellTool()
result = tool("print('Hello from Swarmauri')", timeout=30)

print(result)

Examples

Execute a quick print statement

from swarmauri_tool_jupyterexecutecell import JupyterExecuteCellTool

tool = JupyterExecuteCellTool()
result = tool("print(2 + 2)")

print(result["stdout"])

Capture a runtime error

from swarmauri_tool_jupyterexecutecell import JupyterExecuteCellTool

tool = JupyterExecuteCellTool()
result = tool("raise ValueError('bad input')")

print(result["error"])

Register the tool in a Swarmauri collection

from swarmauri_standard.tools.ToolCollection import ToolCollection
from swarmauri_tool_jupyterexecutecell import JupyterExecuteCellTool

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

Related Packages

• swarmauri_tool_jupyterruncell
• swarmauri_tool_jupyterstartkernel
• swarmauri_tool_jupytershutdownkernel
• swarmauri_tool_jupyterclearoutput

Swarmauri Foundations

• swarmauri
• swarmauri_core
• swarmauri_base
• swarmauri_standard

More Documentation

• IPython documentation
• Jupyter messaging and kernels
• Swarmauri SDK repository

Best Practices

• Keep executed code small and purposeful when running inside agents.
• Use timeouts for untrusted or potentially long-running cells.
• Inspect both stderr and error before assuming success.
• Prefer explicit kernel lifecycle management in multi-step notebook workflows.

License

This project is licensed under the Apache-2.0 License.