Swarmauri Tool · Jupyter Start Kernel
A Swarmauri orchestration tool that spins up Jupyter kernels on demand using jupyter_client. The helper wraps connection-file management, kernel specification, and timeout handling so automation pipelines, notebook CI, or Swarmauri agents can acquire fresh kernels with one function call.
- Launches kernels with configurable names and kernel-spec overrides.
- Surfaces ready-to-use connection metadata for downstream orchestration.
- Keeps a reference to the underlying
KernelManagerso you can interact with the kernel lifecycle after launch.
Requirements
- Python 3.10 – 3.13.
- The environment must have Jupyter kernel specs installed (for example the default
python3). - Dependencies (
jupyter_client,swarmauri_base,swarmauri_standard,pydantic) install automatically.
Installation
Install via the packaging tool that matches your workflow. Each command fetches transitive dependencies.
pip
pip install swarmauri_tool_jupyterstartkernel
Poetry
poetry add swarmauri_tool_jupyterstartkernel
uv
# Add to the current project and update uv.lock
uv add swarmauri_tool_jupyterstartkernel
# or install into the active environment without touching pyproject.toml
uv pip install swarmauri_tool_jupyterstartkernel
Tip: When using uv inside this repository, run commands from the repository root so
uvcan resolve the sharedpyproject.toml.
Quick Start
The tool behaves like a callable. Instantiate it and optionally pass a kernel_name, timeout, or kernel spec.
from swarmauri_tool_jupyterstartkernel import JupyterStartKernelTool
start_kernel = JupyterStartKernelTool()
result = start_kernel() # defaults to python3
print(result)
# {
# 'status': 'success',
# 'kernel_id': '03c7d8f9-ec4d-4a8a-8a90-cdb35ff9e6c9',
# 'kernel_name': 'python3',
# 'connection_file': '/Users/.../jupyter/runtime/kernel-03c7d8f9.json'
# }
A non-success status signals the kernel failed to spawn (missing kernelspec, permission issue, etc.).
Usage Scenarios
Launch With Custom Specification
from swarmauri_tool_jupyterstartkernel import JupyterStartKernelTool
start_kernel = JupyterStartKernelTool()
config = {
"env": {"EXPERIMENT_FLAG": "1"},
"resource_limits": {"memory": "1G"}
}
custom = start_kernel(kernel_name="python3", kernel_spec=config, startup_timeout=20)
if custom["status"] == "success":
print(f"Kernel ready at {custom['connection_file']}")
else:
raise RuntimeError(custom["message"])
Pass a kernel_spec dict to tweak environment variables or other launch parameters that the underlying KernelManager accepts.
Pair With the Shutdown Tool in an Automated Flow
from swarmauri_tool_jupyterstartkernel import JupyterStartKernelTool
from swarmauri_tool_jupytershutdownkernel import JupyterShutdownKernelTool
start_kernel = JupyterStartKernelTool()
shutdown_kernel = JupyterShutdownKernelTool()
launch = start_kernel(kernel_name="python3")
if launch["status"] != "success":
raise RuntimeError(launch["message"])
kernel_id = launch["kernel_id"]
print(f"Kernel started: {kernel_id}")
# ... run your notebook execution workflow ...
cleanup = shutdown_kernel(kernel_id=kernel_id, shutdown_timeout=10)
print(cleanup)
Use this pairing in CI pipelines or agent flows that must guarantee kernels are torn down after execution.
Integrate Inside a Swarmauri Agent
from swarmauri_core.agent.Agent import Agent
from swarmauri_core.messages.HumanMessage import HumanMessage
from swarmauri_standard.tools.registry import ToolRegistry
from swarmauri_tool_jupyterstartkernel import JupyterStartKernelTool
registry = ToolRegistry()
registry.register(JupyterStartKernelTool())
agent = Agent(tool_registry=registry)
message = HumanMessage(content="start a python3 kernel for my notebook batch job")
response = agent.run(message)
print(response)
The agent resolves the registered tool, starts a kernel, and returns the connection metadata to the conversation context.
Troubleshooting
No such kernel– The requestedkernel_nameis not installed. Checkjupyter kernelspec list.Kernel start timeout exceeded– Increasestartup_timeoutfor slow environments or pre-warm interpreters.- Permission errors – Ensure the process can create files inside Jupyter's runtime directory (usually
~/.local/share/jupyter/runtime).
License
swarmauri_tool_jupyterstartkernel is released under the Apache 2.0 License. See LICENSE for details.
1 maintainer
Metadata
1 maintainer
Release files for swarmauri_tool_jupyterstartkernel 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_jupyterstartkernel-0.10.0.tar.gz | 8.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| swarmauri_tool_jupyterstartkernel-0.10.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 18.8 kB
Release files / swarmauri_tool_jupyterstartkernel-0.10.0.tar.gz
| Download URL | swarmauri_tool_jupyterstartkernel-0.10.0.tar.gz |
|---|---|
| Size | 8.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
746fd9712d5e5d991c75b622a4a58e8656d896a6ce034309fe5cd765a20d4b5a
|
|
BLAKE2b-256 checksum How to use checksums |
9c4b2a46b827b4904143767b0d47a55cc3f092bf9b2699de73beeb40f5336016
|
| 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_jupyterstartkernel-0.10.0-py3-none-any.whl
| Download URL | swarmauri_tool_jupyterstartkernel-0.10.0-py3-none-any.whl |
|---|---|
| Size | 10.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a362ad95c4093798c24935155de28fb9d2024c5a5f08e856cdec04a8964ea5d9
|
|
BLAKE2b-256 checksum How to use checksums |
6c7e21d896aab419302c3e7a2f67a09c438384f38f445cea4c119c1951cbd902
|
| 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}
|
