llm_tool_plugin.py

Overview

The llm_tool_plugin.py file defines the foundational structure and interfaces for implementing LLM (Large Language Model) Tool Plugins within a plugin framework. It provides:

Typed dictionary definitions for LLM tool metadata and parameters.
An abstract base class for LLM tool plugins that enforces implementation of metadata retrieval and invocation methods.
A utility function to convert LLM tool metadata into an OpenAI-compatible tool description format.

This file serves as a contract and helper utility for integrating custom tools that interact with or extend LLM capabilities in a standardized way, enabling seamless plugin management and interoperability within a larger system.

Classes and Functions

TypedDict Classes

`LLMToolParameter`

A typed dictionary representing a single parameter's specification for an LLM tool.

Field	Type	Description
`type`	`str`	The data type of the parameter (e.g., "string", "integer").
`description`	`str`	A detailed description of the parameter for internal use.
`displayDescription`	`str`	A user-friendly description for display purposes.
`required`	`bool`	Whether this parameter is mandatory when invoking the tool.

Example usage:

param_example = LLMToolParameter(
    type="string",
    description="The user's email address.",
    displayDescription="User Email",
    required=True
)

`LLMToolMetadata`

A typed dictionary representing the metadata of an LLM tool plugin.

Field	Type	Description
`name`	`str`	Internal identifier of the tool.
`displayName`	`str`	User-friendly name for the tool.
`description`	`str`	Internal descriptive text explaining the tool's purpose.
`displayDescription`	`str`	User-facing description of the tool.
`parameters`	`dict[str, LLMToolParameter]`	Dictionary mapping parameter names to their specifications.

Example usage:

metadata_example = LLMToolMetadata(
    name="translate_text",
    displayName="Text Translator",
    description="Translates text from one language to another.",
    displayDescription="Translate text easily.",
    parameters={
        "source_lang": LLMToolParameter(
            type="string",
            description="Language code to translate from",
            displayDescription="Source Language",
            required=True
        ),
        "target_lang": LLMToolParameter(
            type="string",
            description="Language code to translate to",
            displayDescription="Target Language",
            required=True
        ),
        "text": LLMToolParameter(
            type="string",
            description="Text to be translated",
            displayDescription="Text",
            required=True
        )
    }
)

Class: `LLMToolPlugin`

This is an abstract base class for all LLM tool plugins. It is decorated using @pluginlib.Parent with a plugin type identifier PLUGIN_TYPE_LLM_TOOLS, indicating that it serves as a parent class within the plugin management system.

Purpose

Enforce the implementation of a method to provide the tool's metadata.
Define a standard invoke method interface for executing the tool's functionality.

Methods

@classmethod get_metadata(cls) -> LLMToolMetadata

An abstract class method that must be overridden by subclasses to return the tool's metadata as an LLMToolMetadata typed dictionary.

Parameters: None
Returns: LLMToolMetadata - Metadata describing the tool.
Raises: If not implemented, will raise an error due to @pluginlib.abstractmethod.

Example implementation:

@classmethod
def get_metadata(cls) -> LLMToolMetadata:
    return {
        "name": "example_tool",
        "displayName": "Example Tool",
        "description": "An example tool for demonstration.",
        "displayDescription": "Use this tool to do something.",
        "parameters": {
            "param1": {
                "type": "string",
                "description": "A required string parameter.",
                "displayDescription": "Parameter 1",
                "required": True
            }
        }
    }

invoke(self, **kwargs) -> str
Instance method intended to be overridden by subclasses to perform the tool's main operation.
- Parameters: Arbitrary keyword arguments corresponding to the tool's parameters.
- Returns: str - The result or output of the tool invocation.
- Raises: NotImplementedError if not overridden.
Example usage:
```
def invoke(self, **kwargs) -> str:
    # Example: return a simple string combining parameters.
    text = kwargs.get("text", "")
    return f"Processed text: {text}"
```

Function: `llm_tool_metadata_to_openai_tool`

Converts LLMToolMetadata into a dictionary formatted as an OpenAI tool function definition, suitable for use in OpenAI API calls that support function calling.

Signature

def llm_tool_metadata_to_openai_tool(llm_tool_metadata: LLMToolMetadata) -> dict[str, Any]

Parameters

llm_tool_metadata (LLMToolMetadata): The metadata dictionary describing the LLM tool.

Returns

dict[str, Any]: A dictionary matching the OpenAI function calling schema, including the function name, description, and JSON schema for parameters.

Description

This utility function maps the internally used metadata structure to the OpenAI function calling interface, enabling the plugin's tool to be registered and called as a function by OpenAI-based LLMs.

Implementation Details

The function sets "type": "function" at the top level.
Translates each parameter's type and description into JSON schema properties.
Collects all required parameters into a list for the "required" field.

Example

openai_tool = llm_tool_metadata_to_openai_tool(metadata_example)

# Output:
# {
#   "type": "function",
#   "function": {
#       "name": "translate_text",
#       "description": "Translates text from one language to another.",
#       "parameters": {
#           "type": "object",
#           "properties": {
#               "source_lang": {"type": "string", "description": "Language code to translate from"},
#               "target_lang": {"type": "string", "description": "Language code to translate to"},
#               "text": {"type": "string", "description": "Text to be translated"}
#           },
#           "required": ["source_lang", "target_lang", "text"]
#       }
#   }
# }

Important Implementation Details and Algorithms

The file uses Python's TypedDict to enforce static typing and structure on plugin metadata and parameters, which aids in validation and developer clarity.
The LLMToolPlugin class uses decorators from pluginlib:
- @pluginlib.Parent to register the class as a parent plugin type.
- @pluginlib.abstractmethod to enforce that subclasses implement get_metadata.
The invoke method is intentionally left unimplemented to force concrete plugins to provide their own implementation.
The conversion function llm_tool_metadata_to_openai_tool carefully maps internal metadata to the OpenAI function calling specification, which is crucial for integration with OpenAI's API for dynamic tool invocation.

Interaction with Other Parts of the System

The llm_tool_plugin.py file depends on:
- pluginlib for plugin registration and abstraction management.
- .common module for the constant PLUGIN_TYPE_LLM_TOOLS, which identifies the plugin type.
It serves as a base and utility provider for all LLM tool plugins, meaning:
- Other files will implement concrete subclasses of LLMToolPlugin to define specific tools.
- The plugin manager likely uses get_metadata to discover tool capabilities and parameters.
- The llm_tool_metadata_to_openai_tool function is used when integrating with OpenAI's APIs, enabling these tools to be exposed as callable functions.
This file does not itself implement any concrete tool logic but defines the interface and data structures necessary for the plugin ecosystem.

Diagram: Class Structure of `llm_tool_plugin.py`

classDiagram
    class LLMToolParameter {
        +type: str
        +description: str
        +displayDescription: str
        +required: bool
    }

    class LLMToolMetadata {
        +name: str
        +displayName: str
        +description: str
        +displayDescription: str
        +parameters: dict[str, LLMToolParameter]
    }

    class LLMToolPlugin {
        <<abstract>>
        +get_metadata(): LLMToolMetadata
        +invoke(**kwargs): str
    }

    LLMToolMetadata o-- LLMToolParameter : parameters

Summary

llm_tool_plugin.py defines the core abstractions and helpers for LLM tool plugins, providing typed metadata structures, an abstract plugin base class, and a conversion utility to adapt plugin metadata to OpenAI's function calling format. It is a foundational piece enabling developers to build and integrate custom LLM tools consistently within a plugin-enabled application environment.