camel-ai 0.2.72a10__py3-none-any.whl → 0.2.73a1__py3-none-any.whl

camel/toolkits/notion_mcp_toolkit.py

@@ -0,0 +1,234 @@
+# ========= 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. =========
+
+from typing import Any, ClassVar, Dict, List, Optional, Set
+
+from camel.toolkits import BaseToolkit, FunctionTool
+
+from .mcp_toolkit import MCPToolkit
+
+
+class NotionMCPToolkit(BaseToolkit):
+    r"""NotionMCPToolkit provides an interface for interacting with Notion
+    through the Model Context Protocol (MCP).
+
+    Attributes:
+        timeout (Optional[float]): Connection timeout in seconds.
+            (default: :obj:`None`)
+
+    Note:
+        Currently only supports asynchronous operation mode.
+    """
+
+    # TODO: Create unified method to validate and fix the schema
+    SCHEMA_KEYWORDS: ClassVar[Set[str]] = {
+        "type",
+        "properties",
+        "items",
+        "required",
+        "additionalProperties",
+        "description",
+        "title",
+        "default",
+        "enum",
+        "const",
+        "examples",
+        "$ref",
+        "$defs",
+        "definitions",
+        "allOf",
+        "oneOf",
+        "anyOf",
+        "not",
+        "if",
+        "then",
+        "else",
+        "format",
+        "pattern",
+        "minimum",
+        "maximum",
+        "minLength",
+        "maxLength",
+        "minItems",
+        "maxItems",
+        "uniqueItems",
+    }
+
+    def __init__(
+        self,
+        timeout: Optional[float] = None,
+    ) -> None:
+        r"""Initializes the NotionMCPToolkit.
+
+        Args:
+            timeout (Optional[float]): Connection timeout in seconds.
+                (default: :obj:`None`)
+        """
+        super().__init__(timeout=timeout)
+
+        self._mcp_toolkit = MCPToolkit(
+            config_dict={
+                "mcpServers": {
+                    "notionMCP": {
+                        "command": "npx",
+                        "args": [
+                            "-y",
+                            "mcp-remote",
+                            "https://mcp.notion.com/mcp",
+                        ],
+                    }
+                }
+            },
+            timeout=timeout,
+        )
+
+    async def connect(self):
+        r"""Explicitly connect to the Notion MCP server."""
+        await self._mcp_toolkit.connect()
+
+    async def disconnect(self):
+        r"""Explicitly disconnect from the Notion MCP server."""
+        await self._mcp_toolkit.disconnect()
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Returns a list of tools provided by the NotionMCPToolkit.
+
+        Returns:
+            List[FunctionTool]: List of available tools.
+        """
+        all_tools = []
+        for client in self._mcp_toolkit.clients:
+            try:
+                original_build_schema = client._build_tool_schema
+
+                def create_wrapper(orig_func):
+                    def wrapper(mcp_tool):
+                        return self._build_notion_tool_schema(
+                            mcp_tool, orig_func
+                        )
+
+                    return wrapper
+
+                client._build_tool_schema = create_wrapper(  # type: ignore[method-assign]
+                    original_build_schema
+                )
+
+                client_tools = client.get_tools()
+                all_tools.extend(client_tools)
+
+                client._build_tool_schema = original_build_schema  # type: ignore[method-assign]
+
+            except Exception as e:
+                from camel.logger import get_logger
+
+                logger = get_logger(__name__)
+                logger.error(f"Failed to get tools from client: {e}")
+
+        return all_tools
+
+    def _build_notion_tool_schema(self, mcp_tool, original_build_schema):
+        r"""Build tool schema with Notion-specific fixes."""
+        schema = original_build_schema(mcp_tool)
+        self._fix_notion_schema_recursively(schema)
+        return schema
+
+    def _fix_notion_schema_recursively(self, obj: Any) -> None:
+        r"""Recursively fix Notion MCP schema issues."""
+        if isinstance(obj, dict):
+            self._fix_dict_schema(obj)
+            self._process_nested_structures(obj)
+        elif isinstance(obj, list):
+            for item in obj:
+                self._fix_notion_schema_recursively(item)
+
+    def _fix_dict_schema(self, obj: Dict[str, Any]) -> None:
+        r"""Fix dictionary schema issues."""
+        if "properties" in obj and "type" not in obj:
+            self._fix_missing_type_with_properties(obj)
+        elif obj.get("type") == "object" and "properties" in obj:
+            self._fix_object_with_properties(obj)
+
+    def _fix_missing_type_with_properties(self, obj: Dict[str, Any]) -> None:
+        r"""Fix objects with properties but missing type field."""
+        properties = obj.get("properties", {})
+        if properties and isinstance(properties, dict):
+            obj["type"] = "object"
+            obj["additionalProperties"] = False
+
+            required_properties = self._get_required_properties(
+                properties, conservative=True
+            )
+            if required_properties:
+                obj["required"] = required_properties
+
+    def _fix_object_with_properties(self, obj: Dict[str, Any]) -> None:
+        r"""Fix objects with type="object" and properties."""
+        properties = obj.get("properties", {})
+        if properties and isinstance(properties, dict):
+            existing_required = obj.get("required", [])
+
+            for prop_name, prop_schema in properties.items():
+                if (
+                    prop_name not in existing_required
+                    and prop_name not in self.SCHEMA_KEYWORDS
+                    and self._is_property_required(prop_schema)
+                ):
+                    existing_required.append(prop_name)
+
+            if existing_required:
+                obj["required"] = existing_required
+
+            if "additionalProperties" not in obj:
+                obj["additionalProperties"] = False
+
+    def _get_required_properties(
+        self, properties: Dict[str, Any], conservative: bool = False
+    ) -> List[str]:
+        r"""Get list of required properties from a properties dict."""
+        required = []
+        for prop_name, prop_schema in properties.items():
+            if (
+                prop_name not in self.SCHEMA_KEYWORDS
+                and isinstance(prop_schema, dict)
+                and self._is_property_required(prop_schema)
+            ):
+                required.append(prop_name)
+        return required
+
+    def _is_property_required(self, prop_schema: Dict[str, Any]) -> bool:
+        r"""Check if a property should be marked as required."""
+        prop_type = prop_schema.get("type")
+        return (
+            prop_type is not None
+            and prop_type != "null"
+            and "default" not in prop_schema
+            and not (isinstance(prop_type, list) and "null" in prop_type)
+        )
+
+    def _process_nested_structures(self, obj: Dict[str, Any]) -> None:
+        r"""Process all nested structures in a schema object."""
+        for key, value in obj.items():
+            if key in ["anyOf", "oneOf", "allOf"] and isinstance(value, list):
+                for item in value:
+                    self._fix_notion_schema_recursively(item)
+            elif key == "items" and isinstance(value, dict):
+                self._fix_notion_schema_recursively(value)
+            elif key == "properties" and isinstance(value, dict):
+                for prop_value in value.values():
+                    self._fix_notion_schema_recursively(prop_value)
+            elif key == "$defs" and isinstance(value, dict):
+                for def_value in value.values():
+                    self._fix_notion_schema_recursively(def_value)
+            elif isinstance(value, (dict, list)):
+                self._fix_notion_schema_recursively(value)

camel/toolkits/screenshot_toolkit.py

@@ -12,22 +12,22 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 
-import base64
-import io
 import os
-import time
 from pathlib import Path
 from typing import List, Optional
 
+from PIL import Image
+
 from camel.logger import get_logger
+from camel.messages import BaseMessage
 from camel.toolkits import BaseToolkit, FunctionTool
+from camel.toolkits.base import RegisteredAgentToolkit
 from camel.utils import dependencies_required
-from camel.utils.tool_result import ToolResult
 
 logger = get_logger(__name__)
 
 
-class ScreenshotToolkit(BaseToolkit):
+class ScreenshotToolkit(BaseToolkit, RegisteredAgentToolkit):
     r"""A toolkit for taking screenshots."""
 
     @dependencies_required('PIL')
@@ -50,6 +50,7 @@ class ScreenshotToolkit(BaseToolkit):
         from PIL import ImageGrab
 
         super().__init__(timeout=timeout)
+        RegisteredAgentToolkit.__init__(self)
 
         camel_workdir = os.environ.get("CAMEL_WORKDIR")
         if working_directory:
@@ -60,25 +61,101 @@ class ScreenshotToolkit(BaseToolkit):
             path = Path("camel_working_dir")
 
         self.ImageGrab = ImageGrab
-        self.screenshots_dir = path / "screenshots"
+        self.screenshots_dir = path
         self.screenshots_dir.mkdir(parents=True, exist_ok=True)
 
-    def take_screenshot(
+    def read_image(
+        self,
+        image_path: str,
+        instruction: str = "",
+    ) -> str:
+        r"""Analyzes an image from a local file path.
+
+        This function enables you to "see" and interpret an image from a
+        file. It's useful for tasks where you need to understand visual
+        information, such as reading a screenshot of a webpage or a diagram.
+
+        Args:
+            image_path (str): The local file path to the image.
+                For example: 'screenshots/login_page.png'.
+            instruction (str, optional): Specific instructions for what to look
+                for or what to do with the image. For example: "What is the
+                main headline on this page?" or "Find the 'Submit' button.".
+
+        Returns:
+            str: The response after analyzing the image, which could be a
+                 description, an answer, or a confirmation of an action.
+        """
+        if self.agent is None:
+            logger.error(
+                "Cannot record screenshot in memory: No agent registered. "
+                "Please pass this toolkit to ChatAgent via "
+                "toolkits_to_register_agent parameter."
+            )
+            return (
+                "Error: No agent registered. Please pass this toolkit to "
+                "ChatAgent via toolkits_to_register_agent parameter."
+            )
+
+        try:
+            image_path = str(Path(image_path).absolute())
+
+            # Check if file exists before trying to open
+            if not os.path.exists(image_path):
+                error_msg = f"Screenshot file not found: {image_path}"
+                logger.error(error_msg)
+                return f"Error: {error_msg}"
+
+            # Load the image from the path
+            img = Image.open(image_path)
+
+            # Create a message with the screenshot image
+            message = BaseMessage.make_user_message(
+                role_name="User",
+                content=instruction,
+                image_list=[img],
+            )
+
+            # Record the message in agent's memory
+            response = self.agent.step(message)
+            return response.msgs[0].content
+
+        except Exception as e:
+            logger.error(f"Error reading screenshot: {e}")
+            return f"Error reading screenshot: {e}"
+
+    def take_screenshot_and_read_image(
         self,
+        filename: str,
         save_to_file: bool = True,
-    ) -> ToolResult:
-        r"""Take a screenshot of the entire screen and return it as a
-        base64-encoded image.
+        read_image: bool = True,
+        instruction: Optional[str] = None,
+    ) -> str:
+        r"""Captures a screenshot of the entire screen.
+
+        This function can save the screenshot to a file and optionally analyze
+        it. It's useful for capturing the current state of the UI for
+        documentation, analysis, or to guide subsequent actions.
 
         Args:
-            save_to_file (bool): Whether to save the screenshot to a file.
+            filename (str): The name for the screenshot file (e.g.,
+                "homepage.png"). The file is saved in a `screenshots`
+                subdirectory within the working directory. Must end with
+                `.png`. (default: :obj:`None`)
+            save_to_file (bool, optional): If `True`, saves the screenshot to
+                a file. (default: :obj:`True`)
+            read_image (bool, optional): If `True`, the agent will analyze
+                the screenshot. `save_to_file` must also be `True`.
                 (default: :obj:`True`)
+            instruction (Optional[str], optional): A specific question or
+                command for the agent regarding the screenshot, used only if
+                `read_image` is `True`. For example: "Confirm that the
+                user is logged in.".
 
         Returns:
-            ToolResult: An object containing:
-                - text (str): A description of the screenshot.
-                - images (List[str]): A list containing one base64-encoded
-                  PNG image data URL.
+            str: A confirmation message indicating success or failure,
+                 including the file path if saved, and the agent's response
+                 if `read_image` is `True`.
         """
         try:
             # Take screenshot of entire screen
@@ -90,32 +167,39 @@ class ScreenshotToolkit(BaseToolkit):
                 # Create directory if it doesn't exist
                 os.makedirs(self.screenshots_dir, exist_ok=True)
 
-                # Generate filename with timestamp
-                timestamp = int(time.time())
-                filename = f"screenshot_{timestamp}.png"
-                file_path = os.path.join(self.screenshots_dir, filename)
+                # Create unique filename if file already exists
+                base_path = os.path.join(self.screenshots_dir, filename)
+                file_path = base_path
+                counter = 1
+                while os.path.exists(file_path):
+                    name, ext = os.path.splitext(filename)
+                    unique_filename = f"{name}_{counter}{ext}"
+                    file_path = os.path.join(
+                        self.screenshots_dir, unique_filename
+                    )
+                    counter += 1
+
                 screenshot.save(file_path)
                 logger.info(f"Screenshot saved to {file_path}")
 
-            # Convert to base64
-            img_buffer = io.BytesIO()
-            screenshot.save(img_buffer, format="PNG")
-            img_buffer.seek(0)
-            img_base64 = base64.b64encode(img_buffer.getvalue()).decode(
-                'utf-8'
-            )
-            img_data_url = f"data:image/png;base64,{img_base64}"
-
             # Create result text
             result_text = "Screenshot captured successfully"
             if file_path:
                 result_text += f" and saved to {file_path}"
 
-            return ToolResult(text=result_text, images=[img_data_url])
+            # Record in agent memory if requested
+            if read_image and file_path is not None:
+                inst = instruction if instruction is not None else ""
+                response = self.read_image(
+                    str(Path(file_path).absolute()), inst
+                )
+                result_text += f". Agent response: {response}"
+
+            return result_text
 
         except Exception as e:
             logger.error(f"Error taking screenshot: {e}")
-            return ToolResult(text=f"Error taking screenshot: {e}", images=[])
+            return f"Error taking screenshot: {e}"
 
     def get_tools(self) -> List[FunctionTool]:
         r"""Returns a list of FunctionTool objects for screenshot operations.
@@ -124,5 +208,6 @@ class ScreenshotToolkit(BaseToolkit):
             List[FunctionTool]: List of screenshot functions.
         """
         return [
-            FunctionTool(self.take_screenshot),
+            FunctionTool(self.take_screenshot_and_read_image),
+            FunctionTool(self.read_image),
         ]

camel/toolkits/search_toolkit.py

@@ -36,6 +36,7 @@ class SearchToolkit(BaseToolkit):
         self,
         timeout: Optional[float] = None,
         number_of_result_pages: int = 10,
+        exclude_domains: Optional[List[str]] = None,
     ):
         r"""Initializes the RedditToolkit with the specified number of retries
         and delay.
@@ -45,9 +46,14 @@ class SearchToolkit(BaseToolkit):
                 (default: :obj:`None`)
             number_of_result_pages (int): The number of result pages to
                 retrieve. (default: :obj:`10`)
+            exclude_domains (Optional[List[str]]): List of domains to
+                exclude from search results. Currently only supported
+                by the `search_google` function.
+                (default: :obj:`None`)
         """
         super().__init__(timeout=timeout)
         self.number_of_result_pages = number_of_result_pages
+        self.exclude_domains = exclude_domains
 
     @dependencies_required("wikipedia")
     def search_wiki(self, entity: str) -> str:
@@ -435,7 +441,9 @@ class SearchToolkit(BaseToolkit):
         ]
     )
     def search_google(
-        self, query: str, search_type: str = "web"
+        self,
+        query: str,
+        search_type: str = "web",
     ) -> List[Dict[str, Any]]:
         r"""Use Google search engine to search information for the given query.
 
@@ -499,11 +507,21 @@ class SearchToolkit(BaseToolkit):
         start_page_idx = 1
         # Different language may get different result
         search_language = "en"
+
+        modified_query = query
+        if self.exclude_domains:
+            # Use Google's -site: operator to exclude domains
+            exclusion_terms = " ".join(
+                [f"-site:{domain}" for domain in self.exclude_domains]
+            )
+            modified_query = f"{query} {exclusion_terms}"
+            logger.debug(f"Excluded domains, modified query: {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={query}&start="
+            f"key={GOOGLE_API_KEY}&cx={SEARCH_ENGINE_ID}&q={modified_query}&start="
             f"{start_page_idx}&lr={search_language}&num={self.number_of_result_pages}"
         )
 

camel/toolkits/terminal_toolkit.py

@@ -319,7 +319,14 @@ class TerminalToolkit(BaseToolkit):
                 )
 
             # Install essential packages using uv
-            essential_packages = ["pip", "setuptools", "wheel"]
+            essential_packages = [
+                "pip",
+                "setuptools",
+                "wheel",
+                "pyautogui",
+                "plotly",
+                "ffmpeg",
+            ]
             subprocess.run(
                 [
                     "uv",
@@ -371,7 +378,14 @@ class TerminalToolkit(BaseToolkit):
                 pip_path = os.path.join(self.initial_env_path, "bin", "pip")
 
             # Upgrade pip and install essential packages
-            essential_packages = ["pip", "setuptools", "wheel"]
+            essential_packages = [
+                "pip",
+                "setuptools",
+                "wheel",
+                "pyautogui",
+                "plotly",
+                "ffmpeg",
+            ]
             subprocess.run(
                 [pip_path, "install", "--upgrade", *essential_packages],
                 check=True,

camel/toolkits/video_analysis_toolkit.py

@@ -97,7 +97,7 @@ class VideoAnalysisToolkit(BaseToolkit):
     r"""A class for analysing videos with vision-language model.
 
     Args:
-        download_directory (Optional[str], optional): The directory where the
+        working_directory (Optional[str], optional): The directory where the
             video will be downloaded to. If not provided, video will be stored
             in a temporary directory and will be cleaned up after use.
             (default: :obj:`None`)
@@ -123,7 +123,7 @@ class VideoAnalysisToolkit(BaseToolkit):
     @dependencies_required("ffmpeg", "scenedetect")
     def __init__(
         self,
-        download_directory: Optional[str] = None,
+        working_directory: Optional[str] = None,
         model: Optional[BaseModelBackend] = None,
         use_audio_transcription: bool = False,
         use_ocr: bool = False,
@@ -133,30 +133,30 @@ class VideoAnalysisToolkit(BaseToolkit):
         timeout: Optional[float] = None,
     ) -> None:
         super().__init__(timeout=timeout)
-        self._cleanup = download_directory is None
+        self._cleanup = working_directory is None
         self._temp_files: list[str] = []  # Track temporary files for cleanup
         self._use_audio_transcription = use_audio_transcription
         self._use_ocr = use_ocr
         self.output_language = output_language
         self.frame_interval = frame_interval
 
-        self._download_directory = Path(
-            download_directory or tempfile.mkdtemp()
+        self._working_directory = Path(
+            working_directory or tempfile.mkdtemp()
         ).resolve()
 
         self.video_downloader_toolkit = VideoDownloaderToolkit(
-            download_directory=str(self._download_directory),
+            working_directory=str(self._working_directory),
             cookies_path=cookies_path,
         )
 
         try:
-            self._download_directory.mkdir(parents=True, exist_ok=True)
+            self._working_directory.mkdir(parents=True, exist_ok=True)
         except OSError as e:
             raise ValueError(
-                f"Error creating directory {self._download_directory}: {e}"
+                f"Error creating directory {self._working_directory}: {e}"
             )
 
-        logger.info(f"Video will be downloaded to {self._download_directory}")
+        logger.info(f"Video will be downloaded to {self._working_directory}")
 
         self.vl_model = model
         # Ensure ChatAgent is initialized with a model if provided
@@ -206,16 +206,16 @@ class VideoAnalysisToolkit(BaseToolkit):
                     )
 
         # Clean up temporary directory if needed
-        if self._cleanup and os.path.exists(self._download_directory):
+        if self._cleanup and os.path.exists(self._working_directory):
             try:
                 import sys
 
                 if getattr(sys, 'modules', None) is not None:
                     import shutil
 
-                    shutil.rmtree(self._download_directory)
+                    shutil.rmtree(self._working_directory)
                     logger.debug(
-                        f"Removed temp directory: {self._download_directory}"
+                        f"Removed temp directory: {self._working_directory}"
                     )
             except (ImportError, AttributeError):
                 # Skip cleanup if interpreter is shutting down
@@ -223,7 +223,7 @@ class VideoAnalysisToolkit(BaseToolkit):
             except OSError as e:
                 logger.warning(
                     f"Failed to remove temporary directory "
-                    f"{self._download_directory}: {e}"
+                    f"{self._working_directory}: {e}"
                 )
 
     @dependencies_required("pytesseract", "cv2", "numpy")

camel/toolkits/video_download_toolkit.py

@@ -62,7 +62,7 @@ class VideoDownloaderToolkit(BaseToolkit):
     chunks.
 
     Args:
-        download_directory (Optional[str], optional): The directory where the
+        working_directory (Optional[str], optional): The directory where the
             video will be downloaded to. If not provided, video will be stored
             in a temporary directory and will be cleaned up after use.
             (default: :obj:`None`)
@@ -73,30 +73,30 @@ class VideoDownloaderToolkit(BaseToolkit):
     @dependencies_required("yt_dlp", "ffmpeg")
     def __init__(
         self,
-        download_directory: Optional[str] = None,
+        working_directory: Optional[str] = None,
         cookies_path: Optional[str] = None,
         timeout: Optional[float] = None,
     ) -> None:
         super().__init__(timeout=timeout)
-        self._cleanup = download_directory is None
+        self._cleanup = working_directory is None
         self._cookies_path = cookies_path
 
-        self._download_directory = Path(
-            download_directory or tempfile.mkdtemp()
+        self._working_directory = Path(
+            working_directory or tempfile.mkdtemp()
         ).resolve()
 
         try:
-            self._download_directory.mkdir(parents=True, exist_ok=True)
+            self._working_directory.mkdir(parents=True, exist_ok=True)
         except FileExistsError:
             raise ValueError(
-                f"{self._download_directory} is not a valid directory."
+                f"{self._working_directory} is not a valid directory."
             )
         except OSError as e:
             raise ValueError(
-                f"Error creating directory {self._download_directory}: {e}"
+                f"Error creating directory {self._working_directory}: {e}"
             )
 
-        logger.info(f"Video will be downloaded to {self._download_directory}")
+        logger.info(f"Video will be downloaded to {self._working_directory}")
 
     def __del__(self) -> None:
         r"""Deconstructor for the VideoDownloaderToolkit class.
@@ -111,7 +111,7 @@ class VideoDownloaderToolkit(BaseToolkit):
                 if getattr(sys, 'modules', None) is not None:
                     import shutil
 
-                    shutil.rmtree(self._download_directory, ignore_errors=True)
+                    shutil.rmtree(self._working_directory, ignore_errors=True)
             except (ImportError, AttributeError):
                 # Skip cleanup if interpreter is shutting down
                 pass
@@ -130,7 +130,7 @@ class VideoDownloaderToolkit(BaseToolkit):
         """
         import yt_dlp
 
-        video_template = self._download_directory / "%(title)s.%(ext)s"
+        video_template = self._working_directory / "%(title)s.%(ext)s"
         ydl_opts = {
             'format': 'bestvideo+bestaudio/best',
             'outtmpl': str(video_template),