camel-ai 0.2.71a12__py3-none-any.whl → 0.2.72__py3-none-any.whl

camel/toolkits/note_taking_toolkit.py

@@ -12,6 +12,7 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 import os
+import time
 from pathlib import Path
 from typing import List, Optional
 
@@ -20,10 +21,11 @@ from camel.toolkits.function_tool import FunctionTool
 
 
 class NoteTakingToolkit(BaseToolkit):
-    r"""A toolkit for taking notes in a Markdown file.
+    r"""A toolkit for managing and interacting with markdown note files.
 
-    This toolkit allows an agent to create, append to, and update a specific
-    Markdown file for note-taking purposes.
+    This toolkit provides tools for creating, reading, appending to, and
+    listing notes. All notes are stored as `.md` files in a dedicated working
+    directory and are tracked in a registry.
     """
 
     def __init__(
@@ -34,12 +36,11 @@ class NoteTakingToolkit(BaseToolkit):
         r"""Initialize the NoteTakingToolkit.
 
         Args:
-            working_directory (str, optional): The path to the note file.
-                If not provided, it will be determined by the
-                `CAMEL_WORKDIR` environment variable (if set), saving
-                the note as `notes.md` in that directory. If the
+            working_directory (str, optional): The directory path where notes
+                will be stored. If not provided, it will be determined by the
+                `CAMEL_WORKDIR` environment variable (if set). If the
                 environment variable is not set, it defaults to
-                `camel_working_dir/notes.md`.
+                `camel_working_dir`.
             timeout (Optional[float]): The timeout for the toolkit.
         """
         super().__init__(timeout=timeout)
@@ -47,42 +48,208 @@ class NoteTakingToolkit(BaseToolkit):
         if working_directory:
             path = Path(working_directory)
         elif camel_workdir:
-            path = Path(camel_workdir) / "notes.md"
+            path = Path(camel_workdir)
         else:
-            path = Path("camel_working_dir") / "notes.md"
+            path = Path("camel_working_dir")
 
         self.working_directory = path
-        self.working_directory.parent.mkdir(parents=True, exist_ok=True)
+        self.working_directory.mkdir(parents=True, exist_ok=True)
+        self.registry_file = self.working_directory / ".note_register"
+        self._load_registry()
 
-    def append_note(self, content: str) -> str:
-        r"""Appends a note to the note file.
+    def append_note(self, note_name: str, content: str) -> str:
+        r"""Appends content to a note.
+
+        If the note does not exist, it will be created with the given content.
+        If the note already exists, the new content will be added to the end of
+        the note.
 
         Args:
-            content (str): The content of the note to be appended.
+            note_name (str): The name of the note (without the .md extension).
+            content (str): The content to append to the note.
 
         Returns:
-            str: A message indicating the result of the operation.
+            str: A message confirming that the content was appended or the note
+                 was created.
         """
         try:
-            with self.working_directory.open("a", encoding="utf-8") as f:
+            # Reload registry to get latest state
+            self._load_registry()
+            note_path = self.working_directory / f"{note_name}.md"
+            if note_name not in self.registry or not note_path.exists():
+                self.create_note(note_name, content)
+                return f"Note '{note_name}' created with content added."
+
+            with note_path.open("a", encoding="utf-8") as f:
                 f.write(content + "\n")
-            return (
-                f"Note successfully appended to in {self.working_directory}."
-            )
+            return f"Content successfully appended to '{note_name}.md'."
         except Exception as e:
             return f"Error appending note: {e}"
 
-    def read_note(self) -> str:
-        r"""Reads the content of the note file.
+    def _load_registry(self) -> None:
+        r"""Load the note registry from file."""
+        max_retries = 5
+        retry_delay = 0.1
+
+        for attempt in range(max_retries):
+            try:
+                if self.registry_file.exists():
+                    content = self.registry_file.read_text(
+                        encoding='utf-8'
+                    ).strip()
+                    self.registry = content.split('\n') if content else []
+                else:
+                    self.registry = []
+                return
+            except (IOError, OSError):
+                if attempt < max_retries - 1:
+                    time.sleep(retry_delay * (attempt + 1))
+                else:
+                    # If all retries failed, initialize with empty registry
+                    self.registry = []
+
+    def _save_registry(self) -> None:
+        r"""Save the note registry to file using atomic write."""
+        max_retries = 5
+        retry_delay = 0.1
+
+        for attempt in range(max_retries):
+            try:
+                # Use atomic write with temporary file for all platforms
+                temp_file = self.registry_file.with_suffix('.tmp')
+                temp_file.write_text(
+                    '\n'.join(self.registry), encoding='utf-8'
+                )
+
+                # Atomic rename - works on all platforms
+                temp_file.replace(self.registry_file)
+                return
+            except (IOError, OSError):
+                if attempt < max_retries - 1:
+                    time.sleep(retry_delay * (attempt + 1))
+                else:
+                    raise
+
+    def _register_note(self, note_name: str) -> None:
+        r"""Register a new note in the registry with thread-safe operations."""
+        # Reload registry to get latest state
+        self._load_registry()
+        if note_name not in self.registry:
+            self.registry.append(note_name)
+            self._save_registry()
+
+    def create_note(self, note_name: str, content: str = "") -> str:
+        r"""Creates a new note with a unique name.
+
+        This function will create a new file for your note.
+        You must provide a `note_name` that does not already exist. If you want
+        to add content to an existing note, use the `append_note` function
+        instead.
+
+        Args:
+            note_name (str): The name for your new note (without the .md
+                extension). This name must be unique.
+            content (str, optional): The initial content to write in the note.
+                If not provided, an empty note will be created. Defaults to "".
+
+        Returns:
+            str: A message confirming the creation of the note or an error if
+                 the note name is not valid or already exists.
+        """
+        try:
+            note_path = self.working_directory / f"{note_name}.md"
+
+            if note_path.exists():
+                return f"Error: Note '{note_name}.md' already exists."
+
+            note_path.write_text(content, encoding="utf-8")
+            self._register_note(note_name)
+
+            return f"Note '{note_name}.md' successfully created."
+        except Exception as e:
+            return f"Error creating note: {e}"
+
+    def list_note(self) -> str:
+        r"""Lists all the notes you have created.
+
+        This function will show you a list of all your notes, along with their
+        sizes in bytes. This is useful for seeing what notes you have available
+        to read or append to.
 
         Returns:
-            str: The content of the note file, or an error message if the
-                 file cannot be read.
+            str: A string containing a list of available notes and their sizes,
+                or a message indicating that no notes have been created yet.
         """
         try:
-            if not self.working_directory.exists():
-                return "Note file does not exist yet."
-            return self.working_directory.read_text(encoding="utf-8")
+            # Reload registry to get latest state
+            self._load_registry()
+            if not self.registry:
+                return "No notes have been created yet."
+
+            notes_info = []
+            for note_name in self.registry:
+                note_path = self.working_directory / f"{note_name}.md"
+                if note_path.exists():
+                    size = note_path.stat().st_size
+                    notes_info.append(f"- {note_name}.md ({size} bytes)")
+                else:
+                    notes_info.append(f"- {note_name}.md (file missing)")
+
+            return "Available notes:\n" + "\n".join(notes_info)
+        except Exception as e:
+            return f"Error listing notes: {e}"
+
+    def read_note(self, note_name: Optional[str] = "all_notes") -> str:
+        r"""Reads the content of a specific note or all notes.
+
+        You can use this function in two ways:
+        1.  **Read a specific note:** Provide the `note_name` (without the .md
+            extension) to get the content of that single note.
+        2.  **Read all notes:** Use `note_name="all_notes"` (default), and this
+            function will return the content of all your notes, concatenated
+            together.
+
+        Args:
+            note_name (str, optional): The name of the note you want to read.
+                Defaults to "all_notes" which reads all notes.
+
+        Returns:
+            str: The content of the specified note(s), or an error message if
+                a note cannot be read.
+        """
+        try:
+            # Reload registry to get latest state
+            self._load_registry()
+            if note_name and note_name != "all_notes":
+                if note_name not in self.registry:
+                    return (
+                        f"Error: Note '{note_name}' is not registered "
+                        f"or was not created by this toolkit."
+                    )
+                note_path = self.working_directory / f"{note_name}.md"
+                if not note_path.exists():
+                    return f"Note file '{note_path.name}' does not exist."
+                return note_path.read_text(encoding="utf-8")
+            else:
+                if not self.registry:
+                    return "No notes have been created yet."
+
+                all_notes = []
+                for registered_note in self.registry:
+                    note_path = (
+                        self.working_directory / f"{registered_note}.md"
+                    )
+                    if note_path.exists():
+                        content = note_path.read_text(encoding="utf-8")
+                        all_notes.append(
+                            f"=== {registered_note}.md ===\n{content}"
+                        )
+                    else:
+                        all_notes.append(
+                            f"=== {registered_note}.md ===\n[File not found]"
+                        )
+
+                return "\n\n".join(all_notes)
         except Exception as e:
             return f"Error reading note: {e}"
 
@@ -96,4 +263,6 @@ class NoteTakingToolkit(BaseToolkit):
         return [
             FunctionTool(self.append_note),
             FunctionTool(self.read_note),
+            FunctionTool(self.create_note),
+            FunctionTool(self.list_note),
         ]

camel/toolkits/openai_image_toolkit.py

@@ -69,7 +69,7 @@ class OpenAIImageToolkit(BaseToolkit):
             Literal["transparent", "opaque", "auto"]
         ] = "auto",
         style: Optional[Literal["vivid", "natural"]] = None,
-        image_save_path: Optional[str] = "image_save",
+        working_directory: Optional[str] = "image_save",
     ):
         r"""Initializes a new instance of the OpenAIImageToolkit class.
 
@@ -100,7 +100,7 @@ class OpenAIImageToolkit(BaseToolkit):
                 The background of the image.(default: :obj:`"auto"`)
             style (Optional[Literal["vivid", "natural"]]): The style of the
                 image.(default: :obj:`None`)
-            image_save_path (Optional[str]): The path to save the generated
+            working_directory (Optional[str]): The path to save the generated
                 image.(default: :obj:`"image_save"`)
         """
         super().__init__(timeout=timeout)
@@ -114,7 +114,7 @@ class OpenAIImageToolkit(BaseToolkit):
         self.n = n
         self.background = background
         self.style = style
-        self.image_save_path: str = image_save_path or "image_save"
+        self.working_directory: str = working_directory or "image_save"
 
     def base64_to_image(self, base64_string: str) -> Optional[Image.Image]:
         r"""Converts a base64 encoded string into a PIL Image object.
@@ -213,7 +213,7 @@ class OpenAIImageToolkit(BaseToolkit):
 
                 # Save the image from base64
                 image_bytes = base64.b64decode(image_b64)
-                os.makedirs(self.image_save_path, exist_ok=True)
+                os.makedirs(self.working_directory, exist_ok=True)
 
                 # Add index to filename when multiple images
                 if len(response.data) > 1:
@@ -221,7 +221,7 @@ class OpenAIImageToolkit(BaseToolkit):
                 else:
                     filename = f"{image_name}_{uuid.uuid4().hex}.png"
 
-                image_path = os.path.join(self.image_save_path, filename)
+                image_path = os.path.join(self.working_directory, filename)
 
                 with open(image_path, "wb") as f:
                     f.write(image_bytes)

camel/toolkits/origene_mcp_toolkit.py

@@ -0,0 +1,97 @@
+# ========= 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 Dict, List, Optional
+
+from camel.toolkits import BaseToolkit, FunctionTool, MCPToolkit
+
+
+class OrigeneToolkit(BaseToolkit):
+    r"""OrigeneToolkit provides an interface for interacting with
+    Origene MCP server.
+
+    This toolkit can be used as an async context manager for automatic
+    connection management:
+
+        async with OrigeneToolkit(config_dict=config) as toolkit:
+            tools = toolkit.get_tools()
+            # Toolkit is automatically disconnected when exiting
+
+    Attributes:
+        config_dict (Dict): Configuration dictionary for MCP servers.
+        timeout (Optional[float]): Connection timeout in seconds.
+            (default: :obj:`None`)
+    """
+
+    def __init__(
+        self,
+        config_dict: Optional[Dict] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        r"""Initializes the OrigeneToolkit.
+
+        Args:
+            config_dict (Optional[Dict]): Configuration dictionary for MCP
+                servers. If None, uses default configuration for chembl_mcp.
+                (default: :obj:`None`)
+            timeout (Optional[float]): Connection timeout in seconds.
+                (default: :obj:`None`)
+        """
+        super().__init__(timeout=timeout)
+
+        # Use default configuration if none provided
+        if config_dict is None:
+            raise ValueError("config_dict must be provided")
+
+        self._mcp_toolkit = MCPToolkit(
+            config_dict=config_dict,
+            timeout=timeout,
+        )
+
+    async def connect(self):
+        r"""Explicitly connect to the Origene MCP server."""
+        await self._mcp_toolkit.connect()
+
+    async def disconnect(self):
+        r"""Explicitly disconnect from the Origene MCP server."""
+        await self._mcp_toolkit.disconnect()
+
+    async def __aenter__(self) -> "OrigeneToolkit":
+        r"""Async context manager entry point.
+
+        Returns:
+            OrigeneToolkit: The connected toolkit instance.
+
+        Example:
+            async with OrigeneToolkit(config_dict=config) as toolkit:
+                tools = toolkit.get_tools()
+        """
+        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 Origene MCP server.
+        """
+        await self.disconnect()
+        return None
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Returns a list of tools provided by the Origene MCP server.
+
+        Returns:
+            List[FunctionTool]: List of available tools.
+        """
+        return self._mcp_toolkit.get_tools()

camel/toolkits/screenshot_toolkit.py

@@ -0,0 +1,213 @@
+# ========= 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 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
+
+logger = get_logger(__name__)
+
+
+class ScreenshotToolkit(BaseToolkit, RegisteredAgentToolkit):
+    r"""A toolkit for taking screenshots."""
+
+    @dependencies_required('PIL')
+    def __init__(
+        self,
+        working_directory: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ):
+        r"""Initializes the ScreenshotToolkit.
+
+        Args:
+            working_directory (str, optional): The directory path where notes
+                will be stored. If not provided, it will be determined by the
+                `CAMEL_WORKDIR` environment variable (if set). If the
+                environment variable is not set, it defaults to
+                `camel_working_dir`.
+            timeout (Optional[float]): Timeout for API requests in seconds.
+                (default: :obj:`None`)
+        """
+        from PIL import ImageGrab
+
+        super().__init__(timeout=timeout)
+        RegisteredAgentToolkit.__init__(self)
+
+        camel_workdir = os.environ.get("CAMEL_WORKDIR")
+        if working_directory:
+            path = Path(working_directory)
+        elif camel_workdir:
+            path = Path(camel_workdir)
+        else:
+            path = Path("camel_working_dir")
+
+        self.ImageGrab = ImageGrab
+        self.screenshots_dir = path
+        self.screenshots_dir.mkdir(parents=True, exist_ok=True)
+
+    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,
+        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:
+            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:
+            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
+            screenshot = self.ImageGrab.grab()
+
+            # Save to file if requested
+            file_path = None
+            if save_to_file:
+                # Create directory if it doesn't exist
+                os.makedirs(self.screenshots_dir, exist_ok=True)
+
+                # 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}")
+
+            # Create result text
+            result_text = "Screenshot captured successfully"
+            if file_path:
+                result_text += f" and saved to {file_path}"
+
+            # 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 f"Error taking screenshot: {e}"
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Returns a list of FunctionTool objects for screenshot operations.
+
+        Returns:
+            List[FunctionTool]: List of screenshot functions.
+        """
+        return [
+            FunctionTool(self.take_screenshot_and_read_image),
+            FunctionTool(self.read_image),
+        ]