camel-ai 0.2.37__py3-none-any.whl → 0.2.38__py3-none-any.whl

camel/toolkits/browser_toolkit.py

@@ -27,6 +27,7 @@ from typing import (
     BinaryIO,
     Dict,
     List,
+    Literal,
     Optional,
     Tuple,
     TypedDict,
@@ -51,37 +52,37 @@ logger = get_logger(__name__)
 TOP_NO_LABEL_ZONE = 20
 
 AVAILABLE_ACTIONS_PROMPT = """
-1. `fill_input_id(identifier: Union[str, int], text: str)`: Fill an input 
+1. `fill_input_id(identifier: Union[str, int], text: str)`: Fill an input
 field (e.g. search box) with the given text and press Enter.
 2. `click_id(identifier: Union[str, int])`: Click an element with the given ID.
-3. `hover_id(identifier: Union[str, int])`: Hover over an element with the 
+3. `hover_id(identifier: Union[str, int])`: Hover over an element with the
 given ID.
-4. `download_file_id(identifier: Union[str, int])`: Download a file with the 
-given ID. It returns the path to the downloaded file. If the file is 
-successfully downloaded, you can stop the simulation and report the path to 
+4. `download_file_id(identifier: Union[str, int])`: Download a file with the
+given ID. It returns the path to the downloaded file. If the file is
+successfully downloaded, you can stop the simulation and report the path to
 the downloaded file for further processing.
 5. `scroll_to_bottom()`: Scroll to the bottom of the page.
 6. `scroll_to_top()`: Scroll to the top of the page.
-7. `scroll_up()`: Scroll up the page. It is suitable when you want to see the 
+7. `scroll_up()`: Scroll up the page. It is suitable when you want to see the
 elements above the current viewport.
-8. `scroll_down()`: Scroll down the page. It is suitable when you want to see 
-the elements below the current viewport. If the webpage does not change, It 
+8. `scroll_down()`: Scroll down the page. It is suitable when you want to see
+the elements below the current viewport. If the webpage does not change, It
 means that the webpage has scrolled to the bottom.
-9. `back()`: Navigate back to the previous page. This is useful when you want 
+9. `back()`: Navigate back to the previous page. This is useful when you want
 to go back to the previous page, as current page is not useful.
-10. `stop()`: Stop the action process, because the task is completed or failed 
-(impossible to find the answer). In this situation, you should provide your 
+10. `stop()`: Stop the action process, because the task is completed or failed
+(impossible to find the answer). In this situation, you should provide your
 answer in your output.
 11. `get_url()`: Get the current URL of the current page.
-12. `find_text_on_page(search_text: str)`: Find the next given text on the 
-current whole page, and scroll the page to the targeted text. It is equivalent 
-to pressing Ctrl + F and searching for the text, and is powerful when you want 
+12. `find_text_on_page(search_text: str)`: Find the next given text on the
+current whole page, and scroll the page to the targeted text. It is equivalent
+to pressing Ctrl + F and searching for the text, and is powerful when you want
 to fast-check whether the current page contains some specific text.
 13. `visit_page(url: str)`: Go to the specific url page.
-14. `click_blank_area()`: Click a blank area of the page to unfocus the 
-current element. It is useful when you have clicked an element but it cannot 
+14. `click_blank_area()`: Click a blank area of the page to unfocus the
+current element. It is useful when you have clicked an element but it cannot
 unfocus itself (e.g. Menu bar) to automatically render the updated webpage.
-15. `ask_question_about_video(question: str)`: Ask a question about the 
+15. `ask_question_about_video(question: str)`: Ask a question about the
 current webpage which contains video, e.g. youtube websites.
 """
 
@@ -424,12 +425,20 @@ def _get_random_color(identifier: int) -> Tuple[int, int, int, int]:
 
 
 class BaseBrowser:
-    def __init__(self, headless=True, cache_dir: Optional[str] = None):
-        r"""Initialize the WebBrowserToolkit instance.
+    def __init__(
+        self,
+        headless=True,
+        cache_dir: Optional[str] = None,
+        channel: Literal["chrome", "msedge", "chromium"] = "chromium",
+    ):
+        r"""Initialize the WebBrowser instance.
 
         Args:
             headless (bool): Whether to run the browser in headless mode.
             cache_dir (Union[str, None]): The directory to store cache files.
+            channel (Literal["chrome", "msedge", "chromium"]): The browser
+                channel to use. Must be one of "chrome", "msedge", or
+                "chromium".
 
         Returns:
             None
@@ -438,9 +447,10 @@ class BaseBrowser:
             sync_playwright,
         )
 
-        self._ensure_browser_installed()
         self.history: list = []
         self.headless = headless
+        self.channel = channel
+        self._ensure_browser_installed()
         self.playwright = sync_playwright().start()
         self.page_history: list = []  # stores the history of visited pages
 
@@ -464,7 +474,9 @@ class BaseBrowser:
     def init(self) -> None:
         r"""Initialize the browser."""
         # Launch the browser, if headless is False, the browser will display
-        self.browser = self.playwright.chromium.launch(headless=self.headless)
+        self.browser = self.playwright.chromium.launch(
+            headless=self.headless, channel=self.channel
+        )
         # Create a new context
         self.context = self.browser.new_context(accept_downloads=True)
         # Create a new page
@@ -558,7 +570,7 @@ class BaseBrowser:
 
         Args:
             scroll_ratio (float): The ratio of viewport height to scroll each
-                step (default: 0.8).
+                step. (default: :obj:`0.8`)
 
         Returns:
             List[str]: A list of paths to the screenshot files.
@@ -925,7 +937,7 @@ class BaseBrowser:
             from playwright.sync_api import sync_playwright
 
             with sync_playwright() as p:
-                browser = p.chromium.launch()
+                browser = p.chromium.launch(channel=self.channel)
                 browser.close()
         except Exception:
             logger.info("Installing Chromium browser...")
@@ -936,7 +948,7 @@ class BaseBrowser:
                         "-m",
                         "playwright",
                         "install",
-                        "chromium",
+                        self.channel,
                     ],
                     check=True,
                     capture_output=True,
@@ -948,7 +960,7 @@ class BaseBrowser:
                             "-m",
                             "playwright",
                             "install-deps",
-                            "chromium",
+                            self.channel,
                         ],
                         check=True,
                         capture_output=True,
@@ -969,6 +981,7 @@ class BrowserToolkit(BaseToolkit):
         self,
         headless: bool = False,
         cache_dir: Optional[str] = None,
+        channel: Literal["chrome", "msedge", "chromium"] = "chromium",
         history_window: int = 5,
         web_agent_model: Optional[BaseModelBackend] = None,
         planning_agent_model: Optional[BaseModelBackend] = None,
@@ -979,15 +992,24 @@ class BrowserToolkit(BaseToolkit):
         Args:
             headless (bool): Whether to run the browser in headless mode.
             cache_dir (Union[str, None]): The directory to store cache files.
+            channel (Literal["chrome", "msedge", "chromium"]): The browser
+                channel to use. Must be one of "chrome", "msedge", or
+                "chromium".
             history_window (int): The window size for storing the history of
                 actions.
             web_agent_model (Optional[BaseModelBackend]): The model backend
                 for the web agent.
             planning_agent_model (Optional[BaseModelBackend]): The model
                 backend for the planning agent.
+            output_language (str): The language to use for output.
+                (default: :obj:`"en`")
         """
 
-        self.browser = BaseBrowser(headless=headless, cache_dir=cache_dir)
+        self.browser = BaseBrowser(
+            headless=headless, cache_dir=cache_dir, channel=channel
+        )
+        # This needs to be called explicitly
+        self.browser.init()
 
         self.history_window = history_window
         self.web_agent_model = web_agent_model
@@ -1026,7 +1048,7 @@ class BrowserToolkit(BaseToolkit):
 
         system_prompt = """
 You are a helpful web agent that can assist users in browsing the web.
-Given a high-level task, you can leverage predefined browser tools to help 
+Given a high-level task, you can leverage predefined browser tools to help
 users achieve their goals.
         """
 
@@ -1037,7 +1059,7 @@ users achieve their goals.
         )
 
         planning_system_prompt = """
-You are a helpful planning agent that can assist users in planning complex 
+You are a helpful planning agent that can assist users in planning complex
 tasks which need multi-step browser interaction.
         """
 
@@ -1058,17 +1080,17 @@ tasks which need multi-step browser interaction.
 
         if detailed_plan is not None:
             detailed_plan_prompt = f"""
-Here is a plan about how to solve the task step-by-step which you must follow: 
+Here is a plan about how to solve the task step-by-step which you must follow:
 <detailed_plan>{detailed_plan}<detailed_plan>
         """
 
         observe_prompt = f"""
-Please act as a web agent to help me complete the following high-level task: 
+Please act as a web agent to help me complete the following high-level task:
 <task>{task_prompt}</task>
-Now, I have made screenshot (only the current viewport, not the full webpage) 
-based on the current browser state, and marked interactive elements in the 
+Now, I have made screenshot (only the current viewport, not the full webpage)
+based on the current browser state, and marked interactive elements in the
 webpage.
-Please carefully examine the requirements of the task, and current state of 
+Please carefully examine the requirements of the task, and current state of
 the browser, and provide the next appropriate action to take.
 
 {detailed_plan_prompt}
@@ -1082,14 +1104,14 @@ Here are the latest {self.history_window} trajectory (at most) you have taken:
 </history>
 
 Your output should be in json format, including the following fields:
-- `observation`: The detailed image description about the current viewport. Do 
-not over-confident about the correctness of the history actions. You should 
-always check the current viewport to make sure the correctness of the next 
+- `observation`: The detailed image description about the current viewport. Do
+not over-confident about the correctness of the history actions. You should
+always check the current viewport to make sure the correctness of the next
 action.
-- `reasoning`: The reasoning about the next action you want to take, and the 
-possible obstacles you may encounter, and how to solve them. Do not forget to 
+- `reasoning`: The reasoning about the next action you want to take, and the
+possible obstacles you may encounter, and how to solve them. Do not forget to
 check the history actions to avoid the same mistakes.
-- `action_code`: The action code you want to take. It is only one step action 
+- `action_code`: The action code you want to take. It is only one step action
 code, without any other texts (such as annotation)
 
 Here is two example of the output:
@@ -1108,37 +1130,37 @@ Here is two example of the output:
 
 Here are some tips for you:
 - Never forget the overall question: **{task_prompt}**
-- Maybe after a certain operation (e.g. click_id), the page content has not 
-changed. You can check whether the action step is successful by looking at the 
-`success` of the action step in the history. If successful, it means that the 
+- Maybe after a certain operation (e.g. click_id), the page content has not
+changed. You can check whether the action step is successful by looking at the
+`success` of the action step in the history. If successful, it means that the
 page content is indeed the same after the click. You need to try other methods.
-- If using one way to solve the problem is not successful, try other ways. 
+- If using one way to solve the problem is not successful, try other ways.
 Make sure your provided ID is correct!
-- Some cases are very complex and need to be achieve by an iterative process. 
-You can use the `back()` function to go back to the previous page to try other 
+- Some cases are very complex and need to be achieve by an iterative process.
+You can use the `back()` function to go back to the previous page to try other
 methods.
-- There are many links on the page, which may be useful for solving the 
-problem. You can use the `click_id()` function to click on the link to see if 
+- There are many links on the page, which may be useful for solving the
+problem. You can use the `click_id()` function to click on the link to see if
 it is useful.
-- Always keep in mind that your action must be based on the ID shown in the 
+- Always keep in mind that your action must be based on the ID shown in the
 current image or viewport, not the ID shown in the history.
-- Do not use `stop()` lightly. Always remind yourself that the image only 
-shows a part of the full page. If you cannot find the answer, try to use 
-functions like `scroll_up()` and `scroll_down()` to check the full content of 
-the webpage before doing anything else, because the answer or next key step 
+- Do not use `stop()` lightly. Always remind yourself that the image only
+shows a part of the full page. If you cannot find the answer, try to use
+functions like `scroll_up()` and `scroll_down()` to check the full content of
+the webpage before doing anything else, because the answer or next key step
 may be hidden in the content below.
-- If the webpage needs human verification, you must avoid processing it. 
+- If the webpage needs human verification, you must avoid processing it.
 Please use `back()` to go back to the previous page, and try other ways.
-- If you have tried everything and still cannot resolve the issue, please stop 
+- If you have tried everything and still cannot resolve the issue, please stop
 the simulation, and report issues you have encountered.
-- Check the history actions carefully, detect whether you have repeatedly made 
+- Check the history actions carefully, detect whether you have repeatedly made
 the same actions or not.
-- When dealing with wikipedia revision history related tasks, you need to 
-think about the solution flexibly. First, adjust the browsing history 
-displayed on a single page to the maximum, and then make use of the 
-find_text_on_page function. This is extremely useful which can quickly locate 
+- When dealing with wikipedia revision history related tasks, you need to
+think about the solution flexibly. First, adjust the browsing history
+displayed on a single page to the maximum, and then make use of the
+find_text_on_page function. This is extremely useful which can quickly locate
 the text you want to find and skip massive amount of useless information.
-- Flexibly use interactive elements like slide down selection bar to filter 
+- Flexibly use interactive elements like slide down selection bar to filter
 out the information you need. Sometimes they are extremely useful.
 ```
         """
@@ -1398,7 +1420,8 @@ Your output should be in json format, including the following fields:
         Args:
             task_prompt (str): The task prompt to solve.
             start_url (str): The start URL to visit.
-            round_limit (int): The round limit to solve the task (default: 12).
+            round_limit (int): The round limit to solve the task.
+                (default: :obj:`12`).
 
         Returns:
             str: The simulation result to the task.

camel/toolkits/openai_agent_toolkit.py

@@ -0,0 +1,131 @@
+# ========= 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. =========
+
+import os
+from typing import List, Optional
+
+from openai import OpenAI
+
+from camel.logger import get_logger
+from camel.models import BaseModelBackend, ModelFactory
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+from camel.types import ModelPlatformType, ModelType
+from camel.utils import api_keys_required
+
+logger = get_logger(__name__)
+
+
+class OpenAIAgentToolkit(BaseToolkit):
+    r"""Toolkit for accessing OpenAI's agent tools including web search and
+    file search.
+
+    Provides access to OpenAI's web search and file search capabilities
+    through the Responses API, allowing agents to retrieve information from
+    the web and search through uploaded files.
+    """
+
+    @api_keys_required(
+        [
+            (None, "OPENAI_API_KEY"),
+        ]
+    )
+    def __init__(
+        self,
+        model: Optional[BaseModelBackend] = None,
+        api_key: Optional[str] = None,
+    ) -> None:
+        r"""Initialize the OpenAI agent toolkit.
+
+        Args:
+            model (BaseModelBackend): The OpenAI model to use for responses.
+                If None, defaults to gpt-4o-mini. (default: :obj:`None`)
+            api_key (str): OpenAI API key. If not provided, will attempt to
+                use OPENAI_API_KEY environment variable. (default: :obj:`None`)
+        """
+        super().__init__()
+        self.api_key = api_key or os.getenv("OPENAI_API_KEY")
+        self.client = OpenAI(api_key=self.api_key)
+        self.model = model or ModelFactory.create(
+            model_platform=ModelPlatformType.OPENAI,
+            model_type=ModelType.GPT_4O_MINI,
+        )
+
+    def web_search(self, query: str) -> str:
+        r"""Perform a web search using OpenAI's web search tool.
+
+        Args:
+            query (str): The search query.
+
+        Returns:
+            str: The search result or error message.
+        """
+        try:
+            response = self.client.responses.create(
+                model=str(self.model.model_type),
+                tools=[{"type": "web_search_preview"}],
+                input=query,
+            )
+            return response.output_text
+
+        except Exception as e:
+            logger.error(f"Web search failed: {e!s}")
+            return f"Web search failed: {e!s}"
+
+    def file_search(
+        self,
+        query: str,
+        vector_store_id: str,
+    ) -> str:
+        r"""Search through files using OpenAI's file search tool.
+
+        Args:
+            query (str): The search query.
+            vector_store_id (str): The vector store ID to search in.
+
+        Returns:
+            str: The search result or error message.
+        """
+        if not vector_store_id.strip():
+            logger.error("Empty vector store ID provided.")
+            return "Empty vector store ID provided, it cannot be empty."
+
+        try:
+            response = self.client.responses.create(
+                model=str(self.model.model_type),
+                tools=[
+                    {
+                        "type": "file_search",
+                        "vector_store_ids": [vector_store_id],
+                    }
+                ],
+                input=query,
+            )
+            return response.output_text
+
+        except Exception as e:
+            logger.error(f"File search failed: {e!s}")
+            return f"File search failed: {e!s}"
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Retrieve available toolkit functions as FunctionTool objects.
+
+        Returns:
+            List[FunctionTool]: Collection of FunctionTool objects representing
+                the available search functions in this toolkit.
+        """
+        return [
+            FunctionTool(self.web_search),
+            FunctionTool(self.file_search),
+        ]

camel/toolkits/searxng_toolkit.py

@@ -0,0 +1,207 @@
+# ========= 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 ClassVar, Dict, List, Optional, Union
+from urllib.parse import urlparse
+
+import requests
+
+from camel.logger import get_logger
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+
+logger = get_logger(__name__)
+
+
+class SearxNGToolkit(BaseToolkit):
+    r"""A toolkit for performing web searches using SearxNG search engine.
+
+    This toolkit provides methods to search the web using SearxNG,
+    a privacy-respecting metasearch engine. It supports customizable
+    search parameters and safe search levels.
+
+    Args:
+        searxng_host (str): The URL of the SearxNG instance to use for
+            searches. Must be a valid HTTP/HTTPS URL.
+        language (str, optional): Search language code for results.
+            (default: :obj:`"en"`)
+        categories (List[str], optional): List of search categories to use.
+            (default: :obj:`None`)
+        time_range (str, optional): Time range filter for search results.Valid
+            values are "day", "week", "month", "year". (default: :obj:`None`)
+        safe_search (int, optional): Safe search level (0: None, 1: Moderate,
+            2: Strict). (default: :obj:`1`)
+
+    Raises:
+        ValueError: If searxng_host is not a valid HTTP/HTTPS URL.
+        ValueError: If safe_search is not in the valid range [0, 2].
+        ValueError: If time_range is provided but not in valid options.
+    """
+
+    # Constants for validation
+    _SAFE_SEARCH_LEVELS: ClassVar[Dict[int, str]] = {
+        0: "Disabled",
+        1: "Moderate",
+        2: "Strict",
+    }
+    _VALID_TIME_RANGES: ClassVar[List[str]] = ["day", "week", "month", "year"]
+    _DEFAULT_CATEGORY: ClassVar[str] = "general"
+
+    def __init__(
+        self,
+        searxng_host: str,
+        language: str = "en",
+        categories: Optional[List[str]] = None,
+        time_range: Optional[str] = None,
+        safe_search: int = 1,
+    ) -> None:
+        self._validate_searxng_host(searxng_host)
+        self._validate_safe_search(safe_search)
+        if time_range is not None:
+            self._validate_time_range(time_range)
+
+        self.searxng_host = searxng_host.rstrip('/')
+        self.language = language
+        self.categories = categories or [self._DEFAULT_CATEGORY]
+        self.time_range = time_range
+        self.safe_search = safe_search
+
+        logger.info(
+            f"Initialized SearxNG toolkit with host: {searxng_host}, "
+            f"safe_search: {self._SAFE_SEARCH_LEVELS[safe_search]}"
+        )
+
+    def _validate_searxng_host(self, url: str) -> None:
+        r"""Validate if the given URL is a proper HTTP/HTTPS URL.
+
+        Args:
+            url (str): The URL to validate.
+
+        Raises:
+            ValueError: If the URL is not valid.
+        """
+        try:
+            result = urlparse(url)
+            is_valid = all(
+                [
+                    result.scheme in ('http', 'https'),
+                    result.netloc,
+                ]
+            )
+            if not is_valid:
+                raise ValueError
+        except Exception:
+            raise ValueError(
+                "Invalid searxng_host URL. Must be a valid HTTP/HTTPS URL."
+            )
+
+    def _validate_safe_search(self, level: int) -> None:
+        r"""Validate if the safe search level is valid.
+
+        Args:
+            level (int): The safe search level to validate.
+
+        Raises:
+            ValueError: If the safe search level is not valid.
+        """
+        if level not in self._SAFE_SEARCH_LEVELS:
+            raise ValueError(
+                f"Invalid safe_search level: {level}. Must be one of: "
+                f"{list(self._SAFE_SEARCH_LEVELS.keys())}"
+            )
+
+    def _validate_time_range(self, time_range: str) -> None:
+        r"""Validate if the time range is valid.
+
+        Args:
+            time_range (str): The time range to validate.
+
+        Raises:
+            ValueError: If the time range is not valid.
+        """
+        if time_range not in self._VALID_TIME_RANGES:
+            raise ValueError(
+                f"Invalid time_range: {time_range}. Must be one of: "
+                f"{self._VALID_TIME_RANGES}"
+            )
+
+    def search(
+        self,
+        query: str,
+        num_results: int = 10,
+        category: Optional[str] = None,
+    ) -> List[Dict[str, str]]:
+        r"""Perform a web search using the configured SearxNG instance.
+
+        Args:
+            query (str): The search query string to execute.
+            num_results (int, optional): Maximum number of results to return.
+                (default: :obj:`10`)
+            category (str, optional): Specific search category to use. If not
+                provided, uses the first category from self.categories.
+                (default: :obj:`None`)
+
+        Returns:
+            List[Dict[str, str]]: List of search results, where each result is
+                dictionary containing 'title', 'link', and 'snippet' keys.
+        """
+        params: Dict[str, Union[str, int]] = {
+            "q": query,
+            "format": "json",
+            "language": self.language,
+            "categories": category or self.categories[0],
+            "pageno": 1,
+            "safe": self.safe_search,
+        }
+
+        if self.time_range:
+            params["time_range"] = self.time_range
+
+        try:
+            logger.debug(f"Sending search request with query: {query}")
+            response = requests.get(
+                f"{self.searxng_host}/search",
+                params=params,  # type: ignore[arg-type]
+                headers={"User-Agent": "camel-ai/searxng-toolkit"},
+            )
+            response.raise_for_status()
+            results = response.json().get("results", [])
+
+            formatted_results = []
+            for result in results[:num_results]:
+                formatted_results.append(
+                    {
+                        "title": result.get("title", ""),
+                        "link": result.get("url", ""),
+                        "snippet": result.get("content", ""),
+                    }
+                )
+
+            logger.debug(f"Retrieved {len(formatted_results)} results")
+            return formatted_results
+
+        except Exception as error:
+            logger.error(f"Search failed: {error!s}")
+            return []
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Get the list of available tools in the toolkit.
+
+        Returns:
+            List[FunctionTool]: A list of FunctionTool objects representing the
+                available functions in the toolkit.
+        """
+        return [
+            FunctionTool(self.search),
+        ]