camel-ai 0.2.21__py3-none-any.whl → 0.2.23__py3-none-any.whl

camel/toolkits/data_commons_toolkit.py

@@ -14,6 +14,7 @@
 import logging
 from typing import Any, Dict, List, Optional, Union
 
+from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
 
 logger = logging.getLogger(__name__)
@@ -35,8 +36,18 @@ class DataCommonsToolkit(BaseToolkit):
     Refer to https://datacommons.org/browser/ for more details.
     """
 
-    @staticmethod
+    def __init__(self, timeout: Optional[float] = None):
+        r"""Initialize the DataCommonsToolkit.
+
+        Args:
+            timeout (Optional[float], optional): Maximum time in seconds to
+            wait for API calls to complete. If None, will wait indefinitely.
+                (default: :obj:`None`)
+        """
+        super().__init__(timeout=timeout)
+
     def query_data_commons(
+        self,
         query_string: str,
     ) -> Optional[List[Dict[str, Any]]]:
         r"""Query the Data Commons knowledge graph using SPARQL.
@@ -76,9 +87,8 @@ class DataCommonsToolkit(BaseToolkit):
             )
             return None
 
-    @staticmethod
     def get_triples(
-        dcids: Union[str, List[str]], limit: int = 500
+        self, dcids: Union[str, List[str]], limit: int = 500
     ) -> Optional[Dict[str, List[tuple]]]:
         r"""Retrieve triples associated with nodes.
 
@@ -117,8 +127,8 @@ class DataCommonsToolkit(BaseToolkit):
             logger.error(f"An error occurred: {e!s}")
             return None
 
-    @staticmethod
     def get_stat_time_series(
+        self,
         place: str,
         stat_var: str,
         measurement_method: Optional[str] = None,
@@ -166,9 +176,8 @@ class DataCommonsToolkit(BaseToolkit):
             )
             return None
 
-    @staticmethod
     def get_property_labels(
-        dcids: Union[str, List[str]], out: bool = True
+        self, dcids: Union[str, List[str]], out: bool = True
     ) -> Optional[Dict[str, List[str]]]:
         r"""Retrieves and analyzes property labels for given DCIDs.
 
@@ -195,8 +204,8 @@ class DataCommonsToolkit(BaseToolkit):
             )
             return None
 
-    @staticmethod
     def get_property_values(
+        self,
         dcids: Union[str, List[str]],
         prop: str,
         out: Optional[bool] = True,
@@ -239,9 +248,8 @@ class DataCommonsToolkit(BaseToolkit):
             )
             return None
 
-    @staticmethod
     def get_places_in(
-        dcids: list, place_type: str
+        self, dcids: list, place_type: str
     ) -> Optional[Dict[str, Any]]:
         r"""Retrieves places within a given place type.
 
@@ -269,8 +277,8 @@ class DataCommonsToolkit(BaseToolkit):
             )
             return None
 
-    @staticmethod
     def get_stat_value(
+        self,
         place: str,
         stat_var: str,
         date: Optional[str] = None,
@@ -326,8 +334,7 @@ class DataCommonsToolkit(BaseToolkit):
             )
             return None
 
-    @staticmethod
-    def get_stat_all(places: str, stat_vars: str) -> Optional[dict]:
+    def get_stat_all(self, places: str, stat_vars: str) -> Optional[dict]:
         r"""Retrieves the value of a statistical variable for a given place
         and date.
 
@@ -358,3 +365,22 @@ class DataCommonsToolkit(BaseToolkit):
                 f"statistical variable: {e!s}"
             )
             return None
+
+    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.query_data_commons),
+            FunctionTool(self.get_triples),
+            FunctionTool(self.get_stat_time_series),
+            FunctionTool(self.get_property_labels),
+            FunctionTool(self.get_property_values),
+            FunctionTool(self.get_places_in),
+            FunctionTool(self.get_stat_value),
+            FunctionTool(self.get_stat_all),
+        ]

camel/toolkits/excel_toolkit.py

@@ -0,0 +1,172 @@
+# ========= 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 List
+
+import pandas as pd
+
+from camel.logger import get_logger
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+
+logger = get_logger(__name__)
+
+
+class ExcelToolkit(BaseToolkit):
+    r"""A class representing a toolkit for extract detailed cell information
+    from an Excel file.
+
+    This class provides method for processing docx, pdf, pptx, etc. It cannot
+    process excel files.
+    """
+
+    def _convert_to_markdown(self, df: pd.DataFrame) -> str:
+        r"""Convert DataFrame to Markdown format table.
+
+        Args:
+            df (pd.DataFrame): DataFrame containing the Excel data.
+
+        Returns:
+            str: Markdown formatted table.
+        """
+        from tabulate import tabulate
+
+        md_table = tabulate(df, headers='keys', tablefmt='pipe')
+        return str(md_table)
+
+    def extract_excel_content(self, document_path: str) -> str:
+        r"""Extract detailed cell information from an Excel file, including
+        multiple sheets.
+
+        Args:
+            document_path (str): The path of the Excel file.
+
+        Returns:
+            str: Extracted excel information, including details of each sheet.
+        """
+        from openpyxl import load_workbook
+        from xls2xlsx import XLS2XLSX
+
+        logger.debug(
+            f"Calling extract_excel_content with document_path"
+            f": {document_path}"
+        )
+
+        if not (
+            document_path.endswith("xls")
+            or document_path.endswith("xlsx")
+            or document_path.endswith("csv")
+        ):
+            logger.error("Only xls, xlsx, csv files are supported.")
+            return (
+                f"Failed to process file {document_path}: "
+                f"It is not excel format. Please try other ways."
+            )
+
+        if document_path.endswith("csv"):
+            try:
+                df = pd.read_csv(document_path)
+                md_table = self._convert_to_markdown(df)
+                return f"CSV File Processed:\n{md_table}"
+            except Exception as e:
+                logger.error(f"Failed to process file {document_path}: {e}")
+                return f"Failed to process file {document_path}: {e}"
+
+        if document_path.endswith("xls"):
+            output_path = document_path.replace(".xls", ".xlsx")
+            x2x = XLS2XLSX(document_path)
+            x2x.to_xlsx(output_path)
+            document_path = output_path
+
+        # Load the Excel workbook
+        wb = load_workbook(document_path, data_only=True)
+        sheet_info_list = []
+
+        # Iterate through all sheets
+        for sheet in wb.sheetnames:
+            ws = wb[sheet]
+            cell_info_list = []
+
+            for row in ws.iter_rows():
+                for cell in row:
+                    row_num = cell.row
+                    col_letter = cell.column_letter
+
+                    cell_value = cell.value
+
+                    font_color = None
+                    if (
+                        cell.font
+                        and cell.font.color
+                        and "rgb=None" not in str(cell.font.color)
+                    ):  # Handle font color
+                        font_color = cell.font.color.rgb
+
+                    fill_color = None
+                    if (
+                        cell.fill
+                        and cell.fill.fgColor
+                        and "rgb=None" not in str(cell.fill.fgColor)
+                    ):  # Handle fill color
+                        fill_color = cell.fill.fgColor.rgb
+
+                    cell_info_list.append(
+                        {
+                            "index": f"{row_num}{col_letter}",
+                            "value": cell_value,
+                            "font_color": font_color,
+                            "fill_color": fill_color,
+                        }
+                    )
+
+            # Convert the sheet to a DataFrame and then to markdown
+            sheet_df = pd.read_excel(
+                document_path, sheet_name=sheet, engine='openpyxl'
+            )
+            markdown_content = self._convert_to_markdown(sheet_df)
+
+            # Collect all information for the sheet
+            sheet_info = {
+                "sheet_name": sheet,
+                "cell_info_list": cell_info_list,
+                "markdown_content": markdown_content,
+            }
+            sheet_info_list.append(sheet_info)
+
+        result_str = ""
+        for sheet_info in sheet_info_list:
+            result_str += f"""
+            Sheet Name: {sheet_info['sheet_name']}
+            Cell information list:
+            {sheet_info['cell_info_list']}
+            
+            Markdown View of the content:
+            {sheet_info['markdown_content']}
+            
+            {'-'*40}
+            """
+
+        return result_str
+
+    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.extract_excel_content),
+        ]

camel/toolkits/function_tool.py

@@ -398,6 +398,19 @@ class FunctionTool:
                     f"Error: {e}"
                 )
 
+    async def async_call(self, *args: Any, **kwargs: Any) -> Any:
+        if self.synthesize_output:
+            result = self.synthesize_execution_output(args, kwargs)
+            return result
+        if self.is_async:
+            return await self.func(*args, **kwargs)
+        else:
+            return self.func(*args, **kwargs)
+
+    @property
+    def is_async(self) -> bool:
+        return inspect.iscoroutinefunction(self.func)
+
     @staticmethod
     def validate_openai_tool_schema(
         openai_tool_schema: Dict[str, Any],

camel/toolkits/github_toolkit.py

@@ -39,7 +39,10 @@ class GithubToolkit(BaseToolkit):
 
     @dependencies_required('github')
     def __init__(
-        self, repo_name: str, access_token: Optional[str] = None
+        self,
+        repo_name: str,
+        access_token: Optional[str] = None,
+        timeout: Optional[float] = None,
     ) -> None:
         r"""Initializes a new instance of the GitHubToolkit class.
 
@@ -49,6 +52,7 @@ class GithubToolkit(BaseToolkit):
                 with GitHub. If not provided, it will be obtained using the
                 `get_github_access_token` method.
         """
+        super().__init__(timeout=timeout)
         from github import Auth, Github
 
         if access_token is None:

camel/toolkits/google_maps_toolkit.py

@@ -101,7 +101,8 @@ class GoogleMapsToolkit(BaseToolkit):
     """
 
     @dependencies_required('googlemaps')
-    def __init__(self) -> None:
+    def __init__(self, timeout: Optional[float] = None) -> None:
+        super().__init__(timeout=timeout)
         import googlemaps
 
         api_key = os.environ.get('GOOGLE_API_KEY')

camel/toolkits/google_scholar_toolkit.py

@@ -39,6 +39,7 @@ class GoogleScholarToolkit(BaseToolkit):
         use_free_proxies: bool = False,
         proxy_http: Optional[str] = None,
         proxy_https: Optional[str] = None,
+        timeout: Optional[float] = None,
     ) -> None:
         r"""Initializes the GoogleScholarToolkit with the author's identifier.
 
@@ -54,6 +55,7 @@ class GoogleScholarToolkit(BaseToolkit):
             proxy_https ( Optional[str]): Proxy https address pass to pg.
                 SingleProxy. (default: :obj:`None`)
         """
+        super().__init__(timeout=timeout)
         from scholarly import ProxyGenerator, scholarly
 
         # Set Free Proxies is needed

camel/toolkits/human_toolkit.py

@@ -24,9 +24,6 @@ logger = logging.getLogger(__name__)
 class HumanToolkit(BaseToolkit):
     r"""A class representing a toolkit for human interaction."""
 
-    def __init__(self):
-        pass
-
     def ask_human_via_console(self, question: str) -> str:
         r"""Ask a question to the human via the console.
 

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),
+        ]

camel/toolkits/linkedin_toolkit.py

@@ -15,7 +15,7 @@
 import json
 import os
 from http import HTTPStatus
-from typing import List
+from typing import List, Optional
 
 import requests
 
@@ -33,7 +33,8 @@ class LinkedInToolkit(BaseToolkit):
     retrieving the authenticated user's profile information.
     """
 
-    def __init__(self):
+    def __init__(self, timeout: Optional[float] = None):
+        super().__init__(timeout=timeout)
         self._access_token = self._get_access_token()
 
     def create_post(self, text: str) -> dict:

camel/toolkits/meshy_toolkit.py

@@ -13,7 +13,7 @@
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 
 import os
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 import requests
 
@@ -38,10 +38,11 @@ class MeshyToolkit(BaseToolkit):
             (None, 'MESHY_API_KEY'),
         ]
     )
-    def __init__(self):
+    def __init__(self, timeout: Optional[float] = None):
         r"""Initializes the MeshyToolkit with the API key from the
         environment.
         """
+        super().__init__(timeout=timeout)
         self.api_key = os.getenv('MESHY_API_KEY')
 
     def generate_3d_preview(