camel-ai 0.2.57__py3-none-any.whl → 0.2.59__py3-none-any.whl

camel/toolkits/base.py

@@ -12,7 +12,7 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 
-from typing import List, Optional
+from typing import List, Literal, Optional
 
 from camel.toolkits import FunctionTool
 from camel.utils import AgentOpsMeta, with_timeout
@@ -52,3 +52,14 @@ class BaseToolkit(metaclass=AgentOpsMeta):
                 representing the functions in the toolkit.
         """
         raise NotImplementedError("Subclasses must implement this method.")
+
+    def run_mcp_server(
+        self, mode: Literal["stdio", "sse", "streamable-http"]
+    ) -> None:
+        r"""Run the MCP server in the specified mode.
+
+        Args:
+            mode (Literal["stdio", "sse", "streamable-http"]): The mode to run
+                the MCP server in.
+        """
+        self.mcp.run(mode)

camel/toolkits/browser_toolkit.py

@@ -57,6 +57,7 @@ logger = get_logger(__name__)
 
 TOP_NO_LABEL_ZONE = 20
 
+
 AVAILABLE_ACTIONS_PROMPT = """
 1. `fill_input_id(identifier: Union[str, int], text: str)`: Fill an input
 field (e.g. search box) with the given text and press Enter.
@@ -523,6 +524,7 @@ class BaseBrowser:
         self.page.mouse.click(0, 0)
         self._wait_for_load()
 
+    @retry_on_error()
     def visit_page(self, url: str) -> None:
         r"""Visit a page with the given URL."""
 
@@ -540,10 +542,24 @@ class BaseBrowser:
         Returns:
             str: The answer to the question.
         """
-        video_analyzer = VideoAnalysisToolkit()
-        result = video_analyzer.ask_question_about_video(
-            self.page_url, question
+        current_url = self.get_url()
+
+        # Confirm with user before proceeding due to potential slow processing time
+        confirmation_message = (
+            f"Do you want to analyze the video on the current "
+            f"page({current_url})? This operation may take a long time.(y/n): "
         )
+        user_confirmation = input(confirmation_message)
+
+        if user_confirmation.lower() not in ['y', 'yes']:
+            return "User cancelled the video analysis."
+
+        model = None
+        if hasattr(self, 'web_agent_model'):
+            model = self.web_agent_model
+
+        video_analyzer = VideoAnalysisToolkit(model=model)
+        result = video_analyzer.ask_question_about_video(current_url, question)
         return result
 
     @retry_on_error()

camel/toolkits/excel_toolkit.py

@@ -29,8 +29,9 @@ class ExcelToolkit(BaseToolkit):
     r"""A class representing a toolkit for extract detailed cell information
     from an Excel file.
 
-    This class provides method for processing docx, pdf, pptx, etc. It cannot
-    process excel files.
+    This class provides methods extracting detailed content from Excel files
+    (including .xls, .xlsx,.csv), and converting the data into
+    Markdown formatted table.
     """
 
     def __init__(

camel/toolkits/function_tool.py

@@ -409,7 +409,7 @@ class FunctionTool:
 
     @property
     def is_async(self) -> bool:
-        return inspect.iscoroutinefunction(self.func)
+        return inspect.iscoroutinefunction(inspect.unwrap(self.func))
 
     @staticmethod
     def validate_openai_tool_schema(

camel/toolkits/mcp_toolkit.py

@@ -42,7 +42,7 @@ logger = get_logger(__name__)
 
 class MCPClient(BaseToolkit):
     r"""Internal class that provides an abstraction layer to interact with
-    external tools using the Model Context Protocol (MCP). It supports two
+    external tools using the Model Context Protocol (MCP). It supports three
     modes of connection:
 
     1. stdio mode: Connects via standard input/output streams for local
@@ -51,6 +51,40 @@ class MCPClient(BaseToolkit):
     2. SSE mode (HTTP Server-Sent Events): Connects via HTTP for persistent,
        event-based interactions.
 
+    3. streamable-http mode: Connects via HTTP for persistent, streamable
+        interactions.
+
+    Connection Lifecycle:
+        There are three ways to manage the connection lifecycle:
+
+        1. Using the async context manager:
+           ```python
+           async with MCPClient(command_or_url="...") as client:
+               # Client is connected here
+               result = await client.some_tool()
+           # Client is automatically disconnected here
+           ```
+
+        2. Using the factory method:
+           ```python
+           client = await MCPClient.create(command_or_url="...")
+           # Client is connected here
+           result = await client.some_tool()
+           # Don't forget to disconnect when done!
+           await client.disconnect()
+           ```
+
+        3. Using explicit connect/disconnect:
+           ```python
+           client = MCPClient(command_or_url="...")
+           await client.connect()
+           # Client is connected here
+           result = await client.some_tool()
+           # Don't forget to disconnect when done!
+           await client.disconnect()
+           ```
+
+
     Attributes:
         command_or_url (str): URL for SSE mode or command executable for stdio
             mode. (default: :obj:`None`)
@@ -160,8 +194,13 @@ class MCPClient(BaseToolkit):
 
     async def disconnect(self):
         r"""Explicitly disconnect from the MCP server."""
+        # If the server is not connected, do nothing
+        if not self._is_connected:
+            return
         self._is_connected = False
         await self._exit_stack.aclose()
+        # Reset the exit stack and session for future reuse purposes
+        self._exit_stack = AsyncExitStack()
         self._session = None
 
     @asynccontextmanager
@@ -328,8 +367,6 @@ class MCPClient(BaseToolkit):
             "additionalProperties": False,
         }
 
-        # Because certain parameters in MCP may include keywords that are not
-        # supported by OpenAI, it is essential to set "strict" to False.
         return {
             "type": "function",
             "function": {
@@ -395,6 +432,70 @@ class MCPClient(BaseToolkit):
     def session(self) -> Optional["ClientSession"]:
         return self._session
 
+    @classmethod
+    async def create(
+        cls,
+        command_or_url: str,
+        args: Optional[List[str]] = None,
+        env: Optional[Dict[str, str]] = None,
+        timeout: Optional[float] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> "MCPClient":
+        r"""Factory method that creates and connects to the MCP server.
+
+        This async factory method ensures the connection to the MCP server is
+        established before the client object is fully constructed.
+
+        Args:
+            command_or_url (str): URL for SSE mode or command executable
+                for stdio mode.
+            args (Optional[List[str]]): List of command-line arguments if
+                stdio mode is used. (default: :obj:`None`)
+            env (Optional[Dict[str, str]]): Environment variables for
+                the stdio mode command. (default: :obj:`None`)
+            timeout (Optional[float]): Connection timeout.
+                (default: :obj:`None`)
+            headers (Optional[Dict[str, str]]): Headers for the HTTP request.
+                (default: :obj:`None`)
+
+        Returns:
+            MCPClient: A fully initialized and connected MCPClient instance.
+
+        Raises:
+            RuntimeError: If connection to the MCP server fails.
+        """
+        client = cls(
+            command_or_url=command_or_url,
+            args=args,
+            env=env,
+            timeout=timeout,
+            headers=headers,
+        )
+        try:
+            await client.connect()
+            return client
+        except Exception as e:
+            # Ensure cleanup on initialization failure
+            await client.disconnect()
+            logger.error(f"Failed to initialize MCPClient: {e}")
+            raise RuntimeError(f"Failed to initialize MCPClient: {e}") from e
+
+    async def __aenter__(self) -> "MCPClient":
+        r"""Async context manager entry point. Automatically connects to the
+        MCP server when used in an async with statement.
+
+        Returns:
+            MCPClient: Self with active connection.
+        """
+        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 MCP server when exiting an async with statement.
+        """
+        await self.disconnect()
+
 
 class MCPToolkit(BaseToolkit):
     r"""MCPToolkit provides a unified interface for managing multiple
@@ -404,6 +505,36 @@ class MCPToolkit(BaseToolkit):
     offers a centralized configuration mechanism for both local and remote
     MCP services.
 
+    Connection Lifecycle:
+        There are three ways to manage the connection lifecycle:
+
+        1. Using the async context manager:
+           ```python
+           async with MCPToolkit(config_path="config.json") as toolkit:
+               # Toolkit is connected here
+               tools = toolkit.get_tools()
+           # Toolkit is automatically disconnected here
+           ```
+
+        2. Using the factory method:
+           ```python
+           toolkit = await MCPToolkit.create(config_path="config.json")
+           # Toolkit is connected here
+           tools = toolkit.get_tools()
+           # Don't forget to disconnect when done!
+           await toolkit.disconnect()
+           ```
+
+        3. Using explicit connect/disconnect:
+           ```python
+           toolkit = MCPToolkit(config_path="config.json")
+           await toolkit.connect()
+           # Toolkit is connected here
+           tools = toolkit.get_tools()
+           # Don't forget to disconnect when done!
+           await toolkit.disconnect()
+           ```
+
     Args:
         servers (Optional[List[MCPClient]]): List of MCPClient
             instances to manage. (default: :obj:`None`)
@@ -473,7 +604,6 @@ class MCPToolkit(BaseToolkit):
         if config_dict:
             self.servers.extend(self._load_servers_from_dict(config_dict))
 
-        self._exit_stack = AsyncExitStack()
         self._connected = False
 
     def _load_servers_from_config(
@@ -565,7 +695,6 @@ class MCPToolkit(BaseToolkit):
             logger.warning("MCPToolkit is already connected")
             return self
 
-        self._exit_stack = AsyncExitStack()
         try:
             # Sequentially connect to each server
             for server in self.servers:
@@ -586,7 +715,6 @@ class MCPToolkit(BaseToolkit):
         for server in self.servers:
             await server.disconnect()
         self._connected = False
-        await self._exit_stack.aclose()
 
     @asynccontextmanager
     async def connection(self) -> AsyncGenerator["MCPToolkit", None]:

camel/toolkits/search_toolkit.py

@@ -12,7 +12,6 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 import os
-import xml.etree.ElementTree as ET
 from typing import Any, Dict, List, Literal, Optional, TypeAlias, Union, cast
 
 import requests
@@ -489,173 +488,6 @@ class SearchToolkit(BaseToolkit):
         # If no answer found, return an empty list
         return responses
 
-    @dependencies_required("wolframalpha")
-    def query_wolfram_alpha(
-        self, query: str, is_detailed: bool = False
-    ) -> Union[str, Dict[str, Any]]:
-        r"""Queries Wolfram|Alpha and returns the result. Wolfram|Alpha is an
-        answer engine developed by Wolfram Research. It is offered as an online
-        service that answers factual queries by computing answers from
-        externally sourced data.
-
-        Args:
-            query (str): The query to send to Wolfram Alpha.
-            is_detailed (bool): Whether to include additional details
-                including step by step information in the result.
-                (default: :obj:`False`)
-
-        Returns:
-            Union[str, Dict[str, Any]]: The result from Wolfram Alpha.
-                Returns a string if `is_detailed` is False, otherwise returns
-                a dictionary with detailed information.
-        """
-        import wolframalpha
-
-        WOLFRAMALPHA_APP_ID = os.environ.get("WOLFRAMALPHA_APP_ID")
-        if not WOLFRAMALPHA_APP_ID:
-            raise ValueError(
-                "`WOLFRAMALPHA_APP_ID` not found in environment "
-                "variables. Get `WOLFRAMALPHA_APP_ID` here: `https://products.wolframalpha.com/api/`."
-            )
-
-        try:
-            client = wolframalpha.Client(WOLFRAMALPHA_APP_ID)
-            res = client.query(query)
-
-        except Exception as e:
-            return f"Wolfram Alpha wasn't able to answer it. Error: {e}"
-
-        pased_result = self._parse_wolfram_result(res)
-
-        if is_detailed:
-            step_info = self._get_wolframalpha_step_by_step_solution(
-                WOLFRAMALPHA_APP_ID, query
-            )
-            pased_result["steps"] = step_info
-            return pased_result
-
-        return pased_result["final_answer"]
-
-    def _parse_wolfram_result(self, result) -> Dict[str, Any]:
-        r"""Parses a Wolfram Alpha API result into a structured dictionary
-        format.
-
-        Args:
-            result: The API result returned from a Wolfram Alpha
-                query, structured with multiple pods, each containing specific
-                information related to the query.
-
-        Returns:
-            dict: A structured dictionary with the original query and the
-                final answer.
-        """
-
-        # Extract the original query
-        query = result.get("@inputstring", "")
-
-        # Initialize a dictionary to hold structured output
-        output = {"query": query, "pod_info": [], "final_answer": None}
-
-        # Loop through each pod to extract the details
-        for pod in result.get("pod", []):
-            # Handle the case where subpod might be a list
-            subpod_data = pod.get("subpod", {})
-            if isinstance(subpod_data, list):
-                # If it's a list, get the first item for 'plaintext' and 'img'
-                description, image_url = next(
-                    (
-                        (data["plaintext"], data["img"])
-                        for data in subpod_data
-                        if "plaintext" in data and "img" in data
-                    ),
-                    ("", ""),
-                )
-            else:
-                # Otherwise, handle it as a dictionary
-                description = subpod_data.get("plaintext", "")
-                image_url = subpod_data.get("img", {}).get("@src", "")
-
-            pod_info = {
-                "title": pod.get("@title", ""),
-                "description": description,
-                "image_url": image_url,
-            }
-
-            # For Results pod, collect all plaintext values from subpods
-            if pod.get("@title") == "Results":
-                results_text = []
-                if isinstance(subpod_data, list):
-                    for subpod in subpod_data:
-                        if subpod.get("plaintext"):
-                            results_text.append(subpod["plaintext"])
-                else:
-                    if description:
-                        results_text.append(description)
-                pod_info["description"] = "\n".join(results_text)
-
-            # Add to steps list
-            output["pod_info"].append(pod_info)
-
-            # Get final answer
-            if pod.get("@primary", False):
-                output["final_answer"] = description
-
-        return output
-
-    def _get_wolframalpha_step_by_step_solution(
-        self, app_id: str, query: str
-    ) -> dict:
-        r"""Retrieve a step-by-step solution from the Wolfram Alpha API for a
-        given query.
-
-        Args:
-            app_id (str): Your Wolfram Alpha API application ID.
-            query (str): The mathematical or computational query to solve.
-
-        Returns:
-            dict: The step-by-step solution response text from the Wolfram
-                Alpha API.
-        """
-        # Define the base URL
-        url = "https://api.wolframalpha.com/v2/query"
-
-        # Set up the query parameters
-        params = {
-            "appid": app_id,
-            "input": query,
-            "podstate": ["Result__Step-by-step solution", "Show all steps"],
-            "format": "plaintext",
-        }
-
-        # Send the request
-        response = requests.get(url, params=params)
-        root = ET.fromstring(response.text)
-
-        # Extracting step-by-step steps, including 'SBSStep' and 'SBSHintStep'
-        steps = []
-        # Find all subpods within the 'Results' pod
-        for subpod in root.findall(".//pod[@title='Results']//subpod"):
-            # Check if the subpod has the desired stepbystepcontenttype
-            content_type = subpod.find("stepbystepcontenttype")
-            if content_type is not None and content_type.text in [
-                "SBSStep",
-                "SBSHintStep",
-            ]:
-                plaintext = subpod.find("plaintext")
-                if plaintext is not None and plaintext.text:
-                    step_text = plaintext.text.strip()
-                    cleaned_step = step_text.replace(
-                        "Hint: |", ""
-                    ).strip()  # Remove 'Hint: |' if present
-                    steps.append(cleaned_step)
-
-        # Structuring the steps into a dictionary
-        structured_steps = {}
-        for i, step in enumerate(steps, start=1):
-            structured_steps[f"step{i}"] = step
-
-        return structured_steps
-
     def tavily_search(
         self, query: str, num_results: int = 5, **kwargs
     ) -> List[Dict[str, Any]]:
@@ -1243,7 +1075,6 @@ class SearchToolkit(BaseToolkit):
             FunctionTool(self.search_linkup),
             FunctionTool(self.search_google),
             FunctionTool(self.search_duckduckgo),
-            FunctionTool(self.query_wolfram_alpha),
             FunctionTool(self.tavily_search),
             FunctionTool(self.search_brave),
             FunctionTool(self.search_bocha),