camel-ai 0.2.75a6__py3-none-any.whl → 0.2.76a1__py3-none-any.whl

camel/toolkits/hybrid_browser_toolkit_py/hybrid_browser_toolkit.py

@@ -92,11 +92,12 @@ class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
         user_data_dir: Optional[str] = None,
         stealth: bool = False,
         web_agent_model: Optional[BaseModelBackend] = None,
-        cache_dir: str = "tmp/",
+        cache_dir: Optional[str] = None,
         enabled_tools: Optional[List[str]] = None,
         browser_log_to_file: bool = False,
+        log_dir: Optional[str] = None,
         session_id: Optional[str] = None,
-        default_start_url: str = "https://google.com/",
+        default_start_url: Optional[str] = None,
         default_timeout: Optional[int] = None,
         short_timeout: Optional[int] = None,
         navigation_timeout: Optional[int] = None,
@@ -144,6 +145,8 @@ class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
                 and page loading times.
                 Logs are saved to an auto-generated timestamped file.
                 Defaults to `False`.
+            log_dir (Optional[str]): Custom directory path for log files.
+                If None, defaults to "browser_log". Defaults to `None`.
             session_id (Optional[str]): A unique identifier for this browser
                 session. When multiple HybridBrowserToolkit instances are
                 used
@@ -199,9 +202,10 @@ class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
         self._user_data_dir = user_data_dir
         self._stealth = stealth
         self._web_agent_model = web_agent_model
-        self._cache_dir = cache_dir
+        self._cache_dir = cache_dir or "tmp/"
         self._browser_log_to_file = browser_log_to_file
-        self._default_start_url = default_start_url
+        self._log_dir = log_dir
+        self._default_start_url = default_start_url or "https://google.com/"
         self._session_id = session_id or "default"
         self._viewport_limit = viewport_limit
 
@@ -237,7 +241,7 @@ class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
         # Set up log file if needed
         if self.log_to_file:
             # Create log directory if it doesn't exist
-            log_dir = "browser_log"
+            log_dir = self._log_dir if self._log_dir else "browser_log"
             os.makedirs(log_dir, exist_ok=True)
 
             timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")

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

@@ -15,7 +15,7 @@
 import base64
 import os
 from io import BytesIO
-from typing import List, Literal, Optional, Union
+from typing import ClassVar, List, Literal, Optional, Tuple, Union
 
 from openai import OpenAI
 from PIL import Image
@@ -29,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,
@@ -72,12 +83,12 @@ class OpenAIImageToolkit(BaseToolkit):
         # 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 OpenAIImageToolkit class.
+        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"`)
@@ -103,9 +114,23 @@ 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
@@ -139,7 +164,7 @@ class OpenAIImageToolkit(BaseToolkit):
             return None
 
     def _build_base_params(self, prompt: str, n: Optional[int] = None) -> dict:
-        r"""Build base parameters dict for OpenAI API calls.
+        r"""Build base parameters dict for Image Model API calls.
 
         Args:
             prompt (str): The text prompt for the image operation.
@@ -153,6 +178,10 @@ class OpenAIImageToolkit(BaseToolkit):
         # basic parameters supported by all models
         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
 
@@ -179,16 +208,18 @@ 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: Union[str, List[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.
+            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
@@ -198,8 +229,9 @@ class OpenAIImageToolkit(BaseToolkit):
         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
 
@@ -283,7 +315,7 @@ class OpenAIImageToolkit(BaseToolkit):
         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).
@@ -309,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/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/mcp_toolkit.py

@@ -220,26 +220,34 @@ class MCPToolkit(BaseToolkit):
         self._exit_stack = AsyncExitStack()
 
         try:
-            # Connect to all clients using AsyncExitStack
-            for i, client in enumerate(self.clients):
-                try:
-                    # Use MCPClient directly as async context manager
-                    await self._exit_stack.enter_async_context(client)
-                    msg = f"Connected to client {i+1}/{len(self.clients)}"
-                    logger.debug(msg)
-                except Exception as e:
-                    logger.error(f"Failed to connect to client {i+1}: {e}")
-                    # AsyncExitStack will handle cleanup of already connected
-                    await self._exit_stack.aclose()
-                    self._exit_stack = None
-                    error_msg = f"Failed to connect to client {i+1}: {e}"
-                    raise MCPConnectionError(error_msg) from e
+            # Apply timeout to the entire connection process
+            import asyncio
+
+            timeout_seconds = self.timeout or 30.0
+            await asyncio.wait_for(
+                self._connect_all_clients(), timeout=timeout_seconds
+            )
 
             self._is_connected = True
             msg = f"Successfully connected to {len(self.clients)} MCP servers"
             logger.info(msg)
             return self
 
+        except (asyncio.TimeoutError, asyncio.CancelledError):
+            self._is_connected = False
+            if self._exit_stack:
+                await self._exit_stack.aclose()
+                self._exit_stack = None
+
+            timeout_seconds = self.timeout or 30.0
+            error_msg = (
+                f"Connection timeout after {timeout_seconds}s. "
+                f"One or more MCP servers are not responding. "
+                f"Please check if the servers are running and accessible."
+            )
+            logger.error(error_msg)
+            raise MCPConnectionError(error_msg)
+
         except Exception:
             self._is_connected = False
             if self._exit_stack:
@@ -247,6 +255,23 @@ class MCPToolkit(BaseToolkit):
                 self._exit_stack = None
             raise
 
+    async def _connect_all_clients(self):
+        r"""Connect to all clients sequentially."""
+        # Connect to all clients using AsyncExitStack
+        for i, client in enumerate(self.clients):
+            try:
+                # Use MCPClient directly as async context manager
+                await self._exit_stack.enter_async_context(client)
+                msg = f"Connected to client {i+1}/{len(self.clients)}"
+                logger.debug(msg)
+            except Exception as e:
+                logger.error(f"Failed to connect to client {i+1}: {e}")
+                # AsyncExitStack will cleanup already connected clients
+                await self._exit_stack.aclose()
+                self._exit_stack = None
+                error_msg = f"Failed to connect to client {i+1}: {e}"
+                raise MCPConnectionError(error_msg) from e
+
     async def disconnect(self):
         r"""Disconnect from all MCP servers."""
         if not self._is_connected:

camel/toolkits/minimax_mcp_toolkit.py

@@ -0,0 +1,195 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import os
+from typing import Any, Dict, List, Optional
+
+from camel.toolkits import BaseToolkit, FunctionTool
+
+from .mcp_toolkit import MCPToolkit
+
+
+class MinimaxMCPToolkit(BaseToolkit):
+    r"""MinimaxMCPToolkit provides an interface for interacting with
+    MiniMax AI services using the MiniMax MCP server.
+
+    This toolkit enables access to MiniMax's multimedia generation
+    capabilities including text-to-audio, voice cloning, video generation,
+    image generation, music generation, and voice design.
+
+    This toolkit can be used as an async context manager for automatic
+    connection management:
+
+        # Using explicit API key
+        async with MinimaxMCPToolkit(api_key="your-key") as toolkit:
+            tools = toolkit.get_tools()
+            # Toolkit is automatically disconnected when exiting
+
+        # Using environment variables (recommended for security)
+        # Set MINIMAX_API_KEY=your-key in environment
+        async with MinimaxMCPToolkit() as toolkit:
+            tools = toolkit.get_tools()
+
+    Environment Variables:
+        MINIMAX_API_KEY: MiniMax API key for authentication
+        MINIMAX_API_HOST: API host URL (default: https://api.minimax.io)
+        MINIMAX_MCP_BASE_PATH: Base path for output files
+
+    Attributes:
+        timeout (Optional[float]): Connection timeout in seconds.
+            (default: :obj:`None`)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_host: str = "https://api.minimax.io",
+        base_path: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        r"""Initializes the MinimaxMCPToolkit.
+
+        Args:
+            api_key (Optional[str]): MiniMax API key for authentication.
+                If None, will attempt to read from MINIMAX_API_KEY
+                environment variable. (default: :obj:`None`)
+            api_host (str): MiniMax API host URL. Can be either
+                "https://api.minimax.io" (global) or
+                "https://api.minimaxi.com" (mainland China).
+                Can also be read from MINIMAX_API_HOST environment variable.
+                (default: :obj:`"https://api.minimax.io"`)
+            base_path (Optional[str]): Base path for output files.
+                If None, uses current working directory. Can also be read
+                from MINIMAX_MCP_BASE_PATH environment variable.
+                (default: :obj:`None`)
+            timeout (Optional[float]): Connection timeout in seconds.
+                (default: :obj:`None`)
+        """
+        super().__init__(timeout=timeout)
+
+        # Read API key from parameter or environment variable
+        if api_key is None:
+            api_key = os.getenv("MINIMAX_API_KEY")
+
+        if not api_key:
+            raise ValueError(
+                "api_key must be provided either as a parameter or through "
+                "the MINIMAX_API_KEY environment variable"
+            )
+
+        # Read API host from environment variable if not overridden
+        env_api_host = os.getenv("MINIMAX_API_HOST")
+        if env_api_host:
+            api_host = env_api_host
+
+        # Read base path from environment variable if not provided
+        if base_path is None:
+            base_path = os.getenv("MINIMAX_MCP_BASE_PATH")
+
+        # Set up environment variables for the MCP server
+        env = {
+            "MINIMAX_API_KEY": api_key,
+            "MINIMAX_API_HOST": api_host,
+        }
+
+        if base_path:
+            env["MINIMAX_MCP_BASE_PATH"] = base_path
+
+        self._mcp_toolkit = MCPToolkit(
+            config_dict={
+                "mcpServers": {
+                    "minimax": {
+                        "command": "uvx",
+                        "args": ["minimax-mcp", "-y"],
+                        "env": env,
+                    }
+                }
+            },
+            timeout=timeout,
+        )
+
+    async def connect(self):
+        r"""Explicitly connect to the MiniMax MCP server."""
+        await self._mcp_toolkit.connect()
+
+    async def disconnect(self):
+        r"""Explicitly disconnect from the MiniMax MCP server."""
+        await self._mcp_toolkit.disconnect()
+
+    @property
+    def is_connected(self) -> bool:
+        r"""Check if the toolkit is connected to the MCP server.
+
+        Returns:
+            bool: True if connected, False otherwise.
+        """
+        return self._mcp_toolkit.is_connected
+
+    async def __aenter__(self) -> "MinimaxMCPToolkit":
+        r"""Async context manager entry point.
+
+        Returns:
+            MinimaxMCPToolkit: The connected toolkit instance.
+
+        Example:
+            async with MinimaxMCPToolkit(api_key="your-key") as toolkit:
+                tools = toolkit.get_tools()
+        """
+        await self.connect()
+        return self
+
+    async def __aexit__(self, _exc_type, _exc_val, _exc_tb) -> None:
+        r"""Async context manager exit point.
+
+        Automatically disconnects from the MiniMax MCP server.
+        """
+        await self.disconnect()
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Returns a list of tools provided by the MiniMax MCP server.
+
+        This includes tools for:
+        - Text-to-audio conversion
+        - Voice cloning
+        - Video generation
+        - Image generation
+        - Music generation
+        - Voice design
+
+        Returns:
+            List[FunctionTool]: List of available MiniMax AI tools.
+        """
+        return self._mcp_toolkit.get_tools()
+
+    def get_text_tools(self) -> str:
+        r"""Returns a string containing the descriptions of the tools.
+
+        Returns:
+            str: A string containing the descriptions of all MiniMax tools.
+        """
+        return self._mcp_toolkit.get_text_tools()
+
+    async def call_tool(
+        self, tool_name: str, tool_args: Dict[str, Any]
+    ) -> Any:
+        r"""Call a MiniMax tool by name.
+
+        Args:
+            tool_name (str): Name of the tool to call.
+            tool_args (Dict[str, Any]): Arguments to pass to the tool.
+
+        Returns:
+            Any: The result of the tool call.
+        """
+        return await self._mcp_toolkit.call_tool(tool_name, tool_args)

camel/toolkits/note_taking_toolkit.py

@@ -138,33 +138,43 @@ class NoteTakingToolkit(BaseToolkit):
             self.registry.append(note_name)
             self._save_registry()
 
-    def create_note(self, note_name: str, content: str) -> str:
+    def create_note(
+        self, note_name: str, content: str, overwrite: bool = False
+    ) -> str:
         r"""Creates a new note with a unique name.
 
         This function will create a new file for your note.
-        You must provide a `note_name` that does not already exist. If you want
-        to add content to an existing note, use the `append_note` function
-        instead.
+        By default, you must provide a `note_name` that does not already exist.
+        If you want to add content to an existing note, use the `append_note`
+        function instead. If you want to overwrite an existing note, set
+        `overwrite=True`.
 
         Args:
             note_name (str): The name for your new note (without the .md
-                extension). This name must be unique.
+                extension). This name must be unique unless overwrite is True.
             content (str): The initial content to write in the note.
+            overwrite (bool): Whether to overwrite an existing note.
+                Defaults to False.
 
         Returns:
             str: A message confirming the creation of the note or an error if
-                the note name is not valid or already exists.
+                the note name is not valid or already exists
+                (when overwrite=False).
         """
         try:
             note_path = self.working_directory / f"{note_name}.md"
+            existed_before = note_path.exists()
 
-            if note_path.exists():
+            if existed_before and not overwrite:
                 return f"Error: Note '{note_name}.md' already exists."
 
             note_path.write_text(content, encoding="utf-8")
             self._register_note(note_name)
 
-            return f"Note '{note_name}.md' successfully created."
+            if existed_before and overwrite:
+                return f"Note '{note_name}.md' successfully overwritten."
+            else:
+                return f"Note '{note_name}.md' successfully created."
         except Exception as e:
             return f"Error creating note: {e}"
 

camel/toolkits/terminal_toolkit.py

@@ -66,6 +66,9 @@ class TerminalToolkit(BaseToolkit):
             connecting them to the terminal's standard input. This is useful
             for commands that require user input, like `ssh`. Interactive mode
             is only supported on macOS and Linux. (default: :obj:`False`)
+        log_dir (Optional[str]): Custom directory path for log files.
+            If None, logs are saved to the current working directory.
+            (default: :obj:`None`)
 
     Note:
         Most functions are compatible with Unix-based systems (macOS, Linux).
@@ -83,6 +86,7 @@ class TerminalToolkit(BaseToolkit):
         clone_current_env: bool = False,
         safe_mode: bool = True,
         interactive: bool = False,
+        log_dir: Optional[str] = None,
     ):
         # Store timeout before calling super().__init__
         self._timeout = timeout
@@ -99,6 +103,7 @@ class TerminalToolkit(BaseToolkit):
         self.use_shell_mode = use_shell_mode
         self._human_takeover_active = False
         self.interactive = interactive
+        self.log_dir = log_dir
 
         self.python_executable = sys.executable
         self.is_macos = platform.system() == 'Darwin'
@@ -153,8 +158,13 @@ class TerminalToolkit(BaseToolkit):
         r"""Set up file output to replace GUI, using a fixed file to simulate
         terminal.
         """
-
-        self.log_file = os.path.join(os.getcwd(), "camel_terminal.txt")
+        # Use custom log directory if provided, otherwise use current directory
+        if self.log_dir:
+            # Create the log directory if it doesn't exist
+            os.makedirs(self.log_dir, exist_ok=True)
+            self.log_file = os.path.join(self.log_dir, "camel_terminal.txt")
+        else:
+            self.log_file = os.path.join(os.getcwd(), "camel_terminal.txt")
 
         # Inform the user
         logger.info(f"Terminal output will be redirected to: {self.log_file}")