camel-ai 0.1.5.6__py3-none-any.whl → 0.1.6.1__py3-none-any.whl

camel/toolkits/dalle_toolkit.py

@@ -0,0 +1,146 @@
+# =========== 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 base64
+import os
+import uuid
+from io import BytesIO
+from typing import List, Optional
+
+from openai import OpenAI
+from PIL import Image
+
+from camel.toolkits import OpenAIFunction
+from camel.toolkits.base import BaseToolkit
+
+
+class DalleToolkit(BaseToolkit):
+    r"""A class representing a toolkit for image generation using OpenAI's.
+
+    This class provides methods handle image generation using OpenAI's DALL-E.
+    """
+
+    def base64_to_image(self, base64_string: str) -> Optional[Image.Image]:
+        r"""Converts a base64 encoded string into a PIL Image object.
+
+        Args:
+            base64_string (str): The base64 encoded string of the image.
+
+        Returns:
+            Optional[Image.Image]: The PIL Image object or None if conversion
+                fails.
+        """
+        try:
+            # Decode the base64 string to get the image data
+            image_data = base64.b64decode(base64_string)
+            # Create a memory buffer for the image data
+            image_buffer = BytesIO(image_data)
+            # Open the image using the PIL library
+            image = Image.open(image_buffer)
+            return image
+        except Exception as e:
+            print(f"An error occurred while converting base64 to image: {e}")
+            return None
+
+    def image_path_to_base64(self, image_path: str) -> str:
+        r"""Converts the file path of an image to a Base64 encoded string.
+
+        Args:
+            image_path (str): The path to the image file.
+
+        Returns:
+            str: A Base64 encoded string representing the content of the image
+                file.
+        """
+        try:
+            with open(image_path, "rb") as image_file:
+                return base64.b64encode(image_file.read()).decode('utf-8')
+        except Exception as e:
+            print(
+                f"An error occurred while converting image path to base64: {e}"
+            )
+            return ""
+
+    def image_to_base64(self, image: Image.Image) -> str:
+        r"""Converts an image into a base64-encoded string.
+
+        This function takes an image object as input, encodes the image into a
+        PNG format base64 string, and returns it.
+        If the encoding process encounters an error, it prints the error
+        message and returns None.
+
+        Args:
+            image: The image object to be encoded, supports any image format
+                that can be saved in PNG format.
+
+        Returns:
+            str: A base64-encoded string of the image.
+        """
+        try:
+            with BytesIO() as buffered_image:
+                image.save(buffered_image, format="PNG")
+                buffered_image.seek(0)
+                image_bytes = buffered_image.read()
+                base64_str = base64.b64encode(image_bytes).decode('utf-8')
+                return base64_str
+        except Exception as e:
+            print(f"An error occurred: {e}")
+            return ""
+
+    def get_dalle_img(self, prompt: str, image_dir: str = "img") -> str:
+        r"""Generate an image using OpenAI's DALL-E model.
+            The generated image is saved to the specified directory.
+
+        Args:
+            prompt (str): The text prompt based on which the image is
+                generated.
+            image_dir (str): The directory to save the generated image.
+                Defaults to 'img'.
+
+        Returns:
+            str: The path to the saved image.
+        """
+
+        dalle_client = OpenAI()
+        response = dalle_client.images.generate(
+            model="dall-e-3",
+            prompt=prompt,
+            size="1024x1792",
+            quality="standard",
+            n=1,  # NOTE: now dall-e-3 only supports n=1
+            response_format="b64_json",
+        )
+        image_b64 = response.data[0].b64_json
+        image = self.base64_to_image(image_b64)  # type: ignore[arg-type]
+
+        if image is None:
+            raise ValueError("Failed to convert base64 string to image.")
+
+        os.makedirs(image_dir, exist_ok=True)
+        image_path = os.path.join(image_dir, f"{uuid.uuid4()}.png")
+        image.save(image_path)
+
+        return image_path
+
+    def get_tools(self) -> List[OpenAIFunction]:
+        r"""Returns a list of OpenAIFunction objects representing the
+        functions in the toolkit.
+
+        Returns:
+            List[OpenAIFunction]: A list of OpenAIFunction objects
+                representing the functions in the toolkit.
+        """
+        return [OpenAIFunction(self.get_dalle_img)]
+
+
+DALLE_FUNCS: List[OpenAIFunction] = DalleToolkit().get_tools()

camel/toolkits/github_toolkit.py

@@ -13,17 +13,18 @@
 # =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
 
 import os
-from dataclasses import dataclass
 from datetime import datetime, timedelta
 from typing import List, Optional
 
-from camel.functions import OpenAIFunction
-from camel.toolkits.base import BaseToolkit
+from pydantic import BaseModel
+
 from camel.utils import dependencies_required
 
+from .base import BaseToolkit
+from .openai_function import OpenAIFunction
+
 
-@dataclass
-class GithubIssue:
+class GithubIssue(BaseModel):
     r"""Represents a GitHub issue.
 
     Attributes:
@@ -34,29 +35,11 @@ class GithubIssue:
         file_content (str): The content of the file associated with the issue.
     """
 
-    def __init__(
-        self,
-        title: str,
-        body: str,
-        number: int,
-        file_path: str,
-        file_content: str,
-    ) -> None:
-        r"""Initialize a GithubIssue object.
-
-        Args:
-            title (str): The title of the GitHub issue.
-            body (str): The body/content of the GitHub issue.
-            number (int): The issue number.
-            file_path (str): The path of the file associated with the issue.
-            file_content (str): The content of the file associated with the
-                issue.
-        """
-        self.title = title
-        self.body = body
-        self.number = number
-        self.file_path = file_path
-        self.file_content = file_content
+    title: str
+    body: str
+    number: int
+    file_path: str
+    file_content: str
 
     def __str__(self) -> str:
         r"""Returns a string representation of the issue.
@@ -74,8 +57,7 @@ class GithubIssue:
         )
 
 
-@dataclass
-class GithubPullRequestDiff:
+class GithubPullRequestDiff(BaseModel):
     r"""Represents a single diff of a pull request on Github.
 
     Attributes:
@@ -91,8 +73,7 @@ class GithubPullRequestDiff:
         return f"Filename: {self.filename}\nPatch: {self.patch}"
 
 
-@dataclass
-class GithubPullRequest:
+class GithubPullRequest(BaseModel):
     r"""Represents a pull request on Github.
 
     Attributes:
@@ -250,13 +231,17 @@ class GithubToolkit(BaseToolkit):
                 and pr.merged_at is not None
                 and pr.merged_at.timestamp() > earliest_date.timestamp()
             ):
-                pr_details = GithubPullRequest(pr.title, pr.body, [])
+                pr_details = GithubPullRequest(
+                    title=pr.title, body=pr.body, diffs=[]
+                )
 
                 # Get files changed in the PR
                 files = pr.get_files()
 
                 for file in files:
-                    diff = GithubPullRequestDiff(file.filename, file.patch)
+                    diff = GithubPullRequestDiff(
+                        filename=file.filename, patch=file.patch
+                    )
                     pr_details.diffs.append(diff)
 
                 merged_prs.append(str(pr_details))

camel/toolkits/google_maps_toolkit.py

@@ -0,0 +1,368 @@
+# =========== 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 os
+from functools import wraps
+from typing import Any, Callable, List, Optional, Tuple, Union
+
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.openai_function import OpenAIFunction
+
+
+def handle_googlemaps_exceptions(
+    func: Callable[..., Any],
+) -> Callable[..., Any]:
+    r"""Decorator to catch and handle exceptions raised by Google Maps API
+    calls.
+
+    Args:
+        func (Callable): The function to be wrapped by the decorator.
+
+    Returns:
+        Callable: A wrapper function that calls the wrapped function and
+                handles exceptions.
+    """
+
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            # ruff: noqa: E501
+            from googlemaps.exceptions import (  # type: ignore[import]
+                ApiError,
+                HTTPError,
+                Timeout,
+                TransportError,
+            )
+        except ImportError:
+            raise ImportError(
+                "Please install `googlemaps` first. You can install "
+                "it by running `pip install googlemaps`."
+            )
+
+        try:
+            return func(*args, **kwargs)
+        except ApiError as e:
+            return (
+                'An exception returned by the remote API. '
+                f'Status: {e.status}, Message: {e.message}'
+            )
+        except HTTPError as e:
+            return (
+                'An unexpected HTTP error occurred. '
+                f'Status Code: {e.status_code}'
+            )
+        except Timeout:
+            return 'The request timed out.'
+        except TransportError as e:
+            return (
+                'Something went wrong while trying to execute the '
+                f'request. Details: {e.base_exception}'
+            )
+        except Exception as e:
+            return f'An unexpected error occurred: {e}'
+
+    return wrapper
+
+
+class GoogleMapsToolkit(BaseToolkit):
+    r"""A class representing a toolkit for interacting with GoogleMaps API.
+
+    This class provides methods for validating addresses, retrieving elevation,
+    and fetching timezone information using the Google Maps API.
+    """
+
+    def _import_googlemaps_or_raise(self) -> Any:
+        r"""Attempts to import the `googlemaps` library and returns it.
+
+        Returns:
+            module: The `googlemaps` module if successfully imported.
+
+        Raises:
+            ImportError: If the `googlemaps` library is not installed, this
+            error is raised with a message instructing how to install the
+            library using pip.
+        """
+        try:
+            import googlemaps
+
+            return googlemaps
+        except ImportError:
+            raise ImportError(
+                "Please install `googlemaps` first. You can install "
+                "it by running `pip install googlemaps`."
+            )
+
+    def _get_googlemaps_api_key(self) -> str:
+        r"""Retrieve the Google Maps API key from environment variables.
+
+        Returns:
+            str: The Google Maps API key.
+
+        Raises:
+            ValueError: If the API key is not found in the environment
+                variables.
+        """
+        # Get `GOOGLEMAPS_API_KEY` here:
+        # https://console.cloud.google.com/apis/credentials
+        GOOGLEMAPS_API_KEY = os.environ.get('GOOGLEMAPS_API_KEY')
+        if not GOOGLEMAPS_API_KEY:
+            raise ValueError(
+                "`GOOGLEMAPS_API_KEY` not found in environment "
+                "variables. `GOOGLEMAPS_API_KEY` API keys are "
+                "generated in the `Credentials` page of the "
+                "`APIs & Services` tab of "
+                "https://console.cloud.google.com/apis/credentials."
+            )
+        return GOOGLEMAPS_API_KEY
+
+    def get_address_description(
+        self,
+        address: Union[str, List[str]],
+        region_code: Optional[str] = None,
+        locality: Optional[str] = None,
+    ) -> str:
+        r"""Validates an address via Google Maps API, returns a descriptive
+        summary.
+
+        Validates an address using Google Maps API, returning a summary that
+        includes information on address completion, formatted address, location
+        coordinates, and metadata types that are true for the given address.
+
+        Args:
+            address (Union[str, List[str]]): The address or components to
+                validate. Can be a single string or a list representing
+                different parts.
+            region_code (str, optional): Country code for regional restriction,
+                helps narrowing down results. (default: :obj:`None`)
+            locality (str, optional): Restricts validation to a specific
+                locality, e.g., "Mountain View". (default: :obj:`None`)
+
+        Returns:
+            str: Summary of the address validation results, including
+                information on address completion, formatted address,
+                geographical coordinates (latitude and longitude), and metadata
+                types true for the address.
+
+        Raises:
+            ImportError: If the `googlemaps` library is not installed.
+            Exception: For unexpected errors during the address validation.
+        """
+        googlemaps = self._import_googlemaps_or_raise()
+        google_maps_api_key = self._get_googlemaps_api_key()
+        try:
+            gmaps = googlemaps.Client(key=google_maps_api_key)
+        except Exception as e:
+            return f"Error: {e!s}"
+
+        try:
+            addressvalidation_result = gmaps.addressvalidation(
+                [address],
+                regionCode=region_code,
+                locality=locality,
+                enableUspsCass=False,
+            )  # Always False as per requirements
+
+            # Check if the result contains an error
+            if 'error' in addressvalidation_result:
+                error_info = addressvalidation_result['error']
+                error_message = error_info.get(
+                    'message', 'An unknown error occurred'
+                )
+                error_status = error_info.get('status', 'UNKNOWN_STATUS')
+                error_code = error_info.get('code', 'UNKNOWN_CODE')
+                return (
+                    f"Address validation failed with error: {error_message} "
+                    f"Status: {error_status}, Code: {error_code}"
+                )
+
+            # Assuming the successful response structure
+            # includes a 'result' key
+            result = addressvalidation_result['result']
+            verdict = result.get('verdict', {})
+            address_info = result.get('address', {})
+            geocode = result.get('geocode', {})
+            metadata = result.get('metadata', {})
+
+            # Construct the descriptive string
+            address_complete = (
+                "Yes" if verdict.get('addressComplete', False) else "No"
+            )
+            formatted_address = address_info.get(
+                'formattedAddress', 'Not available'
+            )
+            location = geocode.get('location', {})
+            latitude = location.get('latitude', 'Not available')
+            longitude = location.get('longitude', 'Not available')
+            true_metadata_types = [
+                key for key, value in metadata.items() if value
+            ]
+            true_metadata_types_str = (
+                ', '.join(true_metadata_types)
+                if true_metadata_types
+                else 'None'
+            )
+
+            description = (
+                f"Address completion status: {address_complete}. "
+                f"Formatted address: {formatted_address}. "
+                f"Location (latitude, longitude): ({latitude}, {longitude}). "
+                f"Metadata indicating true types: {true_metadata_types_str}."
+            )
+
+            return description
+        except Exception as e:
+            return f"An unexpected error occurred: {e!s}"
+
+    @handle_googlemaps_exceptions
+    def get_elevation(self, lat_lng: Tuple) -> str:
+        r"""Retrieves elevation data for a given latitude and longitude.
+
+        Uses the Google Maps API to fetch elevation data for the specified
+        latitude and longitude. It handles exceptions gracefully and returns a
+        description of the elevation, including its value in meters and the
+        data resolution.
+
+        Args:
+            lat_lng (Tuple[float, float]): The latitude and longitude for
+                which to retrieve elevation data.
+
+        Returns:
+            str: A description of the elevation at the specified location(s),
+                including the elevation in meters and the data resolution. If
+                elevation data is not available, a message indicating this is
+                returned.
+        """
+        googlemaps = self._import_googlemaps_or_raise()
+        google_maps_api_key = self._get_googlemaps_api_key()
+        try:
+            gmaps = googlemaps.Client(key=google_maps_api_key)
+        except Exception as e:
+            return f"Error: {e!s}"
+
+        # Assuming gmaps is a configured Google Maps client instance
+        elevation_result = gmaps.elevation(lat_lng)
+
+        # Extract the elevation data from the first
+        # (and presumably only) result
+        if elevation_result:
+            elevation = elevation_result[0]['elevation']
+            location = elevation_result[0]['location']
+            resolution = elevation_result[0]['resolution']
+
+            # Format the elevation data into a natural language description
+            description = (
+                f"The elevation at latitude {location['lat']}, "
+                f"longitude {location['lng']} "
+                f"is approximately {elevation:.2f} meters above sea level, "
+                f"with a data resolution of {resolution:.2f} meters."
+            )
+        else:
+            description = (
+                "Elevation data is not available for the given location."
+            )
+
+        return description
+
+    def _format_offset_to_natural_language(self, offset: int) -> str:
+        r"""Converts a time offset in seconds to a more natural language
+        description using hours as the unit, with decimal places to represent
+        minutes and seconds.
+
+        Args:
+            offset (int): The time offset in seconds. Can be positive,
+                negative, or zero.
+
+        Returns:
+            str: A string representing the offset in hours, such as
+                "+2.50 hours" or "-3.75 hours".
+        """
+        # Convert the offset to hours as a float
+        hours = offset / 3600.0
+        hours_str = f"{hours:+.2f} hour{'s' if abs(hours) != 1 else ''}"
+        return hours_str
+
+    @handle_googlemaps_exceptions
+    def get_timezone(self, lat_lng: Tuple) -> str:
+        r"""Retrieves timezone information for a given latitude and longitude.
+
+        This function uses the Google Maps Timezone API to fetch timezone
+        data for the specified latitude and longitude. It returns a natural
+        language description of the timezone, including the timezone ID, name,
+        standard time offset, daylight saving time offset, and the total
+        offset from Coordinated Universal Time (UTC).
+
+        Args:
+            lat_lng (Tuple[float, float]): The latitude and longitude for
+                which to retrieve elevation data.
+
+        Returns:
+            str: A descriptive string of the timezone information,
+            including the timezone ID and name, standard time offset,
+            daylight saving time offset, and total offset from UTC.
+        """
+        googlemaps = self._import_googlemaps_or_raise()
+        google_maps_api_key = self._get_googlemaps_api_key()
+        try:
+            gmaps = googlemaps.Client(key=google_maps_api_key)
+        except Exception as e:
+            return f"Error: {e!s}"
+
+        # Get timezone information
+        timezone_dict = gmaps.timezone(lat_lng)
+
+        # Extract necessary information
+        dst_offset = timezone_dict[
+            'dstOffset'
+        ]  # Daylight Saving Time offset in seconds
+        raw_offset = timezone_dict[
+            'rawOffset'
+        ]  # Standard time offset in seconds
+        timezone_id = timezone_dict['timeZoneId']
+        timezone_name = timezone_dict['timeZoneName']
+
+        raw_offset_str = self._format_offset_to_natural_language(raw_offset)
+        dst_offset_str = self._format_offset_to_natural_language(dst_offset)
+        total_offset_seconds = dst_offset + raw_offset
+        total_offset_str = self._format_offset_to_natural_language(
+            total_offset_seconds
+        )
+
+        # Create a natural language description
+        description = (
+            f"Timezone ID is {timezone_id}, named {timezone_name}. "
+            f"The standard time offset is {raw_offset_str}. "
+            f"Daylight Saving Time offset is {dst_offset_str}. "
+            f"The total offset from Coordinated Universal Time (UTC) is "
+            f"{total_offset_str}, including any "
+            "Daylight Saving Time adjustment "
+            f"if applicable. "
+        )
+
+        return description
+
+    def get_tools(self) -> List[OpenAIFunction]:
+        r"""Returns a list of OpenAIFunction objects representing the
+        functions in the toolkit.
+
+        Returns:
+            List[OpenAIFunction]: A list of OpenAIFunction objects
+                representing the functions in the toolkit.
+        """
+        return [
+            OpenAIFunction(self.get_address_description),
+            OpenAIFunction(self.get_elevation),
+            OpenAIFunction(self.get_timezone),
+        ]
+
+
+MAP_FUNCS: List[OpenAIFunction] = GoogleMapsToolkit().get_tools()

camel/toolkits/math_toolkit.py

@@ -0,0 +1,79 @@
+# =========== 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. ===========
+
+from typing import List
+
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.openai_function import OpenAIFunction
+
+
+class MathToolkit(BaseToolkit):
+    r"""A class representing a toolkit for mathematical operations.
+
+    This class provides methods for basic mathematical operations such as
+    addition, subtraction, and multiplication.
+    """
+
+    def add(self, a: int, b: int) -> int:
+        r"""Adds two numbers.
+
+        Args:
+            a (int): The first number to be added.
+            b (int): The second number to be added.
+
+        Returns:
+            integer: The sum of the two numbers.
+        """
+        return a + b
+
+    def sub(self, a: int, b: int) -> int:
+        r"""Do subtraction between two numbers.
+
+        Args:
+            a (int): The minuend in subtraction.
+            b (int): The subtrahend in subtraction.
+
+        Returns:
+            integer: The result of subtracting :obj:`b` from :obj:`a`.
+        """
+        return a - b
+
+    def mul(self, a: int, b: int) -> int:
+        r"""Multiplies two integers.
+
+        Args:
+            a (int): The multiplier in the multiplication.
+            b (int): The multiplicand in the multiplication.
+
+        Returns:
+            integer: The product of the two numbers.
+        """
+        return a * b
+
+    def get_tools(self) -> List[OpenAIFunction]:
+        r"""Returns a list of OpenAIFunction objects representing the
+        functions in the toolkit.
+
+        Returns:
+            List[OpenAIFunction]: A list of OpenAIFunction objects
+                representing the functions in the toolkit.
+        """
+        return [
+            OpenAIFunction(self.add),
+            OpenAIFunction(self.sub),
+            OpenAIFunction(self.mul),
+        ]
+
+
+MATH_FUNCS: List[OpenAIFunction] = MathToolkit().get_tools()