tavily-python 0.7.24__tar.gz → 0.7.25__tar.gz

{tavily_python-0.7.24 → tavily_python-0.7.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tavily-python
-Version: 0.7.24
+Version: 0.7.25
 Summary: Python wrapper for the Tavily API
 Home-page: https://github.com/tavily-ai/tavily-python
 Author: Tavily AI
@@ -40,6 +40,29 @@ The Tavily Python wrapper allows for easy interaction with the Tavily API, offer
 pip install tavily-python
 ```
 
+## Keyless mode
+
+You can try Tavily without an API key. Instantiate `TavilyClient()` with no arguments and the SDK runs in keyless mode against the public Tavily API. Keyless mode supports `search()` and `extract()` only; other methods raise an error explaining that an API key is required.
+
+```python
+from tavily import TavilyClient, TavilyKeylessLimitError
+
+# No API key needed
+client = TavilyClient()
+
+try:
+    response = client.search("Who is Leo Messi?")
+    print(response)
+except TavilyKeylessLimitError as e:
+    # Rate-limit cap reached. The exception carries the human-readable
+    # message plus structured fields (code, window, retry_after_seconds,
+    # next_actions) returned by the Tavily API.
+    print(e)
+    print("retry after:", e.retry_after_seconds, "seconds")
+```
+
+Keyless usage is rate-limited. For higher limits and the full set of endpoints (including `crawl`, `map`, and `research`), [sign up for a Tavily API key](https://tavily.com) and pass it as `TavilyClient(api_key="tvly-...")`.
+
 # Tavily Search
 
 Search lets you search the web for a given query.

{tavily_python-0.7.24 → tavily_python-0.7.25}/README.md

@@ -13,6 +13,29 @@ The Tavily Python wrapper allows for easy interaction with the Tavily API, offer
 pip install tavily-python
 ```
 
+## Keyless mode
+
+You can try Tavily without an API key. Instantiate `TavilyClient()` with no arguments and the SDK runs in keyless mode against the public Tavily API. Keyless mode supports `search()` and `extract()` only; other methods raise an error explaining that an API key is required.
+
+```python
+from tavily import TavilyClient, TavilyKeylessLimitError
+
+# No API key needed
+client = TavilyClient()
+
+try:
+    response = client.search("Who is Leo Messi?")
+    print(response)
+except TavilyKeylessLimitError as e:
+    # Rate-limit cap reached. The exception carries the human-readable
+    # message plus structured fields (code, window, retry_after_seconds,
+    # next_actions) returned by the Tavily API.
+    print(e)
+    print("retry after:", e.retry_after_seconds, "seconds")
+```
+
+Keyless usage is rate-limited. For higher limits and the full set of endpoints (including `crawl`, `map`, and `research`), [sign up for a Tavily API key](https://tavily.com) and pass it as `TavilyClient(api_key="tvly-...")`.
+
 # Tavily Search
 
 Search lets you search the web for a given query.

{tavily_python-0.7.24 → tavily_python-0.7.25}/setup.py

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

tavily_python-0.7.25/tavily/__init__.py

@@ -0,0 +1,11 @@
+from .async_tavily import AsyncTavilyClient
+from .tavily import Client, TavilyClient
+from .errors import (
+    InvalidAPIKeyError,
+    UsageLimitExceededError,
+    MissingAPIKeyError,
+    BadRequestError,
+    TavilyKeylessLimitError,
+    KeylessUnsupportedEndpointError,
+)
+from .hybrid_rag import TavilyHybridClient

{tavily_python-0.7.24 → tavily_python-0.7.25}/tavily/async_tavily.py

@@ -6,7 +6,37 @@ from typing import Literal, Sequence, Optional, List, Union, AsyncGenerator, Awa
 import httpx
 
 from .utils import get_max_items_from_list
-from .errors import UsageLimitExceededError, InvalidAPIKeyError, MissingAPIKeyError, BadRequestError, ForbiddenError, TimeoutError
+from .errors import (
+    UsageLimitExceededError,
+    InvalidAPIKeyError,
+    MissingAPIKeyError,
+    BadRequestError,
+    ForbiddenError,
+    TimeoutError,
+    TavilyKeylessLimitError,
+    KeylessUnsupportedEndpointError,
+)
+
+
+def _is_keyless_envelope(body) -> bool:
+    """Return True when the response body matches the Tavily recoverable-error envelope shape."""
+    return (
+        isinstance(body, dict)
+        and isinstance(body.get("error"), dict)
+        and isinstance(body["error"].get("code"), str)
+    )
+
+
+def _raise_keyless_envelope(body) -> None:
+    """Raise ``TavilyKeylessLimitError`` from an envelope-shaped response body."""
+    err = body["error"]
+    raise TavilyKeylessLimitError(
+        message=err.get("message") or "",
+        code=err.get("code"),
+        window=err.get("window"),
+        retry_after_seconds=err.get("retry_after_seconds"),
+        next_actions=err.get("next_actions") or [],
+    )
 
 
 class AsyncTavilyClient:
@@ -27,18 +57,28 @@ class AsyncTavilyClient:
         if api_key is None:
             api_key = os.getenv("TAVILY_API_KEY")
 
-        if not api_key and client is None:
-            raise MissingAPIKeyError()
+        # api_key is optional: when absent, the client runs in keyless mode.
+        # Only `search` and `extract` are available in keyless mode.
+        api_key = api_key or None
 
         tavily_project = project_id or os.getenv("TAVILY_PROJECT")
 
         self._api_base_url = api_base_url or "https://api.tavily.com"
         self._company_info_tags = company_info_tags
+        self._keyless = api_key is None and client is None
+
+        if self._keyless:
+            # Honor an explicit client_source so non-SDK keyless surfaces
+            # (e.g. tavily-cli-keyless) are attributed correctly by the server.
+            client_source_header = client_source or "tavily-python-keyless"
+        else:
+            client_source_header = client_source or "tavily-python"
 
         default_headers = {
             "Content-Type": "application/json",
             **({"Authorization": f"Bearer {api_key}"} if api_key else {}),
-            "X-Client-Source": client_source or "tavily-python",
+            **({"X-Tavily-Access-Mode": "keyless"} if self._keyless else {}),
+            "X-Client-Source": client_source_header,
             **({"X-Project-ID": tavily_project} if tavily_project else {}),
             **({"X-Session-Id": session_id} if session_id else {}),
             **({"X-Human-Id": human_id} if human_id else {}),
@@ -89,6 +129,49 @@ class AsyncTavilyClient:
     async def __aexit__(self, exc_type, exc_val, exc_tb):
         await self.close()
 
+    def _handle_error_response(self, response, body_override=None) -> None:
+        """Raise an appropriate exception for a non-2xx httpx response.
+
+        On keyless calls, checks the response body for the recoverable-error
+        envelope shape and raises ``TavilyKeylessLimitError`` with the
+        envelope's structured fields when present.
+        """
+        if body_override is not None:
+            body = body_override
+        else:
+            try:
+                body = response.json()
+            except Exception:
+                body = None
+
+        if self._keyless and _is_keyless_envelope(body):
+            _raise_keyless_envelope(body)
+
+        detail = ""
+        if isinstance(body, dict):
+            try:
+                detail = body.get("detail", {}).get("error", None) or ""
+            except Exception:
+                detail = ""
+        elif isinstance(body, str):
+            detail = body
+
+        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 _check_keyless_supported(self, method: str) -> None:
+        """Raise ``KeylessUnsupportedEndpointError`` when running in keyless mode."""
+        if self._keyless:
+            raise KeylessUnsupportedEndpointError(method)
+
     @staticmethod
     def _pop_request_headers(kwargs: dict) -> Optional[dict]:
         """Pop session_id, human_id, and client_name from kwargs and return them as headers.
@@ -169,22 +252,7 @@ class AsyncTavilyClient:
         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()
+            self._handle_error_response(response)
 
     async def search(self,
                      query: str,
@@ -283,23 +351,7 @@ class AsyncTavilyClient:
         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()
+            self._handle_error_response(response)
 
     async def extract(self,
                       urls: Union[List[str], str],  # Accept a list of URLs or a single URL
@@ -394,22 +446,7 @@ class AsyncTavilyClient:
         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()
+            self._handle_error_response(response)
 
     async def crawl(self,
                     url: str,
@@ -435,6 +472,7 @@ class AsyncTavilyClient:
         Combined crawl method.
 
         """
+        self._check_keyless_supported("crawl")
         response_dict = await self._crawl(url,
                                     max_depth=max_depth,
                                     max_breadth=max_breadth,
@@ -505,22 +543,7 @@ class AsyncTavilyClient:
         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()
+            self._handle_error_response(response)
 
     async def map(self,
                     url: str,
@@ -542,6 +565,7 @@ class AsyncTavilyClient:
         Combined map method.
 
         """
+        self._check_keyless_supported("map")
         response_dict = await self._map(url,
                                     max_depth=max_depth,
                                     max_breadth=max_breadth,
@@ -581,6 +605,7 @@ class AsyncTavilyClient:
 
         Returns a string of JSON containing the search context up to context limit.
         """
+        self._check_keyless_supported("get_search_context")
         timeout = min(timeout, 120)
         response_dict = await self._search(query,
                                            search_depth=search_depth,
@@ -617,6 +642,7 @@ class AsyncTavilyClient:
         """
         Q&A search method. Search depth is advanced by default to get the best answer.
         """
+        self._check_keyless_supported("qna_search")
         timeout = min(timeout, 120)
         response_dict = await self._search(query,
                                            search_depth=search_depth,
@@ -643,6 +669,7 @@ class AsyncTavilyClient:
                                country: str = None,
                                ) -> Sequence[dict]:
         """ Company information search method. Search depth is advanced by default to get the best answer. """
+        self._check_keyless_supported("get_company_info")
         timeout = min(timeout, 120)
 
         async def _perform_search(topic: str):
@@ -707,16 +734,13 @@ class AsyncTavilyClient:
                             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}")
+                            body_override = None
+                            try:
+                                body_override = json.loads(error_text)
+                            except Exception:
+                                body_override = error_text
+
+                            self._handle_error_response(response, body_override=body_override)
 
                         async for chunk in response.aiter_bytes():
                             if chunk:
@@ -737,22 +761,7 @@ class AsyncTavilyClient:
                 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()
+                    self._handle_error_response(response)
 
             return _make_request()
 
@@ -781,6 +790,7 @@ class AsyncTavilyClient:
             When stream=False: dict - the response dictionary.
             When stream=True: AsyncGenerator[bytes, None] - iterate over this to get streaming chunks.
         """
+        self._check_keyless_supported("research")
         result = self._research(
                 input=input,
                 model=model,
@@ -807,6 +817,7 @@ class AsyncTavilyClient:
         Returns:
             dict: Research response containing request_id, created_at, completed_at, status, content, and sources.
         """
+        self._check_keyless_supported("get_research")
         try:
             response = await self._client.get(f"/research/{request_id}")
         except Exception as e:
@@ -816,19 +827,4 @@ class AsyncTavilyClient:
             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()
+            self._handle_error_response(response)

tavily_python-0.7.25/tavily/errors.py

@@ -0,0 +1,71 @@
+from typing import Any, List, Optional
+
+
+class UsageLimitExceededError(Exception):
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class TavilyKeylessLimitError(UsageLimitExceededError):
+    """Raised when a keyless request is rejected by the Tavily API."""
+
+    def __init__(
+        self,
+        message: str,
+        code: Optional[str] = None,
+        window: Optional[str] = None,
+        retry_after_seconds: Optional[int] = None,
+        next_actions: Optional[List[Any]] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.window = window
+        self.retry_after_seconds = retry_after_seconds
+        self.next_actions = next_actions or []
+
+    def __str__(self) -> str:
+        return self.message or ""
+
+
+class BadRequestError(Exception):
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class ForbiddenError(Exception):
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class InvalidAPIKeyError(Exception):
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class TimeoutError(Exception):
+    def __init__(self, timeout: float):
+        super().__init__(f"Request timed out after {timeout} seconds.")
+
+
+class MissingAPIKeyError(Exception):
+    def __init__(self):
+        super().__init__(
+            "No API key provided. Please provide the api_key attribute or set the TAVILY_API_KEY environment variable."
+        )
+
+
+class KeylessUnsupportedEndpointError(Exception):
+    """Raised when a method is called without an API key but does not support keyless mode.
+
+    Only ``search`` and ``extract`` support keyless mode. Calling other methods
+    keyless raises this error before any network request is sent.
+    """
+
+    def __init__(self, method: str):
+        super().__init__(
+            f"`{method}` is not available in keyless mode. "
+            "Only `search` and `extract` can be called without an API key. "
+            "Pass an `api_key` to TavilyClient (or set TAVILY_API_KEY) to use this method."
+        )
+        self.method = method

{tavily_python-0.7.24 → tavily_python-0.7.25}/tavily/tavily.py

@@ -4,7 +4,38 @@ import os
 import warnings
 from typing import Literal, Sequence, Optional, List, Union, Generator
 from .utils import get_max_items_from_list
-from .errors import UsageLimitExceededError, InvalidAPIKeyError, MissingAPIKeyError, BadRequestError, ForbiddenError, TimeoutError
+from .errors import (
+    UsageLimitExceededError,
+    InvalidAPIKeyError,
+    MissingAPIKeyError,
+    BadRequestError,
+    ForbiddenError,
+    TimeoutError,
+    TavilyKeylessLimitError,
+    KeylessUnsupportedEndpointError,
+)
+
+
+def _is_keyless_envelope(body) -> bool:
+    """Return True when the response body matches the Tavily recoverable-error envelope shape."""
+    return (
+        isinstance(body, dict)
+        and isinstance(body.get("error"), dict)
+        and isinstance(body["error"].get("code"), str)
+    )
+
+
+def _raise_keyless_envelope(body) -> None:
+    """Raise ``TavilyKeylessLimitError`` from an envelope-shaped response body."""
+    err = body["error"]
+    raise TavilyKeylessLimitError(
+        message=err.get("message") or "",
+        code=err.get("code"),
+        window=err.get("window"),
+        retry_after_seconds=err.get("retry_after_seconds"),
+        next_actions=err.get("next_actions") or [],
+    )
+
 
 class TavilyClient:
     """
@@ -26,8 +57,7 @@ class TavilyClient:
         if api_key is None:
             api_key = os.getenv("TAVILY_API_KEY")
 
-        if not api_key and session is None:
-            raise MissingAPIKeyError()
+        api_key = api_key or None
 
         resolved_proxies = {
             "http": proxies.get("http") if proxies else os.getenv("TAVILY_HTTP_PROXY"),
@@ -39,12 +69,19 @@ class TavilyClient:
 
         self.base_url = api_base_url or "https://api.tavily.com"
         self.api_key = api_key
+        self._keyless = api_key is None and session is None
         self.proxies = resolved_proxies
 
+        if self._keyless:
+            client_source_header = client_source or "tavily-python-keyless"
+        else:
+            client_source_header = client_source or "tavily-python"
+
         self.headers = {
             "Content-Type": "application/json",
             **({"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}),
-            "X-Client-Source": client_source or "tavily-python",
+            **({"X-Tavily-Access-Mode": "keyless"} if self._keyless else {}),
+            "X-Client-Source": client_source_header,
             **({"X-Project-ID": tavily_project} if tavily_project else {}),
             **({"X-Session-Id": session_id} if session_id else {}),
             **({"X-Human-Id": human_id} if human_id else {}),
@@ -73,6 +110,40 @@ class TavilyClient:
     def __exit__(self, exc_type, exc_val, exc_tb):
         self.close()
 
+    def _handle_error_response(self, response) -> None:
+        """Raise an appropriate exception for a non-2xx response."""
+        body = None
+        try:
+            body = response.json()
+        except Exception:
+            body = None
+
+        if self._keyless and _is_keyless_envelope(body):
+            _raise_keyless_envelope(body)
+
+        detail = ""
+        if isinstance(body, dict):
+            try:
+                detail = body.get("detail", {}).get("error", None) or ""
+            except Exception:
+                detail = ""
+
+        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 _check_keyless_supported(self, method: str) -> None:
+        """Raise ``KeylessUnsupportedEndpointError`` when running in keyless mode."""
+        if self._keyless:
+            raise KeylessUnsupportedEndpointError(method)
+
     @staticmethod
     def _pop_request_headers(kwargs: dict) -> Optional[dict]:
         """Pop session_id, human_id, and client_name from kwargs and return them as headers.
@@ -155,22 +226,7 @@ class TavilyClient:
         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()
+            self._handle_error_response(response)
 
 
     def search(self,
@@ -263,22 +319,7 @@ class TavilyClient:
         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()
+            self._handle_error_response(response)
 
     def extract(self,
                 urls: Union[List[str], str],  # Accept a list of URLs or a single URL
@@ -367,22 +408,7 @@ class TavilyClient:
         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()
+            self._handle_error_response(response)
 
     def crawl(self,
               url: str,
@@ -408,6 +434,7 @@ class TavilyClient:
         Combined crawl method.
         include_favicon: If True, include the favicon in the crawl results.
         """
+        self._check_keyless_supported("crawl")
         return self._crawl(url,
                            max_depth=max_depth,
                            max_breadth=max_breadth,
@@ -476,22 +503,7 @@ class TavilyClient:
         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()
+            self._handle_error_response(response)
 
     def map(self,
               url: str,
@@ -511,8 +523,9 @@ class TavilyClient:
               ) -> dict:
         """
         Combined map method.
-        
+
         """
+        self._check_keyless_supported("map")
         return self._map(url,
                          max_depth=max_depth,
                          max_breadth=max_breadth,
@@ -550,6 +563,7 @@ class TavilyClient:
 
         Returns a string of JSON containing the search context up to context limit.
         """
+        self._check_keyless_supported("get_search_context")
         warnings.warn("get_search_context is deprecated and will be removed in future versions.",
                       DeprecationWarning, stacklevel=2)
 
@@ -589,6 +603,7 @@ class TavilyClient:
         """
         Q&A search method. Search depth is advanced by default to get the best answer.
         """
+        self._check_keyless_supported("qna_search")
         warnings.warn("qna_search is deprecated and will be removed in future versions.",
                       DeprecationWarning, stacklevel=2)
         response_dict = self._search(query,
@@ -647,22 +662,7 @@ class TavilyClient:
                 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()
+                self._handle_error_response(response)
 
             def stream_generator() -> Generator[bytes, None, None]:
                 try:
@@ -687,22 +687,7 @@ class TavilyClient:
             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()
+                self._handle_error_response(response)
 
     def research(self,
                  input: str,
@@ -728,6 +713,7 @@ class TavilyClient:
         Returns:
             dict: Response containing request_id, created_at, status, input, and model.
         """
+        self._check_keyless_supported("research")
 
         return self._research(
             input=input,
@@ -751,6 +737,7 @@ class TavilyClient:
         Returns:
             dict: Research response containing request_id, created_at, completed_at, status, content, and sources.
         """
+        self._check_keyless_supported("get_research")
         try:
             response = self.session.get(self.base_url + f"/research/{request_id}")
         except Exception as e:
@@ -759,22 +746,7 @@ class TavilyClient:
         if response.status_code in (200, 202):
             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()
+            self._handle_error_response(response)
 
 
 class Client(TavilyClient):

{tavily_python-0.7.24 → tavily_python-0.7.25}/tavily_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tavily-python
-Version: 0.7.24
+Version: 0.7.25
 Summary: Python wrapper for the Tavily API
 Home-page: https://github.com/tavily-ai/tavily-python
 Author: Tavily AI
@@ -40,6 +40,29 @@ The Tavily Python wrapper allows for easy interaction with the Tavily API, offer
 pip install tavily-python
 ```
 
+## Keyless mode
+
+You can try Tavily without an API key. Instantiate `TavilyClient()` with no arguments and the SDK runs in keyless mode against the public Tavily API. Keyless mode supports `search()` and `extract()` only; other methods raise an error explaining that an API key is required.
+
+```python
+from tavily import TavilyClient, TavilyKeylessLimitError
+
+# No API key needed
+client = TavilyClient()
+
+try:
+    response = client.search("Who is Leo Messi?")
+    print(response)
+except TavilyKeylessLimitError as e:
+    # Rate-limit cap reached. The exception carries the human-readable
+    # message plus structured fields (code, window, retry_after_seconds,
+    # next_actions) returned by the Tavily API.
+    print(e)
+    print("retry after:", e.retry_after_seconds, "seconds")
+```
+
+Keyless usage is rate-limited. For higher limits and the full set of endpoints (including `crawl`, `map`, and `research`), [sign up for a Tavily API key](https://tavily.com) and pass it as `TavilyClient(api_key="tvly-...")`.
+
 # Tavily Search
 
 Search lets you search the web for a given query.

{tavily_python-0.7.24 → tavily_python-0.7.25}/tests/test_custom_session.py

@@ -4,7 +4,6 @@ from tests.request_intercept import intercept_requests, clear_interceptor, MockS
 import tavily.tavily as sync_tavily
 import tavily.async_tavily as async_tavily
 import pytest
-from tavily.errors import MissingAPIKeyError
 
 
 @pytest.fixture
@@ -104,10 +103,14 @@ class TestSyncCustomSession:
 
     # --- API key validation edge cases ---
 
-    def test_no_api_key_no_session_raises(self, monkeypatch):
+    def test_no_api_key_no_session_creates_keyless_client(self, monkeypatch):
+        """No api_key + no custom session -> keyless mode (search/extract only)."""
         monkeypatch.delenv("TAVILY_API_KEY", raising=False)
-        with pytest.raises(MissingAPIKeyError):
-            sync_tavily.TavilyClient()
+        client = sync_tavily.TavilyClient()
+        assert client._keyless is True
+        assert "Authorization" not in client.headers
+        assert client.headers.get("X-Tavily-Access-Mode") == "keyless"
+        assert client.headers.get("X-Client-Source") == "tavily-python-keyless"
 
     def test_no_api_key_with_session_allowed(self, sync_interceptor, monkeypatch):
         monkeypatch.delenv("TAVILY_API_KEY", raising=False)
@@ -140,10 +143,13 @@ class TestSyncCustomSession:
         assert req is not None
         assert req.headers["Authorization"] == "Bearer apim-token"
 
-    def test_empty_string_api_key_no_session_raises(self, monkeypatch):
+    def test_empty_string_api_key_no_session_creates_keyless_client(self, monkeypatch):
+        """Empty-string api_key + no custom session -> keyless mode."""
         monkeypatch.delenv("TAVILY_API_KEY", raising=False)
-        with pytest.raises(MissingAPIKeyError):
-            sync_tavily.TavilyClient(api_key="")
+        client = sync_tavily.TavilyClient(api_key="")
+        assert client._keyless is True
+        assert "Authorization" not in client.headers
+        assert client.headers.get("X-Tavily-Access-Mode") == "keyless"
 
     def test_empty_string_api_key_with_session_allowed(self, sync_interceptor):
         custom_session = MockSession(sync_interceptor)
@@ -336,10 +342,11 @@ class TestAsyncCustomClient:
 
     # --- API key validation edge cases ---
 
-    def test_no_api_key_no_client_raises(self, monkeypatch):
+    def test_no_api_key_no_client_creates_keyless_client(self, monkeypatch):
+        """Async: no api_key + no custom client -> keyless mode."""
         monkeypatch.delenv("TAVILY_API_KEY", raising=False)
-        with pytest.raises(MissingAPIKeyError):
-            async_tavily.AsyncTavilyClient()
+        client = async_tavily.AsyncTavilyClient()
+        assert client._keyless is True
 
     def test_no_api_key_with_client_allowed(self, monkeypatch):
         monkeypatch.delenv("TAVILY_API_KEY", raising=False)

{tavily_python-0.7.24 → tavily_python-0.7.25}/tests/test_errors.py

@@ -4,7 +4,7 @@ import asyncio
 
 import tavily.tavily as sync_tavily
 import tavily.async_tavily as async_tavily
-from tavily.errors import MissingAPIKeyError, InvalidAPIKeyError
+from tavily.errors import InvalidAPIKeyError
 
 @pytest.fixture
 def set_api_key():
@@ -31,18 +31,17 @@ def test_load_key_from_env(set_api_key):
 
     # No error should be raised
 
-def test_missing_api_key(clear_api_key):
-    with pytest.raises(MissingAPIKeyError):
-        sync_tavily.TavilyClient(api_key='')
-
-    with pytest.raises(MissingAPIKeyError):
-        async_tavily.AsyncTavilyClient(api_key='')
-
-    with pytest.raises(MissingAPIKeyError):
-        sync_tavily.TavilyClient()
-
-    with pytest.raises(MissingAPIKeyError):
-        async_tavily.AsyncTavilyClient()
+def test_no_api_key_creates_keyless_client(clear_api_key):
+    """With no API key (None or empty string) the client constructs in keyless mode."""
+    for ctor_args in [{"api_key": ""}, {}, {"api_key": None}]:
+        sync_client = sync_tavily.TavilyClient(**ctor_args)
+        assert sync_client._keyless is True
+        assert "Authorization" not in sync_client.headers
+        assert sync_client.headers.get("X-Tavily-Access-Mode") == "keyless"
+        assert sync_client.headers.get("X-Client-Source") == "tavily-python-keyless"
+
+        async_client = async_tavily.AsyncTavilyClient(**ctor_args)
+        assert async_client._keyless is True
 
 def test_invalid_api_key():
     with pytest.raises(InvalidAPIKeyError):

tavily_python-0.7.24/tavily/__init__.py

@@ -1,4 +0,0 @@
-from .async_tavily import AsyncTavilyClient
-from .tavily import Client, TavilyClient
-from .errors import InvalidAPIKeyError, UsageLimitExceededError, MissingAPIKeyError, BadRequestError
-from .hybrid_rag import TavilyHybridClient

tavily_python-0.7.24/tavily/errors.py

@@ -1,30 +0,0 @@
-class UsageLimitExceededError(Exception):
-    def __init__(self, message: str):
-        super().__init__(message)
-
-
-class BadRequestError(Exception):
-    def __init__(self, message: str):
-        super().__init__(message)
-
-
-class ForbiddenError(Exception):
-    def __init__(self, message: str):
-        super().__init__(message)
-
-
-class InvalidAPIKeyError(Exception):
-    def __init__(self, message: str):
-        super().__init__(message)
-
-
-class TimeoutError(Exception):
-    def __init__(self, timeout: float):
-        super().__init__(f"Request timed out after {timeout} seconds.")
-
-
-class MissingAPIKeyError(Exception):
-    def __init__(self):
-        super().__init__(
-            "No API key provided. Please provide the api_key attribute or set the TAVILY_API_KEY environment variable."
-        )