exa-py 1.11.0__tar.gz → 1.12.0__tar.gz

{exa_py-1.11.0 → exa_py-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exa-py
-Version: 1.11.0
+Version: 1.12.0
 Summary: Python SDK for Exa API.
 License: MIT
 Author: Exa AI

{exa_py-1.11.0 → exa_py-1.12.0}/exa_py/api.py

@@ -7,6 +7,7 @@ import re
 from dataclasses import dataclass
 from functools import wraps
 from typing import (
+    Any,
     Callable,
     Dict,
     Generic,
@@ -36,6 +37,7 @@ from exa_py.utils import (
     maybe_get_query,
 )
 from .websets import WebsetsClient
+from .websets.core.base import ExaJSONEncoder
 
 is_beta = os.getenv("IS_BETA") == "True"
 
@@ -840,7 +842,7 @@ class Exa:
         self,
         api_key: Optional[str],
         base_url: str = "https://api.exa.ai",
-        user_agent: str = "exa-py 1.11.0",
+        user_agent: str = "exa-py 1.12.0",
     ):
         """Initialize the Exa client with the provided API key and optional base URL and user agent.
 
@@ -857,17 +859,17 @@ class Exa:
                     "API key must be provided as an argument or in EXA_API_KEY environment variable"
                 )
         self.base_url = base_url
-        self.headers = {"x-api-key": api_key, "User-Agent": user_agent}
+        self.headers = {"x-api-key": api_key, "User-Agent": user_agent, "Content-Type": "application/json"}
         self.websets = WebsetsClient(self)
 
-    def request(self, endpoint: str, data=None, method="POST", params=None):
+    def request(self, endpoint: str, data: Optional[Union[Dict[str, Any], str]] = None, method: str = "POST", params: Optional[Dict[str, Any]] = None) -> Union[Dict[str, Any], requests.Response]:
         """Send a request to the Exa API, optionally streaming if data['stream'] is True.
 
         Args:
             endpoint (str): The API endpoint (path).
             data (dict, optional): The JSON payload to send. Defaults to None.
             method (str, optional): The HTTP method to use. Defaults to "POST".
-            params (dict, optional): Query parameters to include. Defaults to None.
+            params (Dict[str, Any], optional): Query parameters to include. Defaults to None.
 
         Returns:
             Union[dict, requests.Response]: If streaming, returns the Response object.
@@ -876,9 +878,20 @@ class Exa:
         Raises:
             ValueError: If the request fails (non-200 status code).
         """
+        # Handle the case when data is a string
+        if isinstance(data, str):
+            # Use the string directly as the data payload
+            json_data = data
+        else:
+            # Otherwise, serialize the dictionary to JSON if it exists
+            json_data = json.dumps(data, cls=ExaJSONEncoder) if data else None
+            
         if data and data.get("stream"):
             res = requests.post(
-                self.base_url + endpoint, json=data, headers=self.headers, stream=True
+                self.base_url + endpoint, 
+                data=json_data,
+                headers=self.headers, 
+                stream=True
             )
             return res
 
@@ -888,11 +901,15 @@ class Exa:
             )
         elif method.upper() == "POST":
             res = requests.post(
-                self.base_url + endpoint, json=data, headers=self.headers
+                self.base_url + endpoint, 
+                data=json_data,
+                headers=self.headers
             )
         elif method.upper() == "PATCH":
             res = requests.patch(
-                self.base_url + endpoint, json=data, headers=self.headers
+                self.base_url + endpoint, 
+                data=json_data,
+                headers=self.headers
             )
         elif method.upper() == "DELETE":
             res = requests.delete(

{exa_py-1.11.0 → exa_py-1.12.0}/exa_py/websets/client.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import time
 from datetime import datetime
-from typing import List, Optional, Literal
+from typing import List, Optional, Literal, Dict, Any, Union
 
 from .types import (
     Webset,
@@ -28,16 +28,16 @@ class WebsetsClient(WebsetsBaseClient):
         self.enrichments = WebsetEnrichmentsClient(client)
         self.webhooks = WebsetWebhooksClient(client)
 
-    def create(self, params: CreateWebsetParameters) -> Webset:
+    def create(self, params: Union[Dict[str, Any], CreateWebsetParameters]) -> Webset:
         """Create a new Webset.
         
         Args:
-            params (CreateWebsetRequest): The parameters for creating a webset.
+            params (CreateWebsetParameters): The parameters for creating a webset.
         
         Returns:
             Webset: The created webset.
         """
-        response = self.request("/v0/websets", data=params.model_dump(by_alias=True, exclude_none=True))
+        response = self.request("/v0/websets", data=params)
         return Webset.model_validate(response)
 
     def get(self, id: str, *, expand: Optional[List[Literal["items"]]] = None) -> GetWebsetResponse:
@@ -69,7 +69,7 @@ class WebsetsClient(WebsetsBaseClient):
         response = self.request("/v0/websets", params=params, method="GET")
         return ListWebsetsResponse.model_validate(response)
 
-    def update(self, id: str, params: UpdateWebsetRequest) -> Webset:
+    def update(self, id: str, params: Union[Dict[str, Any], UpdateWebsetRequest]) -> Webset:
         """Update a Webset.
         
         Args:
@@ -79,7 +79,7 @@ class WebsetsClient(WebsetsBaseClient):
         Returns:
             Webset: The updated webset.
         """
-        response = self.request(f"/v0/websets/{id}", data=params.model_dump(by_alias=True, exclude_none=True), method="POST")
+        response = self.request(f"/v0/websets/{id}", data=params, method="POST")
         return Webset.model_validate(response)
 
     def delete(self, id: str) -> Webset:
@@ -104,23 +104,29 @@ class WebsetsClient(WebsetsBaseClient):
             Webset: The canceled webset.
         """
         response = self.request(f"/v0/websets/{id}/cancel", method="POST")
-        return Webset.model_validate(response) 
-    
-    def wait_until_idle(self, id: str, *, timeout: Optional[int] = None) -> Webset:
+        return Webset.model_validate(response)
+
+    def wait_until_idle(self, id: str, *, timeout: int = 3600, poll_interval: int = 5) -> Webset:
         """Wait until a Webset is idle.
         
         Args:
             id (str): The id or externalId of the Webset.
-        
+            timeout (int, optional): Maximum time to wait in seconds. Defaults to 3600.
+            poll_interval (int, optional): Time to wait between polls in seconds. Defaults to 5.
+            
         Returns:
-            Webset: The webset.
+            Webset: The webset once it's idle.
+            
+        Raises:
+            TimeoutError: If the webset does not become idle within the timeout period.
         """
         start_time = time.time()
         while True:
             webset = self.get(id)
-            if webset.status == WebsetStatus.idle:
-                break
-            time.sleep(1)
-            if timeout and time.time() - start_time > timeout:
-                raise Exception("Webset timed out")
-        return webset
+            if webset.status == WebsetStatus.idle.value:
+                return webset
+                
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Webset {id} did not become idle within {timeout} seconds")
+                
+            time.sleep(poll_interval)

exa_py-1.12.0/exa_py/websets/core/base.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import json
+from pydantic import ConfigDict, BaseModel, AnyUrl
+from enum import Enum
+from typing import Any, Dict, Optional, TypeVar, Generic, Type, get_origin, get_args, Union
+
+# Generic type var for any Enum
+EnumT = TypeVar('EnumT', bound=Enum)
+
+# Generic type for any ExaBaseModel
+ModelT = TypeVar('ModelT', bound='ExaBaseModel')
+
+# Custom JSON encoder for handling AnyUrl
+class ExaJSONEncoder(json.JSONEncoder):
+    def default(self, obj):
+        if isinstance(obj, AnyUrl):
+            return str(obj)
+        return super().default(obj)
+
+class ExaBaseModel(BaseModel):
+    """Base model for all Exa models with common configuration."""
+    model_config = ConfigDict(
+        populate_by_name=True,
+        use_enum_values=True,
+        coerce_numbers_to_str=False,  # Don't convert numbers to strings
+        str_strip_whitespace=True,  # Strip whitespace from strings
+        str_to_lower=False,  # Don't convert strings to lowercase
+        str_to_upper=False,  # Don't convert strings to uppercase
+        from_attributes=True,  # Allow initialization from attributes
+        validate_assignment=True,  # Validate on assignment
+        extra='forbid',  # Forbid extra fields
+        json_encoders={AnyUrl: str}  # Convert AnyUrl to string when serializing to JSON
+    )
+
+class WebsetsBaseClient:
+    base_url: str
+
+    """Base client for Exa API resources."""
+
+    def __init__(self, client):
+        """Initialize the client.
+        
+        Args:
+            client: The parent Exa client.
+        """
+        self._client = client
+        
+    def _prepare_data(self, data: Union[Dict[str, Any], ExaBaseModel, str], model_class: Optional[Type[ModelT]] = None) -> Union[Dict[str, Any], str]:
+        """Prepare data for API request, converting dict to model if needed.
+        
+        Args:
+            data: Either a dictionary, model instance, or string
+            model_class: The model class to use if data is a dictionary
+            
+        Returns:
+            Dictionary prepared for API request or string if string data was provided
+        """
+        if isinstance(data, str):
+            # Return string as is
+            return data
+        elif isinstance(data, dict) and model_class:
+            # Convert dict to model instance
+            model_instance = model_class.model_validate(data)
+            return model_instance.model_dump(by_alias=True, exclude_none=True)
+        elif isinstance(data, ExaBaseModel):
+            # Use model's dump method
+            return data.model_dump(by_alias=True, exclude_none=True)
+        elif isinstance(data, dict):
+            # Use dict directly
+            return data
+        else:
+            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]:
+        """Make a request to the Exa API.
+        
+        Args:
+            endpoint (str): The API endpoint to request.
+            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.
+            
+        Returns:
+            Dict[str, Any]: The API response.
+        """
+        if isinstance(data, str):
+            # If data is a string, pass it as is
+            pass
+        elif data is not None and isinstance(data, ExaBaseModel):
+            # If data is a model instance, convert it to a dict
+            data = data.model_dump(by_alias=True, exclude_none=True)
+            
+        return self._client.request("/websets/" + endpoint, data=data, method=method, params=params) 
+    

{exa_py-1.11.0 → exa_py-1.12.0}/exa_py/websets/enrichments/client.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import Dict, Any, Union
+
 from ..types import (
     CreateEnrichmentParameters,
     WebsetEnrichment,
@@ -12,7 +14,7 @@ class WebsetEnrichmentsClient(WebsetsBaseClient):
     def __init__(self, client):
         super().__init__(client)
 
-    def create(self, webset_id: str, params: CreateEnrichmentParameters) -> WebsetEnrichment:
+    def create(self, webset_id: str, params: Union[Dict[str, Any], CreateEnrichmentParameters]) -> WebsetEnrichment:
         """Create an Enrichment for a Webset.
         
         Args:
@@ -22,7 +24,7 @@ class WebsetEnrichmentsClient(WebsetsBaseClient):
         Returns:
             WebsetEnrichment: The created enrichment.
         """
-        response = self.request(f"/v0/websets/{webset_id}/enrichments", data=params.model_dump(by_alias=True, exclude_none=True))
+        response = self.request(f"/v0/websets/{webset_id}/enrichments", data=params)
         return WebsetEnrichment.model_validate(response)
 
     def get(self, webset_id: str, id: str) -> WebsetEnrichment:

{exa_py-1.11.0 → exa_py-1.12.0}/exa_py/websets/searches/client.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import Dict, Any, Union
+
 from ..types import (
     CreateWebsetSearchParameters,
     WebsetSearch,
@@ -12,7 +14,7 @@ class WebsetSearchesClient(WebsetsBaseClient):
     def __init__(self, client):
         super().__init__(client)
 
-    def create(self, webset_id: str, params: CreateWebsetSearchParameters) -> WebsetSearch:
+    def create(self, webset_id: str, params: Union[Dict[str, Any], CreateWebsetSearchParameters]) -> WebsetSearch:
         """Create a new Search for the Webset.
         
         Args:
@@ -22,7 +24,7 @@ class WebsetSearchesClient(WebsetsBaseClient):
         Returns:
             WebsetSearch: The created search.
         """
-        response = self.request(f"/v0/websets/{webset_id}/searches", data=params.model_dump(by_alias=True, exclude_none=True))
+        response = self.request(f"/v0/websets/{webset_id}/searches", data=params)
         return WebsetSearch.model_validate(response)
 
     def get(self, webset_id: str, id: str) -> WebsetSearch:

{exa_py-1.11.0 → exa_py-1.12.0}/exa_py/websets/types.py

@@ -29,7 +29,7 @@ class CreateEnrichmentParameters(ExaBaseModel):
     """
     Provide a description of the enrichment task you want to perform to each Webset Item.
     """
-    format: Optional[str] = None
+    format: Optional[Format] = None
     """
     Format of the enrichment response.
 
@@ -46,7 +46,7 @@ class CreateEnrichmentParameters(ExaBaseModel):
 
 
 class CreateWebhookParameters(ExaBaseModel):
-    events: List[Event] = Field(..., max_items=12, min_items=1)
+    events: List[EventType] = Field(..., max_items=12, min_items=1)
     """
     The events to trigger the webhook
     """
@@ -127,7 +127,7 @@ class CreateWebsetSearchParameters(ExaBaseModel):
     """
     The behaviour of the Search when it is added to a Webset.
 
-    - `override`: the search will reuse the existing Items found in the Webset and evaluate them against the new criteria. Any Items that don't match the new criteria will not be discarded.
+    - `override`: the search will reuse the existing Items found in the Webset and evaluate them against the new criteria. Any Items that don't match the new criteria will be discarded.
     """
     metadata: Optional[Dict[str, Any]] = None
     """
@@ -149,9 +149,9 @@ class Criterion(ExaBaseModel):
 class EnrichmentResult(ExaBaseModel):
     object: Literal['enrichment_result']
     format: WebsetEnrichmentFormat
-    result: List[str]
+    result: Optional[List[str]] = None
     """
-    The result of the enrichment.
+    The result of the enrichment. None if the enrichment wasn't successful.
     """
     reasoning: Optional[str] = None
     """
@@ -167,7 +167,7 @@ class EnrichmentResult(ExaBaseModel):
     """
 
 
-class Event(Enum):
+class EventType(Enum):
     webset_created = 'webset.created'
     webset_deleted = 'webset.deleted'
     webset_paused = 'webset.paused'
@@ -182,6 +182,7 @@ class Event(Enum):
     webset_item_enriched = 'webset.item.enriched'
 
 
+
 class Format(Enum):
     """
     Format of the enrichment response.
@@ -225,6 +226,21 @@ class ListEventsResponse(ExaBaseModel):
     """
 
 
+class ListWebhookAttemptsResponse(ExaBaseModel):
+    data: List[WebhookAttempt]
+    """
+    The list of webhook attempts
+    """
+    has_more: bool = Field(..., alias='hasMore')
+    """
+    Whether there are more results to paginate through
+    """
+    next_cursor: Optional[str] = Field(..., alias='nextCursor')
+    """
+    The cursor to paginate through the next set of results
+    """
+
+
 class ListWebhooksResponse(ExaBaseModel):
     data: List[Webhook]
     """
@@ -335,7 +351,7 @@ class Search(ExaBaseModel):
 
     Any URL provided will be crawled and used as context for the search.
     """
-    count: confloat(ge=1.0)
+    count: Optional[confloat(ge=1.0)] = 10
     """
     Number of Items the Webset will attempt to find.
 
@@ -374,7 +390,7 @@ class Source(Enum):
 
 
 class UpdateWebhookParameters(ExaBaseModel):
-    events: Optional[List[Event]] = Field(None, max_items=12, min_items=1)
+    events: Optional[List[EventType]] = Field(None, max_items=12, min_items=1)
     """
     The events to trigger the webhook
     """
@@ -389,7 +405,7 @@ class UpdateWebhookParameters(ExaBaseModel):
 
 
 class UpdateWebsetRequest(ExaBaseModel):
-    metadata: Optional[Dict[str, Any]] = None
+    metadata: Optional[Dict[str, constr(max_length=1000)]] = None
     """
     Set of key-value pairs you want to associate with this object.
     """
@@ -405,7 +421,7 @@ class Webhook(ExaBaseModel):
     """
     The status of the webhook
     """
-    events: List[Event] = Field(..., min_items=1)
+    events: List[EventType] = Field(..., min_items=1)
     """
     The events to trigger the webhook
     """
@@ -413,7 +429,11 @@ class Webhook(ExaBaseModel):
     """
     The URL to send the webhook to
     """
-    metadata: Optional[Dict[str, Any]] = None
+    secret: Optional[str] = None
+    """
+    The secret to verify the webhook signature. Only returned on Webhook creation.
+    """
+    metadata: Optional[Dict[str, Any]] = {}
     """
     The metadata of the webhook
     """
@@ -427,6 +447,54 @@ class Webhook(ExaBaseModel):
     """
 
 
+class WebhookAttempt(ExaBaseModel):
+    id: str
+    """
+    The unique identifier for the webhook attempt
+    """
+    object: Literal['webhook_attempt']
+    event_id: str = Field(..., alias='eventId')
+    """
+    The unique identifier for the event
+    """
+    event_type: EventType = Field(..., alias='eventType')
+    """
+    The type of event
+    """
+    webhook_id: str = Field(..., alias='webhookId')
+    """
+    The unique identifier for the webhook
+    """
+    url: str
+    """
+    The URL that was used during the attempt
+    """
+    successful: bool
+    """
+    Whether the attempt was successful
+    """
+    response_headers: Dict[str, Any] = Field(..., alias='responseHeaders')
+    """
+    The headers of the response
+    """
+    response_body: str = Field(..., alias='responseBody')
+    """
+    The body of the response
+    """
+    response_status_code: float = Field(..., alias='responseStatusCode')
+    """
+    The status code of the response
+    """
+    attempt: float
+    """
+    The attempt number of the webhook
+    """
+    attempted_at: datetime = Field(..., alias='attemptedAt')
+    """
+    The date and time the webhook attempt was made
+    """
+
+
 class WebhookStatus(Enum):
     """
     The status of the webhook
@@ -458,7 +526,7 @@ class Webset(ExaBaseModel):
     """
     The Enrichments to apply to the Webset Items.
     """
-    metadata: Optional[Dict[str, Any]] = None
+    metadata: Optional[Dict[str, Any]] = {}
     """
     Set of key-value pairs you want to associate with this object.
     """
@@ -558,7 +626,7 @@ class WebsetEnrichment(ExaBaseModel):
 
     This will be automatically generated based on the description and format.
     """
-    metadata: Optional[Dict[str, Any]] = None
+    metadata: Optional[Dict[str, Any]] = {}
     """
     The metadata of the enrichment
     """
@@ -595,10 +663,6 @@ class WebsetEnrichmentStatus(Enum):
     completed = 'completed'
 
 
-class WebsetExportFormat(Enum):
-    csv = 'csv'
-
-
 class WebsetIdleEvent(ExaBaseModel):
     id: str
     """
@@ -645,7 +709,7 @@ class WebsetItem(ExaBaseModel):
     """
     The criteria evaluations of the item
     """
-    enrichments: Optional[List[EnrichmentResult]]
+    enrichments: List[EnrichmentResult]
     """
     The enrichments results of the Webset item
     """
@@ -806,7 +870,7 @@ class WebsetItemEvaluation(ExaBaseModel):
     """
     The satisfaction of the criterion
     """
-    references: Optional[List[Reference]]
+    references: List[Reference] = []
     """
     The references used to generate the result. `null` if the evaluation is not yet completed.
     """
@@ -912,14 +976,12 @@ class WebsetSearch(ExaBaseModel):
     """
     The query used to create the search.
     """
-    entity: Optional[
-        Union[
-            WebsetCompanyEntity,
-            WebsetPersonEntity,
-            WebsetArticleEntity,
-            WebsetResearchPaperEntity,
-            WebsetCustomEntity,
-        ]
+    entity: Union[
+        WebsetCompanyEntity,
+        WebsetPersonEntity,
+        WebsetArticleEntity,
+        WebsetResearchPaperEntity,
+        WebsetCustomEntity,
     ]
     """
     The entity the search will return results for.
@@ -938,7 +1000,7 @@ class WebsetSearch(ExaBaseModel):
     """
     The progress of the search
     """
-    metadata: Optional[Dict[str, Any]] = None
+    metadata: Optional[Dict[str, Any]] = {}
     """
     Set of key-value pairs you want to associate with this object.
     """
@@ -964,7 +1026,7 @@ class WebsetSearchBehaviour(Enum):
     """
     The behaviour of the Search when it is added to a Webset.
 
-    - `override`: the search will reuse the existing Items found in the Webset and evaluate them against the new criteria. Any Items that don't match the new criteria will not be discarded.
+    - `override`: the search will reuse the existing Items found in the Webset and evaluate them against the new criteria. Any Items that don't match the new criteria will be discarded.
     """
 
     override = 'override'
@@ -1051,4 +1113,4 @@ class GetWebsetResponse(Webset):
     items: Optional[List[WebsetItem]] = None
     """
     When expand query parameter contains `items`, this will contain the items in the webset
-    """
+    """