camel-ai 0.2.59__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]:
@@ -547,7 +655,7 @@ class FunctionTool:
         """
         self.openai_tool_schema["function"]["description"] = description
 
-    def get_paramter_description(self, param_name: str) -> str:
+    def get_parameter_description(self, param_name: str) -> str:
         r"""Gets the description of a specific parameter from the function
         schema.
 
@@ -563,7 +671,7 @@ class FunctionTool:
             param_name
         ]["description"]
 
-    def set_paramter_description(
+    def set_parameter_description(
         self,
         param_name: str,
         description: str,

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
@@ -32,7 +33,6 @@ class GithubToolkit(BaseToolkit):
         specific issues, and creating pull requests in a GitHub repository.
 
     Args:
-        repo_name (str): The name of the GitHub repository.
         access_token (str, optional): The access token to authenticate with
             GitHub. If not provided, it will be obtained using the
             `get_github_access_token` method.
@@ -41,7 +41,6 @@ class GithubToolkit(BaseToolkit):
     @dependencies_required('github')
     def __init__(
         self,
-        repo_name: str,
         access_token: Optional[str] = None,
         timeout: Optional[float] = None,
     ) -> None:
@@ -61,7 +60,6 @@ class GithubToolkit(BaseToolkit):
             access_token = self.get_github_access_token()
 
         self.github = Github(auth=Token(access_token))
-        self.repo = self.github.get_repo(repo_name)
 
     def get_github_access_token(self) -> str:
         r"""Retrieve the GitHub access token from environment variables.
@@ -83,8 +81,9 @@ class GithubToolkit(BaseToolkit):
             )
         return GITHUB_ACCESS_TOKEN
 
-    def create_pull_request(
+    def github_create_pull_request(
         self,
+        repo_name: str,
         file_path: str,
         new_content: str,
         pr_title: str,
@@ -98,6 +97,7 @@ class GithubToolkit(BaseToolkit):
         description contains information about the issue title and number.
 
         Args:
+            repo_name (str): The name of the GitHub repository.
             file_path (str): The path of the file to be updated in the
                 repository.
             new_content (str): The specified new content of the specified file.
@@ -111,12 +111,13 @@ class GithubToolkit(BaseToolkit):
             str: A formatted report of whether the pull request was created
                 successfully or not.
         """
-        sb = self.repo.get_branch(self.repo.default_branch)
+        repo = self.github.get_repo(repo_name)
+        default_branch = repo.get_branch(repo.default_branch)
         from github.GithubException import GithubException
 
         try:
-            self.repo.create_git_ref(
-                ref=f"refs/heads/{branch_name}", sha=sb.commit.sha
+            repo.create_git_ref(
+                ref=f"refs/heads/{branch_name}", sha=default_branch.commit.sha
             )
         except GithubException as e:
             if e.message == "Reference already exists":
@@ -128,19 +129,19 @@ class GithubToolkit(BaseToolkit):
             else:
                 raise
 
-        file = self.repo.get_contents(file_path)
+        file = repo.get_contents(file_path)
 
         from github.ContentFile import ContentFile
 
         if isinstance(file, ContentFile):
-            self.repo.update_file(
+            repo.update_file(
                 file.path, body, new_content, file.sha, branch=branch_name
             )
-            pr = self.repo.create_pull(
+            pr = repo.create_pull(
                 title=pr_title,
                 body=body,
                 head=branch_name,
-                base=self.repo.default_branch,
+                base=repo.default_branch,
             )
 
             if pr is not None:
@@ -150,14 +151,15 @@ class GithubToolkit(BaseToolkit):
         else:
             raise ValueError("PRs with multiple files aren't supported yet.")
 
-    def get_issue_list(
-        self, state: Literal["open", "closed", "all"] = "all"
+    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.
 
         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.
@@ -167,37 +169,43 @@ class GithubToolkit(BaseToolkit):
             List[Dict[str, object]]: A list of dictionaries where each
                 dictionary contains the issue number and title.
         """
+        repo = self.github.get_repo(repo_name)
         issues_info = []
-        issues = self.repo.get_issues(state=state)
+        issues = repo.get_issues(state=state)
 
         for issue in issues:
             issues_info.append({"number": issue.number, "title": issue.title})
 
         return issues_info
 
-    def get_issue_content(self, 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:
+            repo_name (str): The name of the GitHub repository.
             issue_number (int): The number of the issue to retrieve.
 
         Returns:
             str: issues content details.
         """
         try:
-            issue = self.repo.get_issue(number=issue_number)
+            repo = self.github.get_repo(repo_name)
+            issue = repo.get_issue(number=issue_number)
             return issue.body
         except Exception as e:
             return f"can't get Issue number {issue_number}: {e!s}"
 
-    def get_pull_request_list(
-        self, state: Literal["open", "closed", "all"] = "all"
+    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.
 
         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.
@@ -207,18 +215,22 @@ class GithubToolkit(BaseToolkit):
             list: A list of dictionaries where each dictionary contains the
                 pull request number and title.
         """
+        repo = self.github.get_repo(repo_name)
         pull_requests_info = []
-        pull_requests = self.repo.get_pulls(state=state)
+        pull_requests = repo.get_pulls(state=state)
 
         for pr in pull_requests:
             pull_requests_info.append({"number": pr.number, "title": pr.title})
 
         return pull_requests_info
 
-    def get_pull_request_code(self, pr_number: int) -> List[Dict[str, str]]:
+    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.
 
         Args:
+            repo_name (str): The name of the GitHub repository.
             pr_number (int): The number of the pull request to retrieve.
 
         Returns:
@@ -226,8 +238,9 @@ class GithubToolkit(BaseToolkit):
                 contains the file name and the corresponding code changes
                 (patch).
         """
+        repo = self.github.get_repo(repo_name)
         # Retrieve the specific pull request
-        pr = self.repo.get_pull(number=pr_number)
+        pr = repo.get_pull(number=pr_number)
 
         # Collect the file changes from the pull request
         files_changed = []
@@ -243,20 +256,22 @@ class GithubToolkit(BaseToolkit):
 
         return files_changed
 
-    def get_pull_request_comments(
-        self, pr_number: int
+    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.
 
         Args:
+            repo_name (str): The name of the GitHub repository.
             pr_number (int): The number of the pull request to retrieve.
 
         Returns:
             List[Dict[str, str]]: A list of dictionaries where each dictionary
                 contains the user ID and the comment body.
         """
+        repo = self.github.get_repo(repo_name)
         # Retrieve the specific pull request
-        pr = self.repo.get_pull(number=pr_number)
+        pr = repo.get_pull(number=pr_number)
 
         # Collect the comments from the pull request
         comments = []
@@ -266,13 +281,16 @@ class GithubToolkit(BaseToolkit):
 
         return comments
 
-    def get_all_file_paths(self, 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
@@ -280,11 +298,13 @@ class GithubToolkit(BaseToolkit):
         """
         from github.ContentFile import ContentFile
 
+        repo = self.github.get_repo(repo_name)
+
         files: List[str] = []
 
         # Retrieves all contents of the current directory
-        contents: Union[List[ContentFile], ContentFile] = (
-            self.repo.get_contents(path)
+        contents: Union[List[ContentFile], ContentFile] = repo.get_contents(
+            path
         )
 
         if isinstance(contents, ContentFile):
@@ -293,16 +313,19 @@ 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, 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:
+            repo_name (str): The name of the GitHub repository.
             file_path (str): The path of the file to retrieve.
 
         Returns:
@@ -310,7 +333,9 @@ class GithubToolkit(BaseToolkit):
         """
         from github.ContentFile import ContentFile
 
-        file_content = self.repo.get_contents(file_path)
+        repo = self.github.get_repo(repo_name)
+
+        file_content = repo.get_contents(file_path)
         if isinstance(file_content, ContentFile):
             return file_content.decoded_content.decode()
         else:
@@ -325,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)