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

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

camel/toolkits/semantic_scholar_toolkit.py

@@ -19,8 +19,10 @@ import requests
 
 from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
+from camel.utils import MCPServer
 
 
+@MCPServer()
 class SemanticScholarToolkit(BaseToolkit):
     r"""A toolkit for interacting with the Semantic Scholar
     API to fetch paper and author data.

camel/toolkits/slack_toolkit.py

@@ -20,6 +20,7 @@ import os
 from typing import TYPE_CHECKING, List, Optional
 
 from camel.toolkits.base import BaseToolkit
+from camel.utils import MCPServer
 
 if TYPE_CHECKING:
     from ssl import SSLContext
@@ -31,6 +32,7 @@ from camel.toolkits import FunctionTool
 logger = logging.getLogger(__name__)
 
 
+@MCPServer()
 class SlackToolkit(BaseToolkit):
     r"""A class representing a toolkit for Slack operations.
 

camel/toolkits/stripe_toolkit.py

@@ -19,9 +19,10 @@ from typing import List, Optional
 
 from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
-from camel.utils import api_keys_required
+from camel.utils import MCPServer, api_keys_required
 
 
+@MCPServer()
 class StripeToolkit(BaseToolkit):
     r"""A class representing a toolkit for Stripe operations.
 

camel/toolkits/sympy_toolkit.py

@@ -18,10 +18,12 @@ from typing import List, Optional
 from camel.logger import get_logger
 from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
+from camel.utils import MCPServer
 
 logger = get_logger(__name__)
 
 
+@MCPServer()
 class SymPyToolkit(BaseToolkit):
     r"""A toolkit for performing symbolic computations using SymPy.
     This includes methods for Algebraic manipulation calculus

camel/toolkits/terminal_toolkit.py

@@ -19,10 +19,12 @@ from typing import Any, Dict, List, Optional
 from camel.logger import get_logger
 from camel.toolkits.base import BaseToolkit
 from camel.toolkits.function_tool import FunctionTool
+from camel.utils import MCPServer
 
 logger = get_logger(__name__)
 
 
+@MCPServer()
 class TerminalToolkit(BaseToolkit):
     r"""A toolkit for terminal operations across multiple operating systems.
 

camel/toolkits/thinking_toolkit.py

@@ -22,11 +22,7 @@ logger = get_logger(__name__)
 
 
 class ThinkingToolkit(BaseToolkit):
-    r"""A toolkit for recording thoughts during reasoning processes.
-
-    Attributes:
-        thoughts (List[str]): A list to store the recorded thoughts.
-    """
+    r"""A toolkit for recording thoughts during reasoning processes."""
 
     def __init__(
         self,
@@ -39,36 +35,196 @@ class ThinkingToolkit(BaseToolkit):
                 (default: :obj: `None`)
         """
         super().__init__(timeout=timeout)
+        self.plans: List[str] = []
+        self.hypotheses: List[str] = []
         self.thoughts: List[str] = []
+        self.contemplations: List[str] = []
+        self.critiques: List[str] = []
+        self.syntheses: List[str] = []
+        self.reflections: List[str] = []
+
+    def plan(self, plan: str) -> str:
+        r"""Use the tool to create a plan or strategy.
+        This tool is for outlining the approach or steps to be taken before
+        starting the actual thinking process.
+
+        Args:
+            plan (str): A forward-looking plan or strategy.
+
+        Returns:
+            str: The recorded plan.
+        """
+        try:
+            logger.debug(f"Plan: {plan}")
+            self.plans.append(plan)
+            return f"Plan: {plan}"
+
+        except Exception as e:
+            error_msg = f"Error recording plan: {e}"
+            logger.error(error_msg)
+            return error_msg
+
+    def hypothesize(self, hypothesis: str) -> str:
+        r"""Use the tool to form a hypothesis or make a prediction.
+        This tool is for making educated guesses or predictions based on
+        the plan, before detailed thinking.
+
+        Args:
+            hypothesis (str): A hypothesis or prediction to test.
+
+        Returns:
+            str: The recorded hypothesis.
+        """
+        try:
+            logger.debug(f"Hypothesis: {hypothesis}")
+            if not self.plans:
+                return "Consider creating a plan before forming hypotheses."
+            self.hypotheses.append(hypothesis)
+            return f"Hypothesis: {hypothesis}"
+
+        except Exception as e:
+            error_msg = f"Error recording hypothesis: {e}"
+            logger.error(error_msg)
+            return error_msg
 
     def think(self, thought: str) -> str:
         r"""Use the tool to think about something.
         It will not obtain new information or change the database, but just
-        append the thought to the log. Use it when complex reasoning or some
-        cache memory is needed.
+        append the thought to the log. Use it for initial thoughts and
+        observations during the execution of the plan.
 
         Args:
             thought (str): A thought to think about.
 
         Returns:
-            str: The full log of thoughts including the new thought.
+            str: The recorded thought.
         """
         try:
             logger.debug(f"Thought: {thought}")
+            if not self.plans:
+                return (
+                    "Consider creating a plan before thinking "
+                    "through the process."
+                )
             self.thoughts.append(thought)
-
-            thoughts = "\n".join([f"- {t}" for t in self.thoughts])
-            return f"Thoughts:\n{thoughts}"
+            return f"Thought: {thought}"
 
         except Exception as e:
             error_msg = f"Error recording thought: {e}"
             logger.error(error_msg)
             return error_msg
 
+    def contemplate(self, contemplation: str) -> str:
+        r"""Use the tool to deeply contemplate an idea or concept.
+        This tool is for deeper, more thorough exploration of thoughts,
+        considering multiple perspectives and implications. It's more
+        comprehensive than basic thinking but more focused than reflection.
+
+        Args:
+            contemplation (str): A deeper exploration of thoughts or concepts.
+
+        Returns:
+            str: The recorded contemplation.
+        """
+        try:
+            logger.debug(f"Contemplation: {contemplation}")
+            if not self.thoughts:
+                return (
+                    "Consider thinking about the topic before "
+                    "deep contemplation."
+                )
+            self.contemplations.append(contemplation)
+            return f"Contemplation: {contemplation}"
+
+        except Exception as e:
+            error_msg = f"Error recording contemplation: {e}"
+            logger.error(error_msg)
+            return error_msg
+
+    def critique(self, critique: str) -> str:
+        r"""Use the tool to critically evaluate current thoughts.
+        This tool is for identifying potential flaws, biases, or
+        weaknesses in the current thinking process.
+
+        Args:
+            critique (str): A critical evaluation of current thoughts.
+
+        Returns:
+            str: The recorded critique.
+        """
+        try:
+            logger.debug(f"Critique: {critique}")
+            if not self.contemplations:
+                return "Consider contemplating deeply before critiquing."
+            self.critiques.append(critique)
+            return f"Critique: {critique}"
+
+        except Exception as e:
+            error_msg = f"Error recording critique: {e}"
+            logger.error(error_msg)
+            return error_msg
+
+    def synthesize(self, synthesis: str) -> str:
+        r"""Use the tool to combine and integrate various thoughts.
+        This tool is for bringing together different thoughts, contemplations,
+        and critiques into a coherent understanding.
+
+        Args:
+            synthesis (str): An integration of multiple thoughts and insights.
+
+        Returns:
+            str: The recorded synthesis.
+        """
+        try:
+            logger.debug(f"Synthesis: {synthesis}")
+            if not self.critiques:
+                return "Consider critiquing thoughts before synthesizing."
+            self.syntheses.append(synthesis)
+            return f"Synthesis: {synthesis}"
+
+        except Exception as e:
+            error_msg = f"Error recording synthesis: {e}"
+            logger.error(error_msg)
+            return error_msg
+
+    def reflect(self, reflection: str) -> str:
+        r"""Use the tool to reflect on the entire process.
+        This tool is for final evaluation of the entire thinking process,
+        including plans, hypotheses, thoughts, contemplations, critiques,
+        and syntheses.
+
+        Args:
+            reflection (str): A comprehensive reflection on the process.
+
+        Returns:
+            str: The recorded reflection.
+        """
+        try:
+            logger.debug(f"Reflection: {reflection}")
+            if not self.syntheses:
+                return (
+                    "Consider synthesizing insights before final reflection."
+                )
+            self.reflections.append(reflection)
+            return f"Reflection: {reflection}"
+
+        except Exception as e:
+            error_msg = f"Error recording reflection: {e}"
+            logger.error(error_msg)
+            return error_msg
+
     def get_tools(self) -> List[FunctionTool]:
         r"""Get all tools in the toolkit.
 
         Returns:
             List[FunctionTool]: A list of tools.
         """
-        return [FunctionTool(self.think)]
+        return [
+            FunctionTool(self.plan),
+            FunctionTool(self.hypothesize),
+            FunctionTool(self.think),
+            FunctionTool(self.contemplate),
+            FunctionTool(self.critique),
+            FunctionTool(self.synthesize),
+            FunctionTool(self.reflect),
+        ]

camel/toolkits/twitter_toolkit.py

@@ -23,7 +23,7 @@ from requests_oauthlib import OAuth1
 from camel.logger import get_logger
 from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
-from camel.utils import api_keys_required
+from camel.utils import MCPServer, api_keys_required
 
 TWEET_TEXT_LIMIT = 280
 
@@ -418,6 +418,7 @@ def _handle_http_error(response: requests.Response) -> str:
         return "Unexpected Exception"
 
 
+@MCPServer()
 class TwitterToolkit(BaseToolkit):
     r"""A class representing a toolkit for Twitter operations.
 

camel/toolkits/video_analysis_toolkit.py

@@ -24,7 +24,7 @@ from camel.messages import BaseMessage
 from camel.models import BaseModelBackend, OpenAIAudioModels
 from camel.toolkits.base import BaseToolkit
 from camel.toolkits.function_tool import FunctionTool
-from camel.utils import dependencies_required
+from camel.utils import MCPServer, dependencies_required
 
 from .video_download_toolkit import (
     VideoDownloaderToolkit,
@@ -77,6 +77,7 @@ similar-looking species or objects
 """
 
 
+@MCPServer()
 class VideoAnalysisToolkit(BaseToolkit):
     r"""A class for analysing videos with vision-language model.
 

camel/toolkits/video_download_toolkit.py

@@ -23,7 +23,7 @@ from PIL import Image
 from camel.logger import get_logger
 from camel.toolkits.base import BaseToolkit
 from camel.toolkits.function_tool import FunctionTool
-from camel.utils import dependencies_required
+from camel.utils import MCPServer, dependencies_required
 
 logger = get_logger(__name__)
 
@@ -54,6 +54,7 @@ def _capture_screenshot(video_file: str, timestamp: float) -> Image.Image:
     return Image.open(io.BytesIO(out))
 
 
+@MCPServer()
 class VideoDownloaderToolkit(BaseToolkit):
     r"""A class for downloading videos and optionally splitting them into
     chunks.

camel/toolkits/weather_toolkit.py

@@ -16,8 +16,10 @@ from typing import List, Literal
 
 from camel.toolkits.base import BaseToolkit
 from camel.toolkits.function_tool import FunctionTool
+from camel.utils import MCPServer
 
 
+@MCPServer()
 class WeatherToolkit(BaseToolkit):
     r"""A class representing a toolkit for interacting with weather data.
 

camel/toolkits/whatsapp_toolkit.py

@@ -19,9 +19,10 @@ import requests
 
 from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
-from camel.utils import retry_on_error
+from camel.utils import MCPServer, retry_on_error
 
 
+@MCPServer()
 class WhatsAppToolkit(BaseToolkit):
     r"""A class representing a toolkit for WhatsApp operations.
 

camel/toolkits/zapier_toolkit.py

@@ -19,9 +19,10 @@ import requests
 
 from camel.toolkits.base import BaseToolkit
 from camel.toolkits.function_tool import FunctionTool
-from camel.utils import api_keys_required, dependencies_required
+from camel.utils import MCPServer, api_keys_required, dependencies_required
 
 
+@MCPServer()
 class ZapierToolkit(BaseToolkit):
     r"""A class representing a toolkit for interacting with Zapier's NLA API.