Tool System: Registry

1. Behavior and Context

In the jazzmine architecture, the registry acts as a "Metadata and Source Store."

• Source Extraction: When a function is decorated with @tool, the registry physically reads its source code from the disk. This allows the framework to "teleport" your Python function into an isolated Docker container at runtime.
• Dependency Aggregation: It tracks which pip packages and environment variables are required by each tool. It merges these into a single "Environment Specification" for each sandbox.
• Deterministic Integrity: It computes SHA-256 checksums of the code and its requirements. If you modify a tool's logic, the registry detects the change, signaling to the infrastructure layer that a Docker image rebuild is necessary.
• Sandbox Mapping: It organizes tools into logical groups called "Sandboxes," allowing you to run different skills in different environments (e.g., one for web browsing, one for database access).

2. Purpose

• Capability Discovery: Providing the LLM with a complete menu of what it can do.
• Infrastructure Automation: Supplying the SandboxBuilder with the exact list of requirements to provision.
• Security Isolation: Ensuring that only authorized tools are available within specific containers.
• Change Detection: Efficiently managing Docker builds so that unchanged environments are reused.

3. Class: RegisteredTool

Introduction

The RegisteredTool is a comprehensive record representing a single skill. It is an internal data structure created by the @tool decorator.

Attributes

4. Class: ToolRegistry

Introduction

The ToolRegistry is the management engine that stores all tools and sandbox configurations.

Key Methods

• register_sandbox(config: SandboxConfig)

Registers an environment profile. This must be called before any tools referencing that sandbox name are imported.

• aggregate_dependencies(sandbox_name: str) -> List[str]

Returns a deduplicated, stable-sorted list of all pip requirements for a sandbox, merging the sandbox's base dependencies with those of every tool assigned to it.

• aggregate_secrets(sandbox_name: str) -> List[str]

Returns all environment variable names required by the sandbox and its tools.

• sandbox_checksum(sandbox_name: str) -> str

Computes a master hash of the entire sandbox state. If any tool code or dependency within the sandbox changes, this hash changes.

• build_tools_prompt(sandbox_name: Optional[str]) -> str

Generates the XML documentation block for the LLM. It iterates through registered tools and calls their build_prompt() methods.

5. The @tool Decorator

Introduction

The @tool decorator is the primary interface for developers to define agent capabilities.

Parameters

6. High-Level API & Examples

Example: Comprehensive Registration

from jazzmine.core.tools import tool, ToolParameter, ToolResponse, registry, SandboxConfig

# 1. Define a sandbox environment
registry.register_sandbox(SandboxConfig(
    name="analytics",
    dependencies=["numpy"],
    secrets=["DB_URL"]
))

# 2. Define a complex tool
@tool(
    description="Analyze user behavior data.",
    parameters=[
        ToolParameter("user_id", "str", "Unique user identifier", required=True)
    ],
    dependencies=["pandas"],        # Tool-specific dep
    secrets=["ANALYTICS_TOKEN"],    # Tool-specific secret
    sandbox="analytics"
)
async def analyze_behavior(user_id: str) -> ToolResponse:
    import pandas as pd  # Imports must happen inside the function
    import os
    token = os.environ.get("ANALYTICS_TOKEN")
    # Logic goes here...
    return ToolResponse(success=True, data={"score": 0.85})

# 3. Use the registry to build a prompt
prompt = registry.build_tools_prompt("analytics")

8. Error Handling

• ValueError (Source Extraction): Raised if the decorated function is defined in a REPL (interactive shell), Jupyter Notebook, or created via exec(). Tools must be defined in standard .py files.
• ValueError (Syntax): The registry runs an AST parse immediately. If the function contains invalid Python syntax, an error is raised at import time.
• UserWarning: Issued if a tool does not provide a ToolResponse return type hint, alerting the developer that the sandbox executor may have compatibility issues.

9. Remarks

• Deterministic ID: The registry uses uuid5 based on the tool name. This means that even if you restart your server, the tool ID in the Qdrant database remains stable.
• Imports inside Tools: Because only the function body is extracted and moved to a container, you should perform imports inside the function or rely on pre-installed dependencies.
• Async Support: Both def and async def functions are supported. The framework handles the event loop plumbing inside the sandbox automatically.
• Singleton: A default registry instance is provided for global use, which includes a pre-configured "default" sandbox.