tavily-python 0.6.0__tar.gz → 0.7.0__tar.gz

tavily_python-0.7.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: tavily-python
+Version: 0.7.0
+Summary: Python wrapper for the Tavily API
+Home-page: https://github.com/tavily-ai/tavily-python
+Author: Tavily AI
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: tiktoken>=0.5.1
+Requires-Dist: httpx
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Tavily Python Wrapper
+
+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.
+
+## Installing
+
+```bash
+pip install tavily-python
+```
+
+# Tavily Search
+Search lets you search the web for a given query.
+
+## Usage
+
+Below are some code snippets that show you how to interact with our search API. The different steps and components of this code are explained in more detail in the API Methods section further down.
+
+### Getting and printing the full Search API response
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Executing a simple search query
+response = tavily_client.search("Who is Leo Messi?")
+
+# Step 3. That's it! You've done a Tavily Search!
+print(response)
+```
+
+This is equivalent to directly querying our REST API.
+
+### Generating context for a RAG Application
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Executing a context search query
+context = tavily_client.get_search_context(query="What happened during the Burning Man floods?")
+
+# Step 3. That's it! You now have a context string that you can feed directly into your RAG Application
+print(context)
+```
+
+This is how you can generate precise and fact-based context for your RAG application in one line of code.
+
+### Getting a quick answer to a question
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Executing a Q&A search query
+answer = tavily_client.qna_search(query="Who is Leo Messi?")
+
+# Step 3. That's it! Your question has been answered!
+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
+
+Below are some code snippets that demonstrate how to interact with our Extract API. Each step and component of this code is explained in greater detail in the API Methods section below.
+
+### Extracting Raw Content from Multiple URLs using Tavily Extract API
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Defining the list of URLs to extract content from
+urls = [
+    "https://en.wikipedia.org/wiki/Artificial_intelligence",
+    "https://en.wikipedia.org/wiki/Machine_learning",
+    "https://en.wikipedia.org/wiki/Data_science",
+    "https://en.wikipedia.org/wiki/Quantum_computing",
+    "https://en.wikipedia.org/wiki/Climate_change"
+] # You can provide up to 20 URLs simultaneously
+
+# Step 3. Executing the extract request
+response = tavily_client.extract(urls=urls, include_images=True)
+
+# Step 4. Printing the extracted raw content
+for result in response["results"]:
+    print(f"URL: {result['url']}")
+    print(f"Raw Content: {result['raw_content']}")
+    print(f"Images: {result['images']}\n")
+
+# Note that URLs that could not be extracted will be stored in response["failed_results"]
+```
+
+# Tavily Crawl (Invitational Beta)
+
+Crawl lets you traverse a site like a graph starting from a base URL.
+
+> **Note**: Crawl is currently available on an invite-only basis. For more information, please visit [crawl.tavily.com](https://crawl.tavily.com)
+
+## Usage
+
+Below are some code snippets that demonstrate how to interact with our Crawl API. Each step and component of this code is explained in greater detail in the API Methods section below.
+
+### Crawling a website with a query
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Defining the starting URL and query
+start_url = "https://wikipedia.org/wiki/Lemon"
+search_term = "Find all pages on citrus fruits"
+
+# Step 3. Executing the crawl request with a query to surface only pages containing “remote”
+response = tavily_client.crawl(
+    url=start_url,
+    max_depth=3,
+    limit=50,
+    query=search_term
+)
+
+# Step 4. Printing pages matching the query
+for result in response["results"]:
+    print(f"URL: {result['url']}")
+    print(f"Snippet: {result['raw_content'][:200]}...\n")
+
+```
+
+## 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).
+
+## Cost
+
+Tavily is free for personal use for up to 1,000 credits per month.
+Head to the [Credits & Pricing](https://docs.tavily.com/documentation/api-credits) in our documentation to learn more about how many API credits each request costs.
+
+## License
+
+This project is licensed under the terms of the MIT license.
+
+## Contact
+
+If you are encountering issues while using Tavily, please email us at support@tavily.com. We'll be happy to help you.
+
+If you want to stay updated on the latest Tavily news and releases, head to our [Developer Community](https://community.tavily.com) to learn more!

tavily_python-0.7.0/README.md

@@ -0,0 +1,159 @@
+# Tavily Python Wrapper
+
+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.
+
+## Installing
+
+```bash
+pip install tavily-python
+```
+
+# Tavily Search
+Search lets you search the web for a given query.
+
+## Usage
+
+Below are some code snippets that show you how to interact with our search API. The different steps and components of this code are explained in more detail in the API Methods section further down.
+
+### Getting and printing the full Search API response
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Executing a simple search query
+response = tavily_client.search("Who is Leo Messi?")
+
+# Step 3. That's it! You've done a Tavily Search!
+print(response)
+```
+
+This is equivalent to directly querying our REST API.
+
+### Generating context for a RAG Application
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Executing a context search query
+context = tavily_client.get_search_context(query="What happened during the Burning Man floods?")
+
+# Step 3. That's it! You now have a context string that you can feed directly into your RAG Application
+print(context)
+```
+
+This is how you can generate precise and fact-based context for your RAG application in one line of code.
+
+### Getting a quick answer to a question
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Executing a Q&A search query
+answer = tavily_client.qna_search(query="Who is Leo Messi?")
+
+# Step 3. That's it! Your question has been answered!
+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
+
+Below are some code snippets that demonstrate how to interact with our Extract API. Each step and component of this code is explained in greater detail in the API Methods section below.
+
+### Extracting Raw Content from Multiple URLs using Tavily Extract API
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Defining the list of URLs to extract content from
+urls = [
+    "https://en.wikipedia.org/wiki/Artificial_intelligence",
+    "https://en.wikipedia.org/wiki/Machine_learning",
+    "https://en.wikipedia.org/wiki/Data_science",
+    "https://en.wikipedia.org/wiki/Quantum_computing",
+    "https://en.wikipedia.org/wiki/Climate_change"
+] # You can provide up to 20 URLs simultaneously
+
+# Step 3. Executing the extract request
+response = tavily_client.extract(urls=urls, include_images=True)
+
+# Step 4. Printing the extracted raw content
+for result in response["results"]:
+    print(f"URL: {result['url']}")
+    print(f"Raw Content: {result['raw_content']}")
+    print(f"Images: {result['images']}\n")
+
+# Note that URLs that could not be extracted will be stored in response["failed_results"]
+```
+
+# Tavily Crawl (Invitational Beta)
+
+Crawl lets you traverse a site like a graph starting from a base URL.
+
+> **Note**: Crawl is currently available on an invite-only basis. For more information, please visit [crawl.tavily.com](https://crawl.tavily.com)
+
+## Usage
+
+Below are some code snippets that demonstrate how to interact with our Crawl API. Each step and component of this code is explained in greater detail in the API Methods section below.
+
+### Crawling a website with a query
+
+```python
+from tavily import TavilyClient
+
+# Step 1. Instantiating your TavilyClient
+tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Step 2. Defining the starting URL and query
+start_url = "https://wikipedia.org/wiki/Lemon"
+search_term = "Find all pages on citrus fruits"
+
+# Step 3. Executing the crawl request with a query to surface only pages containing “remote”
+response = tavily_client.crawl(
+    url=start_url,
+    max_depth=3,
+    limit=50,
+    query=search_term
+)
+
+# Step 4. Printing pages matching the query
+for result in response["results"]:
+    print(f"URL: {result['url']}")
+    print(f"Snippet: {result['raw_content'][:200]}...\n")
+
+```
+
+## 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).
+
+## Cost
+
+Tavily is free for personal use for up to 1,000 credits per month.
+Head to the [Credits & Pricing](https://docs.tavily.com/documentation/api-credits) in our documentation to learn more about how many API credits each request costs.
+
+## License
+
+This project is licensed under the terms of the MIT license.
+
+## Contact
+
+If you are encountering issues while using Tavily, please email us at support@tavily.com. We'll be happy to help you.
+
+If you want to stay updated on the latest Tavily news and releases, head to our [Developer Community](https://community.tavily.com) to learn more!

{tavily_python-0.6.0 → tavily_python-0.7.0}/setup.py

@@ -5,7 +5,7 @@ with open('README.md', 'r', encoding='utf-8') as f:
 
 setup(
     name='tavily-python',
-    version='0.6.0',
+    version='0.7.0',
     url='https://github.com/tavily-ai/tavily-python',
     author='Tavily AI',
     author_email='support@tavily.com',

{tavily_python-0.6.0 → tavily_python-0.7.0}/tavily/async_tavily.py

@@ -222,17 +222,17 @@ class AsyncTavilyClient:
     
     async def _crawl(self,
                url: str,
-               max_depth: int = 1,
-               max_breadth: int = 20,
-               limit: int = 50,
+               max_depth: int = None,
+               max_breadth: int = None,
+               limit: int = None,
                query: str = None,
                select_paths: Sequence[str] = None,
                select_domains: Sequence[str] = None,
-               allow_external: bool = False,
+               allow_external: bool = None,
                categories: Sequence[Literal["Documentation", "Blog", "About", "Contact", "Pricing",
                                             "Careers", "E-Commerce", "Developers", "Partners",
                                             "Downloads", "Media", "Events"]] = None,
-               extract_depth: Literal["basic", "advanced"] = "basic",
+               extract_depth: Literal["basic", "advanced"] = None,
                timeout: int = 60,
                **kwargs
                ) -> dict:
@@ -255,6 +255,8 @@ class AsyncTavilyClient:
         if kwargs:
             data.update(kwargs)
 
+        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:
@@ -281,17 +283,17 @@ class AsyncTavilyClient:
 
     async def crawl(self,
                     url: str,
-                    max_depth: int = 1,
-                    max_breadth: int = 20,
-                    limit: int = 50,
+                    max_depth: int = None,
+                    max_breadth: int = None,
+                    limit: int = None,
                     query: str = None,
                     select_paths: Sequence[str] = None,
                     select_domains: Sequence[str] = None,
-                    allow_external: bool = False,
+                    allow_external: bool = None,
                     categories: Sequence[Literal["Documentation", "Blog", "About", "Contact", "Pricing",
                                            "Careers", "E-Commerce", "Developers", "Partners",
                                            "Downloads", "Media", "Events"]] = None,
-                    extract_depth: Literal["basic", "advanced"] = "basic",
+                    extract_depth: Literal["basic", "advanced"] = None,
                     timeout: int = 60,
                     **kwargs
                     ) -> dict:
@@ -312,17 +314,97 @@ class AsyncTavilyClient:
                                     timeout=timeout,
                                     **kwargs)
 
-        data = response_dict.get("data", [])
-        metadata = response_dict.get("metadata", {})
-        config = response_dict.get("config", {})
-        success = response_dict.get("success", False)
-        error = response_dict.get("error", None)
-
-        response_dict["data"] = data
-        response_dict["metadata"] = metadata
-        response_dict["config"] = config
-        response_dict["success"] = success
-        response_dict["error"] = error
+        return response_dict
+    
+    async def _map(self,
+               url: str,
+               max_depth: int = None,
+               max_breadth: int = None,
+               limit: int = None,
+               query: str = None,
+               select_paths: Sequence[str] = None,
+               select_domains: Sequence[str] = None,
+               allow_external: bool = None,
+               categories: Sequence[Literal["Documentation", "Blog", "About", "Contact", "Pricing",
+                                            "Careers", "E-Commerce", "Developers", "Partners",
+                                            "Downloads", "Media", "Events"]] = None,
+               timeout: int = 60,
+               **kwargs
+               ) -> dict:
+        """
+        Internal map method to send the request to the API.
+        """
+        data = {
+            "url": url,
+            "max_depth": max_depth,
+            "max_breadth": max_breadth,
+            "limit": limit,
+            "query": query,
+            "select_paths": select_paths,
+            "select_domains": select_domains,
+            "allow_external": allow_external,
+            "categories": categories,
+        }
+
+        if kwargs:
+            data.update(kwargs)
+
+        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:
+            response = await client.post("/map", content=json.dumps(data), timeout=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()
+
+    async def map(self,
+                    url: str,
+                    max_depth: int = None,
+                    max_breadth: int = None,
+                    limit: int = None,
+                    query: str = None,
+                    select_paths: Sequence[str] = None,
+                    select_domains: Sequence[str] = None,
+                    allow_external: bool = None,
+                    categories: Sequence[Literal["Documentation", "Blog", "About", "Contact", "Pricing",
+                                           "Careers", "E-Commerce", "Developers", "Partners",
+                                           "Downloads", "Media", "Events"]] = None,
+                    timeout: int = 60,
+                    **kwargs
+                    ) -> dict:
+        """
+        Combined map method.
+        """
+        timeout = min(timeout, 120)
+        response_dict = await self._map(url,
+                                    max_depth=max_depth,
+                                    max_breadth=max_breadth,
+                                    limit=limit,
+                                    query=query,
+                                    select_paths=select_paths,
+                                    select_domains=select_domains,
+                                    allow_external=allow_external,
+                                    categories=categories,
+                                    timeout=timeout,
+                                    **kwargs)
 
         return response_dict
 

{tavily_python-0.6.0 → tavily_python-0.7.0}/tavily/tavily.py

@@ -205,17 +205,17 @@ class TavilyClient:
 
     def _crawl(self,
             url: str,
-            max_depth: int = 1,
-            max_breadth: int = 20,
-            limit: int = 50,
+            max_depth: int = None,
+            max_breadth: int = None,
+            limit: int = None,
             query: str = None,
             select_paths: Sequence[str] = None,
             select_domains: Sequence[str] = None,
-            allow_external: bool = False,
+            allow_external: bool = None,
             categories: Sequence[Literal["Documentation", "Blog", "About", "Contact", "Pricing",
                                         "Careers", "E-Commerce", "Developers", "Partners",
                                         "Downloads", "Media", "Events"]] = None,
-            extract_depth: Literal["basic", "advanced"] = "basic",
+            extract_depth: Literal["basic", "advanced"] = None,
             timeout: int = 60,
             **kwargs
             ) -> dict:
@@ -237,7 +237,9 @@ class TavilyClient:
 
         if kwargs:
             data.update(kwargs)
-
+        
+        data = {k: v for k, v in data.items() if v is not None}
+    
         timeout = min(timeout, 120)
 
         response = requests.post(
@@ -265,17 +267,17 @@ class TavilyClient:
 
     def crawl(self,
               url: str,
-              max_depth: int = 1,
-              max_breadth: int = 20,
-              limit: int = 50,
+              max_depth: int = None,
+              max_breadth: int = None,
+              limit: int = None,
               query: str = None,
               select_paths: Sequence[str] = None,
               select_domains: Sequence[str] = None,
-              allow_external: bool = False,
+              allow_external: bool = None,
               categories: Sequence[Literal["Documentation", "Blog", "About", "Contact", "Pricing",
                                            "Careers", "E-Commerce", "Developers", "Partners",
                                            "Downloads", "Media", "Events"]] = None,
-              extract_depth: Literal["basic", "advanced"] = "basic",
+              extract_depth: Literal["basic", "advanced"] = None,
               timeout: int = 60,
               **kwargs
               ) -> dict:
@@ -296,17 +298,98 @@ class TavilyClient:
                                     timeout=timeout,
                                     **kwargs)
 
-        data = response_dict.get("data", [])
-        metadata = response_dict.get("metadata", {})
-        config = response_dict.get("config", {})
-        success = response_dict.get("success", False)
-        error = response_dict.get("error", None)
-
-        response_dict["data"] = data
-        response_dict["metadata"] = metadata
-        response_dict["config"] = config
-        response_dict["success"] = success
-        response_dict["error"] = error
+        return response_dict
+    
+    def _map(self,
+            url: str,
+            max_depth: int = None,
+            max_breadth: int = None,
+            limit: int = None,
+            query: str = None,
+            select_paths: Sequence[str] = None,
+            select_domains: Sequence[str] = None,
+            allow_external: bool = None,
+            categories: Sequence[Literal["Documentation", "Blog", "About", "Contact", "Pricing",
+                                        "Careers", "E-Commerce", "Developers", "Partners",
+                                        "Downloads", "Media", "Events"]] = None,
+            timeout: int = 60,
+            **kwargs
+            ) -> dict:
+        """
+        Internal map method to send the request to the API.
+        """
+        data = {
+            "url": url,
+            "max_depth": max_depth,
+            "max_breadth": max_breadth,
+            "limit": limit,
+            "query": query,
+            "select_paths": select_paths,
+            "select_domains": select_domains,
+            "allow_external": allow_external,
+            "categories": categories,
+        }
+
+        if kwargs:
+            data.update(kwargs)
+        
+        data = {k: v for k, v in data.items() if v is not None}
+
+        timeout = min(timeout, 120)
+
+        response = requests.post(
+            self.base_url + "/map", data=json.dumps(data), headers=self.headers, timeout=timeout, proxies=self.proxies)
+
+        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 map(self,
+              url: str,
+              max_depth: int = None,
+              max_breadth: int = None,
+              limit: int = None,
+              query: str = None,
+              select_paths: Sequence[str] = None,
+              select_domains: Sequence[str] = None,
+              allow_external: bool = None,
+              categories: Sequence[Literal["Documentation", "Blog", "About", "Contact", "Pricing",
+                                           "Careers", "E-Commerce", "Developers", "Partners",
+                                           "Downloads", "Media", "Events"]] = None,
+              timeout: int = 60,
+              **kwargs
+              ) -> dict:
+        """
+        Combined map method.
+        """
+        timeout = min(timeout, 120)
+        response_dict = self._map(url,
+                                    max_depth=max_depth,
+                                    max_breadth=max_breadth,
+                                    limit=limit,
+                                    query=query,
+                                    select_paths=select_paths,
+                                    select_domains=select_domains,
+                                    allow_external=allow_external,
+                                    categories=categories,
+                                    timeout=timeout,
+                                    **kwargs)
 
         return response_dict