camel-ai 0.2.23a0__py3-none-any.whl → 0.2.24__py3-none-any.whl

camel/toolkits/file_write_toolkit.py

@@ -0,0 +1,371 @@
+# ========= 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 datetime import datetime
+from pathlib import Path
+from typing import List, Optional, Union
+
+from camel.logger import get_logger
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+
+logger = get_logger(__name__)
+
+# Default format when no extension is provided
+DEFAULT_FORMAT = '.md'
+
+
+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 backups, custom encoding,
+    and enhanced formatting options for specialized formats.
+    """
+
+    def __init__(
+        self,
+        output_dir: str = "./",
+        timeout: Optional[float] = None,
+        default_encoding: str = "utf-8",
+        backup_enabled: bool = True,
+    ) -> None:
+        r"""Initialize the FileWriteToolkit.
+
+        Args:
+            output_dir (str): The default directory for output files.
+                Defaults to the current working directory.
+            timeout (Optional[float]): The timeout for the toolkit.
+                (default: :obj: `None`)
+            default_encoding (str): Default character encoding for text
+                operations. (default: :obj: `utf-8`)
+            backup_enabled (bool): Whether to create backups of existing files
+                before overwriting. (default: :obj: `True`)
+        """
+        super().__init__(timeout=timeout)
+        self.output_dir = Path(output_dir).resolve()
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self.default_encoding = default_encoding
+        self.backup_enabled = backup_enabled
+        logger.info(
+            f"FileWriteToolkit initialized with output directory"
+            f": {self.output_dir}, encoding: {default_encoding}"
+        )
+
+    def _resolve_filepath(self, file_path: str) -> Path:
+        r"""Convert the given string path to a Path object.
+
+        If the provided path is not absolute, it is made relative to the
+        default output directory.
+
+        Args:
+            file_path (str): The file path to resolve.
+
+        Returns:
+            Path: A fully resolved (absolute) Path object.
+        """
+        path_obj = Path(file_path)
+        if not path_obj.is_absolute():
+            path_obj = self.output_dir / path_obj
+        return path_obj.resolve()
+
+    def _write_text_file(
+        self, file_path: Path, content: str, encoding: str = "utf-8"
+    ) -> None:
+        r"""Write text content to a plaintext file.
+
+        Args:
+            file_path (Path): The target file path.
+            content (str): The text content to write.
+            encoding (str): Character encoding to use. (default: :obj: `utf-8`)
+        """
+        with file_path.open("w", encoding=encoding) as f:
+            f.write(content)
+        logger.debug(f"Wrote text to {file_path} with {encoding} encoding")
+
+    def _create_backup(self, file_path: Path) -> None:
+        r"""Create a backup of the file if it exists and backup is enabled.
+
+        Args:
+            file_path (Path): Path to the file to backup.
+        """
+        import shutil
+
+        if not self.backup_enabled or not file_path.exists():
+            return
+
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        backup_path = file_path.parent / f"{file_path.name}.{timestamp}.bak"
+        shutil.copy2(file_path, backup_path)
+        logger.info(f"Created backup at {backup_path}")
+
+    def _write_docx_file(self, file_path: Path, content: str) -> None:
+        r"""Write text content to a DOCX file with default formatting.
+
+        Args:
+            file_path (Path): The target file path.
+            content (str): The text content to write.
+        """
+        import docx
+
+        # Use default formatting values
+        font_name = 'Calibri'
+        font_size = 11
+        line_spacing = 1.0
+
+        document = docx.Document()
+        style = document.styles['Normal']
+        style.font.name = font_name
+        style.font.size = docx.shared.Pt(font_size)
+        style.paragraph_format.line_spacing = line_spacing
+
+        # Split content into paragraphs and add them
+        for para_text in content.split('\n'):
+            para = document.add_paragraph(para_text)
+            para.style = style
+
+        document.save(str(file_path))
+        logger.debug(f"Wrote DOCX to {file_path} with default formatting")
+
+    def _write_pdf_file(self, file_path: Path, content: str, **kwargs) -> None:
+        r"""Write text content to a PDF file with default formatting.
+
+        Args:
+            file_path (Path): The target file path.
+            content (str): The text content to write.
+
+        Raises:
+            RuntimeError: If the 'fpdf' library is not installed.
+        """
+        from fpdf import FPDF
+
+        # Use default formatting values
+        font_family = 'Arial'
+        font_size = 12
+        font_style = ''
+        line_height = 10
+        margin = 10
+
+        pdf = FPDF()
+        pdf.set_margins(margin, margin, margin)
+
+        pdf.add_page()
+        pdf.set_font(font_family, style=font_style, size=font_size)
+
+        # Split content into paragraphs and add them
+        for para in content.split('\n'):
+            if para.strip():  # Skip empty paragraphs
+                pdf.multi_cell(0, line_height, para)
+            else:
+                pdf.ln(line_height)  # Add empty line
+
+        pdf.output(str(file_path))
+        logger.debug(f"Wrote PDF to {file_path} with custom formatting")
+
+    def _write_csv_file(
+        self,
+        file_path: Path,
+        content: Union[str, List[List]],
+        encoding: str = "utf-8",
+    ) -> None:
+        r"""Write CSV content to a file.
+
+        Args:
+            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`)
+        """
+        import csv
+
+        with file_path.open("w", encoding=encoding, newline='') as f:
+            if isinstance(content, str):
+                f.write(content)
+            else:
+                writer = csv.writer(f)
+                writer.writerows(content)
+        logger.debug(f"Wrote CSV to {file_path} with {encoding} encoding")
+
+    def _write_json_file(
+        self,
+        file_path: Path,
+        content: str,
+        encoding: str = "utf-8",
+    ) -> None:
+        r"""Write JSON content to a file.
+
+        Args:
+            file_path (Path): The target file path.
+            content (str): The JSON content as a string.
+            encoding (str): Character encoding to use. (default: :obj: `utf-8`)
+        """
+        import json
+
+        with file_path.open("w", encoding=encoding) as f:
+            if isinstance(content, str):
+                try:
+                    # Try parsing as JSON string first
+                    data = json.loads(content)
+                    json.dump(data, f)
+                except json.JSONDecodeError:
+                    # If not valid JSON string, write as is
+                    f.write(content)
+            else:
+                # If not string, dump as JSON
+                json.dump(content, f)
+        logger.debug(f"Wrote JSON to {file_path} with {encoding} encoding")
+
+    def _write_yaml_file(
+        self,
+        file_path: Path,
+        content: str,
+        encoding: str = "utf-8",
+    ) -> None:
+        r"""Write YAML content to a file.
+
+        Args:
+            file_path (Path): The target file path.
+            content (str): The YAML content as a string.
+            encoding (str): Character encoding to use. (default: :obj: `utf-8`)
+        """
+        with file_path.open("w", encoding=encoding) as f:
+            f.write(content)
+        logger.debug(f"Wrote YAML to {file_path} with {encoding} encoding")
+
+    def _write_html_file(
+        self, file_path: Path, content: str, encoding: str = "utf-8"
+    ) -> None:
+        r"""Write text content to an HTML file.
+
+        Args:
+            file_path (Path): The target file path.
+            content (str): The HTML content to write.
+            encoding (str): Character encoding to use. (default: :obj: `utf-8`)
+        """
+        with file_path.open("w", encoding=encoding) as f:
+            f.write(content)
+        logger.debug(f"Wrote HTML to {file_path} with {encoding} encoding")
+
+    def _write_markdown_file(
+        self, file_path: Path, content: str, encoding: str = "utf-8"
+    ) -> None:
+        r"""Write text content to a Markdown file.
+
+        Args:
+            file_path (Path): The target file path.
+            content (str): The Markdown content to write.
+            encoding (str): Character encoding to use. (default: :obj: `utf-8`)
+        """
+        with file_path.open("w", encoding=encoding) as f:
+            f.write(content)
+        logger.debug(f"Wrote Markdown to {file_path} with {encoding} encoding")
+
+    def write_to_file(
+        self,
+        content: Union[str, List[List[str]]],
+        filename: str,
+        encoding: Optional[str] = None,
+    ) -> str:
+        r"""Write the given content to a file.
+
+        If the file exists, it will be overwritten. Supports multiple formats:
+        Markdown (.md, .markdown, default), Plaintext (.txt), CSV (.csv),
+        DOC/DOCX (.doc, .docx), PDF (.pdf), JSON (.json), YAML (.yml, .yaml),
+        and HTML (.html, .htm).
+
+        Args:
+            content (Union[str, List[List[str]]]): The content to write to the
+                file. For all formats, content must be a string or list in the
+                appropriate format.
+            filename (str): The name or path of the file. If a relative path is
+                supplied, it is resolved to self.output_dir.
+            encoding (Optional[str]): The character encoding to use. (default:
+                :obj: `None`)
+
+        Returns:
+            str: A message indicating success or error details.
+        """
+        file_path = self._resolve_filepath(filename)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Create backup if file exists
+        self._create_backup(file_path)
+
+        extension = file_path.suffix.lower()
+
+        # If no extension is provided, use the default format
+        if extension == "":
+            file_path = file_path.with_suffix(DEFAULT_FORMAT)
+            extension = DEFAULT_FORMAT
+
+        try:
+            # Get encoding or use default
+            file_encoding = encoding or self.default_encoding
+
+            if extension in [".doc", ".docx"]:
+                self._write_docx_file(file_path, str(content))
+            elif extension == ".pdf":
+                self._write_pdf_file(file_path, str(content))
+            elif extension == ".csv":
+                self._write_csv_file(
+                    file_path, content, encoding=file_encoding
+                )
+            elif extension == ".json":
+                self._write_json_file(
+                    file_path,
+                    content,  # type: ignore[arg-type]
+                    encoding=file_encoding,
+                )
+            elif extension in [".yml", ".yaml"]:
+                self._write_yaml_file(
+                    file_path, str(content), encoding=file_encoding
+                )
+            elif extension in [".html", ".htm"]:
+                self._write_html_file(
+                    file_path, str(content), encoding=file_encoding
+                )
+            elif extension in [".md", ".markdown"]:
+                self._write_markdown_file(
+                    file_path, str(content), encoding=file_encoding
+                )
+            else:
+                # Fallback to simple text writing for unknown or .txt
+                # extensions
+                self._write_text_file(
+                    file_path, str(content), encoding=file_encoding
+                )
+
+            msg = f"Content successfully written to file: {file_path}"
+            logger.info(msg)
+            return msg
+        except Exception as e:
+            error_msg = (
+                f"Error occurred while writing to file {file_path}: {e}"
+            )
+            logger.error(error_msg)
+            return error_msg
+
+    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 representing
+                the available functions in this toolkit.
+        """
+        return [
+            FunctionTool(self.write_to_file),
+        ]

camel/toolkits/image_analysis_toolkit.py

@@ -0,0 +1,202 @@
+# ========= 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 io import BytesIO
+from typing import List, Optional
+from urllib.parse import urlparse
+
+import requests
+from PIL import Image
+
+from camel.logger import get_logger
+from camel.messages import BaseMessage
+from camel.models import BaseModelBackend, ModelFactory
+from camel.toolkits import FunctionTool
+from camel.toolkits.base import BaseToolkit
+from camel.types import ModelPlatformType, ModelType
+
+logger = get_logger(__name__)
+
+
+class ImageAnalysisToolkit(BaseToolkit):
+    r"""A toolkit for comprehensive image analysis and understanding.
+    The toolkit uses vision-capable language models to perform these tasks.
+    """
+
+    def __init__(self, model: Optional[BaseModelBackend] = None):
+        r"""Initialize the ImageAnalysisToolkit.
+
+        Args:
+            model (Optional[BaseModelBackend]): The model backend to use for
+                image analysis tasks. This model should support processing
+                images for tasks like image description and visual question
+                answering. If None, a default model will be created using
+                ModelFactory. (default: :obj:`None`)
+        """
+        if model:
+            self.model = model
+        else:
+            self.model = ModelFactory.create(
+                model_platform=ModelPlatformType.DEFAULT,
+                model_type=ModelType.DEFAULT,
+            )
+
+    def image_to_text(
+        self, image_path: str, sys_prompt: Optional[str] = None
+    ) -> str:
+        r"""Generates textual description of an image with optional custom
+        prompt.
+
+        Args:
+            image_path (str): Local path or URL to an image file.
+            sys_prompt (Optional[str]): Custom system prompt for the analysis.
+                (default: :obj:`None`)
+
+        Returns:
+            str: Natural language description of the image.
+        """
+        default_content = '''You are an image analysis expert. Provide a 
+            detailed description including text if present.'''
+
+        system_msg = BaseMessage.make_assistant_message(
+            role_name="Senior Computer Vision Analyst",
+            content=sys_prompt if sys_prompt else default_content,
+        )
+
+        return self._analyze_image(
+            image_path=image_path,
+            prompt="Please describe the contents of this image.",
+            system_message=system_msg,
+        )
+
+    def ask_question_about_image(
+        self, image_path: str, question: str, sys_prompt: Optional[str] = None
+    ) -> str:
+        r"""Answers image questions with optional custom instructions.
+
+        Args:
+            image_path (str): Local path or URL to an image file.
+            question (str): Query about the image content.
+            sys_prompt (Optional[str]): Custom system prompt for the analysis.
+                (default: :obj:`None`)
+
+        Returns:
+            str: Detailed answer based on visual understanding
+        """
+        default_content = """Answer questions about images by:
+            1. Careful visual inspection
+            2. Contextual reasoning
+            3. Text transcription where relevant
+            4. Logical deduction from visual evidence"""
+
+        system_msg = BaseMessage.make_assistant_message(
+            role_name="Visual QA Specialist",
+            content=sys_prompt if sys_prompt else default_content,
+        )
+
+        return self._analyze_image(
+            image_path=image_path,
+            prompt=question,
+            system_message=system_msg,
+        )
+
+    def _load_image(self, image_path: str) -> Image.Image:
+        r"""Loads an image from either local path or URL.
+
+        Args:
+            image_path (str): Local path or URL to image.
+
+        Returns:
+            Image.Image: Loaded PIL Image object.
+
+        Raises:
+            ValueError: For invalid paths/URLs or unreadable images.
+            requests.exceptions.RequestException: For URL fetch failures.
+        """
+        parsed = urlparse(image_path)
+
+        if parsed.scheme in ("http", "https"):
+            logger.debug(f"Fetching image from URL: {image_path}")
+            try:
+                response = requests.get(image_path, timeout=15)
+                response.raise_for_status()
+                return Image.open(BytesIO(response.content))
+            except requests.exceptions.RequestException as e:
+                logger.error(f"URL fetch failed: {e}")
+                raise
+        else:
+            logger.debug(f"Loading local image: {image_path}")
+            try:
+                return Image.open(image_path)
+            except Exception as e:
+                logger.error(f"Image loading failed: {e}")
+                raise ValueError(f"Invalid image file: {e}")
+
+    def _analyze_image(
+        self,
+        image_path: str,
+        prompt: str,
+        system_message: BaseMessage,
+    ) -> str:
+        r"""Core analysis method handling image loading and processing.
+
+        Args:
+            image_path (str): Image location.
+            prompt (str): Analysis query/instructions.
+            system_message (BaseMessage): Custom system prompt for the
+                analysis.
+
+        Returns:
+            str: Analysis result or error message.
+        """
+        try:
+            image = self._load_image(image_path)
+            logger.info(f"Analyzing image: {image_path}")
+
+            from camel.agents.chat_agent import ChatAgent
+
+            agent = ChatAgent(
+                system_message=system_message,
+                model=self.model,
+            )
+
+            user_msg = BaseMessage.make_user_message(
+                role_name="User",
+                content=prompt,
+                image_list=[image],
+            )
+
+            response = agent.step(user_msg)
+            agent.reset()
+            return response.msgs[0].content
+
+        except (ValueError, requests.exceptions.RequestException) as e:
+            logger.error(f"Image handling error: {e}")
+            return f"Image error: {e!s}"
+        except Exception as e:
+            logger.error(f"Unexpected error: {e}")
+            return f"Analysis failed: {e!s}"
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Returns a list of FunctionTool objects representing the functions
+            in the toolkit.
+
+        Returns:
+            List[FunctionTool]: A list of FunctionTool objects representing the
+                functions in the toolkit.
+        """
+        return [
+            FunctionTool(self.image_to_text),
+            FunctionTool(self.ask_question_about_image),
+        ]