exa-py 1.15.0__py3-none-any.whl → 1.15.2__py3-none-any.whl

exa_py/api.py

@@ -23,6 +23,7 @@ from typing import (
     overload,
 )
 
+from .websets import AsyncWebsetsClient
 import httpx
 import requests
 from openai import OpenAI
@@ -2413,6 +2414,8 @@ class AsyncExa(Exa):
         super().__init__(api_key, api_base)
         # Override the synchronous ResearchClient with its async counterpart.
         self.research = AsyncResearchClient(self)
+        # Override the synchronous WebsetsClient with its async counterpart.
+        self.websets = AsyncWebsetsClient(self)
         self._client = None
 
     @property

exa_py/websets/__init__.py

@@ -1,9 +1,10 @@
-from .client import WebsetsClient
+from .client import WebsetsClient, AsyncWebsetsClient
 from .imports import ImportsClient
 from .events import EventsClient
 
 __all__ = [
     "WebsetsClient",
+    "AsyncWebsetsClient", 
     "ImportsClient",
     "EventsClient",
 ] 

exa_py/websets/async_client.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import asyncio
+from typing import List, Optional, Literal, Dict, Any, Union
+
+from .types import (
+    Webset,
+    ListWebsetsResponse,
+    GetWebsetResponse,
+    UpdateWebsetRequest,
+    WebsetStatus,
+    CreateWebsetParameters,
+    PreviewWebsetParameters,
+    PreviewWebsetResponse,
+)
+from .core.async_base import WebsetsAsyncBaseClient
+from .async_items.client import AsyncWebsetItemsClient
+from .async_searches.client import AsyncWebsetSearchesClient
+from .async_enrichments.client import AsyncWebsetEnrichmentsClient
+from .async_webhooks.client import AsyncWebsetWebhooksClient
+from .async_monitors.client import AsyncMonitorsClient
+from .async_imports.client import AsyncImportsClient
+from .async_events.client import AsyncEventsClient
+
+class AsyncWebsetsClient(WebsetsAsyncBaseClient):
+    """Async client for managing Websets."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+        self.items = AsyncWebsetItemsClient(client)
+        self.searches = AsyncWebsetSearchesClient(client)
+        self.enrichments = AsyncWebsetEnrichmentsClient(client)
+        self.webhooks = AsyncWebsetWebhooksClient(client)
+        self.monitors = AsyncMonitorsClient(client)
+        self.imports = AsyncImportsClient(client)
+        self.events = AsyncEventsClient(client)
+
+    async def create(self, params: Union[Dict[str, Any], CreateWebsetParameters]) -> Webset:
+        """Create a new Webset.
+        
+        Args:
+            params (CreateWebsetParameters): The parameters for creating a webset.
+        
+        Returns:
+            Webset: The created webset.
+        """
+        response = await self.request("/v0/websets", data=params)
+        return Webset.model_validate(response)
+
+    async def preview(self, params: Union[Dict[str, Any], PreviewWebsetParameters]) -> PreviewWebsetResponse:
+        """Preview a Webset before creating it.
+        
+        Args:
+            params (PreviewWebsetParameters): The parameters for previewing a webset.
+        
+        Returns:
+            PreviewWebsetResponse: The preview results.
+        """
+        response = await self.request("/v0/websets/preview", data=params)
+        return PreviewWebsetResponse.model_validate(response)
+
+    async def get(self, id: str, *, expand: Optional[List[Literal["items"]]] = None) -> GetWebsetResponse:
+        """Get a Webset by ID.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+            expand (List[Literal["items"]], optional): Expand items in the response.
+        
+        Returns:
+            GetWebsetResponse: The retrieved webset.
+        """
+        params = {}
+        if expand is not None:
+            params["expand"] = expand
+
+        response = await self.request(f"/v0/websets/{id}", params=params, method="GET")
+        return GetWebsetResponse.model_validate(response)
+
+    async def list(self, *, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListWebsetsResponse:
+        """List all Websets.
+        
+        Args:
+            cursor (str, optional): The cursor to paginate through the results.
+            limit (int, optional): The number of results to return (max 200).
+        
+        Returns:
+            ListWebsetsResponse: List of websets.
+        """
+        params = {k: v for k, v in {"cursor": cursor, "limit": limit}.items() if v is not None}
+        response = await self.request("/v0/websets", params=params, method="GET")
+        return ListWebsetsResponse.model_validate(response)
+
+    async def update(self, id: str, params: Union[Dict[str, Any], UpdateWebsetRequest]) -> Webset:
+        """Update a Webset.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+            params (UpdateWebsetRequest): The parameters for updating a webset.
+        
+        Returns:
+            Webset: The updated webset.
+        """
+        response = await self.request(f"/v0/websets/{id}", data=params, method="POST")
+        return Webset.model_validate(response)
+
+    async def delete(self, id: str) -> Webset:
+        """Delete a Webset.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+        
+        Returns:
+            Webset: The deleted webset.
+        """
+        response = await self.request(f"/v0/websets/{id}", method="DELETE")
+        return Webset.model_validate(response)
+
+    async def cancel(self, id: str) -> Webset:
+        """Cancel a running Webset.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+        
+        Returns:
+            Webset: The canceled webset.
+        """
+        response = await self.request(f"/v0/websets/{id}/cancel", method="POST")
+        return Webset.model_validate(response)
+
+    async 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 once it's idle.
+            
+        Raises:
+            TimeoutError: If the webset does not become idle within the timeout period.
+        """
+        start_time = asyncio.get_event_loop().time()
+        while True:
+            webset = await self.get(id)
+            if webset.status == WebsetStatus.idle.value:
+                return webset
+                
+            if asyncio.get_event_loop().time() - start_time > timeout:
+                raise TimeoutError(f"Webset {id} did not become idle within {timeout} seconds")
+                
+            await asyncio.sleep(poll_interval)

exa_py/websets/client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import time
+import asyncio
 from typing import List, Optional, Literal, Dict, Any, Union
 
 from .types import (
@@ -14,13 +15,14 @@ from .types import (
     PreviewWebsetResponse,
 )
 from .core.base import WebsetsBaseClient
-from .items import WebsetItemsClient
-from .searches import WebsetSearchesClient
-from .enrichments import WebsetEnrichmentsClient
-from .webhooks import WebsetWebhooksClient
-from .monitors import MonitorsClient
-from .imports import ImportsClient
-from .events import EventsClient
+from .core.async_base import WebsetsAsyncBaseClient
+from .items import WebsetItemsClient, AsyncWebsetItemsClient
+from .searches import WebsetSearchesClient, AsyncWebsetSearchesClient
+from .enrichments import WebsetEnrichmentsClient, AsyncWebsetEnrichmentsClient
+from .webhooks import WebsetWebhooksClient, AsyncWebsetWebhooksClient
+from .monitors import MonitorsClient, AsyncMonitorsClient
+from .imports import ImportsClient, AsyncImportsClient
+from .events import EventsClient, AsyncEventsClient
 
 class WebsetsClient(WebsetsBaseClient):
     """Client for managing Websets."""
@@ -154,3 +156,134 @@ class WebsetsClient(WebsetsBaseClient):
                 raise TimeoutError(f"Webset {id} did not become idle within {timeout} seconds")
                 
             time.sleep(poll_interval)
+
+
+class AsyncWebsetsClient(WebsetsAsyncBaseClient):
+    """Async client for managing Websets."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+        self.items = AsyncWebsetItemsClient(client)
+        self.searches = AsyncWebsetSearchesClient(client)
+        self.enrichments = AsyncWebsetEnrichmentsClient(client)
+        self.webhooks = AsyncWebsetWebhooksClient(client)
+        self.monitors = AsyncMonitorsClient(client)
+        self.imports = AsyncImportsClient(client)
+        self.events = AsyncEventsClient(client)
+
+    async def create(self, params: Union[Dict[str, Any], CreateWebsetParameters]) -> Webset:
+        """Create a new Webset.
+        
+        Args:
+            params (CreateWebsetParameters): The parameters for creating a webset.
+        
+        Returns:
+            Webset: The created webset.
+        """
+        response = await self.request("/v0/websets", data=params)
+        return Webset.model_validate(response)
+
+    async def preview(self, params: Union[Dict[str, Any], PreviewWebsetParameters]) -> PreviewWebsetResponse:
+        """Preview a Webset before creating it.
+        
+        Args:
+            params (PreviewWebsetParameters): The parameters for previewing a webset.
+        
+        Returns:
+            PreviewWebsetResponse: The preview results.
+        """
+        response = await self.request("/v0/websets/preview", data=params)
+        return PreviewWebsetResponse.model_validate(response)
+
+    async def get(self, id: str, *, expand: Optional[List[Literal["items"]]] = None) -> GetWebsetResponse:
+        """Get a Webset by ID.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+            expand (List[Literal["items"]], optional): Expand items in the response.
+        
+        Returns:
+            GetWebsetResponse: The retrieved webset.
+        """
+        params = {}
+        if expand is not None:
+            params["expand"] = expand
+
+        response = await self.request(f"/v0/websets/{id}", params=params, method="GET")
+        return GetWebsetResponse.model_validate(response)
+
+    async def list(self, *, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListWebsetsResponse:
+        """List all Websets.
+        
+        Args:
+            cursor (str, optional): The cursor to paginate through the results.
+            limit (int, optional): The number of results to return (max 200).
+        
+        Returns:
+            ListWebsetsResponse: List of websets.
+        """
+        params = {k: v for k, v in {"cursor": cursor, "limit": limit}.items() if v is not None}
+        response = await self.request("/v0/websets", params=params, method="GET")
+        return ListWebsetsResponse.model_validate(response)
+
+    async def update(self, id: str, params: Union[Dict[str, Any], UpdateWebsetRequest]) -> Webset:
+        """Update a Webset.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+            params (UpdateWebsetRequest): The parameters for updating a webset.
+        
+        Returns:
+            Webset: The updated webset.
+        """
+        response = await self.request(f"/v0/websets/{id}", data=params, method="POST")
+        return Webset.model_validate(response)
+
+    async def delete(self, id: str) -> Webset:
+        """Delete a Webset.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+        
+        Returns:
+            Webset: The deleted webset.
+        """
+        response = await self.request(f"/v0/websets/{id}", method="DELETE")
+        return Webset.model_validate(response)
+
+    async def cancel(self, id: str) -> Webset:
+        """Cancel a running Webset.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+        
+        Returns:
+            Webset: The canceled webset.
+        """
+        response = await self.request(f"/v0/websets/{id}/cancel", method="POST")
+        return Webset.model_validate(response)
+
+    async 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 once it's idle.
+            
+        Raises:
+            TimeoutError: If the webset does not become idle within the timeout period.
+        """
+        start_time = asyncio.get_event_loop().time()
+        while True:
+            webset = await self.get(id)
+            if webset.status == WebsetStatus.idle.value:
+                return webset
+                
+            if asyncio.get_event_loop().time() - start_time > timeout:
+                raise TimeoutError(f"Webset {id} did not become idle within {timeout} seconds")
+                
+            await asyncio.sleep(poll_interval)

exa_py/websets/core/__init__.py

@@ -1,9 +1,11 @@
 from ..types import *
+from .base import WebsetsBaseClient
+from .async_base import WebsetsAsyncBaseClient
 import sys
 
 # Get all public names from model module that don't start with underscore
 model_module = sys.modules[__name__]
-__all__ = ['WebsetsBaseClient', 'ExaBaseModel'] + [
+__all__ = ['WebsetsBaseClient', 'WebsetsAsyncBaseClient', 'ExaBaseModel'] + [
     name for name in dir(model_module)
-    if not name.startswith('_') and name not in ('WebsetsBaseClient', 'ExaBaseModel')
+    if not name.startswith('_') and name not in ('WebsetsBaseClient', 'WebsetsAsyncBaseClient', 'ExaBaseModel')
 ]

exa_py/websets/core/async_base.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+import asyncio
+from typing import Any, Dict, Optional, Type, TypeVar, Union
+
+from .base import ExaBaseModel
+
+# Generic type for any ExaBaseModel
+ModelT = TypeVar('ModelT', bound=ExaBaseModel)
+
+
+
+class WebsetsAsyncBaseClient:
+    base_url: str
+
+    """Base async client for Exa API resources."""
+
+    def __init__(self, client):
+        """Initialize the async client.
+        
+        Args:
+            client: The parent AsyncExa 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(mode='json', by_alias=True, exclude_none=True)
+        elif isinstance(data, ExaBaseModel):
+            # Use model's dump method
+            return data.model_dump(mode='json', 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)}")
+        
+    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]:
+        """Make an async 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(mode='json', by_alias=True, exclude_none=True)
+            
+        # 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) 

exa_py/websets/enrichments/__init__.py

@@ -1,3 +1,3 @@
-from .client import WebsetEnrichmentsClient
+from .client import WebsetEnrichmentsClient, AsyncWebsetEnrichmentsClient
 
-__all__ = ["WebsetEnrichmentsClient"] 
+__all__ = ["WebsetEnrichmentsClient", "AsyncWebsetEnrichmentsClient"] 

exa_py/websets/enrichments/client.py

@@ -4,9 +4,11 @@ from typing import Dict, Any, Union
 
 from ..types import (
     CreateEnrichmentParameters,
+    UpdateEnrichmentParameters,
     WebsetEnrichment,
 )
 from ..core.base import WebsetsBaseClient
+from ..core.async_base import WebsetsAsyncBaseClient
 
 class WebsetEnrichmentsClient(WebsetsBaseClient):
     """Client for managing Webset Enrichments."""
@@ -40,6 +42,20 @@ class WebsetEnrichmentsClient(WebsetsBaseClient):
         response = self.request(f"/v0/websets/{webset_id}/enrichments/{id}", method="GET")
         return WebsetEnrichment.model_validate(response)
 
+    def update(self, webset_id: str, id: str, params: Union[Dict[str, Any], UpdateEnrichmentParameters]) -> WebsetEnrichment:
+        """Update an Enrichment.
+        
+        Args:
+            webset_id (str): The id of the Webset.
+            id (str): The id of the Enrichment.
+            params (UpdateEnrichmentParameters): The parameters for updating an enrichment.
+        
+        Returns:
+            WebsetEnrichment: The updated enrichment.
+        """
+        response = self.request(f"/v0/websets/{webset_id}/enrichments/{id}", data=params, method="PATCH")
+        return WebsetEnrichment.model_validate(response)
+
     def delete(self, webset_id: str, id: str) -> WebsetEnrichment:
         """Delete an Enrichment.
         
@@ -64,4 +80,77 @@ class WebsetEnrichmentsClient(WebsetsBaseClient):
             WebsetEnrichment: The canceled enrichment.
         """
         response = self.request(f"/v0/websets/{webset_id}/enrichments/{id}/cancel", method="POST")
+        return WebsetEnrichment.model_validate(response)
+
+
+class AsyncWebsetEnrichmentsClient(WebsetsAsyncBaseClient):
+    """Async client for managing Webset Enrichments."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+
+    async def create(self, webset_id: str, params: Union[Dict[str, Any], CreateEnrichmentParameters]) -> WebsetEnrichment:
+        """Create an Enrichment for a Webset.
+        
+        Args:
+            webset_id (str): The id of the Webset.
+            params (CreateEnrichmentParameters): The parameters for creating an enrichment.
+        
+        Returns:
+            WebsetEnrichment: The created enrichment.
+        """
+        response = await self.request(f"/v0/websets/{webset_id}/enrichments", data=params)
+        return WebsetEnrichment.model_validate(response)
+
+    async def get(self, webset_id: str, id: str) -> WebsetEnrichment:
+        """Get an Enrichment by ID.
+        
+        Args:
+            webset_id (str): The id of the Webset.
+            id (str): The id of the Enrichment.
+        
+        Returns:
+            WebsetEnrichment: The retrieved enrichment.
+        """
+        response = await self.request(f"/v0/websets/{webset_id}/enrichments/{id}", method="GET")
+        return WebsetEnrichment.model_validate(response)
+
+    async def update(self, webset_id: str, id: str, params: Union[Dict[str, Any], UpdateEnrichmentParameters]) -> WebsetEnrichment:
+        """Update an Enrichment.
+        
+        Args:
+            webset_id (str): The id of the Webset.
+            id (str): The id of the Enrichment.
+            params (UpdateEnrichmentParameters): The parameters for updating an enrichment.
+        
+        Returns:
+            WebsetEnrichment: The updated enrichment.
+        """
+        response = await self.request(f"/v0/websets/{webset_id}/enrichments/{id}", data=params, method="PATCH")
+        return WebsetEnrichment.model_validate(response)
+
+    async def delete(self, webset_id: str, id: str) -> WebsetEnrichment:
+        """Delete an Enrichment.
+        
+        Args:
+            webset_id (str): The id of the Webset.
+            id (str): The id of the Enrichment.
+        
+        Returns:
+            WebsetEnrichment: The deleted enrichment.
+        """
+        response = await self.request(f"/v0/websets/{webset_id}/enrichments/{id}", method="DELETE")
+        return WebsetEnrichment.model_validate(response)
+
+    async def cancel(self, webset_id: str, id: str) -> WebsetEnrichment:
+        """Cancel a running Enrichment.
+        
+        Args:
+            webset_id (str): The id of the Webset.
+            id (str): The id of the Enrichment.
+        
+        Returns:
+            WebsetEnrichment: The canceled enrichment.
+        """
+        response = await self.request(f"/v0/websets/{webset_id}/enrichments/{id}/cancel", method="POST")
         return WebsetEnrichment.model_validate(response) 

exa_py/websets/events/__init__.py

@@ -1,3 +1,3 @@
-from .client import EventsClient
+from .client import EventsClient, AsyncEventsClient
 
-__all__ = ["EventsClient"]
+__all__ = ["EventsClient", "AsyncEventsClient"]