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.
Metadata
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 | Provenance | Actions |
|---|---|---|---|---|
| swarmauri_tool_jupyterstartkernel-0.10.0.tar.gz | 8.8 kB | Without provenance | Details for swarmauri_tool_jupyterstartkernel-0.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| swarmauri_tool_jupyterstartkernel-0.10.0-py3-none-any.whl | Python 3 | none | any | Details for swarmauri_tool_jupyterstartkernel-0.10.0-py3-none-any.whl |
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}
|
Security for swarmauri_tool_jupyterstartkernel 0.10.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.