camel-ai 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

camel/functions/openai_function.py

@@ -11,44 +11,356 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
-from typing import Any, Callable, Dict, Optional
+from inspect import Parameter, signature
+from typing import Any, Callable, Dict, Mapping, Optional, Tuple
 
+from docstring_parser import parse
+from jsonschema.exceptions import SchemaError
 from jsonschema.validators import Draft202012Validator as JSONValidator
+from pydantic import create_model
+from pydantic.fields import FieldInfo
 
-from camel.utils import parse_doc
+from camel.utils import PYDANTIC_V2, to_pascal
+
+
+def _remove_a_key(d: Dict, remove_key: Any) -> None:
+    r"""Remove a key from a dictionary recursively."""
+    if isinstance(d, dict):
+        for key in list(d.keys()):
+            if key == remove_key:
+                del d[key]
+            else:
+                _remove_a_key(d[key], remove_key)
+
+
+def get_openai_function_schema(func: Callable) -> Dict[str, Any]:
+    r"""Generates a schema dict for an OpenAI function based on its signature.
+
+    This function is deprecated and will be replaced by
+    :obj:`get_openai_tool_schema()` in future versions. It parses the
+    function's parameters and docstring to construct a JSON schema-like
+    dictionary.
+
+    Args:
+        func (Callable): The OpenAI function to generate the schema for.
+
+    Returns:
+        Dict[str, Any]: A dictionary representing the JSON schema of the
+            function, including its name, description, and parameter
+            specifications.
+    """
+    openai_function_schema = get_openai_tool_schema(func)["function"]
+    return openai_function_schema
+
+
+def get_openai_tool_schema(func: Callable) -> Dict[str, Any]:
+    r"""Generates an OpenAI JSON schema from a given Python function.
+
+    This function creates a schema compatible with OpenAI's API specifications,
+    based on the provided Python function. It processes the function's
+    parameters, types, and docstrings, and constructs a schema accordingly.
+
+    Note:
+        - Each parameter in `func` must have a type annotation; otherwise, it's
+          treated as 'Any'.
+        - Variable arguments (*args) and keyword arguments (**kwargs) are not
+          supported and will be ignored.
+        - A functional description including a brief and detailed explanation
+          should be provided in the docstring of `func`.
+        - All parameters of `func` must be described in its docstring.
+        - Supported docstring styles: ReST, Google, Numpydoc, and Epydoc.
+
+    Args:
+        func (Callable): The Python function to be converted into an OpenAI
+                         JSON schema.
+
+    Returns:
+        Dict[str, Any]: A dictionary representing the OpenAI JSON schema of
+                        the provided function.
+
+    See Also:
+        `OpenAI API Reference
+            <https://platform.openai.com/docs/api-reference/assistants/object>`_
+    """
+    params: Mapping[str, Parameter] = signature(func).parameters
+    fields: Dict[str, Tuple[type, FieldInfo]] = {}
+    for param_name, p in params.items():
+        param_type = p.annotation
+        param_default = p.default
+        param_kind = p.kind
+        param_annotation = p.annotation
+        # Variable parameters are not supported
+        if (
+            param_kind == Parameter.VAR_POSITIONAL
+            or param_kind == Parameter.VAR_KEYWORD
+        ):
+            continue
+        # If the parameter type is not specified, it defaults to typing.Any
+        if param_annotation is Parameter.empty:
+            param_type = Any
+        # Check if the parameter has a default value
+        if param_default is Parameter.empty:
+            fields[param_name] = (param_type, FieldInfo())
+        else:
+            fields[param_name] = (param_type, FieldInfo(default=param_default))
+
+    # Applying `create_model()` directly will result in a mypy error,
+    # create an alias to avoid this.
+    def _create_mol(name, field):
+        return create_model(name, **field)
+
+    model = _create_mol(to_pascal(func.__name__), fields)
+    # NOTE: Method `.schema()` is deprecated in pydantic v2.
+    # the result would be identical to `.model_json_schema()` in v2
+    if PYDANTIC_V2:
+        parameters_dict = model.model_json_schema()
+    else:
+        parameters_dict = model.schema()
+    # The `"title"` is generated by `model.model_json_schema()`
+    # but is useless for openai json schema
+    _remove_a_key(parameters_dict, "title")
+
+    docstring = parse(func.__doc__ or "")
+    for param in docstring.params:
+        if (name := param.arg_name) in parameters_dict["properties"] and (
+            description := param.description
+        ):
+            parameters_dict["properties"][name]["description"] = description
+
+    short_description = docstring.short_description or ""
+    long_description = docstring.long_description or ""
+    if long_description:
+        func_description = f"{short_description}\n{long_description}"
+    else:
+        func_description = short_description
+
+    openai_function_schema = {
+        "name": func.__name__,
+        "description": func_description,
+        "parameters": parameters_dict,
+    }
+
+    openai_tool_schema = {
+        "type": "function",
+        "function": openai_function_schema,
+    }
+    return openai_tool_schema
 
 
 class OpenAIFunction:
     r"""An abstraction of a function that OpenAI chat models can call. See
-    https://platform.openai.com/docs/guides/gpt/function-calling. If
-    :obj:`description` and :obj:`parameters` are both :obj:`None`, try to use
-    document parser to generate them.
+    https://platform.openai.com/docs/api-reference/chat/create.
+
+    By default, the tool schema will be parsed from the func, or you can
+    provide a user-defined tool schema to override.
 
-    # flake8: noqa :E501
     Args:
-        func (Callable): The function to call.
-        name (str, optional): The name of the function to be called. Must be
-            a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum
-            length of 64. If :obj:`None`, use the name of :obj:`func`. 
+        func (Callable): The function to call.The tool schema is parsed from
+            the signature and docstring by default.
+        openai_tool_schema (Optional[Dict[str, Any]], optional): A user-defined
+            openai tool schema to override the default result.
             (default: :obj:`None`)
-        description (str, optional): The description of what the
-            function does. (default: :obj:`None`)
-        parameters (dict, optional): The parameters the
-            functions accepts, described as a JSON Schema object. See the
-            `Function calling guide <https://platform.openai.com/docs/guides/gpt/function-calling>`_
-            for examples, and the `JSON Schema reference <https://json-schema.org/understanding-json-schema/>`_
-            for documentation about the format.
     """
 
-    def __init__(self, func: Callable, name: Optional[str] = None,
-                 description: Optional[str] = None,
-                 parameters: Optional[Dict[str, Any]] = None):
+    def __init__(
+        self,
+        func: Callable,
+        openai_tool_schema: Optional[Dict[str, Any]] = None,
+    ) -> None:
         self.func = func
-        self.name = name or func.__name__
+        self.openai_tool_schema = openai_tool_schema or get_openai_tool_schema(
+            func
+        )
+        self.properties = self.openai_tool_schema
+
+    @staticmethod
+    def validate_openai_tool_schema(openai_tool_schema: Dict[str, Any]) -> None:
+        r"""Validates the OpenAI tool schema against
+        :obj:`ToolAssistantToolsFunction`.
+        This function checks if the provided :obj:`openai_tool_schema` adheres
+        to the specifications required by OpenAI's
+        :obj:`ToolAssistantToolsFunction`. It ensures that the function
+        description and parameters are correctly formatted according to JSON
+        Schema specifications.
+        Args:
+            openai_tool_schema (Dict[str, Any]): The OpenAI tool schema to
+                validate.
+        Raises:
+            ValidationError: If the schema does not comply with the
+                specifications.
+            ValueError: If the function description or parameter descriptions
+                are missing in the schema.
+            SchemaError: If the parameters do not meet JSON Schema reference
+                specifications.
+        """
+        # Check the function description
+        if not openai_tool_schema["function"]["description"]:
+            raise ValueError("miss function description")
+
+        # Validate whether parameters
+        # meet the JSON Schema reference specifications.
+        # See https://platform.openai.com/docs/guides/gpt/function-calling
+        # for examples, and the
+        # https://json-schema.org/understanding-json-schema/ for
+        # documentation about the format.
+        parameters = openai_tool_schema["function"]["parameters"]
+        try:
+            JSONValidator.check_schema(parameters)
+        except SchemaError as e:
+            raise e
+        # Check the parameter description
+        properties: Dict[str, Any] = parameters["properties"]
+        for param_name in properties.keys():
+            param_dict = properties[param_name]
+            if "description" not in param_dict:
+                raise ValueError(
+                    f'miss description of parameter "{param_name}"'
+                )
+
+    def get_openai_tool_schema(self) -> Dict[str, Any]:
+        r"""Gets the OpenAI tool schema for this function.
+
+        This method returns the OpenAI tool schema associated with this
+        function, after validating it to ensure it meets OpenAI's
+        specifications.
+
+        Returns:
+            Dict[str, Any]: The OpenAI tool schema for this function.
+        """
+        self.validate_openai_tool_schema(self.openai_tool_schema)
+        return self.openai_tool_schema
+
+    def set_openai_tool_schema(self, schema: Dict[str, Any]) -> None:
+        r"""Sets the OpenAI tool schema for this function.
+
+        Allows setting a custom OpenAI tool schema for this function.
+
+        Args:
+            schema (Dict[str, Any]): The OpenAI tool schema to set.
+        """
+        self.openai_tool_schema = schema
+
+    def get_openai_function_schema(self) -> Dict[str, Any]:
+        r"""Gets the schema of the function from the OpenAI tool schema.
+
+        This method extracts and returns the function-specific part of the
+        OpenAI tool schema associated with this function.
+
+        Returns:
+            Dict[str, Any]: The schema of the function within the OpenAI tool
+                schema.
+        """
+        self.validate_openai_tool_schema(self.openai_tool_schema)
+        return self.openai_tool_schema["function"]
 
-        info = parse_doc(self.func)
-        self.description = description or info["description"]
-        self.parameters = parameters or info["parameters"]
+    def set_openai_function_schema(
+        self,
+        openai_function_schema: Dict[str, Any],
+    ) -> None:
+        r"""Sets the schema of the function within the OpenAI tool schema.
+
+        Args:
+            openai_function_schema (Dict[str, Any]): The function schema to set
+                within the OpenAI tool schema.
+        """
+        self.openai_tool_schema["function"] = openai_function_schema
+
+    def get_function_name(self) -> str:
+        r"""Gets the name of the function from the OpenAI tool schema.
+
+        Returns:
+            str: The name of the function.
+        """
+        self.validate_openai_tool_schema(self.openai_tool_schema)
+        return self.openai_tool_schema["function"]["name"]
+
+    def set_function_name(self, name: str) -> None:
+        r"""Sets the name of the function in the OpenAI tool schema.
+
+        Args:
+            name (str): The name of the function to set.
+        """
+        self.openai_tool_schema["function"]["name"] = name
+
+    def get_function_description(self) -> str:
+        r"""Gets the description of the function from the OpenAI tool
+        schema.
+
+        Returns:
+            str: The description of the function.
+        """
+        self.validate_openai_tool_schema(self.openai_tool_schema)
+        return self.openai_tool_schema["function"]["description"]
+
+    def set_function_description(self, description: str) -> None:
+        r"""Sets the description of the function in the OpenAI tool schema.
+
+        Args:
+            description (str): The description for the function.
+        """
+        self.openai_tool_schema["function"]["description"] = description
+
+    def get_paramter_description(self, param_name: str) -> str:
+        r"""Gets the description of a specific parameter from the function
+        schema.
+
+        Args:
+            param_name (str): The name of the parameter to get the
+                description.
+
+        Returns:
+            str: The description of the specified parameter.
+        """
+        self.validate_openai_tool_schema(self.openai_tool_schema)
+        return self.openai_tool_schema["function"]["parameters"]["properties"][
+            param_name
+        ]["description"]
+
+    def set_paramter_description(
+        self,
+        param_name: str,
+        description: str,
+    ) -> None:
+        r"""Sets the description for a specific parameter in the function
+        schema.
+
+        Args:
+            param_name (str): The name of the parameter to set the description
+                for.
+            description (str): The description for the parameter.
+        """
+        self.openai_tool_schema["function"]["parameters"]["properties"][
+            param_name
+        ]["description"] = description
+
+    def get_parameter(self, param_name: str) -> Dict[str, Any]:
+        r"""Gets the schema for a specific parameter from the function schema.
+
+        Args:
+            param_name (str): The name of the parameter to get the schema.
+
+        Returns:
+            Dict[str, Any]: The schema of the specified parameter.
+        """
+        self.validate_openai_tool_schema(self.openai_tool_schema)
+        return self.openai_tool_schema["function"]["parameters"]["properties"][
+            param_name
+        ]
+
+    def set_parameter(self, param_name: str, value: Dict[str, Any]):
+        r"""Sets the schema for a specific parameter in the function schema.
+
+        Args:
+            param_name (str): The name of the parameter to set the schema for.
+            value (Dict[str, Any]): The schema to set for the parameter.
+        """
+        try:
+            JSONValidator.check_schema(value)
+        except SchemaError as e:
+            raise e
+        self.openai_tool_schema["function"]["parameters"]["properties"][
+            param_name
+        ] = value
 
     @property
     def parameters(self) -> Dict[str, Any]:
@@ -58,10 +370,11 @@ class OpenAIFunction:
             Dict[str, Any]: the dictionary containing information of
                 parameters of this function.
         """
-        return self._parameters
+        self.validate_openai_tool_schema(self.openai_tool_schema)
+        return self.openai_tool_schema["function"]["parameters"]["properties"]
 
     @parameters.setter
-    def parameters(self, value: Dict[str, Any]):
+    def parameters(self, value: Dict[str, Any]) -> None:
         r"""Setter method for the property :obj:`parameters`. It will
         firstly check if the input parameters schema is valid. If invalid,
         the method will raise :obj:`jsonschema.exceptions.SchemaError`.
@@ -70,19 +383,8 @@ class OpenAIFunction:
             value (Dict[str, Any]): the new dictionary value for the
                 function's parameters.
         """
-        JSONValidator.check_schema(value)
-        self._parameters = value
-
-    def as_dict(self) -> Dict[str, Any]:
-        r"""Method to represent the information of this function into
-        a dictionary object.
-
-        Returns:
-            Dict[str, Any]: The dictionary object containing information
-                of this function's name, description and parameters.
-        """
-        return {
-            attr: getattr(self, attr)
-            for attr in ["name", "description", "parameters"]
-            if getattr(self, attr) is not None
-        }
+        try:
+            JSONValidator.check_schema(value)
+        except SchemaError as e:
+            raise e
+        self.openai_tool_schema["function"]["parameters"]["properties"] = value

camel/functions/search_functions.py

@@ -14,8 +14,8 @@
 import os
 from typing import Any, Dict, List
 
-import camel.agents
-from camel.functions import OpenAIFunction
+from camel.agents import ChatAgent
+from camel.functions.openai_function import OpenAIFunction
 from camel.messages import BaseMessage
 from camel.prompts import TextPrompt
 
@@ -25,10 +25,10 @@ def search_wiki(entity: str) -> str:
     required page, containing factual information about the given entity.
 
     Args:
-        entity (string): The entity to be searched.
+        entity (str): The entity to be searched.
 
     Returns:
-        string: The search result. If the page corresponding to the entity
+        str: The search result. If the page corresponding to the entity
             exists, return the summary of this entity in a string.
     """
     try:
@@ -36,19 +36,23 @@ def search_wiki(entity: str) -> str:
     except ImportError:
         raise ImportError(
             "Please install `wikipedia` first. You can install it by running "
-            "`pip install wikipedia`.")
+            "`pip install wikipedia`."
+        )
 
     result: str
 
     try:
         result = wikipedia.summary(entity, sentences=5, auto_suggest=False)
     except wikipedia.exceptions.DisambiguationError as e:
-        result = wikipedia.summary(e.options[0], sentences=5,
-                                   auto_suggest=False)
+        result = wikipedia.summary(
+            e.options[0], sentences=5, auto_suggest=False
+        )
     except wikipedia.exceptions.PageError:
-        result = ("There is no page in Wikipedia corresponding to entity "
-                  f"{entity}, please specify another word to describe the"
-                  " entity to be searched.")
+        result = (
+            "There is no page in Wikipedia corresponding to entity "
+            f"{entity}, please specify another word to describe the"
+            " entity to be searched."
+        )
     except wikipedia.exceptions.WikipediaException as e:
         result = f"An exception occurred during the search: {e}"
 
@@ -59,7 +63,7 @@ def search_google(query: str) -> List[Dict[str, Any]]:
     r"""Use Google search engine to search information for the given query.
 
     Args:
-        query (string): The query to be searched.
+        query (str): The query to be searched.
 
     Returns:
         List[Dict[str, Any]]: A list of dictionaries where each dictionary
@@ -83,7 +87,7 @@ def search_google(query: str) -> List[Dict[str, Any]]:
                 as a whole',
                 'url': 'https://www.openai.com'
             }
-        title, descrption, url of a website.
+        title, description, url of a website.
     """
     import requests
 
@@ -100,9 +104,11 @@ def search_google(query: str) -> List[Dict[str, Any]]:
     num_result_pages = 10
     # Constructing the URL
     # Doc: https://developers.google.com/custom-search/v1/using_rest
-    url = f"https://www.googleapis.com/customsearch/v1?" \
-          f"key={GOOGLE_API_KEY}&cx={SEARCH_ENGINE_ID}&q={query}&start=" \
-          f"{start_page_idx}&lr={search_language}&num={num_result_pages}"
+    url = (
+        f"https://www.googleapis.com/customsearch/v1?"
+        f"key={GOOGLE_API_KEY}&cx={SEARCH_ENGINE_ID}&q={query}&start="
+        f"{start_page_idx}&lr={search_language}&num={num_result_pages}"
+    )
 
     responses = []
     # Fetch the results given the URL
@@ -118,8 +124,9 @@ def search_google(query: str) -> List[Dict[str, Any]]:
             # Iterate over 10 results found
             for i, search_item in enumerate(search_items, start=1):
                 if "og:description" in search_item["pagemap"]["metatags"][0]:
-                    long_description = \
-                        search_item["pagemap"]["metatags"][0]["og:description"]
+                    long_description = search_item["pagemap"]["metatags"][0][
+                        "og:description"
+                    ]
                 else:
                     long_description = "N/A"
                 # Get the page title
@@ -134,7 +141,7 @@ def search_google(query: str) -> List[Dict[str, Any]]:
                     "title": title,
                     "description": snippet,
                     "long_description": long_description,
-                    "url": link
+                    "url": link,
                 }
                 responses.append(response)
         else:
@@ -150,10 +157,10 @@ def text_extract_from_web(url: str) -> str:
     r"""Get the text information from given url.
 
     Args:
-        url (string): The web site you want to search.
+        url (str): The website you want to search.
 
     Returns:
-        string: All texts extract from the web.
+        str: All texts extract from the web.
     """
     import requests
     from bs4 import BeautifulSoup
@@ -171,8 +178,9 @@ def text_extract_from_web(url: str) -> str:
         text = soup.get_text()
         # Strip text
         lines = (line.strip() for line in text.splitlines())
-        chunks = (phrase.strip() for line in lines
-                  for phrase in line.split("  "))
+        chunks = (
+            phrase.strip() for line in lines for phrase in line.split("  ")
+        )
         text = ".".join(chunk for chunk in chunks if chunk)
 
     except requests.RequestException:
@@ -186,11 +194,11 @@ def create_chunks(text: str, n: int) -> List[str]:
     r"""Returns successive n-sized chunks from provided text."
 
     Args:
-        text (string): The text to be split.
+        text (str): The text to be split.
         n (int): The max length of a single chunk.
 
     Returns:
-        List[str]: A list of splited texts.
+        List[str]: A list of split texts.
     """
 
     chunks = []
@@ -220,7 +228,7 @@ def prompt_single_step_agent(prompt: str) -> str:
         role_name="Assistant",
         content="You are a helpful assistant.",
     )
-    agent = camel.agents.ChatAgent(assistant_sys_msg)
+    agent = ChatAgent(assistant_sys_msg)
     agent.reset()
 
     user_msg = BaseMessage.make_user_message(
@@ -238,15 +246,16 @@ def summarize_text(text: str, query: str) -> str:
     given.
 
     Args:
-        text (string): Text to summarise.
-        query (string): What information you want.
+        text (str): Text to summarize.
+        query (str): What information you want.
 
     Returns:
-        string: Strings with information.
+        str: Strings with information.
     """
     summary_prompt = TextPrompt(
         '''Gather information from this text that relative to the question, but
-         do not directly answer the question.\nquestion: {query}\ntext ''')
+         do not directly answer the question.\nquestion: {query}\ntext '''
+    )
     summary_prompt = summary_prompt.format(query=query)
     # Max length of each chunk
     max_len = 3000
@@ -261,7 +270,8 @@ def summarize_text(text: str, query: str) -> str:
     # Final summarise
     final_prompt = TextPrompt(
         '''Here are some summarized texts which split from one text, Using the
-        information to answer the question: {query}.\n\nText: ''')
+        information to answer the question: {query}.\n\nText: '''
+    )
     final_prompt = final_prompt.format(query=query)
     prompt = final_prompt + results
 
@@ -276,10 +286,10 @@ def search_google_and_summarize(query: str) -> str:
     internet, and then return a summarized answer.
 
     Args:
-        query (string): Question you want to be answered.
+        query (str): Question you want to be answered.
 
     Returns:
-        string: Summarized information from webs.
+        str: Summarized information from webs.
     """
     # Google search will return a list of urls
     responses = search_google(query)
@@ -294,7 +304,8 @@ def search_google_and_summarize(query: str) -> str:
             # Let chatgpt decide whether to continue search or not
             prompt = TextPrompt(
                 '''Do you think the answer: {answer} can answer the query:
-                {query}. Use only 'yes' or 'no' to answer.''')
+                {query}. Use only 'yes' or 'no' to answer.'''
+            )
             prompt = prompt.format(answer=answer, query=query)
             reply = prompt_single_step_agent(prompt)
             if "yes" in str(reply).lower():
@@ -303,7 +314,61 @@ def search_google_and_summarize(query: str) -> str:
     return "Failed to find the answer from google search."
 
 
+def query_wolfram_alpha(query: str, is_detailed: bool) -> str:
+    r"""Queries Wolfram|Alpha and returns the result. Wolfram|Alpha is an
+    answer engine developed by Wolfram Research. It is offered as an online
+    service that answers factual queries by computing answers from externally
+    sourced data.
+
+    Args:
+        query (str): The query to send to Wolfram Alpha.
+        is_detailed (bool): Whether to include additional details in the
+            result.
+
+    Returns:
+        str: The result from Wolfram Alpha, formatted as a string.
+    """
+    try:
+        import wolframalpha
+    except ImportError:
+        raise ImportError(
+            "Please install `wolframalpha` first. You can install it by running `pip install wolframalpha`."
+        )
+
+    WOLFRAMALPHA_APP_ID = os.environ.get('WOLFRAMALPHA_APP_ID')
+    if not WOLFRAMALPHA_APP_ID:
+        raise ValueError(
+            "`WOLFRAMALPHA_APP_ID` not found in environment "
+            "variables. Get `WOLFRAMALPHA_APP_ID` here: "
+            "`https://products.wolframalpha.com/api/`."
+        )
+
+    try:
+        client = wolframalpha.Client(WOLFRAMALPHA_APP_ID)
+        res = client.query(query)
+        assumption = next(res.pods).text or "No assumption made."
+        answer = next(res.results).text or "No answer found."
+    except Exception as e:
+        if isinstance(e, StopIteration):
+            return "Wolfram Alpha wasn't able to answer it"
+        else:
+            error_message = f"Wolfram Alpha wasn't able to answer it" f"{e!s}."
+            return error_message
+
+    result = f"Assumption:\n{assumption}\n\nAnswer:\n{answer}"
+
+    # Add additional details in the result
+    if is_detailed:
+        result += '\n'
+        for pod in res.pods:
+            result += '\n' + pod['@title'] + ':\n'
+            for sub in pod.subpods:
+                result += (sub.plaintext or "None") + '\n'
+
+    return result.rstrip()  # Remove trailing whitespace
+
+
 SEARCH_FUNCS: List[OpenAIFunction] = [
-    OpenAIFunction(func)
-    for func in [search_wiki, search_google_and_summarize]
+    OpenAIFunction(func)  # type: ignore[arg-type]
+    for func in [search_wiki, search_google_and_summarize, query_wolfram_alpha]
 ]