camel-ai 0.2.73a4__py3-none-any.whl → 0.2.80a2__py3-none-any.whl

camel/toolkits/edgeone_pages_mcp_toolkit.py

@@ -12,14 +12,12 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 
-from typing import List, Optional
-
-from camel.toolkits import BaseToolkit, FunctionTool
+from typing import Optional
 
 from .mcp_toolkit import MCPToolkit
 
 
-class EdgeOnePagesMCPToolkit(BaseToolkit):
+class EdgeOnePagesMCPToolkit(MCPToolkit):
     r"""EdgeOnePagesMCPToolkit provides an interface for interacting with
     EdgeOne pages using the EdgeOne Pages MCP server.
 
@@ -38,32 +36,14 @@ class EdgeOnePagesMCPToolkit(BaseToolkit):
             timeout (Optional[float]): Connection timeout in seconds.
                 (default: :obj:`None`)
         """
-        super().__init__(timeout=timeout)
-
-        self._mcp_toolkit = MCPToolkit(
-            config_dict={
-                "mcpServers": {
-                    "edgeone-pages-mcp-server": {
-                        "command": "npx",
-                        "args": ["edgeone-pages-mcp"],
-                    }
+        config_dict = {
+            "mcpServers": {
+                "edgeone-pages-mcp-server": {
+                    "command": "npx",
+                    "args": ["edgeone-pages-mcp"],
                 }
-            },
-            timeout=timeout,
-        )
-
-    async def connect(self):
-        r"""Explicitly connect to the EdgeOne Pages MCP server."""
-        await self._mcp_toolkit.connect()
+            }
+        }
 
-    async def disconnect(self):
-        r"""Explicitly disconnect from the EdgeOne Pages MCP server."""
-        await self._mcp_toolkit.disconnect()
-
-    def get_tools(self) -> List[FunctionTool]:
-        r"""Returns a list of tools provided by the EdgeOnePagesMCPToolkit.
-
-        Returns:
-            List[FunctionTool]: List of available tools.
-        """
-        return self._mcp_toolkit.get_tools()
+        # Initialize parent MCPToolkit with EdgeOne Pages configuration
+        super().__init__(config_dict=config_dict, timeout=timeout)

camel/toolkits/excel_toolkit.py

@@ -872,7 +872,7 @@ class ExcelToolkit(BaseToolkit):
             import csv
 
             with open(
-                resolved_csv_path, 'w', newline='', encoding='utf-8'
+                resolved_csv_path, 'w', newline='', encoding='utf-8-sig'
             ) as csvfile:
                 writer = csv.writer(csvfile)
                 writer.writerows(data)

camel/toolkits/{file_write_toolkit.py → file_toolkit.py}

@@ -15,7 +15,7 @@ import os
 import re
 from datetime import datetime
 from pathlib import Path
-from typing import List, Optional, Tuple, Union
+from typing import Dict, List, Optional, Tuple, Union
 
 from camel.logger import get_logger
 from camel.toolkits.base import BaseToolkit
@@ -26,14 +26,17 @@ logger = get_logger(__name__)
 
 
 @MCPServer()
-class FileWriteToolkit(BaseToolkit):
-    r"""A toolkit for creating, writing, and modifying text in files.
-
-    This class provides cross-platform (macOS, Linux, Windows) support for
-    writing to various file formats (Markdown, DOCX, PDF, and plaintext),
-    replacing text in existing files, automatic filename uniquification to
-    prevent overwrites, custom encoding and enhanced formatting options for
-    specialized formats.
+class FileToolkit(BaseToolkit):
+    r"""A comprehensive toolkit for file operations including reading,
+    writing, and editing files.
+
+    This class provides cross-platform (macOS, Linux, Windows) support for:
+    - Reading various file formats (text, JSON, YAML, PDF, DOCX)
+    - Writing to multiple formats (Markdown, DOCX, PDF, plaintext, JSON,
+      YAML, CSV, HTML)
+    - Editing and modifying existing files with content replacement
+    - Automatic backup creation before modifications
+    - Custom encoding and enhanced formatting options
     """
 
     def __init__(
@@ -126,36 +129,32 @@ class FileWriteToolkit(BaseToolkit):
         with file_path.open("w", encoding=encoding) as f:
             f.write(content)
 
-    def _generate_unique_filename(self, file_path: Path) -> Path:
-        r"""Generate a unique filename if the target file already exists.
+    def _create_backup(self, file_path: Path) -> Optional[Path]:
+        r"""Create a backup of the file if it exists and backup is enabled.
 
         Args:
-            file_path (Path): The original file path.
+            file_path (Path): The file path to backup.
 
         Returns:
-            Path: A unique file path that doesn't exist yet.
+            Optional[Path]: Path to the backup file if created, None otherwise.
         """
-        if not file_path.exists():
-            return file_path
+        if not self.backup_enabled or not file_path.exists():
+            return None
 
-        # Generate unique filename with timestamp and counter
+        # Generate backup filename with .bak extension and timestamp
         timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-        stem = file_path.stem
-        suffix = file_path.suffix
-        parent = file_path.parent
-
-        # First try with timestamp
-        new_path = parent / f"{stem}_{timestamp}{suffix}"
-        if not new_path.exists():
-            return new_path
-
-        # If timestamp version exists, add counter
-        counter = 1
-        while True:
-            new_path = parent / f"{stem}_{timestamp}_{counter}{suffix}"
-            if not new_path.exists():
-                return new_path
-            counter += 1
+        backup_path = file_path.parent / f"{file_path.name}.{timestamp}.bak"
+
+        # Copy the file to backup location
+        import shutil
+
+        try:
+            shutil.copy2(file_path, backup_path)
+            logger.info(f"Created backup: {backup_path}")
+            return backup_path
+        except Exception as e:
+            logger.warning(f"Failed to create backup: {e}")
+            return None
 
     def _write_docx_file(self, file_path: Path, content: str) -> None:
         r"""Write text content to a DOCX file with default formatting.
@@ -840,11 +839,74 @@ class FileWriteToolkit(BaseToolkit):
 
         return text
 
+    def _ensure_html_utf8_meta(self, content: str) -> str:
+        r"""Ensure HTML content has UTF-8 meta tag.
+
+        Args:
+            content (str): The HTML content.
+
+        Returns:
+            str: HTML content with UTF-8 meta tag.
+        """
+        # Check if content already has a charset meta tag
+        has_charset = re.search(
+            r'<meta[^>]*charset[^>]*>', content, re.IGNORECASE
+        )
+
+        # UTF-8 meta tag
+        utf8_meta = '<meta charset="utf-8">'
+
+        if has_charset:
+            # Replace existing charset with UTF-8
+            content = re.sub(
+                r'<meta[^>]*charset[^>]*>',
+                utf8_meta,
+                content,
+                flags=re.IGNORECASE,
+            )
+        else:
+            # Add UTF-8 meta tag
+            # Try to find <head> tag
+            head_match = re.search(r'<head[^>]*>', content, re.IGNORECASE)
+            if head_match:
+                # Insert after <head> tag
+                insert_pos = head_match.end()
+                content = (
+                    content[:insert_pos]
+                    + '\n    '
+                    + utf8_meta
+                    + content[insert_pos:]
+                )
+            else:
+                # No <head> tag found, check if there's <html> tag
+                html_match = re.search(r'<html[^>]*>', content, re.IGNORECASE)
+                if html_match:
+                    # Insert <head> with meta tag after <html>
+                    insert_pos = html_match.end()
+                    content = (
+                        content[:insert_pos]
+                        + '\n<head>\n    '
+                        + utf8_meta
+                        + '\n</head>'
+                        + content[insert_pos:]
+                    )
+                else:
+                    # No proper HTML structure, wrap content
+                    content = (
+                        '<!DOCTYPE html>\n<html>\n<head>\n    '
+                        + utf8_meta
+                        + '\n</head>\n<body>\n'
+                        + content
+                        + '\n</body>\n</html>'
+                    )
+
+        return content
+
     def _write_csv_file(
         self,
         file_path: Path,
         content: Union[str, List[List]],
-        encoding: str = "utf-8",
+        encoding: str = "utf-8-sig",
     ) -> None:
         r"""Write CSV content to a file.
 
@@ -852,7 +914,8 @@ class FileWriteToolkit(BaseToolkit):
             file_path (Path): The target file path.
             content (Union[str, List[List]]): The CSV content as a string or
                 list of lists.
-            encoding (str): Character encoding to use. (default: :obj:`utf-8`)
+            encoding (str): Character encoding to use.
+                (default: :obj:`utf-8-sig`)
         """
         import csv
 
@@ -901,6 +964,10 @@ class FileWriteToolkit(BaseToolkit):
             content (str): The content to write.
             encoding (str): Character encoding to use. (default: :obj:`utf-8`)
         """
+        # For HTML files, ensure UTF-8 meta tag is present
+        if file_path.suffix.lower() in ['.html', '.htm']:
+            content = self._ensure_html_utf8_meta(content)
+
         with file_path.open("w", encoding=encoding) as f:
             f.write(content)
 
@@ -939,8 +1006,9 @@ class FileWriteToolkit(BaseToolkit):
         file_path = self._resolve_filepath(filename)
         file_path.parent.mkdir(parents=True, exist_ok=True)
 
-        # Generate unique filename if file exists
-        file_path = self._generate_unique_filename(file_path)
+        # Create backup of existing file if backup is enabled
+        if file_path.exists() and self.backup_enabled:
+            self._create_backup(file_path)
 
         extension = file_path.suffix.lower()
 
@@ -995,6 +1063,309 @@ class FileWriteToolkit(BaseToolkit):
             logger.error(error_msg)
             return error_msg
 
+    # ----------------------------------------------
+    # Read File Functions
+    # ----------------------------------------------
+    def read_file(
+        self, file_paths: Union[str, List[str]]
+    ) -> Union[str, Dict[str, str]]:
+        r"""Read and return content of one or more files using MarkItDown
+        for better format support.
+
+        This method uses MarkItDownLoader to convert various file formats
+        to Markdown. It supports a wide range of formats including:
+        - PDF (.pdf)
+        - Microsoft Office: Word (.doc, .docx), Excel (.xls, .xlsx),
+          PowerPoint (.ppt, .pptx)
+        - EPUB (.epub)
+        - HTML (.html, .htm)
+        - Images (.jpg, .jpeg, .png) for OCR
+        - Audio (.mp3, .wav) for transcription
+        - Text-based formats (.csv, .json, .xml, .txt, .md)
+        - ZIP archives (.zip)
+
+        Args:
+            file_paths (Union[str, List[str]]): A single file path or a list
+                of file paths to read. Paths can be relative or absolute.
+                If relative, they will be resolved relative to the working
+                directory.
+
+        Returns:
+            Union[str, Dict[str, str]]:
+                - If a single file path is provided: Returns the content as
+                  a string.
+                - If multiple file paths are provided: Returns a dictionary
+                  where keys are file paths and values are the corresponding
+                  content in Markdown format.
+                If conversion fails, returns an error message.
+        """
+        from camel.loaders.markitdown import MarkItDownLoader
+
+        try:
+            # Handle single file path for backward compatibility
+            if isinstance(file_paths, str):
+                resolved_path = self._resolve_filepath(file_paths)
+
+                # Use MarkItDownLoader to convert the file
+                result = MarkItDownLoader().convert_files(
+                    file_paths=[str(resolved_path)], parallel=False
+                )
+
+                # Return the converted content or error message
+                return result.get(
+                    str(resolved_path), f"Failed to read file: {resolved_path}"
+                )
+
+            # Handle multiple file paths
+            else:
+                resolved_paths = [
+                    str(self._resolve_filepath(fp)) for fp in file_paths
+                ]
+
+                # Use MarkItDownLoader to convert files in parallel
+                result = MarkItDownLoader().convert_files(
+                    file_paths=resolved_paths, parallel=True
+                )
+
+                # Map back to original paths if needed
+                return_dict = {}
+                for original, resolved in zip(file_paths, resolved_paths):
+                    return_dict[original] = result.get(
+                        resolved, f"Failed to read file: {resolved}"
+                    )
+
+                return return_dict
+
+        except Exception as e:
+            return f"Error reading file(s): {e}"
+
+    # ----------------------------------------------
+    # Edit File Functions
+    # ----------------------------------------------
+    def edit_file(
+        self, file_path: str, old_content: str, new_content: str
+    ) -> str:
+        r"""Edit a file by replacing specified content.
+
+        This method performs simple text replacement in files. It reads
+        the file, replaces all occurrences of old_content with new_content,
+        and writes the result back.
+
+        Args:
+            file_path (str): The path to the file to edit. Can be
+                relative or absolute. If relative, it will be resolved
+                relative to the working directory.
+            old_content (str): The exact text to find and replace.
+            new_content (str): The text to replace old_content with.
+
+        Returns:
+            str: A success message if the edit was successful, or an
+                error message if the content wasn't found or an error occurred.
+        """
+        try:
+            working_path = self._resolve_filepath(file_path)
+
+            if not working_path.exists():
+                return f"Error: File {working_path} does not exist"
+
+            # Create backup before editing if enabled
+            self._create_backup(working_path)
+
+            # Read the file content
+            try:
+                file_text = working_path.read_text(
+                    encoding=self.default_encoding
+                )
+            except Exception as e:
+                return f"Error reading file: {e}"
+
+            # Check if the old_content exists in the file
+            if old_content not in file_text:
+                return (
+                    f"No replacement performed: '{old_content}' not found in "
+                    f"{working_path}."
+                )
+
+            # Replace the content
+            new_file_text = file_text.replace(old_content, new_content)
+
+            # Write back to file
+            try:
+                working_path.write_text(
+                    new_file_text, encoding=self.default_encoding
+                )
+                return f"Successfully edited {working_path}"
+            except Exception as e:
+                return f"Error writing file: {e}"
+
+        except Exception as e:
+            return f"Error editing file: {e}"
+
+    def search_files(
+        self,
+        pattern: str,
+        file_types: Optional[List[str]] = None,
+        file_pattern: Optional[str] = None,
+        path: Optional[str] = None,
+    ) -> str:
+        r"""Search for a text pattern in files with specified extensions or
+        file patterns.
+
+        This method searches for a text pattern (case-insensitive substring
+        match) in files matching either the specified file types or a file
+        pattern. It returns structured results showing which files contain
+        the pattern, along with line numbers and matching content.
+
+        Args:
+            pattern (str): The text pattern to search for (case-insensitive
+                string match).
+            file_types (Optional[List[str]]): List of file extensions to
+                search (e.g., ["md", "txt", "py"]). Do not include the dot.
+                If not provided and file_pattern is also not provided,
+                defaults to ["md"] (markdown files). Ignored if file_pattern
+                is provided. (default: :obj:`None`)
+            file_pattern (Optional[str]): Glob pattern for matching files
+                (e.g., "*_workflow.md", "test_*.py"). If provided, this
+                overrides file_types. (default: :obj:`None`)
+            path (Optional[str]): Directory to search in. If not provided,
+                uses the working_directory. Can be relative or absolute.
+                (default: :obj:`None`)
+
+        Returns:
+            str: JSON-formatted string containing search results with the
+                structure:
+                {
+                    "pattern": "search_pattern",
+                    "searched_path": "/absolute/path",
+                    "file_types": ["md", "txt"],
+                    "file_pattern": "*_workflow.md",
+                    "matches": [
+                        {
+                            "file": "relative/path/to/file.md",
+                            "line": 42,
+                            "content": "matching line content"
+                        },
+                        ...
+                    ],
+                    "total_matches": 10,
+                    "files_searched": 5
+                }
+                If an error occurs, returns a JSON string with an "error" key.
+        """
+        import json
+
+        try:
+            # resolve search path
+            if path:
+                path_obj = Path(path)
+                if not path_obj.is_absolute():
+                    search_path = (self.working_directory / path_obj).resolve()
+                else:
+                    search_path = path_obj.resolve()
+            else:
+                search_path = self.working_directory
+
+            # validate that search path exists
+            if not search_path.exists():
+                return json.dumps(
+                    {"error": f"Search path does not exist: {search_path}"}
+                )
+
+            if not search_path.is_dir():
+                return json.dumps(
+                    {"error": f"Search path is not a directory: {search_path}"}
+                )
+
+            # collect all matching files
+            matching_files: List[Path] = []
+
+            if file_pattern:
+                # use file_pattern if provided (overrides file_types)
+                pattern_glob = f"**/{file_pattern}"
+                matching_files.extend(search_path.rglob(pattern_glob))
+            else:
+                # use file_types if file_pattern not provided
+                if file_types is None:
+                    file_types = ["md"]
+
+                # normalize and deduplicate file types
+                normalized_types = set()
+                for file_type in file_types:
+                    file_type = file_type.lstrip('.')
+                    if file_type:  # skip empty strings
+                        normalized_types.add(file_type)
+
+                for file_type in normalized_types:
+                    # use rglob for recursive search
+                    pattern_glob = f"**/*.{file_type}"
+                    matching_files.extend(search_path.rglob(pattern_glob))
+
+            # search through files (case-insensitive)
+            matches = []
+            files_searched = 0
+            pattern_lower = pattern.lower()
+
+            for file_path in matching_files:
+                files_searched += 1
+                try:
+                    # read file content
+                    content = file_path.read_text(
+                        encoding=self.default_encoding
+                    )
+                    lines = content.splitlines()
+
+                    # search each line for pattern (case-insensitive)
+                    for line_num, line in enumerate(lines, start=1):
+                        if pattern_lower in line.lower():
+                            # get relative path for cleaner output
+                            try:
+                                relative_path = file_path.relative_to(
+                                    search_path
+                                )
+                            except ValueError:
+                                relative_path = file_path
+
+                            matches.append(
+                                {
+                                    "file": str(relative_path),
+                                    "line": line_num,
+                                    "content": line.strip(),
+                                }
+                            )
+
+                except (UnicodeDecodeError, PermissionError) as e:
+                    # skip files that can't be read
+                    logger.debug(f"Skipping file {file_path}: {e}")
+                    continue
+
+            # build result
+            result = {
+                "pattern": pattern,
+                "searched_path": str(search_path),
+                "matches": matches,
+                "total_matches": len(matches),
+                "files_searched": files_searched,
+            }
+
+            # include file_pattern or file_types in result
+            if file_pattern:
+                result["file_pattern"] = file_pattern
+            else:
+                result["file_types"] = (
+                    sorted(normalized_types) if normalized_types else ["md"]
+                )
+
+            logger.info(
+                f"Search completed: found {len(matches)} matches "
+                f"in {files_searched} files"
+            )
+            return json.dumps(result, indent=2)
+
+        except Exception as e:
+            error_msg = f"Error during file search: {e}"
+            logger.error(error_msg)
+            return json.dumps({"error": error_msg})
+
     def get_tools(self) -> List[FunctionTool]:
         r"""Return a list of FunctionTool objects representing the functions
         in the toolkit.
@@ -1005,4 +1376,27 @@ class FileWriteToolkit(BaseToolkit):
         """
         return [
             FunctionTool(self.write_to_file),
+            FunctionTool(self.read_file),
+            FunctionTool(self.edit_file),
+            FunctionTool(self.search_files),
         ]
+
+
+# Backward compatibility: FileWriteToolkit as deprecated alias
+class FileWriteToolkit(FileToolkit):
+    r"""Deprecated: Use FileToolkit instead.
+
+    This class is maintained for backward compatibility only.
+    Please use FileToolkit for new code.
+    """
+
+    def __init__(self, *args, **kwargs):
+        import warnings
+
+        warnings.warn(
+            "FileWriteToolkit is deprecated and will be removed in a "
+            "future version. Please use FileToolkit instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args, **kwargs)

camel/toolkits/function_tool.py

@@ -156,7 +156,12 @@ def get_openai_tool_schema(func: Callable) -> Dict[str, Any]:
         if (name := param.arg_name) in parameters_dict["properties"] and (
             description := param.description
         ):
-            parameters_dict["properties"][name]["description"] = description
+            # OpenAI does not allow descriptions on properties that use $ref.
+            # To avoid schema errors, we only add the description if "$ref" is
+            # not present.
+            prop = parameters_dict["properties"][name]
+            if "$ref" not in prop:
+                prop["description"] = description
 
     short_description = docstring.short_description or ""
     long_description = docstring.long_description or ""
@@ -477,10 +482,15 @@ class FunctionTool:
                 result = self.func(*args, **kwargs)
                 return result
             except Exception as e:
+                parts = []
+                if args:
+                    parts.append(f"args={args}")
+                if kwargs:
+                    parts.append(f"kwargs={kwargs}")
+                args_str = ", ".join(parts) if parts else "no arguments"
                 raise ValueError(
                     f"Execution of function {self.func.__name__} failed with "
-                    f"arguments {args} and {kwargs}. "
-                    f"Error: {e}"
+                    f"{args_str}. Error: {e}"
                 )
 
     async def async_call(self, *args: Any, **kwargs: Any) -> Any: