exa-py 1.15.5__tar.gz → 1.16.0__tar.gz

{exa_py-1.15.5 → exa_py-1.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exa-py
-Version: 1.15.5
+Version: 1.16.0
 Summary: Python SDK for Exa API.
 License: MIT
 Author: Exa AI
@@ -13,9 +13,11 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: httpcore (>=1.0.9)
 Requires-Dist: httpx (>=0.28.1)
 Requires-Dist: openai (>=1.48)
 Requires-Dist: pydantic (>=2.10.6)
+Requires-Dist: python-dotenv (>=1.0.1)
 Requires-Dist: requests (>=2.32.3)
 Requires-Dist: typing-extensions (>=4.12.2)
 Description-Content-Type: text/markdown

{exa_py-1.15.5 → exa_py-1.16.0}/exa_py/api.py

@@ -142,7 +142,9 @@ SEARCH_OPTIONS_TYPES = {
         list
     ],  # Must not be present in webpage text. (One string, up to 5 words)
     "use_autoprompt": [bool],  # Convert query to Exa. (Default: false)
-    "type": [str],  # 'keyword', 'neural', 'hybrid', 'fast', or 'auto' (Default: auto)
+    "type": [
+        str
+    ],  # 'keyword', 'neural', 'hybrid', 'fast', 'deep', or 'auto' (Default: auto)
     "category": [
         str
     ],  # A data category to focus on: 'company', 'research paper', 'news', 'pdf', 'github', 'tweet', 'personal site', 'linkedin profile', 'financial report'
@@ -260,6 +262,10 @@ class HighlightsContentsOptions(TypedDict, total=False):
         query (str): The query string for the highlights.
         num_sentences (int): Size of highlights to return, in sentences. Default: 5
         highlights_per_url (int): Number of highlights to return per URL. Default: 1
+
+    NOTE: When using the "deep" search type, only the default highlights=True is supported.
+          These options will NOT be respected. Highlights will always be based on the user's query,
+          and the number and length may vary.
     """
 
     query: str
@@ -1164,6 +1170,7 @@ class Exa:
         data: Optional[Union[Dict[str, Any], str]] = None,
         method: str = "POST",
         params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
     ) -> Union[Dict[str, Any], requests.Response]:
         """Send a request to the Exa API, optionally streaming if data['stream'] is True.
 
@@ -1172,6 +1179,7 @@ class Exa:
             data (dict, optional): The JSON payload to send. Defaults to None.
             method (str, optional): The HTTP method to use. Defaults to "POST".
             params (Dict[str, Any], optional): Query parameters to include. Defaults to None.
+            headers (Dict[str, str], optional): Additional headers to include in the request. Defaults to None.
 
         Returns:
             Union[dict, requests.Response]: If streaming, returns the Response object.
@@ -1193,38 +1201,43 @@ class Exa:
             params and params.get("stream") == "true"
         )
 
+        # Merge additional headers with existing headers
+        request_headers = {**self.headers}
+        if headers:
+            request_headers.update(headers)
+
         if method.upper() == "GET":
             if needs_streaming:
                 res = requests.get(
                     self.base_url + endpoint,
-                    headers=self.headers,
+                    headers=request_headers,
                     params=params,
                     stream=True,
                 )
                 return res
             else:
                 res = requests.get(
-                    self.base_url + endpoint, headers=self.headers, params=params
+                    self.base_url + endpoint, headers=request_headers, params=params
                 )
         elif method.upper() == "POST":
             if needs_streaming:
                 res = requests.post(
                     self.base_url + endpoint,
                     data=json_data,
-                    headers=self.headers,
+                    headers=request_headers,
                     stream=True,
                 )
                 return res
             else:
                 res = requests.post(
-                    self.base_url + endpoint, data=json_data, headers=self.headers
+                    self.base_url + endpoint, data=json_data, headers=request_headers
                 )
         elif method.upper() == "PATCH":
             res = requests.patch(
-                self.base_url + endpoint, data=json_data, headers=self.headers
+                self.base_url + endpoint, data=json_data, headers=request_headers
             )
         elif method.upper() == "DELETE":
-            res = requests.delete(self.base_url + endpoint, headers=self.headers)
+            res = requests.delete(self.base_url + endpoint, headers=request_headers)
         else:
             raise ValueError(f"Unsupported HTTP method: {method}")
 
@@ -1268,7 +1281,7 @@ class Exa:
             include_text (List[str], optional): Strings that must appear in the page text.
             exclude_text (List[str], optional): Strings that must not appear in the page text.
             use_autoprompt (bool, optional): Convert query to Exa (default False).
-            type (str, optional): 'keyword', 'neural', 'hybrid', 'fast', or 'auto' (default 'auto').
+            type (str, optional): 'keyword', 'neural', 'hybrid', 'fast', 'deep', or 'auto' (default 'auto').
             category (str, optional): e.g. 'company'
             flags (List[str], optional): Experimental flags for Exa usage.
             moderation (bool, optional): If True, the search results will be moderated for safety.
@@ -2431,7 +2444,12 @@ class AsyncExa(Exa):
         return self._client
 
     async def async_request(
-        self, endpoint: str, data=None, method: str = "POST", params=None
+        self,
+        endpoint: str,
+        data=None,
+        method: str = "POST",
+        params=None,
+        headers: Optional[Dict[str, str]] = None,
     ):
         """Send a request to the Exa API, optionally streaming if data['stream'] is True.
 
@@ -2440,6 +2458,7 @@ class AsyncExa(Exa):
             data (dict, optional): The JSON payload to send.
             method (str, optional): The HTTP method to use. Defaults to "POST".
             params (dict, optional): Query parameters.
+            headers (Dict[str, str], optional): Additional headers to include in the request. Defaults to None.
 
         Returns:
             Union[dict, httpx.Response]: If streaming, returns the Response object.
@@ -2453,27 +2472,35 @@ class AsyncExa(Exa):
             params and params.get("stream") == "true"
         )
 
+        # Merge additional headers with existing headers
+        request_headers = {**self.headers}
+        if headers:
+            request_headers.update(headers)
+
         if method.upper() == "GET":
             if needs_streaming:
                 request = httpx.Request(
-                    "GET", self.base_url + endpoint, params=params, headers=self.headers
+                    "GET",
+                    self.base_url + endpoint,
+                    params=params,
+                    headers=request_headers,
                 )
                 res = await self.client.send(request, stream=True)
                 return res
             else:
                 res = await self.client.get(
-                    self.base_url + endpoint, params=params, headers=self.headers
+                    self.base_url + endpoint, params=params, headers=request_headers
                 )
         elif method.upper() == "POST":
             if needs_streaming:
                 request = httpx.Request(
-                    "POST", self.base_url + endpoint, json=data, headers=self.headers
+                    "POST", self.base_url + endpoint, json=data, headers=request_headers
                 )
                 res = await self.client.send(request, stream=True)
                 return res
             else:
                 res = await self.client.post(
-                    self.base_url + endpoint, json=data, headers=self.headers
+                    self.base_url + endpoint, json=data, headers=request_headers
                 )
         if res.status_code != 200 and res.status_code != 201:
             raise ValueError(
@@ -2515,7 +2542,7 @@ class AsyncExa(Exa):
             include_text (List[str], optional): Strings that must appear in the page text.
             exclude_text (List[str], optional): Strings that must not appear in the page text.
             use_autoprompt (bool, optional): Convert query to Exa (default False).
-            type (str, optional): 'keyword', 'neural', 'hybrid', 'fast', or 'auto' (default 'auto').
+            type (str, optional): 'keyword', 'neural', 'hybrid', 'fast', 'deep', or 'auto' (default 'auto').
             category (str, optional): e.g. 'company'
             flags (List[str], optional): Experimental flags for Exa usage.
             moderation (bool, optional): If True, the search results will be moderated for safety.

{exa_py-1.15.5 → exa_py-1.16.0}/exa_py/websets/client.py

@@ -13,6 +13,7 @@ from .types import (
     CreateWebsetParameters,
     PreviewWebsetParameters,
     PreviewWebsetResponse,
+    RequestOptions,
 )
 from .core.base import WebsetsBaseClient
 from .core.async_base import WebsetsAsyncBaseClient
@@ -37,16 +38,19 @@ class WebsetsClient(WebsetsBaseClient):
         self.imports = ImportsClient(client)
         self.events = EventsClient(client)
 
-    def create(self, params: Union[Dict[str, Any], CreateWebsetParameters]) -> Webset:
+    def create(self, params: Union[Dict[str, Any], CreateWebsetParameters], 
+               options: Optional[Union[Dict[str, Any], RequestOptions]] = None) -> Webset:
         """Create a new Webset.
         
         Args:
             params (CreateWebsetParameters): The parameters for creating a webset.
+            options (RequestOptions, optional): Request options including priority and/or custom headers.
+                Can specify priority as 'low', 'medium', or 'high'.
         
         Returns:
             Webset: The created webset.
         """
-        response = self.request("/v0/websets", data=params)
+        response = self.request("/v0/websets", data=params, options=options)
         return Webset.model_validate(response)
 
     def preview(self, params: Union[Dict[str, Any], PreviewWebsetParameters]) -> PreviewWebsetResponse:
@@ -171,16 +175,19 @@ class AsyncWebsetsClient(WebsetsAsyncBaseClient):
         self.imports = AsyncImportsClient(client)
         self.events = AsyncEventsClient(client)
 
-    async def create(self, params: Union[Dict[str, Any], CreateWebsetParameters]) -> Webset:
+    async def create(self, params: Union[Dict[str, Any], CreateWebsetParameters],
+                     options: Optional[Union[Dict[str, Any], RequestOptions]] = None) -> Webset:
         """Create a new Webset.
         
         Args:
             params (CreateWebsetParameters): The parameters for creating a webset.
+            options (RequestOptions, optional): Request options including priority and/or custom headers.
+                Can specify priority as 'low', 'medium', or 'high'.
         
         Returns:
             Webset: The created webset.
         """
-        response = await self.request("/v0/websets", data=params)
+        response = await self.request("/v0/websets", data=params, options=options)
         return Webset.model_validate(response)
 
     async def preview(self, params: Union[Dict[str, Any], PreviewWebsetParameters]) -> PreviewWebsetResponse:

{exa_py-1.15.5 → exa_py-1.16.0}/exa_py/websets/core/async_base.py

@@ -51,7 +51,8 @@ class WebsetsAsyncBaseClient:
             raise TypeError(f"Expected dict, ExaBaseModel, or str, got {type(data)}")
         
     async def request(self, endpoint: str, data: Optional[Union[Dict[str, Any], ExaBaseModel, str]] = None, 
-                method: str = "POST", params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+                method: str = "POST", params: Optional[Dict[str, Any]] = None,
+                headers: Optional[Dict[str, str]] = None, options: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
         """Make an async request to the Exa API.
         
         Args:
@@ -59,6 +60,8 @@ class WebsetsAsyncBaseClient:
             data (Union[Dict[str, Any], ExaBaseModel, str], optional): The request data. Can be a dictionary, model instance, or string. Defaults to None.
             method (str, optional): The HTTP method. Defaults to "POST".
             params (Dict[str, Any], optional): The query parameters. Defaults to None.
+            headers (Dict[str, str], optional): Custom headers to include in the request. Defaults to None.
+            options (Dict[str, Any], optional): Request options that may include 'priority' and/or 'headers'. Defaults to None.
             
         Returns:
             Dict[str, Any]: The API response.
@@ -70,8 +73,35 @@ class WebsetsAsyncBaseClient:
             # If data is a model instance, convert it to a dict
             data = data.model_dump(mode='json', by_alias=True, exclude_none=True)
             
+        # Process options to build headers
+        final_headers = {}
+        
+        # If options are provided, process them
+        if options:
+            # Handle RequestOptions model
+            if hasattr(options, 'priority') or hasattr(options, 'headers'):
+                # It's a RequestOptions instance
+                if hasattr(options, 'priority') and options.priority:
+                    final_headers['x-exa-websets-priority'] = options.priority
+                if hasattr(options, 'headers') and options.headers:
+                    final_headers.update(options.headers)
+            # Handle dict options
+            elif isinstance(options, dict):
+                if 'priority' in options:
+                    final_headers['x-exa-websets-priority'] = options['priority']
+                if 'headers' in options:
+                    final_headers.update(options.get('headers', {}))
+        
+        # Merge with any directly passed headers
+        if headers:
+            final_headers.update(headers)
+            
         # Ensure proper URL construction by removing leading slash from endpoint if present
         if endpoint.startswith("/"):
             endpoint = endpoint[1:]
             
-        return await self._client.async_request("/websets/" + endpoint, data=data, method=method, params=params) 
+        # Only pass headers if there are any
+        if final_headers:
+            return await self._client.async_request("/websets/" + endpoint, data=data, method=method, params=params, headers=final_headers)
+        else:
+            return await self._client.async_request("/websets/" + endpoint, data=data, method=method, params=params) 

{exa_py-1.15.5 → exa_py-1.16.0}/exa_py/websets/core/base.py

@@ -73,7 +73,8 @@ class WebsetsBaseClient:
             raise TypeError(f"Expected dict, ExaBaseModel, or str, got {type(data)}")
         
     def request(self, endpoint: str, data: Optional[Union[Dict[str, Any], ExaBaseModel, str]] = None, 
-                method: str = "POST", params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+                method: str = "POST", params: Optional[Dict[str, Any]] = None, 
+                headers: Optional[Dict[str, str]] = None, options: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
         """Make a request to the Exa API.
         
         Args:
@@ -81,6 +82,8 @@ class WebsetsBaseClient:
             data (Union[Dict[str, Any], ExaBaseModel, str], optional): The request data. Can be a dictionary, model instance, or string. Defaults to None.
             method (str, optional): The HTTP method. Defaults to "POST".
             params (Dict[str, Any], optional): The query parameters. Defaults to None.
+            headers (Dict[str, str], optional): Custom headers to include in the request. Defaults to None.
+            options (Dict[str, Any], optional): Request options that may include 'priority' and/or 'headers'. Defaults to None.
             
         Returns:
             Dict[str, Any]: The API response.
@@ -92,9 +95,36 @@ class WebsetsBaseClient:
             # If data is a model instance, convert it to a dict
             data = data.model_dump(mode='json', by_alias=True, exclude_none=True)
             
+        # Process options to build headers
+        final_headers = {}
+        
+        # If options are provided, process them
+        if options:
+            # Handle RequestOptions model
+            if hasattr(options, 'priority') or hasattr(options, 'headers'):
+                # It's a RequestOptions instance
+                if hasattr(options, 'priority') and options.priority:
+                    final_headers['x-exa-websets-priority'] = options.priority
+                if hasattr(options, 'headers') and options.headers:
+                    final_headers.update(options.headers)
+            # Handle dict options
+            elif isinstance(options, dict):
+                if 'priority' in options:
+                    final_headers['x-exa-websets-priority'] = options['priority']
+                if 'headers' in options:
+                    final_headers.update(options.get('headers', {}))
+        
+        # Merge with any directly passed headers
+        if headers:
+            final_headers.update(headers)
+            
         # Ensure proper URL construction by removing leading slash from endpoint if present
         if endpoint.startswith("/"):
             endpoint = endpoint[1:]
             
-        return self._client.request("/websets/" + endpoint, data=data, method=method, params=params) 
+        # Only pass headers if there are any
+        if final_headers:
+            return self._client.request("/websets/" + endpoint, data=data, method=method, params=params, headers=final_headers)
+        else:
+            return self._client.request("/websets/" + endpoint, data=data, method=method, params=params) 
 

{exa_py-1.15.5 → exa_py-1.16.0}/exa_py/websets/searches/client.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
-from typing import Dict, Any, Union
+from typing import Dict, Any, Union, Optional
 
 from ..types import (
     CreateWebsetSearchParameters,
     WebsetSearch,
+    RequestOptions,
 )
 from ..core.base import WebsetsBaseClient
 from ..core.async_base import WebsetsAsyncBaseClient
@@ -15,17 +16,20 @@ class WebsetSearchesClient(WebsetsBaseClient):
     def __init__(self, client):
         super().__init__(client)
 
-    def create(self, webset_id: str, params: Union[Dict[str, Any], CreateWebsetSearchParameters]) -> WebsetSearch:
+    def create(self, webset_id: str, params: Union[Dict[str, Any], CreateWebsetSearchParameters],
+               options: Optional[Union[Dict[str, Any], RequestOptions]] = None) -> WebsetSearch:
         """Create a new Search for the Webset.
         
         Args:
             webset_id (str): The id of the Webset.
             params (CreateWebsetSearchParameters): The parameters for creating a search.
+            options (RequestOptions, optional): Request options including priority and/or custom headers.
+                Can specify priority as 'low', 'medium', or 'high'.
         
         Returns:
             WebsetSearch: The created search.
         """
-        response = self.request(f"/v0/websets/{webset_id}/searches", data=params)
+        response = self.request(f"/v0/websets/{webset_id}/searches", data=params, options=options)
         return WebsetSearch.model_validate(response)
 
     def get(self, webset_id: str, id: str) -> WebsetSearch:
@@ -61,17 +65,20 @@ class AsyncWebsetSearchesClient(WebsetsAsyncBaseClient):
     def __init__(self, client):
         super().__init__(client)
 
-    async def create(self, webset_id: str, params: Union[Dict[str, Any], CreateWebsetSearchParameters]) -> WebsetSearch:
+    async def create(self, webset_id: str, params: Union[Dict[str, Any], CreateWebsetSearchParameters],
+                     options: Optional[Union[Dict[str, Any], RequestOptions]] = None) -> WebsetSearch:
         """Create a new Search for the Webset.
         
         Args:
             webset_id (str): The id of the Webset.
             params (CreateWebsetSearchParameters): The parameters for creating a search.
+            options (RequestOptions, optional): Request options including priority and/or custom headers.
+                Can specify priority as 'low', 'medium', or 'high'.
         
         Returns:
             WebsetSearch: The created search.
         """
-        response = await self.request(f"/v0/websets/{webset_id}/searches", data=params)
+        response = await self.request(f"/v0/websets/{webset_id}/searches", data=params, options=options)
         return WebsetSearch.model_validate(response)
 
     async def get(self, webset_id: str, id: str) -> WebsetSearch:

{exa_py-1.15.5 → exa_py-1.16.0}/exa_py/websets/types.py

@@ -12,6 +12,21 @@ from pydantic import AnyUrl, Field, PositiveInt
 from .core.base import ExaBaseModel
 
 
+class WebsetPriority(Enum):
+    """Priority levels for webset operations."""
+    low = 'low'
+    medium = 'medium'
+    high = 'high'
+
+
+class RequestOptions(ExaBaseModel):
+    """Options for API requests."""
+    priority: Optional[Literal['low', 'medium', 'high']] = None
+    """Priority level for the request (low, medium, or high)."""
+    headers: Optional[Dict[str, str]] = None
+    """Custom headers to include in the request."""
+
+
 class WebsetSearchBehavior(Enum):
     """
     The behavior of the Search when it is added to a Webset.

{exa_py-1.15.5 → exa_py-1.16.0}/pyproject.toml

@@ -5,17 +5,18 @@ typing-extensions = "^4.12.2"
 openai = "^1.48"
 pydantic = "^2.10.6"
 httpx = "^0.28.1"
+httpcore = "^1.0.9"
+python-dotenv = "^1.0.1"
 
 [tool.poetry.group.dev.dependencies]
-python-dotenv = "^1.0.1"
-setuptools = "^74.0.0"
+setuptools = "^78.1.1"
 docutils = "^0.21.2"
 twine = "^5.1.1"
 datamodel-code-generator = "^0.28.4"
-pytest = "^8.3.5"
-pytest-cov = "^6.0.0"
-pytest-mock = "^3.14.0"
-pytest-asyncio = "^0.24.0"
+pytest = "^8.4.1"
+pytest-cov = "^6.2.1"
+pytest-mock = "^3.14.1"
+pytest-asyncio = "^1.0.0"
 
 [build-system]
 requires = ["poetry-core"]
@@ -23,7 +24,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "exa-py"
-version = "1.15.5"
+version = "1.16.0"
 description = "Python SDK for Exa API."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -35,6 +36,8 @@ dependencies = [
     "openai>=1.48",
     "pydantic>=2.10.6",
     "httpx>=0.28.1",
+    "httpcore>=1.0.9",
+    "python-dotenv>=1.0.1",
 ]
 
 [dependency-groups]