camel-ai 0.2.74a5__py3-none-any.whl → 0.2.75__py3-none-any.whl

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/openai_image_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 List, Literal, Optional, Union
 
 from openai import OpenAI
 from PIL import Image
@@ -64,13 +63,15 @@ 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",
     ):
+        # 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.
 
         Args:
@@ -94,8 +95,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
@@ -111,7 +110,6 @@ class OpenAIImageToolkit(BaseToolkit):
         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 +138,12 @@ class OpenAIImageToolkit(BaseToolkit):
             )
             return None
 
-    def _build_base_params(self, prompt: str) -> dict:
+    def _build_base_params(self, prompt: str, n: Optional[int] = None) -> dict:
         r"""Build base parameters dict for OpenAI 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 +151,8 @@ 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.size is not None:
             params["size"] = self.size
 
@@ -184,13 +183,16 @@ class OpenAIImageToolkit(BaseToolkit):
         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.
 
         Args:
             response: The response object from OpenAI API.
-            image_name (str): Name for the saved image file.
+            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:
@@ -201,6 +203,21 @@ class OpenAIImageToolkit(BaseToolkit):
             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 +232,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,7 +280,8 @@ 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.
         The generated image will be saved locally (for ``b64_json`` response
@@ -263,14 +290,18 @@ class OpenAIImageToolkit(BaseToolkit):
 
         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:

camel/toolkits/search_toolkit.py

@@ -12,6 +12,7 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 import os
+import warnings
 from typing import Any, Dict, List, Literal, Optional, TypeAlias, Union, cast
 
 import requests
@@ -458,17 +459,21 @@ class SearchToolkit(BaseToolkit):
 
         Args:
             query (str): The query to be searched.
-            search_type (str): The type of search to perform. Either "web" for
-                web pages or "image" for image search. (default: "web")
+            search_type (str): The type of search to perform. Must be either
+                "web" for web pages or "image" for image search. Any other
+                value will raise a ValueError. (default: "web")
             number_of_result_pages (int): The number of result pages to
-                retrieve. Adjust this based on your task - use fewer results
-                for focused searches and more for comprehensive searches.
-                (default: :obj:`10`)
-            start_page (int): The result page to start from. Use this for
-                pagination - e.g., start_page=1 for results 1-10,
-                start_page=11 for results 11-20, etc. This allows agents to
-                check initial results and continue searching if needed.
-                (default: :obj:`1`)
+                retrieve. Must be a positive integer between 1 and 10.
+                Google Custom Search API limits results to 10 per request.
+                If a value greater than 10 is provided, it will be capped
+                at 10 with a warning. Adjust this based on your task - use
+                fewer results for focused searches and more for comprehensive
+                searches. (default: :obj:`10`)
+            start_page (int): The result page to start from. Must be a
+                positive integer (>= 1). Use this for pagination - e.g.,
+                start_page=1 for results 1-10, start_page=11 for results
+                11-20, etc. This allows agents to check initial results
+                and continue searching if needed. (default: :obj:`1`)
 
         Returns:
             List[Dict[str, Any]]: A list of dictionaries where each dictionary
@@ -514,8 +519,33 @@ class SearchToolkit(BaseToolkit):
                     'height': 600
                 }
         """
+        from urllib.parse import quote
+
         import requests
 
+        # Validate input parameters
+        if not isinstance(start_page, int) or start_page < 1:
+            raise ValueError("start_page must be a positive integer")
+
+        if (
+            not isinstance(number_of_result_pages, int)
+            or number_of_result_pages < 1
+        ):
+            raise ValueError(
+                "number_of_result_pages must be a positive integer"
+            )
+
+        # Google Custom Search API has a limit of 10 results per request
+        if number_of_result_pages > 10:
+            logger.warning(
+                f"Google API limits results to 10 per request. "
+                f"Requested {number_of_result_pages}, using 10 instead."
+            )
+            number_of_result_pages = 10
+
+        if search_type not in ["web", "image"]:
+            raise ValueError("search_type must be either 'web' or 'image'")
+
         # https://developers.google.com/custom-search/v1/overview
         GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY")
         # https://cse.google.com/cse/all
@@ -535,11 +565,13 @@ class SearchToolkit(BaseToolkit):
             modified_query = f"{query} {exclusion_terms}"
             logger.debug(f"Excluded domains, modified query: {modified_query}")
 
+        encoded_query = quote(modified_query)
+
         # Constructing the URL
         # Doc: https://developers.google.com/custom-search/v1/using_rest
         base_url = (
             f"https://www.googleapis.com/customsearch/v1?"
-            f"key={GOOGLE_API_KEY}&cx={SEARCH_ENGINE_ID}&q={modified_query}&start="
+            f"key={GOOGLE_API_KEY}&cx={SEARCH_ENGINE_ID}&q={encoded_query}&start="
             f"{start_page_idx}&lr={search_language}&num={number_of_result_pages}"
         )
 
@@ -584,7 +616,6 @@ class SearchToolkit(BaseToolkit):
                             "context_url": context_url,
                         }
 
-                        # Add dimensions if available
                         if width:
                             response["width"] = int(width)
                         if height:
@@ -592,8 +623,6 @@ class SearchToolkit(BaseToolkit):
 
                         responses.append(response)
                     else:
-                        # Process web search results (existing logic)
-                        # Check metatags are present
                         if "pagemap" not in search_item:
                             continue
                         if "metatags" not in search_item["pagemap"]:
@@ -607,12 +636,9 @@ class SearchToolkit(BaseToolkit):
                             ][0]["og:description"]
                         else:
                             long_description = "N/A"
-                        # Get the page title
                         title = search_item.get("title")
-                        # Page snippet
                         snippet = search_item.get("snippet")
 
-                        # Extract the page url
                         link = search_item.get("link")
                         response = {
                             "result_id": i,
@@ -623,22 +649,42 @@ class SearchToolkit(BaseToolkit):
                         }
                         responses.append(response)
             else:
-                error_info = data.get("error", {})
-                logger.error(
-                    f"Google search failed - API response: {error_info}"
-                )
-                responses.append(
-                    {
-                        "error": f"Google search failed - "
-                        f"API response: {error_info}"
-                    }
-                )
+                if "error" in data:
+                    error_info = data.get("error", {})
+                    logger.error(
+                        f"Google search failed - API response: {error_info}"
+                    )
+                    responses.append(
+                        {
+                            "error": f"Google search failed - "
+                            f"API response: {error_info}"
+                        }
+                    )
+                elif "searchInformation" in data:
+                    search_info = data.get("searchInformation", {})
+                    total_results = search_info.get("totalResults", "0")
+                    if total_results == "0":
+                        logger.info(f"No results found for query: {query}")
+                        # Return empty list to indicate no results (not an error)
+                        responses = []
+                    else:
+                        logger.warning(
+                            f"Google search returned no items but claims {total_results} results"
+                        )
+                        responses = []
+                else:
+                    logger.error(
+                        f"Unexpected Google API response format: {data}"
+                    )
+                    responses.append(
+                        {"error": "Unexpected response format from Google API"}
+                    )
 
         except Exception as e:
             responses.append({"error": f"google search failed: {e!s}"})
         return responses
 
-    def tavily_search(
+    def search_tavily(
         self, query: str, number_of_result_pages: int = 10, **kwargs
     ) -> List[Dict[str, Any]]:
         r"""Use Tavily Search API to search information for the given query.
@@ -1233,6 +1279,73 @@ class SearchToolkit(BaseToolkit):
                 f"search: {e!s}"
             }
 
+    @api_keys_required([(None, 'METASO_API_KEY')])
+    def search_metaso(
+        self,
+        query: str,
+        page: int = 1,
+        include_summary: bool = False,
+        include_raw_content: bool = False,
+        concise_snippet: bool = False,
+        scope: Literal[
+            "webpage", "document", "scholar", "image", "video", "podcast"
+        ] = "webpage",
+    ) -> Dict[str, Any]:
+        r"""Perform a web search using the metaso.cn API.
+
+        Args:
+            query (str): The search query string.
+            page (int): Page number. (default: :obj:`1`)
+            include_summary (bool): Whether to include summary in the result.
+                (default: :obj:`False`)
+            include_raw_content (bool): Whether to include raw content in the
+                result. (default: :obj:`False`)
+            concise_snippet (bool): Whether to return concise snippet.
+                (default: :obj:`False`)
+            scope (Literal["webpage", "document", "scholar", "image", "video",
+                "podcast"]): Search scope. (default: :obj:`"webpage"`)
+
+        Returns:
+            Dict[str, Any]: Search results or error information.
+        """
+        import http.client
+        import json
+
+        # It is recommended to put the token in environment variable for
+        # security
+
+        METASO_API_KEY = os.getenv("METASO_API_KEY")
+
+        conn = http.client.HTTPSConnection("metaso.cn")
+        payload = json.dumps(
+            {
+                "q": query,
+                "scope": scope,
+                "includeSummary": include_summary,
+                "page": str(page),
+                "includeRawContent": include_raw_content,
+                "conciseSnippet": concise_snippet,
+            }
+        )
+        headers = {
+            'Authorization': f'Bearer {METASO_API_KEY}',
+            'Accept': 'application/json',
+            'Content-Type': 'application/json',
+        }
+        try:
+            conn.request("POST", "/api/v1/search", payload, headers)
+            res = conn.getresponse()
+            data = res.read()
+            result = data.decode("utf-8")
+            try:
+                return json.loads(result)
+            except Exception:
+                return {
+                    "error": f"Metaso returned content could not be parsed: {result}"
+                }
+        except Exception as e:
+            return {"error": f"Metaso search failed: {e}"}
+
     def get_tools(self) -> List[FunctionTool]:
         r"""Returns a list of FunctionTool objects representing the
         functions in the toolkit.
@@ -1246,11 +1359,22 @@ class SearchToolkit(BaseToolkit):
             FunctionTool(self.search_linkup),
             FunctionTool(self.search_google),
             FunctionTool(self.search_duckduckgo),
-            FunctionTool(self.tavily_search),
+            FunctionTool(self.search_tavily),
             FunctionTool(self.search_brave),
             FunctionTool(self.search_bocha),
             FunctionTool(self.search_baidu),
             FunctionTool(self.search_bing),
             FunctionTool(self.search_exa),
             FunctionTool(self.search_alibaba_tongxiao),
+            FunctionTool(self.search_metaso),
         ]
+
+    # Deprecated method alias for backward compatibility
+    def tavily_search(self, *args, **kwargs):
+        r"""Deprecated: Use search_tavily instead for consistency with other search methods."""
+        warnings.warn(
+            "tavily_search is deprecated. Use search_tavily instead for consistency.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.search_tavily(*args, **kwargs)

camel/types/__init__.py

@@ -41,8 +41,8 @@ from .openai_types import (
     ChatCompletionAssistantMessageParam,
     ChatCompletionChunk,
     ChatCompletionMessage,
+    ChatCompletionMessageFunctionToolCall,
     ChatCompletionMessageParam,
-    ChatCompletionMessageToolCall,
     ChatCompletionSystemMessageParam,
     ChatCompletionToolMessageParam,
     ChatCompletionUserMessageParam,
@@ -71,7 +71,7 @@ __all__ = [
     'ChatCompletionUserMessageParam',
     'ChatCompletionAssistantMessageParam',
     'ChatCompletionToolMessageParam',
-    'ChatCompletionMessageToolCall',
+    'ChatCompletionMessageFunctionToolCall',
     'CompletionUsage',
     'OpenAIImageType',
     'OpenAIVisionDetailType',