feat: Tavily search integration

camel/toolkits/search_toolkit.py

@@ -305,7 +305,86 @@ def query_wolfram_alpha(self, query: str, is_detailed: bool) -> str:
                 for sub in pod.subpods:
                     result += (sub.plaintext or "None") + '\n'
 
-        return result.rstrip()  # Remove trailing whitespace
+        return result.rstrip()
+
+    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.
+
+        !! A formal test is not done yet !!
+
+        Args:
+            query (str): The query to be searched.
+            num_results (int): The number of search results to retrieve
+                (default is 10).
+            **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).
+
+        Example:
+            {
+                'result_id': 1,
+                'title': 'OpenAI',
+                'description': 'An AI research organization...',
+                'long_description': 'OpenAI is a non-profit...',
+                'url': 'https://www.openai.com',
+                'content': 'OpenAI focuses on AI safety...',
+                'images': ['https://image.url/1.jpg'],
+                'published_date': '2024-09-15'
+            }
+        """
+        from tavily import (
+            InvalidAPIKeyError,
+            MissingAPIKeyError,
+            TavilyClient,
+            UsageLimitExceededError,
+        )
+
+        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 MissingAPIKeyError:
+            return [{"error": "Missing API key."}]
+        except InvalidAPIKeyError:
+            return [{"error": "Invalid API key."}]
+        except UsageLimitExceededError:
+            return [
+                {
+                    "error": "Usage limit exceeded. Check your plan's "
+                    "usage limits."
+                }
+            ]
+        except Exception as e:
+            return [{"error": f"An unexpected error occurred: {e!s}"}]
 
     def get_tools(self) -> List[OpenAIFunction]:
         r"""Returns a list of OpenAIFunction objects representing the
@@ -320,6 +399,7 @@ def get_tools(self) -> List[OpenAIFunction]:
             OpenAIFunction(self.search_google),
             OpenAIFunction(self.search_duckduckgo),
             OpenAIFunction(self.query_wolfram_alpha),
+            OpenAIFunction(self.tavily_search),
         ]
 
 

pyproject.toml

@@ -91,6 +91,7 @@ botocore = { version = "^1.35.3", optional = true }
 nltk = { version = "3.8.1", optional = true }
 praw = { version = "^7.7.1", optional = true }
 textblob = { version = "^0.18.0.post0", optional = true }
+tavily = { version = "^0.5.0", optional = true }
 
 # encoders
 sentence-transformers = { version = "^3.0.1", optional = true }
@@ -114,6 +115,7 @@ cohere = { version = "^4.56", optional = true }
 pytest = { version = "^7", optional = true }
 pytest-asyncio = { version = "^0.23.0", optional = true }
 mock = { version = "^5", optional = true }
+tavily-python = "^0.5.0"
 
 [tool.poetry.extras]
 test = ["pytest", "mock", "pytest-asyncio"]
@@ -133,6 +135,7 @@ search_tools = [
     "duckduckgo-search",
     "wikipedia",
     "wolframalpha",
+    "tavily",
 ]
 
 model-platforms = [
@@ -273,6 +276,7 @@ all = [
     "azure-storage-blob",
     "google-cloud-storage",
     "botocore",
+    "tavily",
 ]
 
 [tool.poetry.group.dev]
@@ -411,5 +415,6 @@ module = [
     "botocore.*",
     "praw",
     "textblob",
+    "tavily",
 ]
 ignore_missing_imports = true