Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Swarmauri Logo

PyPI - Downloads Hits PyPI - Python Version PyPI - License PyPI - swarmauri_toolkit_runtime Discord

Swarmauri Toolkit RuntimeToolkit

RuntimeToolkit is a Swarmauri runtime-management toolkit for agents that need to register, inspect, list, replace, and remove tools during execution. It keeps tool mutation inside the active toolkit instance and requires both explicit parameter declarations and an explicit __call__ implementation when a new runtime tool is introduced.

Features

  • Bundles agent-callable CRUD operations for toolkit members.
  • Accepts serialized runtime tool specs with type, parameters, and __call__ fields.
  • Enforces a non-empty declared parameters list and a non-empty __call__ body for runtime tool registration and replacement.
  • Evaluates runtime __call__ bodies through a restricted expression rail rather than unrestricted Python execution.
  • Returns agent-friendly dictionaries for reads, lists, and mutation results.
  • Protects the toolkit's own management tools from accidental overwrite or removal.
  • Supports Python 3.10 through 3.12.

Support

  • Python 3.10
  • Python 3.11
  • Python 3.12

Installation

uv

uv add swarmauri_toolkit_runtime

pip

pip install swarmauri_toolkit_runtime

Usage

Use RuntimeToolkit when an agent needs to mutate its own tool surface safely at runtime. The expected workflow is:

  1. Start with the management toolkit.
  2. Register a runtime tool using an explicit parameter contract and explicit callable body.
  3. Inspect or list the available runtime tools.
  4. Execute the registered tool.
  5. Replace or unregister the tool when the runtime surface changes.

Instantiate the toolkit and hand it to an agent or tool-capable model. The toolkit starts with only its management tools, then grows as the agent adds tools.

from swarmauri_toolkit_runtime import RuntimeToolkit

toolkit = RuntimeToolkit()

toolkit.get_tool_by_name("RegisterRuntimeTool")(
    {
        "type": "RuntimeAdditionTool",
        "name": "RuntimeAdditionTool",
        "description": "Adds two integers during the active agent session.",
        "parameters": [
            {
                "name": "x",
                "input_type": "integer",
                "description": "The left operand",
                "required": True,
            },
            {
                "name": "y",
                "input_type": "integer",
                "description": "The right operand",
                "required": True,
            },
        ],
        "__call__": '{"sum": str(x + y)}',
    }
)

result = toolkit.get_tool_by_name("RuntimeAdditionTool")(2, 3)
print(result)

Agent Workflow

  1. Call ListRuntimeTools to inspect the current runtime surface.
  2. Call RegisterRuntimeTool with a tool spec to extend the toolkit.
  3. Call InspectRuntimeTool to inspect the hydrated tool metadata.
  4. Call ReplaceRuntimeTool when the agent needs to replace a tool with a revised spec.
  5. Call UnregisterRuntimeTool when a runtime tool should no longer be available.

Tool Spec Contract

Mutation tools accept a serialized tool specification. At minimum, provide:

  • a non-empty type field that names the runtime tool surface
  • a non-empty parameters list that explicitly declares the runtime callable contract
  • a non-empty __call__ string that evaluates as a safe Python expression over the declared parameters and approved builtins

The runtime evaluator permits only a constrained expression subset and approved builtins such as str, int, float, len, sum, min, max, and abs. Imports, attribute traversal, and arbitrary function calls are rejected.

{
    "type": "RuntimeAdditionTool",
    "name": "RuntimeAdditionTool",
    "description": "Adds two integers.",
    "parameters": [
        {
            "name": "x",
            "input_type": "integer",
            "description": "The left operand",
            "required": True,
        },
        {
            "name": "y",
            "input_type": "integer",
            "description": "The right operand",
            "required": True,
        },
    ],
    "__call__": '{"sum": str(x + y)}',
}

The __call__ value is evaluated against the declared parameter names. A body such as {"sum": str(x + y)} is valid. A body that tries to import modules, access attributes, or reference undeclared names is rejected.

Failure Modes

  • Registration fails when the tool spec omits parameters.
  • Registration fails when the tool spec omits __call__.
  • Registration fails when the __call__ body uses unsafe syntax or disallowed names.
  • Registration fails when the tool name collides with a protected management tool.
  • Execution failures inside an accepted runtime tool return a structured error payload instead of propagating a hard exception or terminating the host process.
  • Replacement fails when the target tool is missing, reserved, or renamed to an existing tool.
  • Unregistration fails when the target is reserved or absent.

License

swarmauri_toolkit_runtime is released under the Apache 2.0 License. See LICENSE for details.

Metadata

Release files for swarmauri_toolkit_runtime 0.11.0.dev4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for swarmauri_toolkit_runtime 0.11.0.dev4
File Size Uploaded Provenance Actions
swarmauri_toolkit_runtime-0.11.0.dev4.tar.gz 9.4 kB Without provenance Details for swarmauri_toolkit_runtime-0.11.0.dev4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for swarmauri_toolkit_runtime 0.11.0.dev4
File Interpreter ABI Platform Actions
swarmauri_toolkit_runtime-0.11.0.dev4-py3-none-any.whl Python 3 none any Details for swarmauri_toolkit_runtime-0.11.0.dev4-py3-none-any.whl

Total release size: 21.7 kB

Release files / swarmauri_toolkit_runtime-0.11.0.dev4.tar.gz

Download URL swarmauri_toolkit_runtime-0.11.0.dev4.tar.gz
Size 9.4 kB
Tags Source
SHA-256 checksum
How to use checksums
1f25be5dbb16f4802b6b0b62f61f1f57e97b61e63065c909c4c104f6d3b2ba21
BLAKE2b-256 checksum
How to use checksums
33bed282dfde404815cbe61220e4c5f00e8d537570ef117ab196f757b1cb80f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","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_toolkit_runtime-0.11.0.dev4-py3-none-any.whl

Download URL swarmauri_toolkit_runtime-0.11.0.dev4-py3-none-any.whl
Size 12.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5fb21769d1d5a03a63f90a21ebb3cf2673b766d2ff188b413020fd43f5ee6588
BLAKE2b-256 checksum
How to use checksums
130ad9b2451a5b867ae3e47484e676f06575f8e53ed6984a5deb98e5e9ad02b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","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_toolkit_runtime 0.11.0.dev4

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page