camel-ai 0.2.6__py3-none-any.whl → 0.2.8__py3-none-any.whl

camel/toolkits/data_commons_toolkit.py

@@ -0,0 +1,360 @@
+# =========== Copyright 2023 @ 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 @ CAMEL-AI.org. All Rights Reserved. ===========
+import logging
+from typing import Any, Dict, List, Optional, Union
+
+from camel.toolkits.base import BaseToolkit
+
+logger = logging.getLogger(__name__)
+
+
+class DataCommonsToolkit(BaseToolkit):
+    r"""A class representing a toolkit for Data Commons.
+
+    This class provides methods for querying and retrieving data from the
+    Data Commons knowledge graph. It includes functionality for:
+    - Executing SPARQL queries
+    - Retrieving triples associated with nodes
+    - Fetching statistical time series data
+    - Analyzing property labels and values
+    - Retrieving places within a given place type
+    - Obtaining statistical values for specific variables and locations
+
+    All the data are grabbed from the knowledge graph of Data Commons.
+    Refer to https://datacommons.org/browser/ for more details.
+    """
+
+    @staticmethod
+    def query_data_commons(
+        query_string: str,
+    ) -> Optional[List[Dict[str, Any]]]:
+        r"""Query the Data Commons knowledge graph using SPARQL.
+
+        Args:
+            query_string (str): A SPARQL query string.
+
+        Returns:
+            Optional[List[Dict[str, Any]]]: A list of dictionaries, each
+                representing a node matching the query conditions if success,
+                (default: :obj:`None`) otherwise.
+
+        Note:
+        - Only supports a limited subset of SPARQL functionality (ORDER BY,
+          DISTINCT, LIMIT).
+        - Each variable in the query should have a 'typeOf' condition.
+        - The Python SPARQL library currently only supports the V1 version
+          of the API.
+
+        Reference:
+            https://docs.datacommons.org/api/python/query.html
+        """
+        import datacommons
+
+        try:
+            results = datacommons.query(query_string)
+
+            processed_results = [
+                {key: value for key, value in row.items()} for row in results
+            ]
+
+            return processed_results
+
+        except Exception as e:
+            logger.error(
+                f"An error occurred while querying Data Commons: {e!s}"
+            )
+            return None
+
+    @staticmethod
+    def get_triples(
+        dcids: Union[str, List[str]], limit: int = 500
+    ) -> Optional[Dict[str, List[tuple]]]:
+        r"""Retrieve triples associated with nodes.
+
+        Args:
+            dcids (Union[str, List[str]]): A single DCID or a list of DCIDs
+                to query.
+            limit (int): The maximum number of triples per
+                combination of property and type. (default: :obj:`500`)
+
+        Returns:
+            Optional[Dict[str, List[tuple]]]: A dictionary where keys are
+                DCIDs and values are lists of associated triples if success,
+                (default: :obj:`None`) otherwise.
+
+        Note:
+        - The function will raise a ValueError if any of the required
+          arguments are missing.
+        - The function will raise a TypeError if the dcids are not a string
+          or a list of strings.
+        - The function will raise a ValueError if the limit is not between
+          1 and 500.
+        - The function will raise a KeyError if one or more of the provided
+          DCIDs do not exist in the Data Commons knowledge graph.
+        - The function will raise an Exception if an unexpected error occurs.
+
+        Reference:
+            https://docs.datacommons.org/api/python/triple.html
+        """
+        import datacommons
+
+        try:
+            result = datacommons.get_triples(dcids, limit)
+            return result
+
+        except Exception as e:
+            logger.error(f"An error occurred: {e!s}")
+            return None
+
+    @staticmethod
+    def get_stat_time_series(
+        place: str,
+        stat_var: str,
+        measurement_method: Optional[str] = None,
+        observation_period: Optional[str] = None,
+        unit: Optional[str] = None,
+        scaling_factor: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        r"""Retrieve statistical time series for a place.
+
+        Args:
+            place (str): The dcid of the Place to query for.
+            stat_var (str): The dcid of the StatisticalVariable.
+            measurement_method (str, optional): The technique used for
+                measuring a statistical variable. (default: :obj:`None`)
+            observation_period (str, optional): The time period over which an
+                observation is made. (default: :obj:`None`)
+            scaling_factor (str, optional): Property of statistical variables
+                indicating factor by which a measurement is multiplied to fit
+                a certain format. (default: :obj:`None`)
+            unit (str, optional): The unit of measurement. (default:
+                :obj:`None`)
+
+        Returns:
+            Optional[Dict[str, Any]]: A dictionary containing the statistical
+                time series data if success, (default: :obj:`None`) otherwise.
+
+        Reference:
+            https://docs.datacommons.org/api/python/stat_series.html
+        """
+        import datacommons_pandas
+
+        try:
+            result = datacommons_pandas.get_stat_series(
+                place,
+                stat_var,
+                measurement_method,
+                observation_period,
+                unit,
+                scaling_factor,
+            )
+            return result
+        except Exception as e:
+            logger.error(
+                f"An error occurred while querying Data Commons: {e!s}"
+            )
+            return None
+
+    @staticmethod
+    def get_property_labels(
+        dcids: Union[str, List[str]], out: bool = True
+    ) -> Optional[Dict[str, List[str]]]:
+        r"""Retrieves and analyzes property labels for given DCIDs.
+
+        Args:
+            dcids (list): A list of Data Commons IDs (DCIDs) to analyze.
+            out (bool): Direction of properties to retrieve. (default:
+                :obj:`True`)
+
+        Returns:
+            Optional[Dict[str, List[str]]]: Analysis results for each DCID if
+                success, (default: :obj:`None`) otherwise.
+
+        Reference:
+            https://docs.datacommons.org/api/python/property_label.html
+        """
+        import datacommons
+
+        try:
+            result = datacommons.get_property_labels(dcids, out=out)
+            return result
+        except Exception as e:
+            logger.error(
+                f"An error occurred while analyzing property labels: {e!s}"
+            )
+            return None
+
+    @staticmethod
+    def get_property_values(
+        dcids: Union[str, List[str]],
+        prop: str,
+        out: Optional[bool] = True,
+        value_type: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Optional[Dict[str, Any]]:
+        r"""Retrieves and analyzes property values for given DCIDs.
+
+        Args:
+            dcids (list): A list of Data Commons IDs (DCIDs) to analyze.
+            prop (str): The property to analyze.
+            value_type (str, optional): The type of the property value to
+                filter by. Defaults to NONE. Only applicable if the value
+                refers to a node.
+            out (bool, optional): The label's direction. (default: :obj:`True`)
+                (only returning response nodes directed towards the requested
+                node). If set to False, will only return response nodes
+                directed away from the request node. (default: :obj:`None`)
+            limit (int, optional): (≤ 500) Maximum number of values returned
+                per node. (default: :obj:`datacommons.utils._MAX_LIMIT`)
+
+        Returns:
+            Optional[Dict[str, Any]]: Analysis results for each DCID if
+                success, (default: :obj:`None`) otherwise.
+
+        Reference:
+            https://docs.datacommons.org/api/python/property_value.html
+        """
+        import datacommons
+
+        try:
+            result = datacommons.get_property_values(
+                dcids, prop, out, value_type, limit
+            )
+            return result
+
+        except Exception as e:
+            logger.error(
+                f"An error occurred while analyzing property values: {e!s}"
+            )
+            return None
+
+    @staticmethod
+    def get_places_in(
+        dcids: list, place_type: str
+    ) -> Optional[Dict[str, Any]]:
+        r"""Retrieves places within a given place type.
+
+        Args:
+            dcids (list): A list of Data Commons IDs (DCIDs) to analyze.
+            place_type (str): The type of the place to filter by.
+
+        Returns:
+            Optional[Dict[str, Any]]: Analysis results for each DCID if
+                success, (default: :obj:`None`) otherwise.
+
+        Reference:
+            https://docs.datacommons.org/api/python/place_in.html
+        """
+        import datacommons
+
+        try:
+            result = datacommons.get_places_in(dcids, place_type)
+            return result
+
+        except Exception as e:
+            logger.error(
+                "An error occurred while retrieving places in a given place "
+                f"type: {e!s}"
+            )
+            return None
+
+    @staticmethod
+    def get_stat_value(
+        place: str,
+        stat_var: str,
+        date: Optional[str] = None,
+        measurement_method: Optional[str] = None,
+        observation_period: Optional[str] = None,
+        unit: Optional[str] = None,
+        scaling_factor: Optional[str] = None,
+    ) -> Optional[float]:
+        r"""Retrieves the value of a statistical variable for a given place
+        and date.
+
+        Args:
+            place (str): The DCID of the Place to query for.
+            stat_var (str): The DCID of the StatisticalVariable.
+            date (str, optional): The preferred date of observation in ISO
+                8601 format. If not specified, returns the latest observation.
+                (default: :obj:`None`)
+            measurement_method (str, optional): The DCID of the preferred
+                measurementMethod value. (default: :obj:`None`)
+            observation_period (str, optional): The preferred observationPeriod
+                value. (default: :obj:`None`)
+            unit (str, optional): The DCID of the preferred unit value.
+                (default: :obj:`None`)
+            scaling_factor (str, optional): The preferred scalingFactor value.
+                (default: :obj:`None`)
+
+        Returns:
+            Optional[float]: The value of the statistical variable for the
+                given place and date if success, (default: :obj:`None`)
+                otherwise.
+
+        Reference:
+            https://docs.datacommons.org/api/python/stat_value.html
+        """
+        import datacommons
+
+        try:
+            result = datacommons.get_stat_value(
+                place,
+                stat_var,
+                date,
+                measurement_method,
+                observation_period,
+                unit,
+                scaling_factor,
+            )
+            return result
+
+        except Exception as e:
+            logger.error(
+                "An error occurred while retrieving the value of a "
+                f"statistical variable: {e!s}"
+            )
+            return None
+
+    @staticmethod
+    def get_stat_all(places: str, stat_vars: str) -> Optional[dict]:
+        r"""Retrieves the value of a statistical variable for a given place
+        and date.
+
+        Args:
+            places (str): The DCID IDs of the Place objects to query for.
+                (Here DCID stands for Data Commons ID, the unique identifier
+                assigned to all entities in Data Commons.)
+            stat_vars (str): The dcids of the StatisticalVariables at
+                https://datacommons.org/browser/StatisticalVariable
+
+        Returns:
+            Optional[dict]: A dictionary with the DCID of the place as the key
+                and a list of tuples as the value if success, (default:
+                :obj:`None`) otherwise.
+
+        Reference:
+            https://docs.datacommons.org/api/python/stat_all.html
+        """
+        import datacommons
+
+        try:
+            result = datacommons.get_stat_all(places, stat_vars)
+            return result
+
+        except Exception as e:
+            logger.error(
+                "An error occurred while retrieving the value of a "
+                f"statistical variable: {e!s}"
+            )
+            return None

camel/toolkits/function_tool.py

@@ -11,8 +11,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
+import logging
 import warnings
-from inspect import Parameter, signature
+from inspect import Parameter, getsource, signature
 from typing import Any, Callable, Dict, Mapping, Optional, Tuple
 
 from docstring_parser import parse
@@ -21,8 +22,13 @@ from jsonschema.validators import Draft202012Validator as JSONValidator
 from pydantic import create_model
 from pydantic.fields import FieldInfo
 
+from camel.agents import ChatAgent
+from camel.models import BaseModelBackend
+from camel.types import ModelType
 from camel.utils import get_pydantic_object_schema, to_pascal
 
+logger = logging.getLogger(__name__)
+
 
 def _remove_a_key(d: Dict, remove_key: Any) -> None:
     r"""Remove a key from a dictionary recursively."""
@@ -143,6 +149,71 @@ def get_openai_tool_schema(func: Callable) -> Dict[str, Any]:
     return openai_tool_schema
 
 
+def generate_docstring(
+    code: str,
+    model: Optional[BaseModelBackend] = None,
+) -> str:
+    r"""Generates a docstring for a given function code using LLM.
+
+    This function leverages a language model to generate a
+    PEP 8/PEP 257-compliant docstring for a provided Python function.
+    If no model is supplied, a default gpt-4o-mini is used.
+
+    Args:
+        code (str): The source code of the function.
+        model (Optional[BaseModelBackend]): An optional language model backend
+            instance. If not provided, a default gpt-4o-mini is used.
+
+    Returns:
+        str: The generated docstring.
+    """
+    # Create the docstring prompt
+    docstring_prompt = '''
+    **Role**: Generate professional Python docstrings conforming to 
+    PEP 8/PEP 257.
+
+    **Requirements**:
+    - Use appropriate format: reST, Google, or NumPy, as needed.
+    - Include parameters, return values, and exceptions.
+    - Reference any existing docstring in the function and 
+      retain useful information.
+
+    **Input**: Python function.
+
+    **Output**: Docstring content (plain text, no code markers).
+
+    **Example:**
+
+    Input:
+    ```python
+    def add(a: int, b: int) -> int:
+        return a + b
+    ```
+
+    Output:
+    Adds two numbers.
+    Args:
+        a (int): The first number.
+        b (int): The second number.
+
+    Returns:
+        int: The sum of the two numbers.
+
+    **Task**: Generate a docstring for the function below.
+
+    '''
+    # Initialize assistant with system message and model
+    assistant_sys_msg = "You are a helpful assistant."
+    docstring_assistant = ChatAgent(assistant_sys_msg, model=model)
+
+    # Create user message to prompt the assistant
+    user_msg = docstring_prompt + code
+
+    # Get the response containing the generated docstring
+    response = docstring_assistant.step(user_msg)
+    return response.msg.content
+
+
 class FunctionTool:
     r"""An abstraction of a function that OpenAI chat models can call. See
     https://platform.openai.com/docs/api-reference/chat/create.
@@ -151,23 +222,52 @@ class FunctionTool:
     provide a user-defined tool schema to override.
 
     Args:
-        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.
+        func (Callable): The function to call. The tool schema is parsed from
+            the function 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`)
+        use_schema_assistant (Optional[bool], optional): Whether to enable the
+            use of a schema assistant model to automatically generate 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
+            provided. (default: :obj:`None`)
+        schema_generation_max_retries (int, optional): The maximum
+            number of attempts to retry schema generation using the schema
+            assistant model if the previous attempts fail. (default: 2)
     """
 
     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,
     ) -> None:
         self.func = func
         self.openai_tool_schema = openai_tool_schema or get_openai_tool_schema(
             func
         )
 
+        if use_schema_assistant:
+            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 schema:
+                self.openai_tool_schema = schema
+            else:
+                raise ValueError(
+                    f"Failed to generate valid schema for "
+                    f"{self.func.__name__}."
+                )
+
     @staticmethod
     def validate_openai_tool_schema(
         openai_tool_schema: Dict[str, Any],
@@ -262,8 +362,8 @@ class FunctionTool:
         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.
+            openai_function_schema (Dict[str, Any]): The function schema to
+                set within the OpenAI tool schema.
         """
         self.openai_tool_schema["function"] = openai_function_schema
 
@@ -364,6 +464,71 @@ class FunctionTool:
             param_name
         ] = value
 
+    def generate_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.
+
+        This method uses a language model (LLM) to generate 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
+        `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
+                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.
+
+        Raises:
+            ValueError: If schema generation 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
+        while retries <= max_retries:
+            try:
+                # Generate the docstring and the schema
+                docstring = generate_docstring(code, schema_assistant_model)
+                self.func.__doc__ = docstring
+                schema = get_openai_tool_schema(self.func)
+                # Validate the schema
+                self.validate_openai_tool_schema(schema)
+                return schema
+
+            except Exception as e:
+                retries += 1
+                if retries == max_retries:
+                    raise ValueError(
+                        f"Failed to generate the OpenAI tool Schema after "
+                        f"{max_retries} retries. "
+                        f"Please set the OpenAI tool schema for "
+                        f"function {self.func.__name__} manually."
+                    ) from e
+                logger.warning("Schema validation failed. Retrying...")
+
+        return {}
+
     @property
     def parameters(self) -> Dict[str, Any]:
         r"""Getter method for the property :obj:`parameters`.
@@ -397,6 +562,8 @@ 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'