camel-ai 0.2.37__py3-none-any.whl → 0.2.39__py3-none-any.whl

camel/toolkits/mcp_toolkit.py

@@ -14,6 +14,7 @@
 import inspect
 import json
 import os
+import shlex
 from contextlib import AsyncExitStack, asynccontextmanager
 from typing import (
     TYPE_CHECKING,
@@ -25,11 +26,12 @@ from typing import (
     Optional,
     Set,
     Union,
+    cast,
 )
 from urllib.parse import urlparse
 
 if TYPE_CHECKING:
-    from mcp import ListToolsResult, Tool
+    from mcp import ClientSession, ListToolsResult, Tool
 
 from camel.logger import get_logger
 from camel.toolkits import BaseToolkit, FunctionTool
@@ -37,7 +39,7 @@ from camel.toolkits import BaseToolkit, FunctionTool
 logger = get_logger(__name__)
 
 
-class _MCPServer(BaseToolkit):
+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
     modes of connection:
@@ -69,7 +71,6 @@ class _MCPServer(BaseToolkit):
         headers: Optional[Dict[str, str]] = None,
     ):
         from mcp import Tool
-        from mcp.client.session import ClientSession
 
         super().__init__(timeout=timeout)
 
@@ -87,7 +88,7 @@ class _MCPServer(BaseToolkit):
         r"""Explicitly connect to the MCP server.
 
         Returns:
-            _MCPServer: The connected server instance
+            MCPClient: The client used to connect to the server.
         """
         from mcp.client.session import ClientSession
         from mcp.client.sse import sse_client
@@ -110,11 +111,20 @@ class _MCPServer(BaseToolkit):
                 )
             else:
                 command = self.command_or_url
+                arguments = self.args
+                if not self.args:
+                    argv = shlex.split(command)
+                    if not argv:
+                        raise ValueError("Command is empty")
+
+                    command = argv[0]
+                    arguments = argv[1:]
+
                 if os.name == "nt" and command.lower() == "npx":
                     command = "npx.cmd"
 
                 server_parameters = StdioServerParameters(
-                    command=command, args=self.args, env=self.env
+                    command=command, args=arguments, env=self.env
                 )
                 (
                     read_stream,
@@ -135,6 +145,7 @@ class _MCPServer(BaseToolkit):
             # Ensure resources are cleaned up on connection failure
             await self.disconnect()
             logger.error(f"Failed to connect to MCP server: {e}")
+            raise e
 
     async def disconnect(self):
         r"""Explicitly disconnect from the MCP server."""
@@ -149,7 +160,7 @@ class _MCPServer(BaseToolkit):
         on the provided `command_or_url`.
 
         Yields:
-            _MCPServer: Instance with active connection ready for tool
+            MCPClient: Instance with active connection ready for tool
                 interaction.
         """
         try:
@@ -170,7 +181,8 @@ class _MCPServer(BaseToolkit):
         try:
             return await self._session.list_tools()
         except Exception as e:
-            return f"Failed to list MCP tools: {e!s}"
+            logger.exception("Failed to list MCP tools")
+            raise e
 
     def generate_function_from_mcp_tool(self, mcp_tool: "Tool") -> Callable:
         r"""Dynamically generates a Python callable function corresponding to
@@ -235,7 +247,7 @@ class _MCPServer(BaseToolkit):
                 logger.error(
                     "MCP Client is not connected. Call `connection()` first."
                 )
-                return (
+                raise RuntimeError(
                     "MCP Client is not connected. Call `connection()` first."
                 )
 
@@ -245,7 +257,7 @@ class _MCPServer(BaseToolkit):
                 )
             except Exception as e:
                 logger.error(f"Failed to call MCP tool '{func_name}': {e!s}")
-                return f"Failed to call MCP tool '{func_name}': {e!s}"
+                raise e
 
             if not result.content or len(result.content) == 0:
                 return "No data available for this request."
@@ -272,7 +284,7 @@ class _MCPServer(BaseToolkit):
                 logger.error(
                     f"Error processing content from MCP tool response: {e!s}"
                 )
-                return "Error processing content from MCP tool response"
+                raise e
 
         dynamic_function.__name__ = func_name
         dynamic_function.__doc__ = func_desc
@@ -331,6 +343,10 @@ class _MCPServer(BaseToolkit):
             for mcp_tool in self._mcp_tools
         ]
 
+    @property
+    def session(self) -> Optional["ClientSession"]:
+        return self._session
+
 
 class MCPToolkit(BaseToolkit):
     r"""MCPToolkit provides a unified interface for managing multiple
@@ -341,7 +357,7 @@ class MCPToolkit(BaseToolkit):
     MCP services.
 
     Args:
-        servers (Optional[List[_MCPServer]]): List of _MCPServer
+        servers (Optional[List[MCPClient]]): List of MCPClient
             instances to manage.
         config_path (Optional[str]): Path to a JSON configuration file
             defining MCP servers.
@@ -359,7 +375,7 @@ class MCPToolkit(BaseToolkit):
         .. code-block:: json
 
             {
-              "mcpWebServers": {
+              "mcpServers": {
                 "protected-server": {
                   "url": "https://example.com/mcp",
                   "timeout": 30,
@@ -372,12 +388,12 @@ class MCPToolkit(BaseToolkit):
             }
 
     Attributes:
-        servers (List[_MCPServer]): List of _MCPServer instances being managed.
+        servers (List[MCPClient]): List of MCPClient instances being managed.
     """
 
     def __init__(
         self,
-        servers: Optional[List[_MCPServer]] = None,
+        servers: Optional[List[MCPClient]] = None,
         config_path: Optional[str] = None,
     ):
         super().__init__()
@@ -388,7 +404,7 @@ class MCPToolkit(BaseToolkit):
                 "Servers from both sources will be combined."
             )
 
-        self.servers = servers or []
+        self.servers: List[MCPClient] = servers or []
 
         if config_path:
             self.servers.extend(self._load_servers_from_config(config_path))
@@ -396,14 +412,14 @@ class MCPToolkit(BaseToolkit):
         self._exit_stack = AsyncExitStack()
         self._connected = False
 
-    def _load_servers_from_config(self, config_path: str) -> List[_MCPServer]:
+    def _load_servers_from_config(self, config_path: str) -> List[MCPClient]:
         r"""Loads MCP server configurations from a JSON file.
 
         Args:
             config_path (str): Path to the JSON configuration file.
 
         Returns:
-            List[_MCPServer]: List of configured _MCPServer instances.
+            List[MCPClient]: List of configured MCPClient instances.
         """
         try:
             with open(config_path, "r", encoding="utf-8") as f:
@@ -413,14 +429,13 @@ class MCPToolkit(BaseToolkit):
                     logger.warning(
                         f"Invalid JSON in config file '{config_path}': {e!s}"
                     )
-                    return []
-        except FileNotFoundError:
+                    raise e
+        except FileNotFoundError as e:
             logger.warning(f"Config file not found: '{config_path}'")
-            return []
+            raise e
 
         all_servers = []
 
-        # Process local MCP servers
         mcp_servers = data.get("mcpServers", {})
         if not isinstance(mcp_servers, dict):
             logger.warning("'mcpServers' is not a dictionary, skipping...")
@@ -433,47 +448,21 @@ class MCPToolkit(BaseToolkit):
                 )
                 continue
 
-            if "command" not in cfg:
+            if "command" not in cfg and "url" not in cfg:
                 logger.warning(
-                    f"Missing required 'command' field for server '{name}'"
+                    f"Missing required 'command' or 'url' field for server "
+                    f"'{name}'"
                 )
                 continue
 
-            server = _MCPServer(
-                command_or_url=cfg["command"],
+            server = MCPClient(
+                command_or_url=cast(str, cfg.get("command") or cfg.get("url")),
                 args=cfg.get("args", []),
                 env={**os.environ, **cfg.get("env", {})},
                 timeout=cfg.get("timeout", None),
             )
             all_servers.append(server)
 
-        # Process remote MCP web servers
-        mcp_web_servers = data.get("mcpWebServers", {})
-        if not isinstance(mcp_web_servers, dict):
-            logger.warning("'mcpWebServers' is not a dictionary, skipping...")
-            mcp_web_servers = {}
-
-        for name, cfg in mcp_web_servers.items():
-            if not isinstance(cfg, dict):
-                logger.warning(
-                    f"Configuration for web server '{name}' must"
-                    "be a dictionary"
-                )
-                continue
-
-            if "url" not in cfg:
-                logger.warning(
-                    f"Missing required 'url' field for web server '{name}'"
-                )
-                continue
-
-            server = _MCPServer(
-                command_or_url=cfg["url"],
-                timeout=cfg.get("timeout", None),
-                headers=cfg.get("headers", {}),
-            )
-            all_servers.append(server)
-
         return all_servers
 
     async def connect(self):
@@ -497,6 +486,7 @@ class MCPToolkit(BaseToolkit):
             # Ensure resources are cleaned up on connection failure
             await self.disconnect()
             logger.error(f"Failed to connect to one or more MCP servers: {e}")
+            raise e
 
     async def disconnect(self):
         r"""Explicitly disconnect from all MCP servers."""

camel/toolkits/meshy_toolkit.py

@@ -13,14 +13,16 @@
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 
 import os
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 import requests
 
+from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
-from camel.utils import api_keys_required
+from camel.utils import MCPServer, api_keys_required
 
 
+@MCPServer()
 class MeshyToolkit(BaseToolkit):
     r"""A class representing a toolkit for 3D model generation using Meshy.
 
@@ -188,3 +190,19 @@ class MeshyToolkit(BaseToolkit):
 
         # Wait for refinement completion and return final result
         return self.wait_for_task_completion(refine_task_id)
+
+    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.generate_3d_preview),
+            FunctionTool(self.refine_3d_model),
+            FunctionTool(self.get_task_status),
+            FunctionTool(self.wait_for_task_completion),
+            FunctionTool(self.generate_3d_model_complete),
+        ]

camel/toolkits/networkx_toolkit.py

@@ -18,10 +18,12 @@ from typing import Any, Callable, Dict, List, Literal, Optional, Tuple, Union
 from camel.logger import get_logger
 from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
+from camel.utils import MCPServer
 
 logger = get_logger(__name__)
 
 
+@MCPServer()
 class NetworkXToolkit(BaseToolkit):
     _nx = None  # Class variable to store the networkx module
 

camel/toolkits/notion_toolkit.py

@@ -16,6 +16,7 @@ from typing import List, Optional, cast
 
 from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
+from camel.utils import MCPServer, api_keys_required
 
 
 def get_plain_text_from_rich_text(rich_text: List[dict]) -> str:
@@ -66,6 +67,7 @@ def get_media_source_text(block: dict) -> str:
     return source
 
 
+@MCPServer()
 class NotionToolkit(BaseToolkit):
     r"""A toolkit for retrieving information from the user's notion pages.
 
@@ -76,6 +78,11 @@ class NotionToolkit(BaseToolkit):
             the notion APIs.
     """
 
+    @api_keys_required(
+        [
+            ("notion_token", 'NOTION_TOKEN'),
+        ]
+    )
     def __init__(
         self,
         notion_token: Optional[str] = None,

camel/toolkits/openai_agent_toolkit.py

@@ -0,0 +1,131 @@
+# ========= 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 List, Optional
+
+from openai import OpenAI
+
+from camel.logger import get_logger
+from camel.models import BaseModelBackend, ModelFactory
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+from camel.types import ModelPlatformType, ModelType
+from camel.utils import api_keys_required
+
+logger = get_logger(__name__)
+
+
+class OpenAIAgentToolkit(BaseToolkit):
+    r"""Toolkit for accessing OpenAI's agent tools including web search and
+    file search.
+
+    Provides access to OpenAI's web search and file search capabilities
+    through the Responses API, allowing agents to retrieve information from
+    the web and search through uploaded files.
+    """
+
+    @api_keys_required(
+        [
+            (None, "OPENAI_API_KEY"),
+        ]
+    )
+    def __init__(
+        self,
+        model: Optional[BaseModelBackend] = None,
+        api_key: Optional[str] = None,
+    ) -> None:
+        r"""Initialize the OpenAI agent toolkit.
+
+        Args:
+            model (BaseModelBackend): The OpenAI model to use for responses.
+                If None, defaults to gpt-4o-mini. (default: :obj:`None`)
+            api_key (str): OpenAI API key. If not provided, will attempt to
+                use OPENAI_API_KEY environment variable. (default: :obj:`None`)
+        """
+        super().__init__()
+        self.api_key = api_key or os.getenv("OPENAI_API_KEY")
+        self.client = OpenAI(api_key=self.api_key)
+        self.model = model or ModelFactory.create(
+            model_platform=ModelPlatformType.OPENAI,
+            model_type=ModelType.GPT_4O_MINI,
+        )
+
+    def web_search(self, query: str) -> str:
+        r"""Perform a web search using OpenAI's web search tool.
+
+        Args:
+            query (str): The search query.
+
+        Returns:
+            str: The search result or error message.
+        """
+        try:
+            response = self.client.responses.create(
+                model=str(self.model.model_type),
+                tools=[{"type": "web_search_preview"}],
+                input=query,
+            )
+            return response.output_text
+
+        except Exception as e:
+            logger.error(f"Web search failed: {e!s}")
+            return f"Web search failed: {e!s}"
+
+    def file_search(
+        self,
+        query: str,
+        vector_store_id: str,
+    ) -> str:
+        r"""Search through files using OpenAI's file search tool.
+
+        Args:
+            query (str): The search query.
+            vector_store_id (str): The vector store ID to search in.
+
+        Returns:
+            str: The search result or error message.
+        """
+        if not vector_store_id.strip():
+            logger.error("Empty vector store ID provided.")
+            return "Empty vector store ID provided, it cannot be empty."
+
+        try:
+            response = self.client.responses.create(
+                model=str(self.model.model_type),
+                tools=[
+                    {
+                        "type": "file_search",
+                        "vector_store_ids": [vector_store_id],
+                    }
+                ],
+                input=query,
+            )
+            return response.output_text
+
+        except Exception as e:
+            logger.error(f"File search failed: {e!s}")
+            return f"File search failed: {e!s}"
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Retrieve available toolkit functions as FunctionTool objects.
+
+        Returns:
+            List[FunctionTool]: Collection of FunctionTool objects representing
+                the available search functions in this toolkit.
+        """
+        return [
+            FunctionTool(self.web_search),
+            FunctionTool(self.file_search),
+        ]

camel/toolkits/openbb_toolkit.py

@@ -17,9 +17,10 @@ from typing import List, Literal, Optional
 
 from camel.toolkits.base import BaseToolkit
 from camel.toolkits.function_tool import FunctionTool
-from camel.utils import api_keys_required, dependencies_required
+from camel.utils import MCPServer, api_keys_required, dependencies_required
 
 
+@MCPServer()
 class OpenBBToolkit(BaseToolkit):
     r"""A toolkit for accessing financial data and analysis through OpenBB
     Platform.

camel/toolkits/pubmed_toolkit.py

@@ -18,10 +18,12 @@ import requests
 
 from camel.logger import get_logger
 from camel.toolkits import BaseToolkit, FunctionTool
+from camel.utils import MCPServer
 
 logger = get_logger(__name__)
 
 
+@MCPServer()
 class PubMedToolkit(BaseToolkit):
     r"""A toolkit for interacting with PubMed's E-utilities API to access
     MEDLINE data.

camel/toolkits/reddit_toolkit.py

@@ -18,9 +18,10 @@ from typing import Any, Dict, List, Optional, Union
 
 from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
-from camel.utils import retry_on_error
+from camel.utils import MCPServer, retry_on_error
 
 
+@MCPServer()
 class RedditToolkit(BaseToolkit):
     r"""A class representing a toolkit for Reddit operations.
 

camel/toolkits/retrieval_toolkit.py

@@ -17,9 +17,10 @@ from camel.retrievers import AutoRetriever
 from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
 from camel.types import StorageType
-from camel.utils import Constants
+from camel.utils import Constants, MCPServer
 
 
+@MCPServer()
 class RetrievalToolkit(BaseToolkit):
     r"""A class representing a toolkit for information retrieval.
 

camel/toolkits/search_toolkit.py

@@ -19,9 +19,10 @@ import requests
 
 from camel.toolkits.base import BaseToolkit
 from camel.toolkits.function_tool import FunctionTool
-from camel.utils import api_keys_required, dependencies_required
+from camel.utils import MCPServer, api_keys_required, dependencies_required
 
 
+@MCPServer()
 class SearchToolkit(BaseToolkit):
     r"""A class representing a toolkit for web search.