swarmauri_tool_jupytershutdownkernel 0.11.0.dev1

Swarmauri notebook-lifecycle tool for shutting down Jupyter kernels programmatically with jupyter_client.

Swarmauri Tool Jupyter Shutdown Kernel

swarmauri_tool_jupytershutdownkernel is a Swarmauri notebook-lifecycle tool for shutting down Jupyter kernels programmatically. It is useful for notebook automation cleanup, CI teardown, resource reclamation, and agent workflows that must terminate kernels after execution.

Why Use Swarmauri Tool Jupyter Shutdown Kernel

• Stop Jupyter kernels cleanly after execution workflows complete.
• Reclaim compute and runtime resources in automated notebook pipelines.
• Provide a standard Swarmauri tool surface for kernel teardown.
• Return structured shutdown status suitable for orchestration and logging.

FAQ

What inputs does the tool expect?
A kernel_id string and an optional shutdown_timeout.

What does the tool return?
A dictionary with kernel_id, status, and message.

How does it behave when graceful shutdown fails?
It attempts a forced shutdown if the kernel stays alive after the timeout.

What if the kernel cannot be found?
The tool returns an error status with a descriptive message.

Features

• Swarmauri ToolBase implementation registered as JupyterShutdownKernelTool.
• Supports graceful shutdown with forced fallback.
• Reports structured success and error states.
• Useful for CI cleanup, notebook automation, and agent-managed kernels.
• Supports Python 3.10, 3.11, 3.12, 3.13, and 3.14.

Installation

uv add swarmauri_tool_jupytershutdownkernel

pip install swarmauri_tool_jupytershutdownkernel

Usage

from swarmauri_tool_jupytershutdownkernel import JupyterShutdownKernelTool

tool = JupyterShutdownKernelTool()
result = tool(kernel_id="example-kernel-id", shutdown_timeout=5)

print(result)

Examples

Shut down a kernel by ID

from swarmauri_tool_jupytershutdownkernel import JupyterShutdownKernelTool

tool = JupyterShutdownKernelTool()
result = tool("kernel-uuid-value", 5)

print(result["status"])

Use after a start-kernel workflow

from swarmauri_tool_jupyterstartkernel import JupyterStartKernelTool
from swarmauri_tool_jupytershutdownkernel import JupyterShutdownKernelTool

starter = JupyterStartKernelTool()
shutdown = JupyterShutdownKernelTool()

launch = starter()
cleanup = shutdown(launch["kernel_id"])

print(cleanup)

Register the tool in a Swarmauri collection

from swarmauri_standard.tools.ToolCollection import ToolCollection
from swarmauri_tool_jupytershutdownkernel import JupyterShutdownKernelTool

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

Related Packages

• swarmauri_tool_jupyterstartkernel
• swarmauri_tool_jupyterexecutecell
• swarmauri_tool_jupyterruncell
• swarmauri_tool_jupyterclearoutput

Swarmauri Foundations

• swarmauri
• swarmauri_core
• swarmauri_base
• swarmauri_standard

More Documentation

• jupyter_client documentation
• Jupyter kernels overview
• Swarmauri SDK repository

Best Practices

• Keep track of the kernel ID returned by your startup workflow.
• Use explicit shutdown in CI and automation even when processes are short-lived.
• Increase the timeout for busy kernels that may need a little longer to exit.
• Run shutdown logic on the same host that owns the kernel runtime files.

License

This project is licensed under the Apache-2.0 License.