camel-ai 0.2.9__py3-none-any.whl → 0.2.11__py3-none-any.whl

camel/toolkits/function_tool.py

@@ -1,30 +1,32 @@
-# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
-# Licensed under the Apache License, Version 2.0 (the “License”);
+# ========= Copyright 2023-2024 @ 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
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an “AS IS” BASIS,
+# distributed under the License is distributed on an "AS IS" BASIS,
 # 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 @ CAMEL-AI.org. All Rights Reserved. ===========
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+import ast
+import inspect
 import logging
 import warnings
 from inspect import Parameter, getsource, signature
-from typing import Any, Callable, Dict, Mapping, Optional, Tuple
+from typing import Any, Callable, Dict, Mapping, Optional, Tuple, Type
 
 from docstring_parser import parse
 from jsonschema.exceptions import SchemaError
 from jsonschema.validators import Draft202012Validator as JSONValidator
-from pydantic import create_model
+from pydantic import BaseModel, create_model
 from pydantic.fields import FieldInfo
 
 from camel.agents import ChatAgent
-from camel.models import BaseModelBackend
-from camel.types import ModelType
+from camel.models import BaseModelBackend, ModelFactory
+from camel.types import ModelPlatformType, ModelType
 from camel.utils import get_pydantic_object_schema, to_pascal
 
 logger = logging.getLogger(__name__)
@@ -40,6 +42,31 @@ def _remove_a_key(d: Dict, remove_key: Any) -> None:
                 _remove_a_key(d[key], remove_key)
 
 
+def _remove_title_recursively(data, parent_key=None):
+    r"""Recursively removes the 'title' key from all levels of a nested
+    dictionary, except when 'title' is an argument name in the schema.
+    """
+    if isinstance(data, dict):
+        # Only remove 'title' if it's not an argument name
+        if parent_key not in [
+            "properties",
+            "$defs",
+            "items",
+            "allOf",
+            "oneOf",
+            "anyOf",
+        ]:
+            data.pop("title", None)
+
+        # Recursively process each key-value pair
+        for key, value in data.items():
+            _remove_title_recursively(value, parent_key=key)
+    elif isinstance(data, list):
+        # Recursively process each element in the list
+        for item in data:
+            _remove_title_recursively(item, parent_key=parent_key)
+
+
 def get_openai_function_schema(func: Callable) -> Dict[str, Any]:
     r"""Generates a schema dict for an OpenAI function based on its signature.
 
@@ -118,9 +145,11 @@ def get_openai_tool_schema(func: Callable) -> Dict[str, Any]:
 
     model = _create_mol(to_pascal(func.__name__), fields)
     parameters_dict = get_pydantic_object_schema(model)
+
     # The `"title"` is generated by `model.model_json_schema()`
-    # but is useless for openai json schema
-    _remove_a_key(parameters_dict, "title")
+    # but is useless for openai json schema, remove generated 'title' from
+    # parameters_dict
+    _remove_title_recursively(parameters_dict)
 
     docstring = parse(func.__doc__ or "")
     for param in docstring.params:
@@ -227,47 +256,105 @@ class FunctionTool:
         openai_tool_schema (Optional[Dict[str, Any]], optional): A
             user-defined OpenAI tool schema to override the default result.
             (default: :obj:`None`)
-        use_schema_assistant (Optional[bool], optional): Whether to enable the
-            use of a schema assistant model to automatically generate the
+        synthesize_schema (Optional[bool], optional): Whether to enable the
+            use of a schema assistant model to automatically synthesize the
             schema if validation fails or no valid schema is provided.
             (default: :obj:`False`)
-        schema_assistant_model (Optional[BaseModelBackend], optional): An
-            assistant model (e.g., an LLM model) used to generate the schema
-            if `use_schema_assistant` is enabled and no valid schema is
+        synthesize_schema_model (Optional[BaseModelBackend], optional): An
+            assistant model (e.g., an LLM model) used to synthesize the schema
+            if `synthesize_schema` is enabled and no valid schema is
             provided. (default: :obj:`None`)
-        schema_generation_max_retries (int, optional): The maximum
-            number of attempts to retry schema generation using the schema
+        synthesize_schema_max_retries (int, optional): The maximum
+            number of attempts to retry schema synthesis using the schema
             assistant model if the previous attempts fail. (default: 2)
+        synthesize_output (Optional[bool], optional): Flag for enabling
+            synthesis output mode, where output is synthesized based on the
+            function's execution. (default: :obj:`False`)
+        synthesize_output_model (Optional[BaseModelBackend], optional):
+            Model used for output synthesis in synthesis mode.
+            (default: :obj:`None`)
+        synthesize_output_format (Optional[Type[BaseModel]], optional): Format
+            for the response when synthesizing output. (default: :obj:`None`)
     """
 
     def __init__(
         self,
         func: Callable,
         openai_tool_schema: Optional[Dict[str, Any]] = None,
-        use_schema_assistant: Optional[bool] = False,
-        schema_assistant_model: Optional[BaseModelBackend] = None,
-        schema_generation_max_retries: int = 2,
+        synthesize_schema: Optional[bool] = False,
+        synthesize_schema_model: Optional[BaseModelBackend] = None,
+        synthesize_schema_max_retries: int = 2,
+        synthesize_output: Optional[bool] = False,
+        synthesize_output_model: Optional[BaseModelBackend] = None,
+        synthesize_output_format: Optional[Type[BaseModel]] = None,
     ) -> None:
         self.func = func
         self.openai_tool_schema = openai_tool_schema or get_openai_tool_schema(
             func
         )
+        self.synthesize_output = synthesize_output
+        self.synthesize_output_model = synthesize_output_model
+        if synthesize_output and synthesize_output_model is None:
+            self.synthesize_output_model = ModelFactory.create(
+                model_platform=ModelPlatformType.DEFAULT,
+                model_type=ModelType.DEFAULT,
+            )
+            logger.warning(
+                "Warning: No synthesize_output_model provided. "
+                f"Use `{self.synthesize_output_model.model_type}` to "
+                "synthesize the output."
+            )
+        self.synthesize_output_format: Optional[type[BaseModel]] = None
+        return_annotation = inspect.signature(self.func).return_annotation
+        if synthesize_output_format is not None:
+            self.synthesize_output_format = synthesize_output_format
+        elif isinstance(return_annotation, type) and issubclass(
+            return_annotation, BaseModel
+        ):
+            self.synthesize_output_format = return_annotation
 
-        if use_schema_assistant:
+        self.synthesize_schema_model = synthesize_schema_model
+        if synthesize_schema:
             if openai_tool_schema:
                 logger.warning("""The user-defined OpenAI tool schema will be
                               overridden by the schema assistant model.""")
-            schema = self.generate_openai_tool_schema(
-                schema_generation_max_retries, schema_assistant_model
+            if self.synthesize_schema_model is None:
+                self.synthesize_schema_model = ModelFactory.create(
+                    model_platform=ModelPlatformType.DEFAULT,
+                    model_type=ModelType.DEFAULT,
+                )
+                logger.warning(
+                    "Warning: No synthesize_schema_model provided. "
+                    f"Use `{self.synthesize_schema_model.model_type}` to "
+                    "synthesize the schema."
+                )
+            schema = self.synthesize_openai_tool_schema(
+                synthesize_schema_max_retries
             )
             if schema:
                 self.openai_tool_schema = schema
             else:
                 raise ValueError(
-                    f"Failed to generate valid schema for "
+                    f"Failed to synthesize a valid schema for "
                     f"{self.func.__name__}."
                 )
 
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        if self.synthesize_output:
+            result = self.synthesize_execution_output(args, kwargs)
+            return result
+        else:
+            # Pass the extracted arguments to the indicated function
+            try:
+                result = self.func(*args, **kwargs)
+                return result
+            except Exception as e:
+                raise ValueError(
+                    f"Execution of function {self.func.__name__} failed with "
+                    f"arguments {args} and {kwargs}. "
+                    f"Error: {e}"
+                )
+
     @staticmethod
     def validate_openai_tool_schema(
         openai_tool_schema: Dict[str, Any],
@@ -464,52 +551,42 @@ class FunctionTool:
             param_name
         ] = value
 
-    def generate_openai_tool_schema(
+    def synthesize_openai_tool_schema(
         self,
         max_retries: Optional[int] = None,
-        schema_assistant_model: Optional[BaseModelBackend] = None,
     ) -> Dict[str, Any]:
-        r"""Generates an OpenAI tool schema for the specified function.
+        r"""Synthesizes an OpenAI tool schema for the specified function.
 
-        This method uses a language model (LLM) to generate the OpenAI tool
+        This method uses a language model (LLM) to synthesize the OpenAI tool
         schema for the specified function by first generating a docstring and
-        then creating a schema based on the function's source code. If no LLM
-        is provided, it defaults to initializing a gpt-4o-mini model. The
-        schema generation and validation process is retried up to
+        then creating a schema based on the function's source code. The
+        schema synthesis and validation process is retried up to
         `max_retries` times in case of failure.
 
-
         Args:
             max_retries (Optional[int], optional): The maximum number of
-                retries for schema generation and validation if the process
+                retries for schema synthesis and validation if the process
                 fails. (default: :obj:`None`)
-            schema_assistant_model (Optional[BaseModelBackend], optional): An
-                optional LLM backend model used for generating the docstring
-                and schema. If not provided, a gpt-4o-mini model
-                will be created. (default: :obj:`None`)
 
         Returns:
-            Dict[str, Any]: The generated OpenAI tool schema for the function.
+            Dict[str, Any]: The synthesis OpenAI tool schema for the function.
 
         Raises:
-            ValueError: If schema generation or validation fails after the
+            ValueError: If schema synthesis or validation fails after the
                 maximum number of retries, a ValueError is raised, prompting
                 manual schema setting.
         """
-        if not schema_assistant_model:
-            logger.warning(
-                "Warning: No model provided. "
-                f"Use `{ModelType.GPT_4O_MINI.value}` to generate the schema."
-            )
         code = getsource(self.func)
         retries = 0
         if max_retries is None:
             max_retries = 0
-        # Retry loop to handle schema generation and validation
+        # Retry loop to handle schema synthesis and validation
         while retries <= max_retries:
             try:
                 # Generate the docstring and the schema
-                docstring = generate_docstring(code, schema_assistant_model)
+                docstring = generate_docstring(
+                    code, self.synthesize_schema_model
+                )
                 self.func.__doc__ = docstring
                 schema = get_openai_tool_schema(self.func)
                 # Validate the schema
@@ -520,7 +597,7 @@ class FunctionTool:
                 retries += 1
                 if retries == max_retries:
                     raise ValueError(
-                        f"Failed to generate the OpenAI tool Schema after "
+                        f"Failed to synthesize the OpenAI tool Schema after "
                         f"{max_retries} retries. "
                         f"Please set the OpenAI tool schema for "
                         f"function {self.func.__name__} manually."
@@ -529,6 +606,102 @@ class FunctionTool:
 
         return {}
 
+    def synthesize_execution_output(
+        self,
+        args: Optional[tuple[Any, ...]] = None,
+        kwargs: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        r"""Synthesizes the output of the function based on the provided
+        positional arguments and keyword arguments.
+
+        Args:
+            args (Optional[tuple]): Positional arguments to pass to the
+                function during synthesis. (default: :obj:`None`)
+            kwargs (Optional[Dict[str, Any]]): Keyword arguments to pass to the
+                function during synthesis. (default: :obj:`None`)
+
+        Returns:
+            Any: Synthesized output from the function execution. If no
+                synthesis model is provided, a warning is logged.
+        """
+        import textwrap
+
+        # Retrieve the function source code
+        function_string = inspect.getsource(self.func)
+
+        # Check and update docstring if necessary
+        if self.func.__doc__ is not None:
+            function_string = textwrap.dedent(function_string)
+            tree = ast.parse(function_string)
+            func_node = (
+                tree.body[0]
+                if isinstance(tree.body[0], ast.FunctionDef)
+                else None
+            )
+            if func_node:
+                existing_docstring = ast.get_docstring(func_node)
+                if existing_docstring != self.func.__doc__:
+                    func_node.body[0] = ast.Expr(
+                        value=ast.Constant(value=self.func.__doc__, kind=None)
+                    )
+                    function_string = ast.unparse(tree)
+
+        # Append the args and kwargs information to the function string
+        if args:
+            function_string += f"\nargs:\n{list(args)}"
+        if kwargs:
+            function_string += f"\nkwargs:\n{kwargs}"
+
+        # Define the assistant system message
+        assistant_sys_msg = '''
+**Role:** AI Assistant specialized in synthesizing tool execution outputs
+without actual execution.
+
+**Capabilities:**
+- Analyzes function to understand their
+  purpose and expected outputs.
+- Generates synthetic outputs based on the function logic.
+- Ensures the synthesized output is contextually accurate and aligns with the
+  function's intended behavior.
+
+**Instructions:**
+1. **Input:** Provide the function code, function docstring, args, and kwargs.
+2. **Output:** Synthesize the expected output of the function based on the
+   provided args and kwargs.
+
+**Example:**
+- **User Input:**
+def sum(a, b, c=0):
+    """Adds three numbers together."""
+    return a + b + c
+
+- **Input Arguments:**
+args: (1, 2)
+kwargs: {"c": 3}
+
+- **Output:**
+6
+
+**Note:**
+- Just return the synthesized output of the function without any explanation.
+- The output should be in plain text without any formatting.
+'''
+
+        # Initialize the synthesis agent
+        synthesis_agent = ChatAgent(
+            assistant_sys_msg,
+            model=self.synthesize_output_model,
+        )
+
+        # User message combining function string and additional context
+        user_msg = function_string
+        response = synthesis_agent.step(
+            user_msg,
+            response_format=self.synthesize_output_format,
+        )
+
+        return response.msg.content
+
     @property
     def parameters(self) -> Dict[str, Any]:
         r"""Getter method for the property :obj:`parameters`.
@@ -555,25 +728,3 @@ class FunctionTool:
         except SchemaError as e:
             raise e
         self.openai_tool_schema["function"]["parameters"]["properties"] = value
-
-
-warnings.simplefilter('always', DeprecationWarning)
-
-
-# Alias for backwards compatibility
-class OpenAIFunction(FunctionTool):
-    r"""Alias for backwards compatibility."""
-
-    def __init__(self, *args, **kwargs):
-        PURPLE = '\033[95m'
-        RESET = '\033[0m'
-
-        def purple_warning(msg):
-            warnings.warn(
-                PURPLE + msg + RESET, DeprecationWarning, stacklevel=2
-            )
-
-        purple_warning(
-            "OpenAIFunction is deprecated, please use FunctionTool instead."
-        )
-        super().__init__(*args, **kwargs)

camel/toolkits/github_toolkit.py

@@ -1,16 +1,16 @@
-# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
-# Licensed under the Apache License, Version 2.0 (the “License”);
+# ========= Copyright 2023-2024 @ 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
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an “AS IS” BASIS,
+# distributed under the License is distributed on an "AS IS" BASIS,
 # 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 @ CAMEL-AI.org. All Rights Reserved. ===========
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 
 import logging
 import os

camel/toolkits/google_maps_toolkit.py

@@ -1,16 +1,16 @@
-# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
-# Licensed under the Apache License, Version 2.0 (the “License”);
+# ========= Copyright 2023-2024 @ 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
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an “AS IS” BASIS,
+# distributed under the License is distributed on an "AS IS" BASIS,
 # 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 @ CAMEL-AI.org. All Rights Reserved. ===========
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 import os
 from functools import wraps
 from typing import Any, Callable, List, Optional, Union

camel/toolkits/google_scholar_toolkit.py

@@ -1,16 +1,16 @@
-# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
-# Licensed under the Apache License, Version 2.0 (the “License”);
+# ========= Copyright 2023-2024 @ 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
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an “AS IS” BASIS,
+# distributed under the License is distributed on an "AS IS" BASIS,
 # 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 @ CAMEL-AI.org. All Rights Reserved. ===========
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 import re
 from typing import Any, Dict, List, Optional
 

camel/toolkits/human_toolkit.py

@@ -0,0 +1,53 @@
+# ========= Copyright 2023-2024 @ 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
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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. =========
+
+import logging
+from typing import List
+
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+
+logger = logging.getLogger(__name__)
+
+
+class HumanToolkit(BaseToolkit):
+    r"""A class representing a toolkit for human interaction."""
+
+    def __init__(self):
+        pass
+
+    def ask_human_via_console(self, question: str) -> str:
+        r"""Ask a question to the human via the console.
+
+        Args:
+            question (str): The question to ask the human.
+
+        Returns:
+            str: The answer from the human.
+        """
+        print(f"Question: {question}")
+        logger.info(f"Question: {question}")
+        reply = input("Your reply: ")
+        logger.info(f"User reply: {reply}")
+        return reply
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Returns a list of FunctionTool objects representing the
+        functions in the toolkit.
+
+        Returns:
+            List[FunctionTool]: A list of FunctionTool objects
+                representing the functions in the toolkit.
+        """
+        return [FunctionTool(self.ask_human_via_console)]

camel/toolkits/linkedin_toolkit.py

@@ -1,16 +1,16 @@
-# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
-# Licensed under the Apache License, Version 2.0 (the “License”);
+# ========= Copyright 2023-2024 @ 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
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an “AS IS” BASIS,
+# distributed under the License is distributed on an "AS IS" BASIS,
 # 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 @ CAMEL-AI.org. All Rights Reserved. ===========
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 
 import json
 import os

camel/toolkits/math_toolkit.py

@@ -1,16 +1,16 @@
-# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
-# Licensed under the Apache License, Version 2.0 (the “License”);
+# ========= Copyright 2023-2024 @ 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
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an “AS IS” BASIS,
+# distributed under the License is distributed on an "AS IS" BASIS,
 # 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 @ CAMEL-AI.org. All Rights Reserved. ===========
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 
 from typing import List
 
@@ -74,6 +74,3 @@ class MathToolkit(BaseToolkit):
             FunctionTool(self.sub),
             FunctionTool(self.mul),
         ]
-
-
-MATH_FUNCS: List[FunctionTool] = MathToolkit().get_tools()