camel-ai 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

camel/toolkits/notion_toolkit.py

@@ -0,0 +1,279 @@
+# =========== 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 List, Optional, cast
+
+from camel.toolkits import FunctionTool
+from camel.toolkits.base import BaseToolkit
+
+
+def get_plain_text_from_rich_text(rich_text: List[dict]) -> str:
+    r"""Extracts plain text from a list of rich text elements.
+
+    Args:
+        rich_text: A list of dictionaries representing rich text elements.
+            Each dictionary should contain a key named "plain_text" with
+            the plain text content.
+
+    Returns:
+        str: A string containing the combined plain text from all elements,
+            joined together.
+    """
+    plain_texts = [element.get("plain_text", "") for element in rich_text]
+    return "".join(plain_texts)
+
+
+def get_media_source_text(block: dict) -> str:
+    r"""Extracts the source URL and optional caption from a
+    Notion media block.
+
+    Args:
+        block: A dictionary representing a Notion media block.
+
+    Returns:
+        A string containing the source URL and caption (if available),
+            separated by a colon.
+    """
+    block_type = block.get("type", "Unknown Type")
+    block_content = block.get(block_type, {})
+
+    # Extract source URL based on available types
+    source = (
+        block_content.get("external", {}).get("url")
+        or block_content.get("file", {}).get("url")
+        or block_content.get(
+            "url", "[Missing case for media block types]: " + block_type
+        )
+    )
+
+    # Extract caption if available
+    caption_elements = block_content.get("caption", [])
+    if caption_elements:
+        caption = get_plain_text_from_rich_text(caption_elements)
+        return f"{caption}: {source}"
+
+    return source
+
+
+class NotionToolkit(BaseToolkit):
+    r"""A toolkit for retrieving information from the user's notion pages.
+
+    Attributes:
+        notion_token (Optional[str], optional): The notion_token used to
+            interact with notion APIs.(default: :obj:`None`)
+        notion_client (module): The notion module for interacting with
+            the notion APIs.
+    """
+
+    def __init__(
+        self,
+        notion_token: Optional[str] = None,
+    ) -> None:
+        r"""Initializes the NotionToolkit.
+
+        Args:
+            notion_token (Optional[str], optional): The optional notion_token
+                used to interact with notion APIs.(default: :obj:`None`)
+        """
+        from notion_client import Client
+
+        self.notion_token = notion_token or os.environ.get("NOTION_TOKEN")
+        self.notion_client = Client(auth=self.notion_token)
+
+    def list_all_users(self) -> List[dict]:
+        r"""Lists all users via the Notion integration.
+
+        Returns:
+            List[dict]: A list of user objects with type, name, and workspace.
+        """
+        all_users_info: List[dict] = []
+        cursor = None
+
+        while True:
+            response = cast(
+                dict,
+                self.notion_client.users.list(start_cursor=cursor),
+            )
+            all_users_info.extend(response["results"])
+
+            if not response["has_more"]:
+                break
+
+            cursor = response["next_cursor"]
+
+        formatted_users = [
+            {
+                "type": user["type"],
+                "name": user["name"],
+                "workspace": user.get(user.get("type"), {}).get(
+                    "workspace_name", ""
+                ),
+            }
+            for user in all_users_info
+        ]
+
+        return formatted_users
+
+    def list_all_pages(self) -> List[dict]:
+        r"""Lists all pages in the Notion workspace.
+
+        Returns:
+            List[dict]: A list of page objects with title and id.
+        """
+        all_pages_info: List[dict] = []
+        cursor = None
+
+        while True:
+            response = cast(
+                dict,
+                self.notion_client.search(
+                    filter={"property": "object", "value": "page"},
+                    start_cursor=cursor,
+                ),
+            )
+            all_pages_info.extend(response["results"])
+
+            if not response["has_more"]:
+                break
+
+            cursor = response["next_cursor"]
+
+        formatted_pages = [
+            {
+                "id": page.get("id"),
+                "title": next(
+                    (
+                        title.get("text", {}).get("content")
+                        for title in page["properties"]
+                        .get("title", {})
+                        .get("title", [])
+                        if title["type"] == "text"
+                    ),
+                    None,
+                ),
+            }
+            for page in all_pages_info
+        ]
+
+        return formatted_pages
+
+    def get_notion_block_text_content(self, block_id: str) -> str:
+        r"""Retrieves the text content of a Notion block.
+
+        Args:
+            block_id (str): The ID of the Notion block to retrieve.
+
+        Returns:
+            str: The text content of a Notion block, containing all
+                the sub blocks.
+        """
+        blocks: List[dict] = []
+        cursor = None
+
+        while True:
+            response = cast(
+                dict,
+                self.notion_client.blocks.children.list(
+                    block_id=block_id, start_cursor=cursor
+                ),
+            )
+            blocks.extend(response["results"])
+
+            if not response["has_more"]:
+                break
+
+            cursor = response["next_cursor"]
+
+        block_text_content = " ".join(
+            [self.get_text_from_block(sub_block) for sub_block in blocks]
+        )
+
+        return block_text_content
+
+    def get_text_from_block(self, block: dict) -> str:
+        r"""Extracts plain text from a Notion block based on its type.
+
+        Args:
+            block (dict): A dictionary representing a Notion block.
+
+        Returns:
+            str: A string containing the extracted plain text and block type.
+        """
+        # Get rich text for supported block types
+        if block.get(block.get("type"), {}).get("rich_text"):
+            # Empty string if it's an empty line
+            text = get_plain_text_from_rich_text(
+                block[block["type"]]["rich_text"]
+            )
+        else:
+            # Handle block types by case
+            block_type = block.get("type")
+            if block_type == "unsupported":
+                text = "[Unsupported block type]"
+            elif block_type == "bookmark":
+                text = block["bookmark"]["url"]
+            elif block_type == "child_database":
+                text = block["child_database"]["title"]
+                # Use other API endpoints for full database data
+            elif block_type == "child_page":
+                text = block["child_page"]["title"]
+            elif block_type in ("embed", "video", "file", "image", "pdf"):
+                text = get_media_source_text(block)
+            elif block_type == "equation":
+                text = block["equation"]["expression"]
+            elif block_type == "link_preview":
+                text = block["link_preview"]["url"]
+            elif block_type == "synced_block":
+                if block["synced_block"].get("synced_from"):
+                    text = (
+                        f"This block is synced with a block with ID: "
+                        f"""
+                        {block['synced_block']['synced_from']
+                        [block['synced_block']['synced_from']['type']]}
+                        """
+                    )
+                else:
+                    text = (
+                        "Source sync block that another"
+                        + "blocked is synced with."
+                    )
+            elif block_type == "table":
+                text = f"Table width: {block['table']['table_width']}"
+                # Fetch children for full table data
+            elif block_type == "table_of_contents":
+                text = f"ToC color: {block['table_of_contents']['color']}"
+            elif block_type in ("breadcrumb", "column_list", "divider"):
+                text = "No text available"
+            else:
+                text = "[Needs case added]"
+
+        # Query children for blocks with children
+        if block.get("has_children"):
+            text += self.get_notion_block_text_content(block["id"])
+
+        return text
+
+    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.list_all_pages),
+            FunctionTool(self.list_all_users),
+            FunctionTool(self.get_notion_block_text_content),
+        ]

camel/toolkits/search_toolkit.py

@@ -12,10 +12,14 @@
 # limitations under the License.
 # =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
 import os
-from typing import Any, Dict, List
+import xml.etree.ElementTree as ET
+from typing import Any, Dict, List, Union
+
+import requests
 
 from camel.toolkits.base import BaseToolkit
 from camel.toolkits.function_tool import FunctionTool
+from camel.utils import api_keys_required, dependencies_required
 
 
 class SearchToolkit(BaseToolkit):
@@ -25,6 +29,7 @@ class SearchToolkit(BaseToolkit):
     search engines like Google, DuckDuckGo, Wikipedia and Wolfram Alpha.
     """
 
+    @dependencies_required("wikipedia")
     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
@@ -37,13 +42,7 @@ class SearchToolkit(BaseToolkit):
             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`."
-            )
+        import wikipedia
 
         result: str
 
@@ -64,6 +63,7 @@ class SearchToolkit(BaseToolkit):
 
         return result
 
+    @dependencies_required("duckduckgo_search")
     def search_duckduckgo(
         self, query: str, source: str = "text", max_results: int = 5
     ) -> List[Dict[str, Any]]:
@@ -151,6 +151,7 @@ class SearchToolkit(BaseToolkit):
         # If no answer found, return an empty list
         return responses
 
+    @api_keys_required("GOOGLE_API_KEY", "SEARCH_ENGINE_ID")
     def search_google(
         self, query: str, num_result_pages: int = 5
     ) -> List[Dict[str, Any]]:
@@ -251,7 +252,10 @@ class SearchToolkit(BaseToolkit):
         # If no answer found, return an empty list
         return responses
 
-    def query_wolfram_alpha(self, query: str, is_detailed: bool) -> str:
+    @dependencies_required("wolframalpha")
+    def query_wolfram_alpha(
+        self, query: str, is_detailed: bool = False
+    ) -> Union[str, Dict[str, Any]]:
         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
@@ -259,19 +263,16 @@ class SearchToolkit(BaseToolkit):
 
         Args:
             query (str): The query to send to Wolfram Alpha.
-            is_detailed (bool): Whether to include additional details in the
-                result.
+            is_detailed (bool): Whether to include additional details
+                including step by step information in the result.
+                (default::obj:`False`)
 
         Returns:
-            str: The result from Wolfram Alpha, formatted as a string.
+            Union[str, Dict[str, Any]]: The result from Wolfram Alpha.
+                Returns a string if `is_detailed` is False, otherwise returns
+                a dictionary with detailed information.
         """
-        try:
-            import wolframalpha
-        except ImportError:
-            raise ImportError(
-                "Please install `wolframalpha` first. You can install it by"
-                " running `pip install wolframalpha`."
-            )
+        import wolframalpha
 
         WOLFRAMALPHA_APP_ID = os.environ.get('WOLFRAMALPHA_APP_ID')
         if not WOLFRAMALPHA_APP_ID:
@@ -284,28 +285,154 @@ class SearchToolkit(BaseToolkit):
         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
+            return f"Wolfram Alpha wasn't able to answer it. Error: {e}"
 
-        result = f"Assumption:\n{assumption}\n\nAnswer:\n{answer}"
+        pased_result = self._parse_wolfram_result(res)
 
-        # 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'
+            step_info = self._get_wolframalpha_step_by_step_solution(
+                WOLFRAMALPHA_APP_ID, query
+            )
+            pased_result["steps"] = step_info
+            return pased_result
+
+        return pased_result["final_answer"]
+
+    def _parse_wolfram_result(self, result) -> Dict[str, Any]:
+        r"""Parses a Wolfram Alpha API result into a structured dictionary
+        format.
+
+        Args:
+            result: The API result returned from a Wolfram Alpha
+                query, structured with multiple pods, each containing specific
+                information related to the query.
+
+        Returns:
+            dict: A structured dictionary with the original query and the
+                final answer.
+        """
+
+        # Extract the original query
+        query = result.get('@inputstring', '')
+
+        # Initialize a dictionary to hold structured output
+        output = {"query": query, "pod_info": [], "final_answer": None}
+
+        # Loop through each pod to extract the details
+        for pod in result.get('pod', []):
+            pod_info = {
+                "title": pod.get('@title', ''),
+                "description": pod.get('subpod', {}).get('plaintext', ''),
+                "image_url": pod.get('subpod', {})
+                .get('img', {})
+                .get('@src', ''),
+            }
+
+            # Add to steps list
+            output["pod_info"].append(pod_info)
+
+            # Get final answer
+            if pod.get('@primary', False):
+                output["final_answer"] = pod_info["description"]
 
-        return result.rstrip()  # Remove trailing whitespace
+        return output
+
+    def _get_wolframalpha_step_by_step_solution(
+        self, app_id: str, query: str
+    ) -> dict:
+        r"""Retrieve a step-by-step solution from the Wolfram Alpha API for a
+        given query.
+
+        Args:
+            app_id (str): Your Wolfram Alpha API application ID.
+            query (str): The mathematical or computational query to solve.
+
+        Returns:
+            dict: The step-by-step solution response text from the Wolfram
+                Alpha API.
+        """
+        # Define the base URL
+        url = "https://api.wolframalpha.com/v2/query"
+
+        # Set up the query parameters
+        params = {
+            'appid': app_id,
+            'input': query,
+            'podstate': ['Result__Step-by-step solution', 'Show all steps'],
+            'format': 'plaintext',
+        }
+
+        # Send the request
+        response = requests.get(url, params=params)
+        root = ET.fromstring(response.text)
+
+        # Extracting step-by-step hints and removing 'Hint: |'
+        steps = []
+        for subpod in root.findall(
+            ".//pod[@title='Results']//subpod[stepbystepcontenttype='SBSHintStep']//plaintext"
+        ):
+            if subpod.text:
+                step_text = subpod.text.strip()
+                cleaned_step = step_text.replace('Hint: |', '').strip()
+                steps.append(cleaned_step)
+
+        # Structuring the steps into a dictionary
+        structured_steps = {}
+        for i, step in enumerate(steps, start=1):
+            structured_steps[f"step{i}"] = step
+
+        return structured_steps
+
+    def tavily_search(
+        self, query: str, num_results: int = 5, **kwargs
+    ) -> List[Dict[str, Any]]:
+        r"""Use Tavily Search API to search information for the given query.
+
+        Args:
+            query (str): The query to be searched.
+            num_results (int): The number of search results to retrieve
+                (default is `5`).
+            **kwargs: Additional optional parameters supported by Tavily's API:
+                - search_depth (str): "basic" or "advanced" search depth.
+                - topic (str): The search category, e.g., "general" or "news."
+                - days (int): Time frame in days for news-related searches.
+                - max_results (int): Max number of results to return
+                  (overrides `num_results`).
+                See https://docs.tavily.com/docs/python-sdk/tavily-search/
+                api-reference for details.
+
+        Returns:
+            List[Dict[str, Any]]: A list of dictionaries representing search
+                results. Each dictionary contains:
+                - 'result_id' (int): The result's index.
+                - 'title' (str): The title of the result.
+                - 'description' (str): A brief description of the result.
+                - 'long_description' (str): Detailed information, if available.
+                - 'url' (str): The URL of the result.
+                - 'content' (str): Relevant content from the search result.
+                - 'images' (list): A list of related images (if
+                  `include_images` is True).
+                - 'published_date' (str): Publication date for news topics
+                  (if available).
+        """
+        from tavily import TavilyClient  # type: ignore[import-untyped]
+
+        Tavily_API_KEY = os.getenv("TAVILY_API_KEY")
+        if not Tavily_API_KEY:
+            raise ValueError(
+                "`TAVILY_API_KEY` not found in environment variables. "
+                "Get `TAVILY_API_KEY` here: `https://www.tavily.com/api/`."
+            )
+
+        client = TavilyClient(Tavily_API_KEY)
+
+        try:
+            results = client.search(query, max_results=num_results, **kwargs)
+            return results
+        except Exception as e:
+            return [{"error": f"An unexpected error occurred: {e!s}"}]
 
     def get_tools(self) -> List[FunctionTool]:
         r"""Returns a list of FunctionTool objects representing the
@@ -320,6 +447,7 @@ class SearchToolkit(BaseToolkit):
             FunctionTool(self.search_google),
             FunctionTool(self.search_duckduckgo),
             FunctionTool(self.query_wolfram_alpha),
+            FunctionTool(self.tavily_search),
         ]