tavily-python 0.7.12__tar.gz → 0.7.14__tar.gz

{tavily_python-0.7.12 → tavily_python-0.7.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tavily-python
-Version: 0.7.12
+Version: 0.7.14
 Summary: Python wrapper for the Tavily API
 Home-page: https://github.com/tavily-ai/tavily-python
 Author: Tavily AI
@@ -8,7 +8,7 @@ Author-email: support@tavily.com
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests
@@ -32,7 +32,7 @@ Dynamic: summary
 [![License](https://img.shields.io/github/license/tavily-ai/tavily-python)](https://github.com/tavily-ai/tavily-python/blob/main/LICENSE)
 [![CI](https://github.com/tavily-ai/tavily-python/actions/workflows/tests.yml/badge.svg)](https://github.com/tavily-ai/tavily-python/actions)
 
-The Tavily Python wrapper allows for easy interaction with the Tavily API, offering the full range of our search and extract functionalities directly from your Python programs. Easily integrate smart search and content extraction capabilities into your applications, harnessing Tavily's powerful search and extract features.
+The Tavily Python wrapper allows for easy interaction with the Tavily API, offering the full range of our search, extract, crawl, map, and research functionalities directly from your Python programs. Easily integrate smart search, content extraction, and research capabilities into your applications, harnessing Tavily's powerful features.
 
 ## Installing
 
@@ -41,6 +41,7 @@ pip install tavily-python
 ```
 
 # Tavily Search
+
 Search lets you search the web for a given query.
 
 ## Usage
@@ -99,6 +100,7 @@ print(answer)
 This is how you get accurate and concise answers to questions, in one line of code. Perfect for usage by LLMs!
 
 # Tavily Extract
+
 Extract web page content from one or more specified URLs.
 
 ## Usage
@@ -203,6 +205,59 @@ for result in response["results"]:
 
 ```
 
+# Tavily Research
+
+Research lets you create comprehensive research reports on any topic, with automatic source gathering, analysis, and structured output.
+
+## Usage
+
+Below are some code snippets that demonstrate how to interact with our Research API. Each step and component of this code is explained in greater detail in the API Methods section below.
+
+### Creating a research task and retrieving results
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Creating a research task
+response = tavily_client.research(
+    input="Research the latest developments in AI",
+    model="pro",
+    citation_format="apa"
+)
+
+# Step 3. Retrieving the research results
+request_id = response["request_id"]
+result = tavily_client.get_research(request_id)
+
+# Step 4. Printing the research report
+print(f"Status: {result['status']}")
+print(f"Content: {result['content']}")
+print(f"Sources: {len(result['sources'])} sources found")
+```
+
+### Streaming research results
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Creating a streaming research task
+stream = tavily_client.research(
+    input="Research the latest developments in AI",
+    model="pro",
+    stream=True
+)
+
+# Step 3. Processing the stream as it arrives
+for chunk in stream:
+    print(chunk.decode('utf-8'))
+```
+
 ## Documentation
 
 For a complete guide on how to use the different endpoints and their parameters, please head to our [Python API Reference](https://docs.tavily.com/sdk/python/reference).

{tavily_python-0.7.12 → tavily_python-0.7.14}/README.md

@@ -5,7 +5,7 @@
 [![License](https://img.shields.io/github/license/tavily-ai/tavily-python)](https://github.com/tavily-ai/tavily-python/blob/main/LICENSE)
 [![CI](https://github.com/tavily-ai/tavily-python/actions/workflows/tests.yml/badge.svg)](https://github.com/tavily-ai/tavily-python/actions)
 
-The Tavily Python wrapper allows for easy interaction with the Tavily API, offering the full range of our search and extract functionalities directly from your Python programs. Easily integrate smart search and content extraction capabilities into your applications, harnessing Tavily's powerful search and extract features.
+The Tavily Python wrapper allows for easy interaction with the Tavily API, offering the full range of our search, extract, crawl, map, and research functionalities directly from your Python programs. Easily integrate smart search, content extraction, and research capabilities into your applications, harnessing Tavily's powerful features.
 
 ## Installing
 
@@ -14,6 +14,7 @@ pip install tavily-python
 ```
 
 # Tavily Search
+
 Search lets you search the web for a given query.
 
 ## Usage
@@ -72,6 +73,7 @@ print(answer)
 This is how you get accurate and concise answers to questions, in one line of code. Perfect for usage by LLMs!
 
 # Tavily Extract
+
 Extract web page content from one or more specified URLs.
 
 ## Usage
@@ -176,6 +178,59 @@ for result in response["results"]:
 
 ```
 
+# Tavily Research
+
+Research lets you create comprehensive research reports on any topic, with automatic source gathering, analysis, and structured output.
+
+## Usage
+
+Below are some code snippets that demonstrate how to interact with our Research API. Each step and component of this code is explained in greater detail in the API Methods section below.
+
+### Creating a research task and retrieving results
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Creating a research task
+response = tavily_client.research(
+    input="Research the latest developments in AI",
+    model="pro",
+    citation_format="apa"
+)
+
+# Step 3. Retrieving the research results
+request_id = response["request_id"]
+result = tavily_client.get_research(request_id)
+
+# Step 4. Printing the research report
+print(f"Status: {result['status']}")
+print(f"Content: {result['content']}")
+print(f"Sources: {len(result['sources'])} sources found")
+```
+
+### Streaming research results
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Creating a streaming research task
+stream = tavily_client.research(
+    input="Research the latest developments in AI",
+    model="pro",
+    stream=True
+)
+
+# Step 3. Processing the stream as it arrives
+for chunk in stream:
+    print(chunk.decode('utf-8'))
+```
+
 ## Documentation
 
 For a complete guide on how to use the different endpoints and their parameters, please head to our [Python API Reference](https://docs.tavily.com/sdk/python/reference).

{tavily_python-0.7.12 → tavily_python-0.7.14}/setup.py

@@ -5,7 +5,7 @@ with open('README.md', 'r', encoding='utf-8') as f:
 
 setup(
     name='tavily-python',
-    version='0.7.12',
+    version='0.7.14',
     url='https://github.com/tavily-ai/tavily-python',
     author='Tavily AI',
     author_email='support@tavily.com',
@@ -19,5 +19,5 @@ setup(
         'License :: OSI Approved :: MIT License',
         'Operating System :: OS Independent',
     ],
-    python_requires='>=3.6',
+    python_requires='>=3.8',
 )

{tavily_python-0.7.12 → tavily_python-0.7.14}/tavily/async_tavily.py

@@ -1,7 +1,7 @@
 import asyncio
 import json
 import os
-from typing import Literal, Sequence, Optional, List, Union
+from typing import Literal, Sequence, Optional, List, Union, AsyncGenerator, Awaitable
 
 import httpx
 
@@ -66,7 +66,7 @@ class AsyncTavilyClient:
             include_answer: Union[bool, Literal["basic", "advanced"]] = None,
             include_raw_content: Union[bool, Literal["markdown", "text"]] = None,
             include_images: bool = None,
-            timeout: int = 60,
+            timeout: float = 60,
             country: str = None,
             auto_parameters: bool = None,
             include_favicon: bool = None,
@@ -141,7 +141,7 @@ class AsyncTavilyClient:
                      include_answer: Union[bool, Literal["basic", "advanced"]] = None,
                      include_raw_content: Union[bool, Literal["markdown", "text"]] = None,
                      include_images: bool = None,
-                     timeout: int = 60,
+                     timeout: float = 60,
                      country: str = None,
                      auto_parameters: bool = None,
                      include_favicon: bool = None,
@@ -183,7 +183,7 @@ class AsyncTavilyClient:
             include_images: bool = None,
             extract_depth: Literal["basic", "advanced"] = None,
             format: Literal["markdown", "text"] = None,
-            timeout: int = 30,
+            timeout: float = 30,
             include_favicon: bool = None,
             **kwargs
     ) -> dict:
@@ -205,8 +205,6 @@ class AsyncTavilyClient:
         if kwargs:
             data.update(kwargs)
 
-        timeout = min(timeout, 120)
-
         async with self._client_creator() as client:
             try:
                 response = await client.post("/extract", content=json.dumps(data), timeout=timeout)
@@ -239,7 +237,7 @@ class AsyncTavilyClient:
                       include_images: bool = None,
                       extract_depth: Literal["basic", "advanced"] = None,
                       format: Literal["markdown", "text"] = None,
-                      timeout: int = 30,
+                      timeout: float = 30,
                       include_favicon: bool = None,
                       **kwargs,  # Accept custom arguments
                       ) -> dict:
@@ -247,7 +245,6 @@ class AsyncTavilyClient:
         Combined extract method.
         include_favicon: If True, include the favicon in the extraction results.
         """
-        timeout = min(timeout, 120)
         response_dict = await self._extract(urls,
                                             include_images,
                                             extract_depth,
@@ -279,7 +276,7 @@ class AsyncTavilyClient:
                include_images: bool = None,
                extract_depth: Literal["basic", "advanced"] = None,
                format: Literal["markdown", "text"] = None,
-               timeout: int = 60,
+               timeout: float = 150,
                include_favicon: bool = None,
                **kwargs
                ) -> dict:
@@ -300,6 +297,7 @@ class AsyncTavilyClient:
             "include_images": include_images,
             "extract_depth": extract_depth,
             "format": format,
+            "timeout": timeout,
             "include_favicon": include_favicon,
         }
 
@@ -308,8 +306,6 @@ class AsyncTavilyClient:
 
         data = {k: v for k, v in data.items() if v is not None}
 
-        timeout = min(timeout, 120)
-
         async with self._client_creator() as client:
             try:
                 response = await client.post("/crawl", content=json.dumps(data), timeout=timeout)
@@ -350,7 +346,7 @@ class AsyncTavilyClient:
                     extract_depth: Literal["basic", "advanced"] = None,
                     include_images: bool = None,
                     format: Literal["markdown", "text"] = None,
-                    timeout: int = 60,
+                    timeout: float = 150,
                     include_favicon: bool = None,
                     **kwargs
                     ) -> dict:
@@ -358,7 +354,6 @@ class AsyncTavilyClient:
         Combined crawl method.
         
         """
-        timeout = min(timeout, 120)
         response_dict = await self._crawl(url,
                                     max_depth=max_depth,
                                     max_breadth=max_breadth,
@@ -390,7 +385,7 @@ class AsyncTavilyClient:
                exclude_domains: Sequence[str] = None,
                allow_external: bool = None,
                include_images: bool = None,
-               timeout: int = 60,
+               timeout: float = 150,
                **kwargs
                ) -> dict:
         """
@@ -408,6 +403,7 @@ class AsyncTavilyClient:
             "exclude_domains": exclude_domains,
             "allow_external": allow_external,
             "include_images": include_images,
+            "timeout": timeout,
         }
 
         if kwargs:
@@ -415,8 +411,6 @@ class AsyncTavilyClient:
 
         data = {k: v for k, v in data.items() if v is not None}
 
-        timeout = min(timeout, 120)
-
         async with self._client_creator() as client:
             try:
                 response = await client.post("/map", content=json.dumps(data), timeout=timeout)
@@ -455,14 +449,13 @@ class AsyncTavilyClient:
                     exclude_domains: Sequence[str] = None,
                     allow_external: bool = None,
                     include_images: bool = None,
-                    timeout: int = 60,
+                    timeout: float = 150,
                     **kwargs
                     ) -> dict:
         """
         Combined map method.
 
         """
-        timeout = min(timeout, 120)
         response_dict = await self._map(url,
                                     max_depth=max_depth,
                                     max_breadth=max_breadth,
@@ -488,7 +481,7 @@ class AsyncTavilyClient:
                                  include_domains: Sequence[str] = None,
                                  exclude_domains: Sequence[str] = None,
                                  max_tokens: int = 4000,
-                                 timeout: int = 60,
+                                 timeout: float = 60,
                                  country: str = None,
                                  include_favicon: bool = None,
                                  **kwargs,  # Accept custom arguments
@@ -529,7 +522,7 @@ class AsyncTavilyClient:
                          max_results: int = 5,
                          include_domains: Sequence[str] = None,
                          exclude_domains: Sequence[str] = None,
-                         timeout: int = 60,
+                         timeout: float = 60,
                          country: str = None,
                          include_favicon: bool = None,
                          **kwargs,  # Accept custom arguments
@@ -559,7 +552,7 @@ class AsyncTavilyClient:
                                query: str,
                                search_depth: Literal["basic", "advanced"] = "advanced",
                                max_results: int = 5,
-                               timeout: int = 60,
+                               timeout: float = 60,
                                country: str = None,
                                ) -> Sequence[dict]:
         """ Company information search method. Search depth is advanced by default to get the best answer. """
@@ -583,3 +576,173 @@ class AsyncTavilyClient:
         sorted_results = sorted(all_results, key=lambda x: x["score"], reverse=True)[:max_results]
 
         return sorted_results
+
+    def _research(self,
+                  input: str,
+                  model: Literal["mini", "pro", "auto"] = None,
+                  output_schema: dict = None,
+                  stream: bool = False,
+                  citation_format: Literal["numbered", "mla", "apa", "chicago"] = "numbered",
+                  timeout: Optional[float] = None,
+                  **kwargs
+                  ) -> Union[AsyncGenerator[bytes, None], Awaitable[dict]]:
+        """
+        Internal research method to send the request to the API.
+        """
+        data = {
+            "input": input,
+            "model": model,
+            "output_schema": output_schema,
+            "stream": stream,
+            "citation_format": citation_format,
+        }
+
+        data = {k: v for k, v in data.items() if v is not None}
+
+        if kwargs:
+            data.update(kwargs)
+
+        if stream:
+            async def stream_generator() -> AsyncGenerator[bytes, None]:
+                try:
+                    async with self._client_creator() as client:
+                        async with client.stream(
+                            "POST",
+                            "/research",
+                            content=json.dumps(data),
+                            timeout=timeout
+                        ) as response:
+                            if response.status_code != 200:
+                                try:
+                                    error_text = await response.aread()
+                                    error_text = error_text.decode('utf-8') if isinstance(error_text, bytes) else error_text
+                                except Exception:
+                                    error_text = "Unknown error"
+                                
+                                if response.status_code == 429:
+                                    raise UsageLimitExceededError(error_text)
+                                elif response.status_code in [403,432,433]:
+                                    raise ForbiddenError(error_text)
+                                elif response.status_code == 401:
+                                    raise InvalidAPIKeyError(error_text)
+                                elif response.status_code == 400:
+                                    raise BadRequestError(error_text)
+                                else:
+                                    raise Exception(f"Error {response.status_code}: {error_text}")
+                            
+                            async for chunk in response.aiter_bytes():
+                                if chunk:
+                                    yield chunk
+                except httpx.TimeoutException:
+                    raise TimeoutError(timeout)
+                except Exception as e:
+                    raise Exception(f"Error during research stream: {str(e)}")
+            
+            return stream_generator()
+        else:
+            async def _make_request():
+                async with self._client_creator() as client:
+                    try:
+                        response = await client.post("/research", content=json.dumps(data), timeout=timeout)
+                    except httpx.TimeoutException:
+                        raise TimeoutError(timeout)
+
+                    if response.status_code == 200:
+                        return response.json()
+                    else:
+                        detail = ""
+                        try:
+                            detail = response.json().get("detail", {}).get("error", None)
+                        except Exception:
+                            pass
+
+                        if response.status_code == 429:
+                            raise UsageLimitExceededError(detail)
+                        elif response.status_code in [403,432,433]:
+                            raise ForbiddenError(detail)
+                        elif response.status_code == 401:
+                            raise InvalidAPIKeyError(detail)
+                        elif response.status_code == 400:
+                            raise BadRequestError(detail)
+                        else:
+                            raise response.raise_for_status()
+            
+            return _make_request()
+
+    async def research(self,
+                       input: str,
+                       model: Literal["mini", "pro", "auto"] = None,
+                       output_schema: dict = None,
+                       stream: bool = False,
+                       citation_format: Literal["numbered", "mla", "apa", "chicago"] = "numbered",
+                       timeout: Optional[float] = None,
+                       **kwargs
+                       ) -> Union[dict, AsyncGenerator[bytes, None]]:
+        """
+        Research method to create a research task.
+        
+        Args:
+            input: The research task description (required).
+            model: Research depth - must be either 'mini', 'pro', or 'auto'.
+            output_schema: Schema for the 'structured_output' response format (JSON Schema dict).
+            stream: Whether to stream the research task.
+            citation_format: Citation format - must be either 'numbered', 'mla', 'apa', or 'chicago'.
+            timeout: Optional HTTP request timeout in seconds. 
+            **kwargs: Additional custom arguments.
+        
+        Returns:
+            When stream=False: dict - the response dictionary.
+            When stream=True: AsyncGenerator[bytes, None] - iterate over this to get streaming chunks.
+        """
+        result = self._research(
+                input=input,
+                model=model,
+                output_schema=output_schema,
+                stream=stream,
+                citation_format=citation_format,
+                timeout=timeout,
+                **kwargs
+        )
+        if stream:
+            return result # Don't await the result, it's an AsyncGenerator that will be lazy and only execute when iterated over with async for
+        else:
+            return await result 
+
+    async def get_research(self,
+                           request_id: str
+                           ) -> dict:
+        """
+        Get research results by request_id.
+        
+        Args:
+            request_id: The research request ID.
+        
+        Returns:
+            dict: Research response containing request_id, created_at, completed_at, status, content, and sources.
+        """
+        async with self._client_creator() as client:
+            try:
+                response = await client.get(f"/research/{request_id}")
+            except Exception as e:
+                raise Exception(f"Error getting research: {e}")
+
+            if response.status_code in (200, 202):
+                data = response.json()
+                return data
+            else:
+                detail = ""
+                try:
+                    detail = response.json().get("detail", {}).get("error", None)
+                except Exception:
+                    pass
+
+                if response.status_code == 429:
+                    raise UsageLimitExceededError(detail)
+                elif response.status_code in [403,432,433]:
+                    raise ForbiddenError(detail)
+                elif response.status_code == 401:
+                    raise InvalidAPIKeyError(detail)
+                elif response.status_code == 400:
+                    raise BadRequestError(detail)
+                else:
+                    raise response.raise_for_status()

{tavily_python-0.7.12 → tavily_python-0.7.14}/tavily/errors.py

@@ -17,7 +17,7 @@ class InvalidAPIKeyError(Exception):
         super().__init__(message)
 
 class TimeoutError(Exception):
-    def __init__(self, timeout: int):
+    def __init__(self, timeout: float):
         super().__init__(f"Request timed out after {timeout} seconds.")
 
 class MissingAPIKeyError(Exception):

{tavily_python-0.7.12 → tavily_python-0.7.14}/tavily/tavily.py

@@ -2,7 +2,7 @@ import requests
 import json
 import warnings
 import os
-from typing import Literal, Sequence, Optional, List, Union
+from typing import Literal, Sequence, Optional, List, Union, Generator
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from .utils import get_max_items_from_list
 from .errors import UsageLimitExceededError, InvalidAPIKeyError, MissingAPIKeyError, BadRequestError, ForbiddenError, TimeoutError
@@ -49,7 +49,7 @@ class TavilyClient:
                 include_answer: Union[bool, Literal["basic", "advanced"]] = None,
                 include_raw_content: Union[bool, Literal["markdown", "text"]] = None,
                 include_images: bool = None,
-                timeout: int = 60,
+                timeout: float = 60,
                 country: str = None,
                 auto_parameters: bool = None,
                 include_favicon: bool = None,
@@ -126,7 +126,7 @@ class TavilyClient:
                include_answer: Union[bool, Literal["basic", "advanced"]] = None,
                include_raw_content: Union[bool, Literal["markdown", "text"]] = None,
                include_images: bool = None,
-               timeout: int = 60,
+               timeout: float = 60,
                country: str = None,
                auto_parameters: bool = None,
                include_favicon: bool = None,
@@ -135,7 +135,7 @@ class TavilyClient:
         """
         Combined search method.
         """
-        timeout = min(timeout, 120)
+
         response_dict = self._search(query,
                                      search_depth=search_depth,
                                      topic=topic,
@@ -167,7 +167,7 @@ class TavilyClient:
                  include_images: bool = None,
                  extract_depth: Literal["basic", "advanced"] = None,
                  format: Literal["markdown", "text"] = None,
-                 timeout: int = 30,
+                 timeout: float = 30,
                  include_favicon: bool = None,
                  **kwargs
                  ) -> dict:
@@ -188,8 +188,6 @@ class TavilyClient:
         if kwargs:
             data.update(kwargs)
 
-        timeout = min(timeout, 120)
-
         try:
             response = requests.post(self.base_url + "/extract", data=json.dumps(data), headers=self.headers, timeout=timeout, proxies=self.proxies)
         except requests.exceptions.Timeout:
@@ -220,14 +218,13 @@ class TavilyClient:
                 include_images: bool = None,
                 extract_depth: Literal["basic", "advanced"] = None,
                 format: Literal["markdown", "text"] = None,
-                timeout: int = 30,
+                timeout: float = 30,
                 include_favicon: bool = None,
                 **kwargs,  # Accept custom arguments
                 ) -> dict:
         """
         Combined extract method.
         """
-        timeout = min(timeout, 120)
         response_dict = self._extract(urls,
                                       include_images,
                                       extract_depth,
@@ -258,7 +255,7 @@ class TavilyClient:
             include_images: bool = None,
             extract_depth: Literal["basic", "advanced"] = None,
             format: Literal["markdown", "text"] = None,
-            timeout: int = 60,
+            timeout: float = 150,
             include_favicon: bool = None,
             **kwargs
             ) -> dict:
@@ -280,6 +277,7 @@ class TavilyClient:
             "include_images": include_images,
             "extract_depth": extract_depth,
             "format": format,
+            "timeout": timeout,
             "include_favicon": include_favicon,
         }
 
@@ -287,8 +285,6 @@ class TavilyClient:
             data.update(kwargs)
         
         data = {k: v for k, v in data.items() if v is not None}
-    
-        timeout = min(timeout, 120)
 
         try:
             response = requests.post(
@@ -330,7 +326,7 @@ class TavilyClient:
               include_images: bool = None,
               extract_depth: Literal["basic", "advanced"] = None,
               format: Literal["markdown", "text"] = None,
-              timeout: int = 60,
+              timeout: float = 150,
               include_favicon: bool = None,
               **kwargs
               ) -> dict:
@@ -338,7 +334,6 @@ class TavilyClient:
         Combined crawl method.
         include_favicon: If True, include the favicon in the crawl results.
         """
-        timeout = min(timeout, 120)
         response_dict = self._crawl(url,
                                     max_depth=max_depth,
                                     max_breadth=max_breadth,
@@ -370,7 +365,7 @@ class TavilyClient:
             exclude_domains: Sequence[str] = None,
             allow_external: bool = None,
             include_images: bool = None,
-            timeout: int = 60,
+            timeout: float = 150,
             **kwargs
             ) -> dict:
         """
@@ -388,6 +383,7 @@ class TavilyClient:
             "exclude_domains": exclude_domains,
             "allow_external": allow_external,
             "include_images": include_images,
+            "timeout": timeout,
         }
 
         if kwargs:
@@ -395,8 +391,6 @@ class TavilyClient:
         
         data = {k: v for k, v in data.items() if v is not None}
 
-        timeout = min(timeout, 120)
-
         try:
             response = requests.post(
                 self.base_url + "/map", data=json.dumps(data), headers=self.headers, timeout=timeout, proxies=self.proxies)
@@ -435,14 +429,13 @@ class TavilyClient:
               exclude_domains: Sequence[str] = None,
               allow_external: bool = None,
               include_images: bool = None,
-              timeout: int = 60,
+              timeout: float = 150,
               **kwargs
               ) -> dict:
         """
         Combined map method.
         
         """
-        timeout = min(timeout, 120)
         response_dict = self._map(url,
                                     max_depth=max_depth,
                                     max_breadth=max_breadth,
@@ -468,7 +461,7 @@ class TavilyClient:
                            include_domains: Sequence[str] = None,
                            exclude_domains: Sequence[str] = None,
                            max_tokens: int = 4000,
-                           timeout: int = 60,
+                           timeout: float = 60,
                            country: str = None,
                            include_favicon: bool = None,
                            **kwargs,  # Accept custom arguments
@@ -481,7 +474,7 @@ class TavilyClient:
 
         Returns a string of JSON containing the search context up to context limit.
         """
-        timeout = min(timeout, 120)
+
         response_dict = self._search(query,
                                      search_depth=search_depth,
                                      topic=topic,
@@ -510,7 +503,7 @@ class TavilyClient:
                    max_results: int = 5,
                    include_domains: Sequence[str] = None,
                    exclude_domains: Sequence[str] = None,
-                   timeout: int = 60,
+                   timeout: float = 60,
                    country: str = None,
                    include_favicon: bool = None,
                    **kwargs,  # Accept custom arguments
@@ -518,7 +511,6 @@ class TavilyClient:
         """
         Q&A search method. Search depth is advanced by default to get the best answer.
         """
-        timeout = min(timeout, 120)
         response_dict = self._search(query,
                                      search_depth=search_depth,
                                      topic=topic,
@@ -541,11 +533,10 @@ class TavilyClient:
                          search_depth: Literal["basic",
                                                "advanced"] = "advanced",
                          max_results: int = 5,
-                         timeout: int = 60,
+                         timeout: float = 60,
                          country: str = None,
                          ) -> Sequence[dict]:
         """ Company information search method. Search depth is advanced by default to get the best answer. """
-        timeout = min(timeout, 120)
         def _perform_search(topic):
             return self._search(query,
                                 search_depth=search_depth,
@@ -574,6 +565,183 @@ class TavilyClient:
 
         return sorted_results
 
+    def _research(self,
+                  input: str,
+                  model: Literal["mini", "pro", "auto"] = None,
+                  output_schema: dict = None,
+                  stream: bool = False,
+                  citation_format: Literal["numbered", "mla", "apa", "chicago"] = "numbered",
+                  timeout: Optional[float] = None,
+                  **kwargs
+                  ) -> Union[dict, Generator[bytes, None, None]]:
+        """
+        Internal research method to send the request to the API.
+        """
+        data = {
+            "input": input,
+            "model": model,
+            "output_schema": output_schema,
+            "stream": stream,
+            "citation_format": citation_format,
+        }
+
+        data = {k: v for k, v in data.items() if v is not None}
+
+        if kwargs:
+            data.update(kwargs)
+
+        if stream:
+            try:
+                response = requests.post(
+                    self.base_url + "/research",
+                    data=json.dumps(data),
+                    headers=self.headers,
+                    timeout=timeout,
+                    proxies=self.proxies,
+                    stream=True
+                )
+            except requests.exceptions.Timeout:
+                raise TimeoutError(timeout)
+
+            if response.status_code != 200:
+                detail = ""
+                try:
+                    detail = response.json().get("detail", {}).get("error", None)
+                except Exception:
+                    pass
+
+                if response.status_code == 429:
+                    raise UsageLimitExceededError(detail)
+                elif response.status_code in [403,432,433]:
+                    raise ForbiddenError(detail)
+                elif response.status_code == 401:
+                    raise InvalidAPIKeyError(detail)
+                elif response.status_code == 400:
+                    raise BadRequestError(detail)
+                else:
+                    raise response.raise_for_status()
+
+            def stream_generator() -> Generator[bytes, None, None]:
+                try:
+                    for chunk in response.iter_content(chunk_size=None):
+                        if chunk:
+                            yield chunk
+                finally:
+                    response.close()
+
+            return stream_generator()
+        else:
+            try:
+                response = requests.post(
+                    self.base_url + "/research",
+                    data=json.dumps(data),
+                    headers=self.headers,
+                    timeout=timeout,
+                    proxies=self.proxies
+                )
+            except requests.exceptions.Timeout:
+                raise TimeoutError(timeout)
+
+            if response.status_code == 200:
+                return response.json()
+            else:
+                detail = ""
+                try:
+                    detail = response.json().get("detail", {}).get("error", None)
+                except Exception:
+                    pass
+
+                if response.status_code == 429:
+                    raise UsageLimitExceededError(detail)
+                elif response.status_code in [403,432,433]:
+                    raise ForbiddenError(detail)
+                elif response.status_code == 401:
+                    raise InvalidAPIKeyError(detail)
+                elif response.status_code == 400:
+                    raise BadRequestError(detail)
+                else:
+                    raise response.raise_for_status()
+
+    def research(self,
+                 input: str,
+                 model: Literal["mini", "pro", "auto"] = None,
+                 output_schema: dict = None,
+                 stream: bool = False,
+                 citation_format: Literal["numbered", "mla", "apa", "chicago"] = "numbered",
+                 timeout: Optional[float] = None,
+                 **kwargs
+                 ) -> Union[dict, Generator[bytes, None, None]]:
+        """
+        Research method to create a research task.
+        
+        Args:
+            input: The research task or question to investigate (required).
+            model: The model used by the research agent - must be either 'mini', 'pro', or 'auto'.
+            output_schema: Schema for the 'structured_output' response format (JSON Schema dict).
+            stream: Whether to stream the research task.
+            citation_format: Citation format - must be either 'numbered', 'mla', 'apa', or 'chicago'.
+            timeout: Optional HTTP request timeout in seconds. 
+            **kwargs: Additional custom arguments.
+        
+        Returns:
+            dict: Response containing request_id, created_at, status, input, and model.
+        """
+
+        
+        response_dict = self._research(
+            input=input,
+            model=model,
+            output_schema=output_schema,
+            stream=stream,
+            citation_format=citation_format,
+            timeout=timeout,
+            **kwargs
+        )
+
+        return response_dict
+
+    def get_research(self,
+                     request_id: str
+                     ) -> dict:
+        """
+        Get research results by request_id.
+        
+        Args:
+            request_id: The research request ID.
+        
+        Returns:
+            dict: Research response containing request_id, created_at, completed_at, status, content, and sources.
+        """
+        try:
+            response = requests.get(
+                self.base_url + f"/research/{request_id}",
+                headers=self.headers,
+                proxies=self.proxies,
+            )
+        except Exception as e:
+            raise Exception(f"Error getting research: {e}")
+
+        if response.status_code in (200, 202):
+            data = response.json()
+            return data
+        else:
+            detail = ""
+            try:
+                detail = response.json().get("detail", {}).get("error", None)
+            except Exception:
+                pass
+
+            if response.status_code == 429:
+                raise UsageLimitExceededError(detail)
+            elif response.status_code in [403,432,433]:
+                raise ForbiddenError(detail)
+            elif response.status_code == 401:
+                raise InvalidAPIKeyError(detail)
+            elif response.status_code == 400:
+                raise BadRequestError(detail)
+            else:
+                raise response.raise_for_status()
+
 
 class Client(TavilyClient):
     """

{tavily_python-0.7.12 → tavily_python-0.7.14}/tavily_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tavily-python
-Version: 0.7.12
+Version: 0.7.14
 Summary: Python wrapper for the Tavily API
 Home-page: https://github.com/tavily-ai/tavily-python
 Author: Tavily AI
@@ -8,7 +8,7 @@ Author-email: support@tavily.com
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests
@@ -32,7 +32,7 @@ Dynamic: summary
 [![License](https://img.shields.io/github/license/tavily-ai/tavily-python)](https://github.com/tavily-ai/tavily-python/blob/main/LICENSE)
 [![CI](https://github.com/tavily-ai/tavily-python/actions/workflows/tests.yml/badge.svg)](https://github.com/tavily-ai/tavily-python/actions)
 
-The Tavily Python wrapper allows for easy interaction with the Tavily API, offering the full range of our search and extract functionalities directly from your Python programs. Easily integrate smart search and content extraction capabilities into your applications, harnessing Tavily's powerful search and extract features.
+The Tavily Python wrapper allows for easy interaction with the Tavily API, offering the full range of our search, extract, crawl, map, and research functionalities directly from your Python programs. Easily integrate smart search, content extraction, and research capabilities into your applications, harnessing Tavily's powerful features.
 
 ## Installing
 
@@ -41,6 +41,7 @@ pip install tavily-python
 ```
 
 # Tavily Search
+
 Search lets you search the web for a given query.
 
 ## Usage
@@ -99,6 +100,7 @@ print(answer)
 This is how you get accurate and concise answers to questions, in one line of code. Perfect for usage by LLMs!
 
 # Tavily Extract
+
 Extract web page content from one or more specified URLs.
 
 ## Usage
@@ -203,6 +205,59 @@ for result in response["results"]:
 
 ```
 
+# Tavily Research
+
+Research lets you create comprehensive research reports on any topic, with automatic source gathering, analysis, and structured output.
+
+## Usage
+
+Below are some code snippets that demonstrate how to interact with our Research API. Each step and component of this code is explained in greater detail in the API Methods section below.
+
+### Creating a research task and retrieving results
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Creating a research task
+response = tavily_client.research(
+    input="Research the latest developments in AI",
+    model="pro",
+    citation_format="apa"
+)
+
+# Step 3. Retrieving the research results
+request_id = response["request_id"]
+result = tavily_client.get_research(request_id)
+
+# Step 4. Printing the research report
+print(f"Status: {result['status']}")
+print(f"Content: {result['content']}")
+print(f"Sources: {len(result['sources'])} sources found")
+```
+
+### Streaming research results
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Creating a streaming research task
+stream = tavily_client.research(
+    input="Research the latest developments in AI",
+    model="pro",
+    stream=True
+)
+
+# Step 3. Processing the stream as it arrives
+for chunk in stream:
+    print(chunk.decode('utf-8'))
+```
+
 ## Documentation
 
 For a complete guide on how to use the different endpoints and their parameters, please head to our [Python API Reference](https://docs.tavily.com/sdk/python/reference).

{tavily_python-0.7.12 → tavily_python-0.7.14}/tavily_python.egg-info/SOURCES.txt

@@ -17,4 +17,5 @@ tavily_python.egg-info/top_level.txt
 tests/test_crawl.py
 tests/test_errors.py
 tests/test_map.py
+tests/test_research.py
 tests/test_search.py

tavily_python-0.7.14/tests/test_research.py

@@ -0,0 +1,149 @@
+import asyncio
+
+BASE_URL = "https://api.tavily.com"
+
+dummy_queued_response = {
+    "request_id": "test-request-123",
+    "created_at": "2024-01-01T00:00:00Z",
+    "status": "pending",
+    "input": "Research the latest developments in AI",
+    "model": "mini"
+}
+
+dummy_research_response = {
+    "request_id": "test-request-123",
+    "created_at": "2024-01-01T00:00:00Z",
+    "completed_at": "2024-01-01T00:05:00Z",
+    "status": "completed",
+    "content": "This is a comprehensive research report on AI developments...",
+    "sources": [
+        {
+            "title": "AI Research Paper",
+            "url": "https://example.com/ai-paper",
+        }
+    ]
+}
+
+def validate_research_default(request, response):
+    assert request.method == "POST"
+    assert request.url == f"{BASE_URL}/research"
+    assert request.headers["Authorization"] == "Bearer tvly-test"
+    assert request.headers["X-Client-Source"] == "tavily-python"
+    assert request.json().get('input') == "Research the latest developments in AI"
+    assert response == dummy_queued_response
+
+def validate_research_specific(request, response):
+    assert request.method == "POST"
+    assert request.url == f"{BASE_URL}/research"
+    assert request.headers["Authorization"] == "Bearer tvly-test"
+    assert request.headers["X-Client-Source"] == "tavily-python"
+    
+    request_json = request.json()
+    for key, value in {
+        "input": "Research the latest developments in AI",
+        "model": "mini",
+        "citation_format": "apa",
+        "stream": True,
+        "output_schema": {
+            "title": "ResearchReport",
+            "description": "A structured research report",
+            "type": "object",
+            "properties": {
+                "summary": {"type": "string"},
+                "key_points": {"type": "array", "items": {"type": "string"}}
+            }
+        }
+    }.items():
+        assert request_json.get(key) == value
+
+    assert response == dummy_queued_response
+
+def validate_get_research(request, response):
+    assert request.method == "GET"
+    assert request.url == f"{BASE_URL}/research/test-request-123"
+    assert request.headers["Authorization"] == "Bearer tvly-test"
+    assert request.headers["X-Client-Source"] == "tavily-python"
+    assert response == dummy_research_response
+
+def test_sync_research_defaults(sync_interceptor, sync_client):
+    sync_interceptor.set_response(200, json=dummy_queued_response)
+    response = sync_client.research("Research the latest developments in AI")
+    request = sync_interceptor.get_request()
+    validate_research_default(request, response)
+
+def test_sync_research_specific(sync_interceptor, sync_client):
+    sync_interceptor.set_response(200, json=dummy_queued_response)
+    response = sync_client.research(
+        input="Research the latest developments in AI",
+        model="mini",
+        citation_format="apa",
+        stream=True,
+        timeout=300,
+        output_schema={
+            "title": "ResearchReport",
+            "description": "A structured research report",
+            "type": "object",
+            "properties": {
+                "summary": {"type": "string"},
+                "key_points": {"type": "array", "items": {"type": "string"}}
+            }
+        }
+    )
+
+    request = sync_interceptor.get_request()
+    # When stream=True, response is a generator
+    assert hasattr(response, '__iter__') and not isinstance(response, (str, dict))
+    validate_research_specific(request, dummy_queued_response)
+
+def test_sync_get_research(sync_interceptor, sync_client):
+    sync_interceptor.set_response(200, json=dummy_research_response)
+    response = sync_client.get_research("test-request-123")
+    request = sync_interceptor.get_request()
+    validate_get_research(request, response)
+
+def test_async_research_defaults(async_interceptor, async_client):
+    async_interceptor.set_response(200, json=dummy_queued_response)
+    response = asyncio.run(async_client.research("Research the latest developments in AI"))
+    request = async_interceptor.get_request()
+    validate_research_default(request, response)
+
+def test_async_research_specific(async_interceptor, async_client):
+    async_interceptor.set_response(200, json=dummy_queued_response)
+    
+    async def run_test():
+        response = await async_client.research(
+            input="Research the latest developments in AI",
+            model="mini",
+            citation_format="apa",
+            stream=True,
+            timeout=300,
+            output_schema={
+                "title": "ResearchReport",
+                "description": "A structured research report",
+                "type": "object",
+                "properties": {
+                    "summary": {"type": "string"},
+                    "key_points": {"type": "array", "items": {"type": "string"}}
+                }
+            }
+        )
+        # When stream=True, response is an async generator
+        assert hasattr(response, '__aiter__')
+        try:
+            async for chunk in response:
+                # Just consume one chunk to trigger the request
+                break
+        except StopAsyncIteration:
+            pass
+        return response
+    
+    response = asyncio.run(run_test())
+    request = async_interceptor.get_request()
+    validate_research_specific(request, dummy_queued_response)
+
+def test_async_get_research(async_interceptor, async_client):
+    async_interceptor.set_response(200, json=dummy_research_response)
+    response = asyncio.run(async_client.get_research("test-request-123"))
+    request = async_interceptor.get_request()
+    validate_get_research(request, response)
+