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

exa_py/websets/events/client.py

@@ -15,8 +15,16 @@ from ..types import (
     WebsetSearchUpdatedEvent,
     WebsetSearchCanceledEvent,
     WebsetSearchCompletedEvent,
+    ImportCreatedEvent,
+    ImportCompletedEvent,
+    MonitorCreatedEvent,
+    MonitorUpdatedEvent,
+    MonitorDeletedEvent,
+    MonitorRunCreatedEvent,
+    MonitorRunCompletedEvent,
 )
 from ..core.base import WebsetsBaseClient
+from ..core.async_base import WebsetsAsyncBaseClient
 
 # Type alias for all event types
 Event = Union[
@@ -30,6 +38,13 @@ Event = Union[
     WebsetSearchUpdatedEvent,
     WebsetSearchCanceledEvent,
     WebsetSearchCompletedEvent,
+    ImportCreatedEvent,
+    ImportCompletedEvent,
+    MonitorCreatedEvent,
+    MonitorUpdatedEvent,
+    MonitorDeletedEvent,
+    MonitorRunCreatedEvent,
+    MonitorRunCompletedEvent,
 ]
 
 class EventsClient(WebsetsBaseClient):
@@ -89,6 +104,94 @@ class EventsClient(WebsetsBaseClient):
             'webset.search.updated': WebsetSearchUpdatedEvent,
             'webset.search.canceled': WebsetSearchCanceledEvent,
             'webset.search.completed': WebsetSearchCompletedEvent,
+            'import.created': ImportCreatedEvent,
+            'import.completed': ImportCompletedEvent,
+            'monitor.created': MonitorCreatedEvent,
+            'monitor.updated': MonitorUpdatedEvent,
+            'monitor.deleted': MonitorDeletedEvent,
+            'monitor.run.created': MonitorRunCreatedEvent,
+            'monitor.run.completed': MonitorRunCompletedEvent,
+        }
+        
+        event_class = event_type_map.get(event_type)
+        if event_class:
+            return event_class.model_validate(response)
+        else:
+            # Fallback - try each type until one validates
+            # This shouldn't happen in normal operation
+            for event_class in event_type_map.values():
+                try:
+                    return event_class.model_validate(response)
+                except Exception:
+                    continue
+            
+            raise ValueError(f"Unknown event type: {event_type}")
+
+
+class AsyncEventsClient(WebsetsAsyncBaseClient):
+    """Async client for managing Events."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+
+    async def list(self, *, cursor: Optional[str] = None, limit: Optional[int] = None, 
+             types: Optional[List[EventType]] = None) -> ListEventsResponse:
+        """List all Events.
+        
+        Args:
+            cursor (str, optional): The cursor to paginate through the results.
+            limit (int, optional): The number of results to return.
+            types (List[EventType], optional): The types of events to filter by.
+        
+        Returns:
+            ListEventsResponse: List of events.
+        """
+        params = {}
+        if cursor is not None:
+            params["cursor"] = cursor
+        if limit is not None:
+            params["limit"] = limit
+        if types is not None:
+            # Convert EventType enums to their string values
+            params["types"] = [t.value if hasattr(t, 'value') else t for t in types]
+            
+        response = await self.request("/v0/events", params=params, method="GET")
+        return ListEventsResponse.model_validate(response)
+
+    async def get(self, id: str) -> Event:
+        """Get an Event by ID.
+        
+        Args:
+            id (str): The ID of the Event.
+        
+        Returns:
+            Event: The retrieved event.
+        """
+        response = await self.request(f"/v0/events/{id}", method="GET")
+        
+        # The response should contain a 'type' field that helps us determine
+        # which specific event class to use for validation
+        event_type = response.get('type')
+        
+        # Map event types to their corresponding classes
+        event_type_map = {
+            'webset.created': WebsetCreatedEvent,
+            'webset.deleted': WebsetDeletedEvent,
+            'webset.idle': WebsetIdleEvent,
+            'webset.paused': WebsetPausedEvent,
+            'webset.item.created': WebsetItemCreatedEvent,
+            'webset.item.enriched': WebsetItemEnrichedEvent,
+            'webset.search.created': WebsetSearchCreatedEvent,
+            'webset.search.updated': WebsetSearchUpdatedEvent,
+            'webset.search.canceled': WebsetSearchCanceledEvent,
+            'webset.search.completed': WebsetSearchCompletedEvent,
+            'import.created': ImportCreatedEvent,
+            'import.completed': ImportCompletedEvent,
+            'monitor.created': MonitorCreatedEvent,
+            'monitor.updated': MonitorUpdatedEvent,
+            'monitor.deleted': MonitorDeletedEvent,
+            'monitor.run.created': MonitorRunCreatedEvent,
+            'monitor.run.completed': MonitorRunCompletedEvent,
         }
         
         event_class = event_type_map.get(event_type)

exa_py/websets/imports/__init__.py

@@ -1,3 +1,3 @@
-from .client import ImportsClient
- 
-__all__ = ["ImportsClient"] 
+from .client import ImportsClient, AsyncImportsClient
+
+__all__ = ["ImportsClient", "AsyncImportsClient"] 

exa_py/websets/imports/client.py

@@ -4,7 +4,9 @@ import time
 import os
 import csv
 import io
+import asyncio
 import requests
+import httpx
 from typing import Dict, Any, Union, Optional
 from pathlib import Path
 
@@ -16,6 +18,7 @@ from ..types import (
     UpdateImport,
 )
 from ..core.base import WebsetsBaseClient
+from ..core.async_base import WebsetsAsyncBaseClient
 
 class ImportsClient(WebsetsBaseClient):
     """Client for managing Imports."""
@@ -176,4 +179,169 @@ class ImportsClient(WebsetsBaseClient):
             if time.time() - start_time > timeout:
                 raise TimeoutError(f"Import {import_id} did not complete within {timeout} seconds")
                 
-            time.sleep(poll_interval) 
+            time.sleep(poll_interval)
+
+
+class AsyncImportsClient(WebsetsAsyncBaseClient):
+    """Async client for managing Imports."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+
+    async def create(
+        self, 
+        params: Union[Dict[str, Any], CreateImportParameters], 
+        *,
+        csv_data: Optional[Union[str, Path]] = None
+    ) -> Union[CreateImportResponse, Import]:
+        """Create a new import to upload your data into Websets.
+        
+        Imports can be used to:
+        - Enrich: Enhance your data with additional information using our AI-powered enrichment engine
+        - Search: Query your data using Websets' agentic search with natural language filters
+        - Exclude: Prevent duplicate or already known results from appearing in your searches
+
+        Args:
+            params (CreateImportParameters): The parameters for creating an import.
+            csv_data (Union[str, Path], optional): CSV data to upload. Can be raw CSV string or file path.
+                                                   When provided, size and count will be automatically calculated 
+                                                   if not specified in params.
+        
+        Returns:
+            CreateImportResponse: If csv_data is None (traditional usage with upload URL).
+            Import: If csv_data is provided (uploaded and processing).
+        """
+        if csv_data is not None:
+            if isinstance(csv_data, (str, Path)) and os.path.isfile(csv_data):
+                # Use synchronous file reading for simplicity (file reading is typically fast)
+                with open(csv_data, 'r', encoding='utf-8') as f:
+                    csv_content = f.read()
+            else:
+                csv_content = str(csv_data)
+            
+            if isinstance(params, dict):
+                current_size = params.get('size')
+                current_count = params.get('count')
+            else:
+                current_size = getattr(params, 'size', None)
+                current_count = getattr(params, 'count', None)
+            
+            if current_size is None or current_count is None:
+                calculated_size = len(csv_content.encode('utf-8'))
+                csv_reader = csv.reader(io.StringIO(csv_content))
+                rows = list(csv_reader)
+                calculated_count = max(0, len(rows) - 1)
+                
+                if isinstance(params, dict):
+                    params = params.copy()
+                    if current_size is None:
+                        params['size'] = calculated_size
+                    if current_count is None:
+                        params['count'] = calculated_count
+                else:
+                    params_dict = params.model_dump()
+                    if current_size is None:
+                        params_dict['size'] = calculated_size
+                    if current_count is None:
+                        params_dict['count'] = calculated_count
+                    params = CreateImportParameters.model_validate(params_dict)
+        
+        response = await self.request("/v0/imports", data=params)
+        import_response = CreateImportResponse.model_validate(response)
+        
+        if csv_data is None:
+            return import_response
+        
+        # Use httpx for async HTTP requests
+        async with httpx.AsyncClient() as http_client:
+            upload_response = await http_client.put(
+                import_response.upload_url,
+                data=csv_content,
+                headers={'Content-Type': 'text/csv'}
+            )
+            upload_response.raise_for_status()
+        
+        return await self.get(import_response.id)
+
+    async def get(self, import_id: str) -> Import:
+        """Get a specific import.
+        
+        Args:
+            import_id (str): The id of the Import.
+        
+        Returns:
+            Import: The retrieved import.
+        """
+        response = await self.request(f"/v0/imports/{import_id}", method="GET")
+        return Import.model_validate(response)
+
+    async def list(self, *, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListImportsResponse:
+        """List all imports.
+        
+        Args:
+            cursor (str, optional): The cursor to paginate through the results.
+            limit (int, optional): The number of results to return (1-200, default 25).
+        
+        Returns:
+            ListImportsResponse: List of imports with pagination info.
+        """
+        params = {
+            k: v 
+            for k, v in {
+                "cursor": cursor, 
+                "limit": limit
+            }.items() 
+            if v is not None
+        }
+        response = await self.request("/v0/imports", params=params, method="GET")
+        return ListImportsResponse.model_validate(response)
+
+    async def update(self, import_id: str, params: Union[Dict[str, Any], UpdateImport]) -> Import:
+        """Update an import configuration.
+        
+        Args:
+            import_id (str): The id of the Import.
+            params (UpdateImport): The parameters for updating an import.
+        
+        Returns:
+            Import: The updated import.
+        """
+        response = await self.request(f"/v0/imports/{import_id}", data=params, method="PATCH")
+        return Import.model_validate(response)
+
+    async def delete(self, import_id: str) -> Import:
+        """Delete an import.
+        
+        Args:
+            import_id (str): The id of the Import.
+        
+        Returns:
+            Import: The deleted import.
+        """
+        response = await self.request(f"/v0/imports/{import_id}", method="DELETE")
+        return Import.model_validate(response)
+
+    async def wait_until_completed(self, import_id: str, *, timeout: int = 1800, poll_interval: int = 5) -> Import:
+        """Wait until an import is completed or failed.
+        
+        Args:
+            import_id (str): The id of the Import.
+            timeout (int, optional): Maximum time to wait in seconds. Defaults to 1800 (30 minutes).
+            poll_interval (int, optional): Time to wait between polls in seconds. Defaults to 5.
+            
+        Returns:
+            Import: The import once it's completed or failed.
+            
+        Raises:
+            TimeoutError: If the import does not complete within the timeout period.
+        """
+        start_time = asyncio.get_event_loop().time()
+        while True:
+            import_obj = await self.get(import_id)
+            if import_obj.status in ['completed', 'failed']:
+                return import_obj
+                
+            if asyncio.get_event_loop().time() - start_time > timeout:
+                raise TimeoutError(f"Import {import_id} did not complete within {timeout} seconds")
+                
+            await asyncio.sleep(poll_interval) 

exa_py/websets/items/__init__.py

@@ -1,3 +1,3 @@
-from .client import WebsetItemsClient
+from .client import WebsetItemsClient, AsyncWebsetItemsClient
 
-__all__ = ["WebsetItemsClient"] 
+__all__ = ["WebsetItemsClient", "AsyncWebsetItemsClient"] 

exa_py/websets/items/client.py

@@ -1,12 +1,13 @@
 from __future__ import annotations
 
-from typing import  Optional, Iterator
+from typing import Optional, Iterator, AsyncIterator
 
 from ..types import (
     WebsetItem,
     ListWebsetItemResponse,
 )
 from ..core.base import WebsetsBaseClient
+from ..core.async_base import WebsetsAsyncBaseClient
 
 class WebsetItemsClient(WebsetsBaseClient):
     """Client for managing Webset Items."""
@@ -77,4 +78,76 @@ class WebsetItemsClient(WebsetsBaseClient):
             WebsetItem: The deleted item.
         """
         response = self.request(f"/v0/websets/{webset_id}/items/{id}", method="DELETE")
+        return WebsetItem.model_validate(response)
+
+
+class AsyncWebsetItemsClient(WebsetsAsyncBaseClient):
+    """Async client for managing Webset Items."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+
+    async def list(self, webset_id: str, *, cursor: Optional[str] = None, 
+             limit: Optional[int] = None, source_id: Optional[str] = None) -> ListWebsetItemResponse:
+        """List all Items for a Webset.
+        
+        Args:
+            webset_id (str): The id or externalId of the Webset.
+            cursor (str, optional): The cursor to paginate through the results.
+            limit (int, optional): The number of results to return (max 200).
+            source_id (str, optional): Filter items by source ID.
+        
+        Returns:
+            ListWebsetItemResponse: List of webset items.
+        """
+        params = {k: v for k, v in {"cursor": cursor, "limit": limit, "sourceId": source_id}.items() if v is not None}
+        response = await self.request(f"/v0/websets/{webset_id}/items", params=params, method="GET")
+        return ListWebsetItemResponse.model_validate(response)
+
+    async def list_all(self, webset_id: str, *, limit: Optional[int] = None, source_id: Optional[str] = None) -> AsyncIterator[WebsetItem]:
+        """Iterate through all Items in a Webset, handling pagination automatically.
+        
+        Args:
+            webset_id (str): The id or externalId of the Webset.
+            limit (int, optional): The number of results to return per page (max 200).
+            source_id (str, optional): Filter items by source ID.
+            
+        Yields:
+            WebsetItem: Each item in the webset.
+        """
+        cursor = None
+        while True:
+            response = await self.list(webset_id, cursor=cursor, limit=limit, source_id=source_id)
+            for item in response.data:
+                yield item
+            
+            if not response.has_more or not response.next_cursor:
+                break
+                
+            cursor = response.next_cursor
+
+    async def get(self, webset_id: str, id: str) -> WebsetItem:
+        """Get an Item by ID.
+        
+        Args:
+            webset_id (str): The id or externalId of the Webset.
+            id (str): The id of the Webset item.
+        
+        Returns:
+            WebsetItem: The retrieved item.
+        """
+        response = await self.request(f"/v0/websets/{webset_id}/items/{id}", method="GET")
+        return WebsetItem.model_validate(response)
+
+    async def delete(self, webset_id: str, id: str) -> WebsetItem:
+        """Delete an Item.
+        
+        Args:
+            webset_id (str): The id or externalId of the Webset.
+            id (str): The id of the Webset item.
+        
+        Returns:
+            WebsetItem: The deleted item.
+        """
+        response = await self.request(f"/v0/websets/{webset_id}/items/{id}", method="DELETE")
         return WebsetItem.model_validate(response) 

exa_py/websets/monitors/__init__.py

@@ -1,4 +1,4 @@
-from .client import MonitorsClient
-from .runs import MonitorRunsClient
+from .client import MonitorsClient, AsyncMonitorsClient
+from .runs import MonitorRunsClient, AsyncMonitorRunsClient
 
-__all__ = ["MonitorsClient", "MonitorRunsClient"] 
+__all__ = ["MonitorsClient", "AsyncMonitorsClient", "MonitorRunsClient", "AsyncMonitorRunsClient"] 

exa_py/websets/monitors/client.py

@@ -9,6 +9,7 @@ from ..types import (
     ListMonitorsResponse,
 )
 from ..core.base import WebsetsBaseClient
+from ..core.async_base import WebsetsAsyncBaseClient
 from .runs import MonitorRunsClient
 
 class MonitorsClient(WebsetsBaseClient):
@@ -93,4 +94,39 @@ class MonitorsClient(WebsetsBaseClient):
             Monitor: The deleted monitor.
         """
         response = self.request(f"/v0/monitors/{monitor_id}", method="DELETE")
+        return Monitor.model_validate(response)
+
+
+class AsyncMonitorsClient(WebsetsAsyncBaseClient):
+    """Async client for managing Monitors."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+        from .runs import AsyncMonitorRunsClient
+        self.runs = AsyncMonitorRunsClient(client)
+
+    async def create(self, params: Union[Dict[str, Any], CreateMonitorParameters]) -> Monitor:
+        """Create a new Monitor to continuously keep your Websets updated with fresh data."""
+        response = await self.request("/v0/monitors", data=params)
+        return Monitor.model_validate(response)
+
+    async def get(self, monitor_id: str) -> Monitor:
+        """Get a specific monitor."""
+        response = await self.request(f"/v0/monitors/{monitor_id}", method="GET")
+        return Monitor.model_validate(response)
+
+    async def list(self, *, cursor: Optional[str] = None, limit: Optional[int] = None, webset_id: Optional[str] = None) -> ListMonitorsResponse:
+        """List all monitors."""
+        params = {k: v for k, v in {"cursor": cursor, "limit": limit, "websetId": webset_id}.items() if v is not None}
+        response = await self.request("/v0/monitors", params=params, method="GET")
+        return ListMonitorsResponse.model_validate(response)
+
+    async def update(self, monitor_id: str, params: Union[Dict[str, Any], UpdateMonitor]) -> Monitor:
+        """Update a monitor configuration."""
+        response = await self.request(f"/v0/monitors/{monitor_id}", data=params, method="PATCH")
+        return Monitor.model_validate(response)
+
+    async def delete(self, monitor_id: str) -> Monitor:
+        """Delete a monitor."""
+        response = await self.request(f"/v0/monitors/{monitor_id}", method="DELETE")
         return Monitor.model_validate(response) 

exa_py/websets/monitors/runs/__init__.py

@@ -1,3 +1,3 @@
-from .client import MonitorRunsClient
+from .client import MonitorRunsClient, AsyncMonitorRunsClient
 
-__all__ = ["MonitorRunsClient"] 
+__all__ = ["MonitorRunsClient", "AsyncMonitorRunsClient"] 

exa_py/websets/monitors/runs/client.py

@@ -5,6 +5,7 @@ from ...types import (
     ListMonitorRunsResponse,
 )
 from ...core.base import WebsetsBaseClient
+from ...core.async_base import WebsetsAsyncBaseClient
 
 class MonitorRunsClient(WebsetsBaseClient):
     """Client for managing Monitor Runs."""
@@ -35,4 +36,21 @@ class MonitorRunsClient(WebsetsBaseClient):
             MonitorRun: The monitor run details.
         """
         response = self.request(f"/v0/monitors/{monitor_id}/runs/{run_id}", method="GET")
+        return MonitorRun.model_validate(response)
+
+
+class AsyncMonitorRunsClient(WebsetsAsyncBaseClient):
+    """Async client for managing Monitor Runs."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+
+    async def list(self, monitor_id: str) -> ListMonitorRunsResponse:
+        """List all runs for the Monitor."""
+        response = await self.request(f"/v0/monitors/{monitor_id}/runs", method="GET")
+        return ListMonitorRunsResponse.model_validate(response)
+
+    async def get(self, monitor_id: str, run_id: str) -> MonitorRun:
+        """Get a specific monitor run."""
+        response = await self.request(f"/v0/monitors/{monitor_id}/runs/{run_id}", method="GET")
         return MonitorRun.model_validate(response) 

exa_py/websets/searches/__init__.py

@@ -1,3 +1,3 @@
-from .client import WebsetSearchesClient
+from .client import WebsetSearchesClient, AsyncWebsetSearchesClient
 
-__all__ = ["WebsetSearchesClient"] 
+__all__ = ["WebsetSearchesClient", "AsyncWebsetSearchesClient"] 

exa_py/websets/searches/client.py

@@ -7,6 +7,7 @@ from ..types import (
     WebsetSearch,
 )
 from ..core.base import WebsetsBaseClient
+from ..core.async_base import WebsetsAsyncBaseClient
 
 class WebsetSearchesClient(WebsetsBaseClient):
     """Client for managing Webset Searches."""
@@ -51,4 +52,50 @@ class WebsetSearchesClient(WebsetsBaseClient):
             WebsetSearch: The canceled search.
         """
         response = self.request(f"/v0/websets/{webset_id}/searches/{id}/cancel", method="POST")
+        return WebsetSearch.model_validate(response)
+
+
+class AsyncWebsetSearchesClient(WebsetsAsyncBaseClient):
+    """Async client for managing Webset Searches."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+
+    async def create(self, webset_id: str, params: Union[Dict[str, Any], CreateWebsetSearchParameters]) -> 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.
+        
+        Returns:
+            WebsetSearch: The created search.
+        """
+        response = await self.request(f"/v0/websets/{webset_id}/searches", data=params)
+        return WebsetSearch.model_validate(response)
+
+    async def get(self, webset_id: str, id: str) -> WebsetSearch:
+        """Get a Search by ID.
+        
+        Args:
+            webset_id (str): The id of the Webset.
+            id (str): The id of the Search.
+        
+        Returns:
+            WebsetSearch: The retrieved search.
+        """
+        response = await self.request(f"/v0/websets/{webset_id}/searches/{id}", method="GET")
+        return WebsetSearch.model_validate(response)
+
+    async def cancel(self, webset_id: str, id: str) -> WebsetSearch:
+        """Cancel a running Search.
+        
+        Args:
+            webset_id (str): The id of the Webset.
+            id (str): The id of the Search.
+        
+        Returns:
+            WebsetSearch: The canceled search.
+        """
+        response = await self.request(f"/v0/websets/{webset_id}/searches/{id}/cancel", method="POST")
         return WebsetSearch.model_validate(response)