toolregistry 0.2.0__tar.gz

toolregistry-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peng Ding
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

toolregistry-0.2.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.2
+Name: toolregistry
+Version: 0.2.0
+Summary: A library for managing tool registries
+Home-page: https://github.com/Oaklight/ToolRegistry
+Author: Oaklight
+Author-email: oaklight@gmx.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=1.5.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# ToolRegistry
+
+A Python library for managing and executing tools in a structured way.
+
+## Features
+
+- Tool registration and management
+- JSON Schema generation for tool parameters
+- Tool execution and result handling
+- Support for both synchronous and asynchronous tools
+
+## Installation
+
+```bash
+pip install toolregistry
+```
+
+## Usage
+
+## Examples
+
+### OpenAI Implementation
+
+The [openai_tool_usage_example.py](example/openai_tool_usage_example.py) shows how to integrate ToolRegistry with OpenAI's API.
+
+### Cicada Implementation
+
+The [cicada_tool_usage_example.py](example/cicada_tool_usage_example.py) demonstrates how to use ToolRegistry with the Cicada MultiModalModel.
+
+## OpenAI Integration
+
+The ToolRegistry integrates seamlessly with OpenAI's API. Here are some common usage patterns:
+
+### Getting Tools JSON for OpenAI
+
+```python
+tools_json = registry.get_tools_json()
+# Use this with OpenAI's API to provide available tools
+```
+
+### Executing Tool Calls
+
+```python
+# Assuming tool_calls is received from OpenAI's API
+tool_responses = registry.execute_tool_calls(tool_calls)
+```
+
+### Recovering Assistant Messages
+
+```python
+# After executing tool calls
+messages = registry.recover_tool_call_assistant_message(tool_calls, tool_responses)
+# Use these messages to continue the conversation
+```
+
+### Manual Tool Execution
+
+```python
+# Get a callable function
+add_fn = registry.get_callable("add")
+result = add_fn(a=1, b=2)  # Output: 3
+```
+
+## Documentation
+
+Full documentation is available at [https://github.com/Oaklight/ToolRegistry](https://github.com/Oaklight/ToolRegistry)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

toolregistry-0.2.0/README.md

@@ -0,0 +1,74 @@
+# ToolRegistry
+
+A Python library for managing and executing tools in a structured way.
+
+## Features
+
+- Tool registration and management
+- JSON Schema generation for tool parameters
+- Tool execution and result handling
+- Support for both synchronous and asynchronous tools
+
+## Installation
+
+```bash
+pip install toolregistry
+```
+
+## Usage
+
+## Examples
+
+### OpenAI Implementation
+
+The [openai_tool_usage_example.py](example/openai_tool_usage_example.py) shows how to integrate ToolRegistry with OpenAI's API.
+
+### Cicada Implementation
+
+The [cicada_tool_usage_example.py](example/cicada_tool_usage_example.py) demonstrates how to use ToolRegistry with the Cicada MultiModalModel.
+
+## OpenAI Integration
+
+The ToolRegistry integrates seamlessly with OpenAI's API. Here are some common usage patterns:
+
+### Getting Tools JSON for OpenAI
+
+```python
+tools_json = registry.get_tools_json()
+# Use this with OpenAI's API to provide available tools
+```
+
+### Executing Tool Calls
+
+```python
+# Assuming tool_calls is received from OpenAI's API
+tool_responses = registry.execute_tool_calls(tool_calls)
+```
+
+### Recovering Assistant Messages
+
+```python
+# After executing tool calls
+messages = registry.recover_tool_call_assistant_message(tool_calls, tool_responses)
+# Use these messages to continue the conversation
+```
+
+### Manual Tool Execution
+
+```python
+# Get a callable function
+add_fn = registry.get_callable("add")
+result = add_fn(a=1, b=2)  # Output: 3
+```
+
+## Documentation
+
+Full documentation is available at [https://github.com/Oaklight/ToolRegistry](https://github.com/Oaklight/ToolRegistry)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

toolregistry-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

toolregistry-0.2.0/setup.py

@@ -0,0 +1,32 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="toolregistry",
+    version="0.2.0",
+    description="A library for managing tool registries",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author="Oaklight",
+    author_email="oaklight@gmx.com",
+    url="https://github.com/Oaklight/ToolRegistry",
+    packages=find_packages(where="src"),
+    package_dir={"": "src"},
+    install_requires=[
+        "pydantic>=1.5.1",
+    ],
+    python_requires=">=3.8",
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ],
+)

toolregistry-0.2.0/src/toolregistry/__init__.py

@@ -0,0 +1,3 @@
+from .tool_registry import *
+
+__all__ = ["ToolRegistry", "Tool"]

toolregistry-0.2.0/src/toolregistry/tool_registry.py

@@ -0,0 +1,272 @@
+import inspect
+import json
+from typing import Any, Callable, Dict, List, Optional
+
+from pydantic import BaseModel
+
+
+class Tool(BaseModel):
+    """
+    Represents a tool (function) that can be called by the language model.
+    """
+
+    name: str
+    description: str
+    parameters: Dict[str, Any]
+    callable: Callable
+
+
+class ToolRegistry:
+    """
+    A registry for managing tools (functions) and their metadata.
+    """
+
+    def __init__(self):
+        self._tools: Dict[str, Tool] = {}
+
+    def __len__(self):
+        return len(self._tools)
+
+    def __contains__(self, name: str) -> bool:
+        """
+        Check if a tool with the given name is registered.
+        """
+        return name in self._tools
+
+    def register(self, func: Callable, description: Optional[str] = None):
+        """
+        Register a function as a tool.
+
+        Args:
+            func (Callable): The function to register.
+            description (str, optional): A description of the function. If not provided,
+                                        the function's docstring will be used.
+        """
+        # Generate the function's JSON schema based on its signature
+        parameters = self._generate_parameters_schema(func)
+        name = func.__name__
+        description = description or func.__doc__ or "No description provided."
+
+        # Create a Tool instance
+        tool = Tool(
+            name=name,
+            description=description,
+            parameters=parameters,
+            callable=func,
+        )
+
+        # Add the tool to the registry
+        self._tools[name] = tool
+
+    def merge(self, other: "ToolRegistry", keep_existing: bool = False):
+        """
+        Merge tools from another ToolRegistry into this one.
+
+        Args:
+            other (ToolRegistry): The other ToolRegistry to merge into this one.
+        """
+        if not isinstance(other, ToolRegistry):
+            raise TypeError("Can only merge with another ToolRegistry instance.")
+
+        if keep_existing:
+            for name, tool in other._tools.items():
+                if name not in self._tools:
+                    self._tools[name] = tool
+        else:
+            self._tools.update(other._tools)
+
+    def _generate_parameters_schema(self, func: Callable) -> Dict[str, Any]:
+        """
+        Generate a JSON Schema-compliant schema for the function's parameters.
+
+        Args:
+            func (Callable): The function to generate the schema for.
+
+        Returns:
+            Dict[str, Any]: The JSON Schema for the function's parameters.
+        """
+        signature = inspect.signature(func)
+        properties = {}
+        required = []
+
+        for name, param in signature.parameters.items():
+            if name == "self":
+                continue  # Skip 'self' for methods
+
+            # Map Python types to JSON Schema types
+            param_type = (
+                self._map_python_type_to_json_schema(param.annotation)
+                if param.annotation != inspect.Parameter.empty
+                else "string"
+            )
+
+            # Add the parameter to the properties
+            properties[name] = {
+                "type": param_type,
+                "description": f"The {name} parameter.",
+            }
+
+            # Check if the parameter is required
+            if param.default == inspect.Parameter.empty:
+                required.append(name)
+
+        return {
+            "type": "object",
+            "properties": properties,
+            "required": required,
+            "additionalProperties": False,  # Enforce strict parameter validation
+        }
+
+    def _map_python_type_to_json_schema(self, python_type: Any) -> str:
+        """
+        Map Python types to JSON Schema types.
+
+        Args:
+            python_type (Any): The Python type to map.
+
+        Returns:
+            str: The corresponding JSON Schema type.
+        """
+        type_mapping = {
+            "str": "string",
+            "int": "integer",
+            "float": "number",
+            "bool": "boolean",
+            "list": "array",
+            "dict": "object",
+        }
+
+        # Handle cases where the type is a class (e.g., `int`, `str`)
+        if hasattr(python_type, "__name__"):
+            return type_mapping.get(python_type.__name__, "string")
+
+        # Default to "string" if the type is not recognized
+        return "string"
+
+    def get_tools_json(self) -> List[Dict[str, Any]]:
+        """
+        Get the JSON representation of all registered tools, following JSON Schema.
+
+        Returns:
+            List[Dict[str, Any]]: A list of tools in JSON format, compliant with JSON Schema.
+        """
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "parameters": tool.parameters,
+                },
+            }
+            for tool in self._tools.values()
+        ]
+
+    def get_callable(self, function_name: str) -> Callable:
+        """
+        Get a callable function by its name.
+
+        Args:
+            function_name (str): The name of the function.
+
+        Returns:
+            Callable: The function to call, or None if not found.
+        """
+        tool = self._tools.get(function_name)
+        return tool.callable if tool else None
+
+    def execute_tool_calls(self, tool_calls: List[Any]) -> Dict[str, str]:
+        """
+        Execute tool calls and return results.
+
+        Args:
+            tool_calls (List[Any]): List of tool calls
+
+        Returns:
+            Dict[str, str]: Dictionary mapping tool call IDs to results
+        """
+        tool_responses = {}
+        for tool_call in tool_calls:
+            tool_result = None
+            try:
+                function_name = tool_call.function.name
+                function_args = json.loads(tool_call.function.arguments)
+                tool_call_id = tool_call.id
+
+                # Get the tool from registry
+                tool = self.get_callable(function_name)
+                if tool:
+                    function_response = tool(**function_args)
+                    tool_result = f"{function_name} -> {function_response}"
+                else:
+                    tool_result = f"Error: Tool '{function_name}' not found"
+            except Exception as e:
+                tool_result = f"Error executing {function_name}: {str(e)}"
+
+            tool_responses[tool_call_id] = tool_result
+
+        return tool_responses
+
+    def recover_tool_call_assistant_message(
+        self, tool_calls: List[Any], tool_responses: Dict[str, str]
+    ) -> List[Dict[str, Any]]:
+        """
+        Construct assistant messages with tool call results.
+
+        Args:
+            tool_calls (List[Any]): List of tool calls
+            tool_responses (Dict[str, str]): Tool execution results
+
+        Returns:
+            List[Dict[str, Any]]: List of message dictionaries
+        """
+        messages = []
+        for tool_call in tool_calls:
+            messages.append(
+                {
+                    "role": "assistant",
+                    "content": None,
+                    "tool_calls": [
+                        {
+                            "id": tool_call.id,
+                            "type": "function",
+                            "function": {
+                                "name": tool_call.function.name,
+                                "arguments": tool_call.function.arguments,
+                            },
+                        }
+                    ],
+                }
+            )
+            messages.append(
+                {
+                    "role": "tool",
+                    "content": tool_responses[tool_call.id],
+                    "tool_call_id": tool_call.id,
+                }
+            )
+        return messages
+
+    def __repr__(self):
+        """
+        Return the JSON representation of the registry for debugging purposes.
+        """
+        return json.dumps(self.get_tools_json(), indent=2)
+
+    def __str__(self):
+        """
+        Return the JSON representation of the registry as a string.
+        """
+        return json.dumps(self.get_tools_json(), indent=2)
+
+    def __getitem__(self, key: str) -> Callable:
+        """
+        Enable key-value access to retrieve callables.
+
+        Args:
+            key (str): The name of the function.
+
+        Returns:
+            Callable: The function to call, or None if not found.
+        """
+        return self.get_callable(key)

toolregistry-0.2.0/src/toolregistry.egg-info/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.2
+Name: toolregistry
+Version: 0.2.0
+Summary: A library for managing tool registries
+Home-page: https://github.com/Oaklight/ToolRegistry
+Author: Oaklight
+Author-email: oaklight@gmx.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=1.5.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# ToolRegistry
+
+A Python library for managing and executing tools in a structured way.
+
+## Features
+
+- Tool registration and management
+- JSON Schema generation for tool parameters
+- Tool execution and result handling
+- Support for both synchronous and asynchronous tools
+
+## Installation
+
+```bash
+pip install toolregistry
+```
+
+## Usage
+
+## Examples
+
+### OpenAI Implementation
+
+The [openai_tool_usage_example.py](example/openai_tool_usage_example.py) shows how to integrate ToolRegistry with OpenAI's API.
+
+### Cicada Implementation
+
+The [cicada_tool_usage_example.py](example/cicada_tool_usage_example.py) demonstrates how to use ToolRegistry with the Cicada MultiModalModel.
+
+## OpenAI Integration
+
+The ToolRegistry integrates seamlessly with OpenAI's API. Here are some common usage patterns:
+
+### Getting Tools JSON for OpenAI
+
+```python
+tools_json = registry.get_tools_json()
+# Use this with OpenAI's API to provide available tools
+```
+
+### Executing Tool Calls
+
+```python
+# Assuming tool_calls is received from OpenAI's API
+tool_responses = registry.execute_tool_calls(tool_calls)
+```
+
+### Recovering Assistant Messages
+
+```python
+# After executing tool calls
+messages = registry.recover_tool_call_assistant_message(tool_calls, tool_responses)
+# Use these messages to continue the conversation
+```
+
+### Manual Tool Execution
+
+```python
+# Get a callable function
+add_fn = registry.get_callable("add")
+result = add_fn(a=1, b=2)  # Output: 3
+```
+
+## Documentation
+
+Full documentation is available at [https://github.com/Oaklight/ToolRegistry](https://github.com/Oaklight/ToolRegistry)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

toolregistry-0.2.0/src/toolregistry.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+setup.py
+src/toolregistry/__init__.py
+src/toolregistry/tool_registry.py
+src/toolregistry.egg-info/PKG-INFO
+src/toolregistry.egg-info/SOURCES.txt
+src/toolregistry.egg-info/dependency_links.txt
+src/toolregistry.egg-info/requires.txt
+src/toolregistry.egg-info/top_level.txt

toolregistry-0.2.0/src/toolregistry.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

toolregistry-0.2.0/src/toolregistry.egg-info/requires.txt

@@ -0,0 +1 @@
+pydantic>=1.5.1

toolregistry-0.2.0/src/toolregistry.egg-info/top_level.txt

@@ -0,0 +1 @@
+toolregistry