camel-ai 0.2.56__py3-none-any.whl → 0.2.58__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,12 @@ 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"]) -> None:
+        r"""Run the MCP server in the specified mode.
+
+        Args:
+            mode (Literal["stdio", "sse"]): 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,7 @@ 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 method for processing excel files.
     """
 
     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`)
@@ -328,8 +362,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 +427,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 +500,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`)

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),

camel/toolkits/wolfram_alpha_toolkit.py

@@ -0,0 +1,237 @@
+# ========= 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
+import xml.etree.ElementTree as ET
+from typing import Any, Dict, List, Union
+
+import requests
+
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+from camel.utils import MCPServer, api_keys_required, dependencies_required
+
+
+@MCPServer()
+class WolframAlphaToolkit(BaseToolkit):
+    r"""A class representing a toolkit for WolframAlpha.
+
+    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.
+    """
+
+    @api_keys_required(
+        [
+            (None, "WOLFRAMALPHA_APP_ID"),
+        ]
+    )
+    @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.
+
+        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", "")
+
+        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"]
+
+    @api_keys_required(
+        [
+            (None, "WOLFRAMALPHA_APP_ID"),
+        ]
+    )
+    def query_wolfram_llm(self, query: str) -> str:
+        r"""Queries Wolfram|Alpha LLM API and returns the result.
+
+        Args:
+            query (str): The query to send to Wolfram Alpha LLM.
+
+        Returns:
+            str: The result from Wolfram Alpha as a string.
+        """
+
+        WOLFRAMALPHA_APP_ID = os.environ.get("WOLFRAMALPHA_APP_ID", "")
+
+        try:
+            url = "https://www.wolframalpha.com/api/v1/llm-api"
+            params = {"input": query, "appid": WOLFRAMALPHA_APP_ID}
+
+            response = requests.get(url, params=params)
+            response.raise_for_status()
+            return response.text
+
+        except Exception as e:
+            return f"Wolfram Alpha wasn't able to answer it. Error: {e}"
+
+    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[str, Any]: 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 get_tools(self) -> List[FunctionTool]:
+        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.
+        """
+        return [
+            FunctionTool(self.query_wolfram_alpha),
+            FunctionTool(self.query_wolfram_llm),
+        ]