exa-py 1.14.6__tar.gz → 1.14.7__tar.gz

{exa_py-1.14.6 → exa_py-1.14.7}/PKG-INFO

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

{exa_py-1.14.6 → exa_py-1.14.7}/exa_py/websets/__init__.py

@@ -1,5 +1,7 @@
 from .client import WebsetsClient
+from .imports import ImportsClient
 
 __all__ = [
     "WebsetsClient",
+    "ImportsClient",
 ] 

{exa_py-1.14.6 → exa_py-1.14.7}/exa_py/websets/client.py

@@ -17,6 +17,7 @@ from .searches import WebsetSearchesClient
 from .enrichments import WebsetEnrichmentsClient
 from .webhooks import WebsetWebhooksClient
 from .monitors import MonitorsClient
+from .imports import ImportsClient
 
 class WebsetsClient(WebsetsBaseClient):
     """Client for managing Websets."""
@@ -28,6 +29,7 @@ class WebsetsClient(WebsetsBaseClient):
         self.enrichments = WebsetEnrichmentsClient(client)
         self.webhooks = WebsetWebhooksClient(client)
         self.monitors = MonitorsClient(client)
+        self.imports = ImportsClient(client)
 
     def create(self, params: Union[Dict[str, Any], CreateWebsetParameters]) -> Webset:
         """Create a new Webset.

exa_py-1.14.7/exa_py/websets/imports/__init__.py

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

exa_py-1.14.7/exa_py/websets/imports/client.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import time
+import os
+import csv
+import io
+import requests
+from typing import Dict, Any, Union, Optional
+from pathlib import Path
+
+from ..types import (
+    CreateImportParameters,
+    CreateImportResponse,
+    Import,
+    ListImportsResponse,
+    UpdateImport,
+)
+from ..core.base import WebsetsBaseClient
+
+class ImportsClient(WebsetsBaseClient):
+    """Client for managing Imports."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+
+    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):
+                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 = self.request("/v0/imports", data=params)
+        import_response = CreateImportResponse.model_validate(response)
+        
+        if csv_data is None:
+            return import_response
+        
+        upload_response = requests.put(
+            import_response.upload_url,
+            data=csv_content,
+            headers={'Content-Type': 'text/csv'}
+        )
+        upload_response.raise_for_status()
+        
+        return self.get(import_response.id)
+
+    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 = self.request(f"/v0/imports/{import_id}", method="GET")
+        return Import.model_validate(response)
+
+    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 = self.request("/v0/imports", params=params, method="GET")
+        return ListImportsResponse.model_validate(response)
+
+    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 = self.request(f"/v0/imports/{import_id}", data=params, method="PATCH")
+        return Import.model_validate(response)
+
+    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 = self.request(f"/v0/imports/{import_id}", method="DELETE")
+        return Import.model_validate(response)
+
+    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 = time.time()
+        while True:
+            import_obj = self.get(import_id)
+            if import_obj.status in ['completed', 'failed']:
+                return import_obj
+                
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Import {import_id} did not complete within {timeout} seconds")
+                
+            time.sleep(poll_interval) 

{exa_py-1.14.6 → exa_py-1.14.7}/exa_py/websets/types.py

@@ -93,10 +93,14 @@ class CreateWebhookParameters(ExaBaseModel):
 
 
 class CreateWebsetParameters(ExaBaseModel):
-    search: CreateWebsetParametersSearch
+    search: Optional[CreateWebsetParametersSearch] = None
     """
     Create initial search for the Webset.
     """
+    imports: Optional[List[ImportItem]] = Field(None, alias='import')
+    """
+    Import data from existing Websets and Imports into this Webset.
+    """
     enrichments: Optional[List[CreateEnrichmentParameters]] = None
     """
     Add Enrichments for the Webset.
@@ -153,6 +157,10 @@ class CreateWebsetSearchParameters(ExaBaseModel):
 
     It's not required to provide your own criteria, we automatically detect the criteria from all the information provided in the query.
     """
+    exclude: Optional[List[ExcludeItem]] = None
+    """
+    Sources (existing imports or websets) to exclude from search results. Any results found within these sources will be omitted to prevent finding them during search.
+    """
     behavior: Optional[WebsetSearchBehavior] = 'override'
     """
     The behavior of the Search when it is added to a Webset.
@@ -219,6 +227,9 @@ class EventType(Enum):
     webset_search_canceled = 'webset.search.canceled'
     webset_search_completed = 'webset.search.completed'
     webset_search_updated = 'webset.search.updated'
+    import_created = 'import.created'
+    import_completed = 'import.completed'
+    import_processing = 'import.processing'
     webset_export_created = 'webset.export.created'
     webset_export_completed = 'webset.export.completed'
     webset_item_created = 'webset.item.created'
@@ -240,6 +251,41 @@ class Format(Enum):
     phone = 'phone'
 
 
+class ImportFormat(Enum):
+    """
+    The format of the import.
+    """
+    csv = 'csv'
+    webset = 'webset'
+
+
+class ImportStatus(Enum):
+    """
+    The status of the import.
+    """
+    pending = 'pending'
+    processing = 'processing'
+    completed = 'completed'
+    failed = 'failed'
+
+
+class ImportFailedReason(Enum):
+    """
+    The reason the import failed.
+    """
+    invalid_format = 'invalid_format'
+    invalid_file_content = 'invalid_file_content'
+    missing_identifier = 'missing_identifier'
+
+
+class ImportSource(Enum):
+    """
+    The source type for imports and excludes.
+    """
+    import_ = 'import'
+    webset = 'webset'
+
+
 class ListEventsResponse(ExaBaseModel):
     data: List[
         Union[
@@ -358,6 +404,254 @@ class ListWebsetsResponse(ExaBaseModel):
     """
 
 
+class ImportItem(ExaBaseModel):
+    """
+    Represents a source to import from.
+    """
+    source: ImportSource
+    """
+    The type of source (import or webset)
+    """
+    id: constr(min_length=1)
+    """
+    The ID of the source to import from
+    """
+
+
+class ExcludeItem(ExaBaseModel):
+    """
+    Represents a source to exclude from search results.
+    """
+    source: ImportSource
+    """
+    The type of source (import or webset)
+    """
+    id: constr(min_length=1)
+    """
+    The ID of the source to exclude
+    """
+
+
+class CsvImportConfig(ExaBaseModel):
+    """
+    Configuration for CSV imports.
+    """
+    identifier: Optional[PositiveInt] = None
+    """
+    Column index containing the key identifier for the entity (e.g., URL). If not provided, will be inferred.
+    """
+
+
+class CreateImportParameters(ExaBaseModel):
+    """
+    Parameters for creating an import.
+    """
+    size: Optional[confloat(le=50000000.0)] = None
+    """
+    The size of the file in bytes. Maximum size is 50 MB.
+    Auto-calculated when csv_data is provided and size is not specified.
+    """
+    count: Optional[float] = None
+    """
+    The number of records to import
+    Auto-calculated when csv_data is provided and count is not specified.
+    """
+    title: Optional[str] = None
+    """
+    The title of the import
+    """
+    format: ImportFormat
+    """
+    The format of the import data
+    """
+    entity: Union[
+        WebsetCompanyEntity,
+        WebsetPersonEntity,
+        WebsetArticleEntity,
+        WebsetResearchPaperEntity,
+        WebsetCustomEntity,
+    ]
+    """
+    The type of entity the import contains
+    """
+    csv: Optional[CsvImportConfig] = None
+    """
+    CSV-specific configuration when format is 'csv'
+    """
+    metadata: Optional[Dict[str, Any]] = None
+    """
+    Set of key-value pairs you want to associate with this object.
+    """
+
+
+class CreateImportResponse(ExaBaseModel):
+    """
+    Response from creating an import.
+    """
+    id: str
+    """
+    The unique identifier for the Import
+    """
+    object: Literal['import']
+    """
+    The type of object
+    """
+    status: ImportStatus
+    """
+    The status of the Import
+    """
+    format: ImportFormat
+    """
+    The format of the import
+    """
+    entity: Optional[Union[
+        WebsetCompanyEntity,
+        WebsetPersonEntity,
+        WebsetArticleEntity,
+        WebsetResearchPaperEntity,
+        WebsetCustomEntity,
+    ]] = None
+    """
+    The type of entity the import contains
+    """
+    title: str
+    """
+    The title of the import
+    """
+    count: float
+    """
+    The number of entities in the import
+    """
+    metadata: Dict[str, Any]
+    """
+    Set of key-value pairs associated with this object
+    """
+    failed_reason: Optional[ImportFailedReason] = Field(None, alias='failedReason')
+    """
+    The reason the import failed, if applicable
+    """
+    failed_at: Optional[datetime] = Field(None, alias='failedAt')
+    """
+    When the import failed, if applicable
+    """
+    failed_message: Optional[str] = Field(None, alias='failedMessage')
+    """
+    A human readable message describing the import failure
+    """
+    created_at: datetime = Field(..., alias='createdAt')
+    """
+    When the import was created
+    """
+    updated_at: datetime = Field(..., alias='updatedAt')
+    """
+    When the import was last updated
+    """
+    upload_url: str = Field(..., alias='uploadUrl')
+    """
+    The URL to upload the file to
+    """
+    upload_valid_until: str = Field(..., alias='uploadValidUntil')
+    """
+    The date and time until the upload URL is valid
+    """
+
+
+class Import(ExaBaseModel):
+    """
+    Represents an import.
+    """
+    id: str
+    """
+    The unique identifier for the Import
+    """
+    object: Literal['import']
+    """
+    The type of object
+    """
+    status: ImportStatus
+    """
+    The status of the Import
+    """
+    format: ImportFormat
+    """
+    The format of the import
+    """
+    entity: Optional[Union[
+        WebsetCompanyEntity,
+        WebsetPersonEntity,
+        WebsetArticleEntity,
+        WebsetResearchPaperEntity,
+        WebsetCustomEntity,
+    ]] = None
+    """
+    The type of entity the import contains
+    """
+    title: str
+    """
+    The title of the import
+    """
+    count: float
+    """
+    The number of entities in the import
+    """
+    metadata: Dict[str, Any]
+    """
+    Set of key-value pairs associated with this object
+    """
+    failed_reason: Optional[ImportFailedReason] = Field(None, alias='failedReason')
+    """
+    The reason the import failed, if applicable
+    """
+    failed_at: Optional[datetime] = Field(None, alias='failedAt')
+    """
+    When the import failed, if applicable
+    """
+    failed_message: Optional[str] = Field(None, alias='failedMessage')
+    """
+    A human readable message describing the import failure
+    """
+    created_at: datetime = Field(..., alias='createdAt')
+    """
+    When the import was created
+    """
+    updated_at: datetime = Field(..., alias='updatedAt')
+    """
+    When the import was last updated
+    """
+
+
+class ListImportsResponse(ExaBaseModel):
+    """
+    Response from listing imports.
+    """
+    data: List[Import]
+    """
+    The list of imports
+    """
+    has_more: bool = Field(..., alias='hasMore')
+    """
+    Whether there are more results to paginate through
+    """
+    next_cursor: Optional[str] = Field(None, alias='nextCursor')
+    """
+    The cursor to use for the next page of results
+    """
+
+
+class UpdateImport(ExaBaseModel):
+    """
+    Parameters for updating an import.
+    """
+    metadata: Optional[Dict[str, Any]] = None
+    """
+    Set of key-value pairs you want to associate with this object.
+    """
+    title: Optional[str] = None
+    """
+    The title of the import
+    """
+
+
 class Option(ExaBaseModel):
     label: str
     """
@@ -451,6 +745,10 @@ class CreateWebsetParametersSearch(ExaBaseModel):
 
     It's not required to provide your own criteria, we automatically detect the criteria from all the information provided in the query.
     """
+    exclude: Optional[List[ExcludeItem]] = None
+    """
+    Sources (existing imports or websets) to exclude from search results. Any results found within these sources will be omitted to prevent finding them during search.
+    """
 
 
 class Source(Enum):

{exa_py-1.14.6 → exa_py-1.14.7}/pyproject.toml

@@ -25,7 +25,7 @@ in-project = true
 
 [project]
 name = "exa-py"
-version = "1.14.6"
+version = "1.14.7"
 description = "Python SDK for Exa API."
 readme = "README.md"
 requires-python = ">=3.9"