camel-ai 0.2.73a4__py3-none-any.whl → 0.2.80a2__py3-none-any.whl

camel/toolkits/{openai_image_toolkit.py → image_generation_toolkit.py}

@@ -14,9 +14,8 @@
 
 import base64
 import os
-import uuid
 from io import BytesIO
-from typing import List, Literal, Optional
+from typing import ClassVar, List, Literal, Optional, Tuple, Union
 
 from openai import OpenAI
 from PIL import Image
@@ -30,21 +29,32 @@ logger = get_logger(__name__)
 
 
 @MCPServer()
-class OpenAIImageToolkit(BaseToolkit):
-    r"""A class toolkit for image generation using OpenAI's
-    Image Generation API.
-    """
-
-    @api_keys_required(
-        [
-            ("api_key", "OPENAI_API_KEY"),
-        ]
-    )
+class ImageGenToolkit(BaseToolkit):
+    r"""A class toolkit for image generation using Grok and OpenAI models."""
+
+    GROK_MODELS: ClassVar[List[str]] = [
+        "grok-2-image",
+        "grok-2-image-latest",
+        "grok-2-image-1212",
+    ]
+    OPENAI_MODELS: ClassVar[List[str]] = [
+        "gpt-image-1",
+        "dall-e-3",
+        "dall-e-2",
+    ]
+
     def __init__(
         self,
         model: Optional[
-            Literal["gpt-image-1", "dall-e-3", "dall-e-2"]
-        ] = "gpt-image-1",
+            Literal[
+                "gpt-image-1",
+                "dall-e-3",
+                "dall-e-2",
+                "grok-2-image",
+                "grok-2-image-latest",
+                "grok-2-image-1212",
+            ]
+        ] = "dall-e-3",
         timeout: Optional[float] = None,
         api_key: Optional[str] = None,
         url: Optional[str] = None,
@@ -64,19 +74,21 @@ class OpenAIImageToolkit(BaseToolkit):
             Literal["auto", "low", "medium", "high", "standard", "hd"]
         ] = "standard",
         response_format: Optional[Literal["url", "b64_json"]] = "b64_json",
-        n: Optional[int] = 1,
         background: Optional[
             Literal["transparent", "opaque", "auto"]
         ] = "auto",
         style: Optional[Literal["vivid", "natural"]] = None,
         working_directory: Optional[str] = "image_save",
     ):
-        r"""Initializes a new instance of the OpenAIImageToolkit class.
+        # NOTE: Some arguments are set in the constructor to prevent the agent
+        # from making invalid API calls with model-specific parameters. For
+        # example, the 'style' argument is only supported by 'dall-e-3'.
+        r"""Initializes a new instance of the ImageGenToolkit class.
 
         Args:
             api_key (Optional[str]): The API key for authenticating
-                with the OpenAI service. (default: :obj:`None`)
-            url (Optional[str]): The url to the OpenAI service.
+                with the image model service. (default: :obj:`None`)
+            url (Optional[str]): The url to the image model service.
                 (default: :obj:`None`)
             model (Optional[str]): The model to use.
                 (default: :obj:`"dall-e-3"`)
@@ -94,8 +106,6 @@ class OpenAIImageToolkit(BaseToolkit):
                 (default: :obj:`"standard"`)
             response_format (Optional[Literal["url", "b64_json"]]):
                 The format of the response.(default: :obj:`"b64_json"`)
-            n (Optional[int]): The number of images to generate.
-                (default: :obj:`1`)
             background (Optional[Literal["transparent", "opaque", "auto"]]):
                 The background of the image.(default: :obj:`"auto"`)
             style (Optional[Literal["vivid", "natural"]]): The style of the
@@ -104,14 +114,27 @@ class OpenAIImageToolkit(BaseToolkit):
                 image.(default: :obj:`"image_save"`)
         """
         super().__init__(timeout=timeout)
-        api_key = api_key or os.environ.get("OPENAI_API_KEY")
-        url = url or os.environ.get("OPENAI_API_BASE_URL")
-        self.client = OpenAI(api_key=api_key, base_url=url)
+        if model not in self.GROK_MODELS + self.OPENAI_MODELS:
+            available_models = sorted(self.OPENAI_MODELS + self.GROK_MODELS)
+            raise ValueError(
+                f"Unsupported model: {model}. "
+                f"Supported models are: {available_models}"
+            )
+
+        # Set default url for Grok models
+        url = "https://api.x.ai/v1" if model in self.GROK_MODELS else url
+
+        api_key, base_url = (
+            self.get_openai_credentials(url, api_key)
+            if model in self.OPENAI_MODELS
+            else self.get_grok_credentials(url, api_key)
+        )
+
+        self.client = OpenAI(api_key=api_key, base_url=base_url)
         self.model = model
         self.size = size
         self.quality = quality
         self.response_format = response_format
-        self.n = n
         self.background = background
         self.style = style
         self.working_directory: str = working_directory or "image_save"
@@ -140,11 +163,12 @@ class OpenAIImageToolkit(BaseToolkit):
             )
             return None
 
-    def _build_base_params(self, prompt: str) -> dict:
-        r"""Build base parameters dict for OpenAI API calls.
+    def _build_base_params(self, prompt: str, n: Optional[int] = None) -> dict:
+        r"""Build base parameters dict for Image Model API calls.
 
         Args:
             prompt (str): The text prompt for the image operation.
+            n (Optional[int]): The number of images to generate.
 
         Returns:
             dict: Parameters dictionary with non-None values.
@@ -152,8 +176,12 @@ class OpenAIImageToolkit(BaseToolkit):
         params = {"prompt": prompt, "model": self.model}
 
         # basic parameters supported by all models
-        if self.n is not None:
-            params["n"] = self.n  # type: ignore[assignment]
+        if n is not None:
+            params["n"] = n  # type: ignore[assignment]
+
+        if self.model in self.GROK_MODELS:
+            return params
+
         if self.size is not None:
             params["size"] = self.size
 
@@ -180,27 +208,48 @@ class OpenAIImageToolkit(BaseToolkit):
                 params["quality"] = self.quality
             if self.background is not None:
                 params["background"] = self.background
-
         return params
 
     def _handle_api_response(
-        self, response, image_name: str, operation: str
+        self,
+        response,
+        image_name: Union[str, List[str]],
+        operation: str,
     ) -> str:
-        r"""Handle API response from OpenAI image operations.
+        r"""Handle API response from image operations.
 
         Args:
-            response: The response object from OpenAI API.
-            image_name (str): Name for the saved image file.
+            response: The response object from image model API.
+            image_name (Union[str, List[str]]): Name(s) for the saved image
+                file(s). If str, the same name is used for all images (will
+                cause error for multiple images). If list, must have exactly
+                the same length as the number of images generated.
             operation (str): Operation type for success message ("generated").
 
         Returns:
             str: Success message with image path/URL or error message.
         """
+        source = "Grok" if self.model in self.GROK_MODELS else "OpenAI"
         if response.data is None or len(response.data) == 0:
-            error_msg = "No image data returned from OpenAI API."
+            error_msg = f"No image data returned from {source} API."
             logger.error(error_msg)
             return error_msg
 
+        # Validate image_name parameter
+        if isinstance(image_name, list):
+            if len(image_name) != len(response.data):
+                error_msg = (
+                    f"Error: Number of image names"
+                    f" ({len(image_name)}) does not match number of "
+                    f"images generated({len(response.data)})"
+                )
+                logger.error(error_msg)
+                return error_msg
+            image_names = image_name
+        else:
+            # If string, use same name for all images
+            image_names = [image_name] * len(response.data)
+
         results = []
 
         for i, image_data in enumerate(response.data):
@@ -215,18 +264,27 @@ class OpenAIImageToolkit(BaseToolkit):
                 image_bytes = base64.b64decode(image_b64)
                 os.makedirs(self.working_directory, exist_ok=True)
 
-                # Add index to filename when multiple images
-                if len(response.data) > 1:
-                    filename = f"{image_name}_{i+1}_{uuid.uuid4().hex}.png"
-                else:
-                    filename = f"{image_name}_{uuid.uuid4().hex}.png"
+                filename = f"{image_names[i]}"
 
                 image_path = os.path.join(self.working_directory, filename)
 
-                with open(image_path, "wb") as f:
-                    f.write(image_bytes)
-
-                results.append(f"Image saved to {image_path}")
+                # Check if file already exists
+                if os.path.exists(image_path):
+                    error_msg = (
+                        f"Error: File '{image_path}' already exists. "
+                        "Please use a different image_name."
+                    )
+                    logger.error(error_msg)
+                    return error_msg
+
+                try:
+                    with open(image_path, "wb") as f:
+                        f.write(image_bytes)
+                    results.append(f"Image saved to {image_path}")
+                except Exception as e:
+                    error_msg = f"Error saving image to '{image_path}': {e!s}"
+                    logger.error(error_msg)
+                    return error_msg
             else:
                 error_msg = (
                     f"No valid image data (URL or base64) found in image {i+1}"
@@ -254,23 +312,28 @@ class OpenAIImageToolkit(BaseToolkit):
     def generate_image(
         self,
         prompt: str,
-        image_name: str = "image",
+        image_name: Union[str, List[str]] = "image.png",
+        n: int = 1,
     ) -> str:
-        r"""Generate an image using OpenAI's Image Generation models.
+        r"""Generate an image using image models.
         The generated image will be saved locally (for ``b64_json`` response
         formats) or an image URL will be returned (for ``url`` response
         formats).
 
         Args:
             prompt (str): The text prompt to generate the image.
-            image_name (str): The name of the image to save.
-                (default: :obj:`"image"`)
+            image_name (Union[str, List[str]]): The name(s) of the image(s) to
+                save. The image name must end with `.png`. If str: same name
+                used for all images (causes error if n > 1). If list: must
+                match the number of images being generated (n parameter).
+                (default: :obj:`"image.png"`)
+            n (int): The number of images to generate. (default: :obj:`1`)
 
         Returns:
             str: the content of the model response or format of the response.
         """
         try:
-            params = self._build_base_params(prompt)
+            params = self._build_base_params(prompt, n)
             response = self.client.images.generate(**params)
             return self._handle_api_response(response, image_name, "generated")
         except Exception as e:
@@ -278,15 +341,50 @@ class OpenAIImageToolkit(BaseToolkit):
             logger.error(error_msg)
             return error_msg
 
+    @api_keys_required([("api_key", "XAI_API_KEY")])
+    def get_grok_credentials(self, url, api_key) -> Tuple[str, str]:  # type: ignore[return-value]
+        r"""Get API credentials for the specified Grok model.
+
+        Args:
+            url (str): The base URL for the Grok API.
+            api_key (str): The API key for the Grok API.
+
+        Returns:
+            tuple: (api_key, base_url)
+        """
+
+        # Get credentials based on model type
+        api_key = api_key or os.getenv("XAI_API_KEY")
+        return api_key, url
+
+    @api_keys_required([("api_key", "OPENAI_API_KEY")])
+    def get_openai_credentials(self, url, api_key) -> Tuple[str, str | None]:  # type: ignore[return-value]
+        r"""Get API credentials for the specified OpenAI model.
+
+        Args:
+            url (str): The base URL for the OpenAI API.
+            api_key (str): The API key for the OpenAI API.
+
+        Returns:
+            Tuple[str, str | None]: (api_key, base_url)
+        """
+
+        api_key = api_key or os.getenv("OPENAI_API_KEY")
+        base_url = url or os.getenv("OPENAI_API_BASE_URL")
+        return api_key, base_url
+
     def get_tools(self) -> List[FunctionTool]:
-        r"""Returns a list of FunctionTool objects representing the
-        functions in the toolkit.
+        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.
+            List[FunctionTool]: A list of FunctionTool objects representing the
+                functions in the toolkit.
         """
         return [
             FunctionTool(self.generate_image),
-            # could add edit_image function later
         ]
+
+
+# Backward compatibility alias
+OpenAIImageToolkit = ImageGenToolkit

camel/toolkits/klavis_toolkit.py

@@ -21,7 +21,11 @@ import requests
 from camel.logger import get_logger
 from camel.toolkits.base import BaseToolkit
 from camel.toolkits.function_tool import FunctionTool
-from camel.utils import MCPServer, api_keys_required, dependencies_required
+from camel.utils import (
+    MCPServer,
+    api_keys_required,
+    dependencies_required,
+)
 
 logger = get_logger(__name__)
 

camel/toolkits/markitdown_toolkit.py

@@ -25,12 +25,38 @@ logger = get_logger(__name__)
 
 @MCPServer()
 class MarkItDownToolkit(BaseToolkit):
-    r"""A class representing a toolkit for MarkItDown."""
+    r"""A class representing a toolkit for MarkItDown.
+
+    .. deprecated::
+        MarkItDownToolkit is deprecated. Use FileToolkit instead, which now
+        includes the same functionality through its read_file method that
+        supports both single files and multiple files.
+
+        Example migration:
+            # Old way
+            from camel.toolkits import MarkItDownToolkit
+            toolkit = MarkItDownToolkit()
+            content = toolkit.read_files(['file1.pdf', 'file2.docx'])
+
+            # New way
+            from camel.toolkits import FileToolkit
+            toolkit = FileToolkit()
+            content = toolkit.read_file(['file1.pdf', 'file2.docx'])
+    """
 
     def __init__(
         self,
         timeout: Optional[float] = None,
     ):
+        import warnings
+
+        warnings.warn(
+            "MarkItDownToolkit is deprecated and will be removed in a future "
+            "version. Please use FileToolkit instead, which now includes "
+            "read_file method that supports both single and multiple files.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         super().__init__(timeout=timeout)
 
     def read_files(self, file_paths: List[str]) -> Dict[str, str]:

camel/toolkits/math_toolkit.py

@@ -12,6 +12,7 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 
+import warnings
 from typing import List
 
 from camel.toolkits.base import BaseToolkit
@@ -27,7 +28,7 @@ class MathToolkit(BaseToolkit):
     addition, subtraction, multiplication, division, and rounding.
     """
 
-    def add(self, a: float, b: float) -> float:
+    def math_add(self, a: float, b: float) -> float:
         r"""Adds two numbers.
 
         Args:
@@ -39,7 +40,7 @@ class MathToolkit(BaseToolkit):
         """
         return a + b
 
-    def sub(self, a: float, b: float) -> float:
+    def math_subtract(self, a: float, b: float) -> float:
         r"""Do subtraction between two numbers.
 
         Args:
@@ -51,7 +52,9 @@ class MathToolkit(BaseToolkit):
         """
         return a - b
 
-    def multiply(self, a: float, b: float, decimal_places: int = 2) -> float:
+    def math_multiply(
+        self, a: float, b: float, decimal_places: int = 2
+    ) -> float:
         r"""Multiplies two numbers.
 
         Args:
@@ -65,7 +68,9 @@ class MathToolkit(BaseToolkit):
         """
         return round(a * b, decimal_places)
 
-    def divide(self, a: float, b: float, decimal_places: int = 2) -> float:
+    def math_divide(
+        self, a: float, b: float, decimal_places: int = 2
+    ) -> float:
         r"""Divides two numbers.
 
         Args:
@@ -79,7 +84,7 @@ class MathToolkit(BaseToolkit):
         """
         return round(a / b, decimal_places)
 
-    def round(self, a: float, decimal_places: int = 0) -> float:
+    def math_round(self, a: float, decimal_places: int = 0) -> float:
         r"""Rounds a number to a specified number of decimal places.
 
         Args:
@@ -101,9 +106,58 @@ class MathToolkit(BaseToolkit):
                 representing the functions in the toolkit.
         """
         return [
-            FunctionTool(self.add),
-            FunctionTool(self.sub),
-            FunctionTool(self.multiply),
-            FunctionTool(self.divide),
-            FunctionTool(self.round),
+            FunctionTool(self.math_add),
+            FunctionTool(self.math_subtract),
+            FunctionTool(self.math_multiply),
+            FunctionTool(self.math_divide),
+            FunctionTool(self.math_round),
         ]
+
+    # Deprecated method aliases for backward compatibility
+    def add(self, *args, **kwargs):
+        r"""Deprecated: Use math_add instead."""
+        warnings.warn(
+            "add is deprecated. Use math_add instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.math_add(*args, **kwargs)
+
+    def sub(self, *args, **kwargs):
+        r"""Deprecated: Use math_subtract instead."""
+        warnings.warn(
+            "sub is deprecated. Use math_subtract instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.math_subtract(*args, **kwargs)
+
+    def multiply(self, *args, **kwargs):
+        r"""Deprecated: Use math_multiply instead."""
+        warnings.warn(
+            "multiply is deprecated. Use math_multiply instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.math_multiply(*args, **kwargs)
+
+    def divide(self, *args, **kwargs):
+        r"""Deprecated: Use math_divide instead."""
+        warnings.warn(
+            "divide is deprecated. Use math_divide instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.math_divide(*args, **kwargs)
+
+    def round(self, *args, **kwargs):
+        r"""Deprecated: Use math_round instead. Note: This was shadowing
+        Python's built-in round().
+        """
+        warnings.warn(
+            "round is deprecated. Use math_round instead. This was "
+            "shadowing Python's built-in round().",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.math_round(*args, **kwargs)