camel-ai 0.2.65__py3-none-any.whl → 0.2.82__py3-none-any.whl

camel/toolkits/function_tool.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -10,12 +10,15 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 import ast
+import asyncio
+import functools
 import inspect
 import logging
 import textwrap
 import warnings
+from concurrent.futures import ThreadPoolExecutor
 from inspect import Parameter, getsource, signature
 from typing import Any, Callable, Dict, Mapping, Optional, Tuple, Type
 
@@ -31,6 +34,9 @@ from camel.utils import get_pydantic_object_schema, to_pascal
 
 logger = logging.getLogger(__name__)
 
+# Shared thread pool for running sync tools without blocking the event loop
+_SYNC_TOOL_EXECUTOR = ThreadPoolExecutor(max_workers=64)
+
 
 def _remove_a_key(d: Dict, remove_key: Any) -> None:
     r"""Remove a key from a dictionary recursively."""
@@ -156,7 +162,12 @@ def get_openai_tool_schema(func: Callable) -> Dict[str, Any]:
         if (name := param.arg_name) in parameters_dict["properties"] and (
             description := param.description
         ):
-            parameters_dict["properties"][name]["description"] = description
+            # OpenAI does not allow descriptions on properties that use $ref.
+            # To avoid schema errors, we only add the description if "$ref" is
+            # not present.
+            prop = parameters_dict["properties"][name]
+            if "$ref" not in prop:
+                prop["description"] = description
 
     short_description = docstring.short_description or ""
     long_description = docstring.long_description or ""
@@ -190,7 +201,9 @@ def sanitize_and_enforce_required(parameters_dict):
     r"""Cleans and updates the function schema to conform with OpenAI's
     requirements:
     - Removes invalid 'default' fields from the parameters schema.
-    - Ensures all fields or function parameters are marked as required.
+    - Ensures all fields are marked as required or have null type for optional
+    fields.
+    - Recursively adds additionalProperties: false to all nested objects.
 
     Args:
         parameters_dict (dict): The dictionary representing the function
@@ -198,8 +211,38 @@ def sanitize_and_enforce_required(parameters_dict):
 
     Returns:
         dict: The updated dictionary with invalid defaults removed and all
-            fields set as required.
+            fields properly configured for strict mode.
     """
+
+    def _add_additional_properties_false(obj):
+        r"""Recursively add additionalProperties: false to all objects."""
+        if isinstance(obj, dict):
+            if (
+                obj.get("type") == "object"
+                and "additionalProperties" not in obj
+            ):
+                obj["additionalProperties"] = False
+
+            # Process nested structures
+            for key, value in obj.items():
+                if key == "properties" and isinstance(value, dict):
+                    for prop_value in value.values():
+                        _add_additional_properties_false(prop_value)
+                elif key in [
+                    "items",
+                    "allOf",
+                    "oneOf",
+                    "anyOf",
+                ] and isinstance(value, (dict, list)):
+                    if isinstance(value, dict):
+                        _add_additional_properties_false(value)
+                    elif isinstance(value, list):
+                        for item in value:
+                            _add_additional_properties_false(item)
+                elif key == "$defs" and isinstance(value, dict):
+                    for def_value in value.values():
+                        _add_additional_properties_false(def_value)
+
     # Check if 'function' and 'parameters' exist
     if (
         'function' in parameters_dict
@@ -209,12 +252,65 @@ def sanitize_and_enforce_required(parameters_dict):
         parameters = parameters_dict['function']['parameters']
         properties = parameters.get('properties', {})
 
-        # Remove 'default' key from each property
-        for field in properties.values():
-            field.pop('default', None)
+        # Track which fields should be required vs optional
+        required_fields = []
+
+        # Process each property
+        for field_name, field_schema in properties.items():
+            # Check if this field had a default value (making it optional)
+            had_default = 'default' in field_schema
+
+            # Remove 'default' key from field schema as required by OpenAI
+            field_schema.pop('default', None)
+
+            if had_default:
+                # This field is optional - add null to its type
+                current_type = field_schema.get('type')
+                has_ref = '$ref' in field_schema
+                has_any_of = 'anyOf' in field_schema
+
+                if has_ref:
+                    # Fields with $ref shouldn't have additional type field
+                    # The $ref itself defines the type structure
+                    pass
+                elif has_any_of:
+                    # Field already has anyOf
+                    any_of_types = field_schema['anyOf']
+                    has_null_type = any(
+                        item.get('type') == 'null' for item in any_of_types
+                    )
+                    if not has_null_type:
+                        # Add null type to anyOf
+                        field_schema['anyOf'].append({'type': 'null'})
+                    # Remove conflicting type field if it exists
+                    if 'type' in field_schema:
+                        del field_schema['type']
+                elif current_type:
+                    if isinstance(current_type, str):
+                        # Single type - convert to array with null
+                        field_schema['type'] = [current_type, 'null']
+                    elif (
+                        isinstance(current_type, list)
+                        and 'null' not in current_type
+                    ):
+                        # Array of types - add null if not present
+                        field_schema['type'] = [*current_type, 'null']
+                else:
+                    # No type specified, add null type
+                    field_schema['type'] = ['null']
+
+                # Optional fields are still marked as required in strict mode
+                # but with null type to indicate they can be omitted
+                required_fields.append(field_name)
+            else:
+                # This field is required
+                required_fields.append(field_name)
+
+        # Set all fields as required (strict mode requirement)
+        parameters['required'] = required_fields
 
-        # Mark all keys in 'properties' as required
-        parameters['required'] = list(properties.keys())
+        # Recursively add additionalProperties: false to all objects
+        _add_additional_properties_false(parameters)
 
     return parameters_dict
 
@@ -392,10 +488,15 @@ class FunctionTool:
                 result = self.func(*args, **kwargs)
                 return result
             except Exception as e:
+                parts = []
+                if args:
+                    parts.append(f"args={args}")
+                if kwargs:
+                    parts.append(f"kwargs={kwargs}")
+                args_str = ", ".join(parts) if parts else "no arguments"
                 raise ValueError(
                     f"Execution of function {self.func.__name__} failed with "
-                    f"arguments {args} and {kwargs}. "
-                    f"Error: {e}"
+                    f"{args_str}. Error: {e}"
                 )
 
     async def async_call(self, *args: Any, **kwargs: Any) -> Any:
@@ -405,7 +506,13 @@ class FunctionTool:
         if self.is_async:
             return await self.func(*args, **kwargs)
         else:
-            return self.func(*args, **kwargs)
+            # Run sync function in executor to avoid blocking event loop
+            # Use functools.partial to properly capture args/kwargs
+            loop = asyncio.get_running_loop()
+            return await loop.run_in_executor(
+                _SYNC_TOOL_EXECUTOR,
+                functools.partial(self.func, *args, **kwargs),
+            )
 
     @property
     def is_async(self) -> bool:
@@ -437,8 +544,8 @@ class FunctionTool:
 
         # Check the function description, if no description then raise warming
         if not openai_tool_schema["function"].get("description"):
-            warnings.warn(f"""Function description is missing for 
-                          {openai_tool_schema['function']['name']}. This may 
+            warnings.warn(f"""Function description is missing for
+                          {openai_tool_schema['function']['name']}. This may
                           affect the quality of tool calling.""")
 
         # Validate whether parameters
@@ -459,9 +566,10 @@ class FunctionTool:
             param_dict = properties[param_name]
             if "description" not in param_dict:
                 warnings.warn(
-                    f"Parameter description is missing "
-                    f"for {param_dict}. This may affect the "
-                    f"quality of tool calling."
+                    f"Parameter description is missing for the "
+                    f"function '{openai_tool_schema['function']['name']}'. "
+                    f"The parameter definition is {param_dict}. "
+                    f"This may affect the quality of tool calling."
                 )
 
     def get_openai_tool_schema(self) -> Dict[str, Any]:

camel/toolkits/github_toolkit.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -10,10 +10,11 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 
 import logging
 import os
+import warnings
 from typing import Dict, List, Literal, Optional, Union
 
 from camel.toolkits import FunctionTool
@@ -80,7 +81,7 @@ class GithubToolkit(BaseToolkit):
             )
         return GITHUB_ACCESS_TOKEN
 
-    def create_pull_request(
+    def github_create_pull_request(
         self,
         repo_name: str,
         file_path: str,
@@ -150,7 +151,7 @@ class GithubToolkit(BaseToolkit):
         else:
             raise ValueError("PRs with multiple files aren't supported yet.")
 
-    def get_issue_list(
+    def github_get_issue_list(
         self, repo_name: str, state: Literal["open", "closed", "all"] = "all"
     ) -> List[Dict[str, object]]:
         r"""Retrieves all issues from the GitHub repository.
@@ -158,7 +159,7 @@ class GithubToolkit(BaseToolkit):
         Args:
             repo_name (str): The name of the GitHub repository.
             state (Literal["open", "closed", "all"]): The state of pull
-                requests to retrieve. (default: :obj: `all`)
+                requests to retrieve. (default: :obj:`all`)
                 Options are:
                 - "open": Retrieve only open pull requests.
                 - "closed": Retrieve only closed pull requests.
@@ -177,7 +178,9 @@ class GithubToolkit(BaseToolkit):
 
         return issues_info
 
-    def get_issue_content(self, repo_name: str, issue_number: int) -> str:
+    def github_get_issue_content(
+        self, repo_name: str, issue_number: int
+    ) -> str:
         r"""Retrieves the content of a specific issue by its number.
 
         Args:
@@ -194,7 +197,7 @@ class GithubToolkit(BaseToolkit):
         except Exception as e:
             return f"can't get Issue number {issue_number}: {e!s}"
 
-    def get_pull_request_list(
+    def github_get_pull_request_list(
         self, repo_name: str, state: Literal["open", "closed", "all"] = "all"
     ) -> List[Dict[str, object]]:
         r"""Retrieves all pull requests from the GitHub repository.
@@ -202,7 +205,7 @@ class GithubToolkit(BaseToolkit):
         Args:
             repo_name (str): The name of the GitHub repository.
             state (Literal["open", "closed", "all"]): The state of pull
-                requests to retrieve. (default: :obj: `all`)
+                requests to retrieve. (default: :obj:`all`)
                 Options are:
                 - "open": Retrieve only open pull requests.
                 - "closed": Retrieve only closed pull requests.
@@ -221,7 +224,7 @@ class GithubToolkit(BaseToolkit):
 
         return pull_requests_info
 
-    def get_pull_request_code(
+    def github_get_pull_request_code(
         self, repo_name: str, pr_number: int
     ) -> List[Dict[str, str]]:
         r"""Retrieves the code changes of a specific pull request.
@@ -253,7 +256,7 @@ class GithubToolkit(BaseToolkit):
 
         return files_changed
 
-    def get_pull_request_comments(
+    def github_get_pull_request_comments(
         self, repo_name: str, pr_number: int
     ) -> List[Dict[str, str]]:
         r"""Retrieves the comments from a specific pull request.
@@ -278,14 +281,16 @@ class GithubToolkit(BaseToolkit):
 
         return comments
 
-    def get_all_file_paths(self, repo_name: str, path: str = "") -> List[str]:
+    def github_get_all_file_paths(
+        self, repo_name: str, path: str = ""
+    ) -> List[str]:
         r"""Recursively retrieves all file paths in the GitHub repository.
 
         Args:
             repo_name (str): The name of the GitHub repository.
             path (str): The repository path to start the traversal from.
                 empty string means starts from the root directory.
-                (default: :obj: `""`)
+                (default: :obj:`""`)
 
         Returns:
             List[str]: A list of file paths within the specified directory
@@ -308,13 +313,15 @@ class GithubToolkit(BaseToolkit):
             for content in contents:
                 if content.type == "dir":
                     # If it's a directory, recursively retrieve its file paths
-                    files.extend(self.get_all_file_paths(content.path))
+                    files.extend(self.github_get_all_file_paths(content.path))
                 else:
                     # If it's a file, add its path to the list
                     files.append(content.path)
         return files
 
-    def retrieve_file_content(self, repo_name: str, file_path: str) -> str:
+    def github_retrieve_file_content(
+        self, repo_name: str, file_path: str
+    ) -> str:
         r"""Retrieves the content of a file from the GitHub repository.
 
         Args:
@@ -343,12 +350,92 @@ class GithubToolkit(BaseToolkit):
                 the functions in the toolkit.
         """
         return [
-            FunctionTool(self.create_pull_request),
-            FunctionTool(self.get_issue_list),
-            FunctionTool(self.get_issue_content),
-            FunctionTool(self.get_pull_request_list),
-            FunctionTool(self.get_pull_request_code),
-            FunctionTool(self.get_pull_request_comments),
-            FunctionTool(self.get_all_file_paths),
-            FunctionTool(self.retrieve_file_content),
+            FunctionTool(self.github_create_pull_request),
+            FunctionTool(self.github_get_issue_list),
+            FunctionTool(self.github_get_issue_content),
+            FunctionTool(self.github_get_pull_request_list),
+            FunctionTool(self.github_get_pull_request_code),
+            FunctionTool(self.github_get_pull_request_comments),
+            FunctionTool(self.github_get_all_file_paths),
+            FunctionTool(self.github_retrieve_file_content),
         ]
+
+    # Deprecated method aliases for backward compatibility
+    def create_pull_request(self, *args, **kwargs):
+        r"""Deprecated: Use github_create_pull_request instead."""
+        warnings.warn(
+            "create_pull_request is deprecated. Use "
+            "github_create_pull_request instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.github_create_pull_request(*args, **kwargs)
+
+    def get_issue_list(self, *args, **kwargs):
+        r"""Deprecated: Use github_get_issue_list instead."""
+        warnings.warn(
+            "get_issue_list is deprecated. Use github_get_issue_list instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.github_get_issue_list(*args, **kwargs)
+
+    def get_issue_content(self, *args, **kwargs):
+        r"""Deprecated: Use github_get_issue_content instead."""
+        warnings.warn(
+            "get_issue_content is deprecated. Use "
+            "github_get_issue_content instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.github_get_issue_content(*args, **kwargs)
+
+    def get_pull_request_list(self, *args, **kwargs):
+        r"""Deprecated: Use github_get_pull_request_list instead."""
+        warnings.warn(
+            "get_pull_request_list is deprecated. "
+            "Use github_get_pull_request_list instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.github_get_pull_request_list(*args, **kwargs)
+
+    def get_pull_request_code(self, *args, **kwargs):
+        r"""Deprecated: Use github_get_pull_request_code instead."""
+        warnings.warn(
+            "get_pull_request_code is deprecated. Use "
+            "github_get_pull_request_code instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.github_get_pull_request_code(*args, **kwargs)
+
+    def get_pull_request_comments(self, *args, **kwargs):
+        r"""Deprecated: Use github_get_pull_request_comments instead."""
+        warnings.warn(
+            "get_pull_request_comments is deprecated. "
+            "Use github_get_pull_request_comments instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.github_get_pull_request_comments(*args, **kwargs)
+
+    def get_all_file_paths(self, *args, **kwargs):
+        r"""Deprecated: Use github_get_all_file_paths instead."""
+        warnings.warn(
+            "get_all_file_paths is deprecated. Use "
+            "github_get_all_file_paths instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.github_get_all_file_paths(*args, **kwargs)
+
+    def retrieve_file_content(self, *args, **kwargs):
+        r"""Deprecated: Use github_retrieve_file_content instead."""
+        warnings.warn(
+            "retrieve_file_content is deprecated. "
+            "Use github_retrieve_file_content instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.github_retrieve_file_content(*args, **kwargs)