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

camel/toolkits/mineru_toolkit.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ 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
@@ -10,7 +10,7 @@
 # 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. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 
 from typing import Dict, List, Optional
 

camel/toolkits/minimax_mcp_toolkit.py

@@ -0,0 +1,195 @@
+# ========= Copyright 2023-2025 @ 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-2025 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import os
+from typing import Any, Dict, List, Optional
+
+from camel.toolkits import BaseToolkit, FunctionTool
+
+from .mcp_toolkit import MCPToolkit
+
+
+class MinimaxMCPToolkit(BaseToolkit):
+    r"""MinimaxMCPToolkit provides an interface for interacting with
+    MiniMax AI services using the MiniMax MCP server.
+
+    This toolkit enables access to MiniMax's multimedia generation
+    capabilities including text-to-audio, voice cloning, video generation,
+    image generation, music generation, and voice design.
+
+    This toolkit can be used as an async context manager for automatic
+    connection management:
+
+        # Using explicit API key
+        async with MinimaxMCPToolkit(api_key="your-key") as toolkit:
+            tools = toolkit.get_tools()
+            # Toolkit is automatically disconnected when exiting
+
+        # Using environment variables (recommended for security)
+        # Set MINIMAX_API_KEY=your-key in environment
+        async with MinimaxMCPToolkit() as toolkit:
+            tools = toolkit.get_tools()
+
+    Environment Variables:
+        MINIMAX_API_KEY: MiniMax API key for authentication
+        MINIMAX_API_HOST: API host URL (default: https://api.minimax.io)
+        MINIMAX_MCP_BASE_PATH: Base path for output files
+
+    Attributes:
+        timeout (Optional[float]): Connection timeout in seconds.
+            (default: :obj:`None`)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_host: str = "https://api.minimax.io",
+        base_path: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        r"""Initializes the MinimaxMCPToolkit.
+
+        Args:
+            api_key (Optional[str]): MiniMax API key for authentication.
+                If None, will attempt to read from MINIMAX_API_KEY
+                environment variable. (default: :obj:`None`)
+            api_host (str): MiniMax API host URL. Can be either
+                "https://api.minimax.io" (global) or
+                "https://api.minimaxi.com" (mainland China).
+                Can also be read from MINIMAX_API_HOST environment variable.
+                (default: :obj:`"https://api.minimax.io"`)
+            base_path (Optional[str]): Base path for output files.
+                If None, uses current working directory. Can also be read
+                from MINIMAX_MCP_BASE_PATH environment variable.
+                (default: :obj:`None`)
+            timeout (Optional[float]): Connection timeout in seconds.
+                (default: :obj:`None`)
+        """
+        super().__init__(timeout=timeout)
+
+        # Read API key from parameter or environment variable
+        if api_key is None:
+            api_key = os.getenv("MINIMAX_API_KEY")
+
+        if not api_key:
+            raise ValueError(
+                "api_key must be provided either as a parameter or through "
+                "the MINIMAX_API_KEY environment variable"
+            )
+
+        # Read API host from environment variable if not overridden
+        env_api_host = os.getenv("MINIMAX_API_HOST")
+        if env_api_host:
+            api_host = env_api_host
+
+        # Read base path from environment variable if not provided
+        if base_path is None:
+            base_path = os.getenv("MINIMAX_MCP_BASE_PATH")
+
+        # Set up environment variables for the MCP server
+        env = {
+            "MINIMAX_API_KEY": api_key,
+            "MINIMAX_API_HOST": api_host,
+        }
+
+        if base_path:
+            env["MINIMAX_MCP_BASE_PATH"] = base_path
+
+        self._mcp_toolkit = MCPToolkit(
+            config_dict={
+                "mcpServers": {
+                    "minimax": {
+                        "command": "uvx",
+                        "args": ["minimax-mcp", "-y"],
+                        "env": env,
+                    }
+                }
+            },
+            timeout=timeout,
+        )
+
+    async def connect(self):
+        r"""Explicitly connect to the MiniMax MCP server."""
+        await self._mcp_toolkit.connect()
+
+    async def disconnect(self):
+        r"""Explicitly disconnect from the MiniMax MCP server."""
+        await self._mcp_toolkit.disconnect()
+
+    @property
+    def is_connected(self) -> bool:
+        r"""Check if the toolkit is connected to the MCP server.
+
+        Returns:
+            bool: True if connected, False otherwise.
+        """
+        return self._mcp_toolkit.is_connected
+
+    async def __aenter__(self) -> "MinimaxMCPToolkit":
+        r"""Async context manager entry point.
+
+        Returns:
+            MinimaxMCPToolkit: The connected toolkit instance.
+
+        Example:
+            async with MinimaxMCPToolkit(api_key="your-key") 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 MiniMax MCP server.
+        """
+        await self.disconnect()
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Returns a list of tools provided by the MiniMax MCP server.
+
+        This includes tools for:
+        - Text-to-audio conversion
+        - Voice cloning
+        - Video generation
+        - Image generation
+        - Music generation
+        - Voice design
+
+        Returns:
+            List[FunctionTool]: List of available MiniMax AI tools.
+        """
+        return self._mcp_toolkit.get_tools()
+
+    def get_text_tools(self) -> str:
+        r"""Returns a string containing the descriptions of the tools.
+
+        Returns:
+            str: A string containing the descriptions of all MiniMax tools.
+        """
+        return self._mcp_toolkit.get_text_tools()
+
+    async def call_tool(
+        self, tool_name: str, tool_args: Dict[str, Any]
+    ) -> Any:
+        r"""Call a MiniMax tool by name.
+
+        Args:
+            tool_name (str): Name of the tool to call.
+            tool_args (Dict[str, Any]): Arguments to pass to the tool.
+
+        Returns:
+            Any: The result of the tool call.
+        """
+        return await self._mcp_toolkit.call_tool(tool_name, tool_args)

camel/toolkits/networkx_toolkit.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ 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
@@ -10,7 +10,7 @@
 # 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. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 
 import json
 from typing import Any, Callable, Dict, List, Literal, Optional, Tuple, Union

camel/toolkits/note_taking_toolkit.py

@@ -0,0 +1,277 @@
+# ========= Copyright 2023-2025 @ 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-2025 @ CAMEL-AI.org. All Rights Reserved. =========
+import os
+import time
+from pathlib import Path
+from typing import List, Optional
+
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+
+
+class NoteTakingToolkit(BaseToolkit):
+    r"""A toolkit for managing and interacting with markdown note files.
+
+    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__(
+        self,
+        working_directory: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        r"""Initialize the NoteTakingToolkit.
+
+        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]): The timeout for the toolkit.
+        """
+        super().__init__(timeout=timeout)
+        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.working_directory = path
+        self.working_directory.mkdir(parents=True, exist_ok=True)
+        self.registry_file = self.working_directory / ".note_register"
+        self._load_registry()
+
+    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:
+            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 confirming that the content was appended or the note
+                 was created.
+        """
+        try:
+            # 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"Content successfully appended to '{note_name}.md'."
+        except Exception as e:
+            return f"Error appending note: {e}"
+
+    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, overwrite: bool = False
+    ) -> str:
+        r"""Creates a new note with a unique name.
+
+        This function will create a new file for your note.
+        By default, 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. If you want to overwrite an existing note, set
+        `overwrite=True`.
+
+        Args:
+            note_name (str): The name for your new note (without the .md
+                extension). This name must be unique unless overwrite is True.
+            content (str): The initial content to write in the note.
+            overwrite (bool): Whether to overwrite an existing note.
+                Defaults to False.
+
+        Returns:
+            str: A message confirming the creation of the note or an error if
+                the note name is not valid or already exists
+                (when overwrite=False).
+        """
+        try:
+            note_path = self.working_directory / f"{note_name}.md"
+            existed_before = note_path.exists()
+
+            if existed_before and not overwrite:
+                return f"Error: Note '{note_name}.md' already exists."
+
+            note_path.write_text(content, encoding="utf-8")
+            self._register_note(note_name)
+
+            if existed_before and overwrite:
+                return f"Note '{note_name}.md' successfully overwritten."
+            else:
+                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: A string containing a list of available notes and their sizes,
+                or a message indicating that no notes have been created yet.
+        """
+        try:
+            # 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}"
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Return a list of FunctionTool objects representing the functions
+        in the toolkit.
+
+        Returns:
+            List[FunctionTool]: A list of FunctionTool objects.
+        """
+        return [
+            FunctionTool(self.append_note),
+            FunctionTool(self.read_note),
+            FunctionTool(self.create_note),
+            FunctionTool(self.list_note),
+        ]