camel-ai 0.1.5.5__py3-none-any.whl → 0.1.5.9__py3-none-any.whl

camel/toolkits/search_toolkit.py

@@ -0,0 +1,326 @@
+# =========== Copyright 2023 @ 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 @ CAMEL-AI.org. All Rights Reserved. ===========
+import os
+from typing import Any, Dict, List
+
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.openai_function import OpenAIFunction
+
+
+class SearchToolkit(BaseToolkit):
+    r"""A class representing a toolkit for web search.
+
+    This class provides methods for searching information on the web using
+    search engines like Google, DuckDuckGo, Wikipedia and Wolfram Alpha.
+    """
+
+    def search_wiki(self, entity: str) -> str:
+        r"""Search the entity in WikiPedia and return the summary of the
+            required page, containing factual information about
+            the given entity.
+
+        Args:
+            entity (str): The entity to be searched.
+
+        Returns:
+            str: The search result. If the page corresponding to the entity
+                exists, return the summary of this entity in a string.
+        """
+        try:
+            import wikipedia
+        except ImportError:
+            raise ImportError(
+                "Please install `wikipedia` first. You can install it "
+                "by running `pip install wikipedia`."
+            )
+
+        result: str
+
+        try:
+            result = wikipedia.summary(entity, sentences=5, auto_suggest=False)
+        except wikipedia.exceptions.DisambiguationError as e:
+            result = wikipedia.summary(
+                e.options[0], sentences=5, auto_suggest=False
+            )
+        except wikipedia.exceptions.PageError:
+            result = (
+                "There is no page in Wikipedia corresponding to entity "
+                f"{entity}, please specify another word to describe the"
+                " entity to be searched."
+            )
+        except wikipedia.exceptions.WikipediaException as e:
+            result = f"An exception occurred during the search: {e}"
+
+        return result
+
+    def search_duckduckgo(
+        self, query: str, source: str = "text", max_results: int = 10
+    ) -> List[Dict[str, Any]]:
+        r"""Use DuckDuckGo search engine to search information for
+        the given query.
+
+        This function queries the DuckDuckGo API for related topics to
+        the given search term. The results are formatted into a list of
+        dictionaries, each representing a search result.
+
+        Args:
+            query (str): The query to be searched.
+            source (str): The type of information to query (e.g., "text",
+                "images", "videos"). Defaults to "text".
+            max_results (int): Max number of results, defaults to `10`.
+
+        Returns:
+            List[Dict[str, Any]]: A list of dictionaries where each dictionary
+                represents a search result.
+        """
+        from duckduckgo_search import DDGS
+        from requests.exceptions import RequestException
+
+        ddgs = DDGS()
+        responses: List[Dict[str, Any]] = []
+
+        if source == "text":
+            try:
+                results = ddgs.text(keywords=query, max_results=max_results)
+            except RequestException as e:
+                # Handle specific exceptions or general request exceptions
+                responses.append({"error": f"duckduckgo search failed.{e}"})
+
+            # Iterate over results found
+            for i, result in enumerate(results, start=1):
+                # Creating a response object with a similar structure
+                response = {
+                    "result_id": i,
+                    "title": result["title"],
+                    "description": result["body"],
+                    "url": result["href"],
+                }
+                responses.append(response)
+
+        elif source == "images":
+            try:
+                results = ddgs.images(keywords=query, max_results=max_results)
+            except RequestException as e:
+                # Handle specific exceptions or general request exceptions
+                responses.append({"error": f"duckduckgo search failed.{e}"})
+
+            # Iterate over results found
+            for i, result in enumerate(results, start=1):
+                # Creating a response object with a similar structure
+                response = {
+                    "result_id": i,
+                    "title": result["title"],
+                    "image": result["image"],
+                    "url": result["url"],
+                    "source": result["source"],
+                }
+                responses.append(response)
+
+        elif source == "videos":
+            try:
+                results = ddgs.videos(keywords=query, max_results=max_results)
+            except RequestException as e:
+                # Handle specific exceptions or general request exceptions
+                responses.append({"error": f"duckduckgo search failed.{e}"})
+
+            # Iterate over results found
+            for i, result in enumerate(results, start=1):
+                # Creating a response object with a similar structure
+                response = {
+                    "result_id": i,
+                    "title": result["title"],
+                    "description": result["description"],
+                    "embed_url": result["embed_url"],
+                    "publisher": result["publisher"],
+                    "duration": result["duration"],
+                    "published": result["published"],
+                }
+                responses.append(response)
+
+        # If no answer found, return an empty list
+        return responses
+
+    def search_google(
+        self, query: str, num_result_pages: int = 10
+    ) -> List[Dict[str, Any]]:
+        r"""Use Google search engine to search information for the given query.
+
+        Args:
+            query (str): The query to be searched.
+            num_result_pages (int): The number of result pages to retrieve.
+
+        Returns:
+            List[Dict[str, Any]]: A list of dictionaries where each dictionary
+            represents a website.
+                Each dictionary contains the following keys:
+                - 'result_id': A number in order.
+                - 'title': The title of the website.
+                - 'description': A brief description of the website.
+                - 'long_description': More detail of the website.
+                - 'url': The URL of the website.
+
+                Example:
+                {
+                    'result_id': 1,
+                    'title': 'OpenAI',
+                    'description': 'An organization focused on ensuring that
+                    artificial general intelligence benefits all of humanity.',
+                    'long_description': 'OpenAI is a non-profit artificial
+                    intelligence research company. Our goal is to advance
+                    digital intelligence in the way that is most likely to
+                    benefit humanity as a whole',
+                    'url': 'https://www.openai.com'
+                }
+            title, description, url of a website.
+        """
+        import requests
+
+        # https://developers.google.com/custom-search/v1/overview
+        GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY")
+        # https://cse.google.com/cse/all
+        SEARCH_ENGINE_ID = os.getenv("SEARCH_ENGINE_ID")
+
+        # Using the first page
+        start_page_idx = 1
+        # Different language may get different result
+        search_language = "en"
+        # How many pages to return
+        num_result_pages = 10
+        # Constructing the URL
+        # Doc: https://developers.google.com/custom-search/v1/using_rest
+        url = (
+            f"https://www.googleapis.com/customsearch/v1?"
+            f"key={GOOGLE_API_KEY}&cx={SEARCH_ENGINE_ID}&q={query}&start="
+            f"{start_page_idx}&lr={search_language}&num={num_result_pages}"
+        )
+
+        responses = []
+        # Fetch the results given the URL
+        try:
+            # Make the get
+            result = requests.get(url)
+            data = result.json()
+
+            # Get the result items
+            if "items" in data:
+                search_items = data.get("items")
+
+                # Iterate over 10 results found
+                for i, search_item in enumerate(search_items, start=1):
+                    if (
+                        "og:description"
+                        in search_item["pagemap"]["metatags"][0]
+                    ):
+                        long_description = search_item["pagemap"]["metatags"][
+                            0
+                        ]["og:description"]
+                    else:
+                        long_description = "N/A"
+                    # Get the page title
+                    title = search_item.get("title")
+                    # Page snippet
+                    snippet = search_item.get("snippet")
+
+                    # Extract the page url
+                    link = search_item.get("link")
+                    response = {
+                        "result_id": i,
+                        "title": title,
+                        "description": snippet,
+                        "long_description": long_description,
+                        "url": link,
+                    }
+                    responses.append(response)
+            else:
+                responses.append({"error": "google search failed."})
+
+        except requests.RequestException:
+            # Handle specific exceptions or general request exceptions
+            responses.append({"error": "google search failed."})
+        # If no answer found, return an empty list
+        return responses
+
+    def query_wolfram_alpha(self, query: str, is_detailed: bool) -> str:
+        r"""Queries Wolfram|Alpha and returns the result. Wolfram|Alpha is an
+        answer engine developed by Wolfram Research. It is offered as an online
+        service that answers factual queries by computing answers from
+        externally sourced data.
+
+        Args:
+            query (str): The query to send to Wolfram Alpha.
+            is_detailed (bool): Whether to include additional details in the
+                result.
+
+        Returns:
+            str: The result from Wolfram Alpha, formatted as a string.
+        """
+        try:
+            import wolframalpha
+        except ImportError:
+            raise ImportError(
+                "Please install `wolframalpha` first. You can install it by"
+                " running `pip install wolframalpha`."
+            )
+
+        WOLFRAMALPHA_APP_ID = os.environ.get('WOLFRAMALPHA_APP_ID')
+        if not WOLFRAMALPHA_APP_ID:
+            raise ValueError(
+                "`WOLFRAMALPHA_APP_ID` not found in environment "
+                "variables. Get `WOLFRAMALPHA_APP_ID` here: "
+                "`https://products.wolframalpha.com/api/`."
+            )
+
+        try:
+            client = wolframalpha.Client(WOLFRAMALPHA_APP_ID)
+            res = client.query(query)
+            assumption = next(res.pods).text or "No assumption made."
+            answer = next(res.results).text or "No answer found."
+        except Exception as e:
+            if isinstance(e, StopIteration):
+                return "Wolfram Alpha wasn't able to answer it"
+            else:
+                error_message = (
+                    f"Wolfram Alpha wasn't able to answer it" f"{e!s}."
+                )
+                return error_message
+
+        result = f"Assumption:\n{assumption}\n\nAnswer:\n{answer}"
+
+        # Add additional details in the result
+        if is_detailed:
+            result += '\n'
+            for pod in res.pods:
+                result += '\n' + pod['@title'] + ':\n'
+                for sub in pod.subpods:
+                    result += (sub.plaintext or "None") + '\n'
+
+        return result.rstrip()  # Remove trailing whitespace
+
+    def get_tools(self) -> List[OpenAIFunction]:
+        r"""Returns a list of OpenAIFunction objects representing the
+        functions in the toolkit.
+
+        Returns:
+            List[OpenAIFunction]: A list of OpenAIFunction objects
+                representing the functions in the toolkit.
+        """
+        return [
+            OpenAIFunction(self.search_wiki),
+            OpenAIFunction(self.search_google),
+            OpenAIFunction(self.search_duckduckgo),
+            OpenAIFunction(self.query_wolfram_alpha),
+        ]
+
+
+SEARCH_FUNCS: List[OpenAIFunction] = SearchToolkit().get_tools()

camel/toolkits/slack_toolkit.py

@@ -0,0 +1,308 @@
+# =========== Copyright 2023 @ 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 @ CAMEL-AI.org. All Rights Reserved. ===========
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import TYPE_CHECKING, List, Optional
+
+from camel.toolkits.base import BaseToolkit
+
+if TYPE_CHECKING:
+    from ssl import SSLContext
+
+    from slack_sdk import WebClient
+
+from camel.toolkits import OpenAIFunction
+
+logger = logging.getLogger(__name__)
+
+
+class SlackToolkit(BaseToolkit):
+    r"""A class representing a toolkit for Slack operations.
+
+    This class provides methods for Slack operations such as creating a new
+    channel, joining an existing channel, leaving a channel.
+    """
+
+    def _login_slack(
+        self,
+        slack_token: Optional[str] = None,
+        ssl: Optional[SSLContext] = None,
+    ) -> WebClient:
+        r"""Authenticate using the Slack API.
+
+        Args:
+            slack_token (str, optional): The Slack API token.
+                If not provided, it attempts to retrieve the token from
+                the environment variable SLACK_BOT_TOKEN or SLACK_USER_TOKEN.
+            ssl (SSLContext, optional): SSL context for secure connections.
+                Defaults to `None`.
+
+        Returns:
+            WebClient: A WebClient object for interacting with Slack API.
+
+        Raises:
+            ImportError: If slack_sdk package is not installed.
+            KeyError: If SLACK_BOT_TOKEN or SLACK_USER_TOKEN
+                environment variables are not set.
+        """
+        try:
+            from slack_sdk import WebClient
+        except ImportError as e:
+            raise ImportError(
+                "Cannot import slack_sdk. Please install the package with \
+                `pip install slack_sdk`."
+            ) from e
+        if not slack_token:
+            slack_token = os.environ.get("SLACK_BOT_TOKEN") or os.environ.get(
+                "SLACK_USER_TOKEN"
+            )
+            if not slack_token:
+                raise KeyError(
+                    "SLACK_BOT_TOKEN or SLACK_USER_TOKEN environment "
+                    "variable not set."
+                )
+
+        client = WebClient(token=slack_token, ssl=ssl)
+        logger.info("Slack login successful.")
+        return client
+
+    def create_slack_channel(
+        self, name: str, is_private: Optional[bool] = True
+    ) -> str:
+        r"""Creates a new slack channel, either public or private.
+
+        Args:
+            name (str): Name of the public or private channel to create.
+            is_private (bool, optional): Whether to create a private channel
+                instead of a public one. Defaults to `True`.
+
+        Returns:
+            str: JSON string containing information about Slack
+                channel created.
+
+        Raises:
+            SlackApiError: If there is an error during get slack channel
+                information.
+        """
+        from slack_sdk.errors import SlackApiError
+
+        try:
+            slack_client = self._login_slack()
+            response = slack_client.conversations_create(
+                name=name, is_private=is_private
+            )
+            channel_id = response["channel"]["id"]
+            response = slack_client.conversations_archive(channel=channel_id)
+            return str(response)
+        except SlackApiError as e:
+            return f"Error creating conversation: {e.response['error']}"
+
+    def join_slack_channel(self, channel_id: str) -> str:
+        r"""Joins an existing Slack channel.
+
+        Args:
+            channel_id (str): The ID of the Slack channel to join.
+
+        Returns:
+            str: A confirmation message indicating whether join successfully
+                or an error message.
+
+        Raises:
+            SlackApiError: If there is an error during get slack channel
+                information.
+        """
+        from slack_sdk.errors import SlackApiError
+
+        try:
+            slack_client = self._login_slack()
+            response = slack_client.conversations_join(channel=channel_id)
+            return str(response)
+        except SlackApiError as e:
+            return f"Error creating conversation: {e.response['error']}"
+
+    def leave_slack_channel(self, channel_id: str) -> str:
+        r"""Leaves an existing Slack channel.
+
+        Args:
+            channel_id (str): The ID of the Slack channel to leave.
+
+        Returns:
+            str: A confirmation message indicating whether leave successfully
+                or an error message.
+
+        Raises:
+            SlackApiError: If there is an error during get slack channel
+                information.
+        """
+        from slack_sdk.errors import SlackApiError
+
+        try:
+            slack_client = self._login_slack()
+            response = slack_client.conversations_leave(channel=channel_id)
+            return str(response)
+        except SlackApiError as e:
+            return f"Error creating conversation: {e.response['error']}"
+
+    def get_slack_channel_information(self) -> str:
+        r"""Retrieve Slack channels and return relevant information in JSON
+            format.
+
+        Returns:
+            str: JSON string containing information about Slack channels.
+
+        Raises:
+            SlackApiError: If there is an error during get slack channel
+                information.
+        """
+        from slack_sdk.errors import SlackApiError
+
+        try:
+            slack_client = self._login_slack()
+            response = slack_client.conversations_list()
+            conversations = response["channels"]
+            # Filtering conversations and extracting required information
+            filtered_result = [
+                {
+                    key: conversation[key]
+                    for key in ("id", "name", "created", "num_members")
+                }
+                for conversation in conversations
+                if all(
+                    key in conversation
+                    for key in ("id", "name", "created", "num_members")
+                )
+            ]
+            return json.dumps(filtered_result, ensure_ascii=False)
+        except SlackApiError as e:
+            return f"Error creating conversation: {e.response['error']}"
+
+    def get_slack_channel_message(self, channel_id: str) -> str:
+        r"""Retrieve messages from a Slack channel.
+
+        Args:
+            channel_id (str): The ID of the Slack channel to retrieve messages
+                from.
+
+        Returns:
+            str: JSON string containing filtered message data.
+
+        Raises:
+            SlackApiError: If there is an error during get
+                slack channel message.
+        """
+        from slack_sdk.errors import SlackApiError
+
+        try:
+            slack_client = self._login_slack()
+            result = slack_client.conversations_history(channel=channel_id)
+            messages = result["messages"]
+            filtered_messages = [
+                {key: message[key] for key in ("user", "text", "ts")}
+                for message in messages
+                if all(key in message for key in ("user", "text", "ts"))
+            ]
+            return json.dumps(filtered_messages, ensure_ascii=False)
+        except SlackApiError as e:
+            return f"Error retrieving messages: {e.response['error']}"
+
+    def send_slack_message(
+        self,
+        message: str,
+        channel_id: str,
+        user: Optional[str] = None,
+    ) -> str:
+        r"""Send a message to a Slack channel.
+
+        Args:
+            message (str): The message to send.
+            channel_id (str): The ID of the Slack channel to send message.
+            user (Optional[str]): The user ID of the recipient.
+                Defaults to `None`.
+
+        Returns:
+            str: A confirmation message indicating whether the message was sent
+                successfully or an error message.
+
+        Raises:
+            SlackApiError: If an error occurs while sending the message.
+        """
+        from slack_sdk.errors import SlackApiError
+
+        try:
+            slack_client = self._login_slack()
+            if user:
+                response = slack_client.chat_postEphemeral(
+                    channel=channel_id, text=message, user=user
+                )
+            else:
+                response = slack_client.chat_postMessage(
+                    channel=channel_id, text=message
+                )
+            return str(response)
+        except SlackApiError as e:
+            return f"Error creating conversation: {e.response['error']}"
+
+    def delete_slack_message(
+        self,
+        time_stamp: str,
+        channel_id: str,
+    ) -> str:
+        r"""Delete a message to a Slack channel.
+
+        Args:
+            time_stamp (str): Timestamp of the message to be deleted.
+            channel_id (str): The ID of the Slack channel to delete message.
+
+        Returns:
+            str: A confirmation message indicating whether the message
+                was delete successfully or an error message.
+
+        Raises:
+            SlackApiError: If an error occurs while sending the message.
+        """
+        from slack_sdk.errors import SlackApiError
+
+        try:
+            slack_client = self._login_slack()
+            response = slack_client.chat_delete(
+                channel=channel_id, ts=time_stamp
+            )
+            return str(response)
+        except SlackApiError as e:
+            return f"Error creating conversation: {e.response['error']}"
+
+    def get_tools(self) -> List[OpenAIFunction]:
+        r"""Returns a list of OpenAIFunction objects representing the
+        functions in the toolkit.
+
+        Returns:
+            List[OpenAIFunction]: A list of OpenAIFunction objects
+                representing the functions in the toolkit.
+        """
+        return [
+            OpenAIFunction(self.create_slack_channel),
+            OpenAIFunction(self.join_slack_channel),
+            OpenAIFunction(self.leave_slack_channel),
+            OpenAIFunction(self.get_slack_channel_information),
+            OpenAIFunction(self.get_slack_channel_message),
+            OpenAIFunction(self.send_slack_message),
+            OpenAIFunction(self.delete_slack_message),
+        ]
+
+
+SLACK_FUNCS: List[OpenAIFunction] = SlackToolkit().get_tools()