exa-py 1.14.16__tar.gz → 1.14.18__tar.gz

{exa_py-1.14.16 → exa_py-1.14.18}/PKG-INFO

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

{exa_py-1.14.16 → exa_py-1.14.18}/exa_py/websets/client.py

@@ -10,6 +10,8 @@ from .types import (
     UpdateWebsetRequest,
     WebsetStatus,
     CreateWebsetParameters,
+    PreviewWebsetParameters,
+    PreviewWebsetResponse,
 )
 from .core.base import WebsetsBaseClient
 from .items import WebsetItemsClient
@@ -45,6 +47,23 @@ class WebsetsClient(WebsetsBaseClient):
         response = self.request("/v0/websets", data=params)
         return Webset.model_validate(response)
 
+    def preview(self, params: Union[Dict[str, Any], PreviewWebsetParameters]) -> PreviewWebsetResponse:
+        """Preview a webset query.
+        
+        Preview how a search query will be decomposed before creating a webset. 
+        This endpoint performs the same query analysis that happens during webset creation, 
+        allowing you to see the detected entity type, generated search criteria, and 
+        available enrichment columns in advance.
+        
+        Args:
+            params (PreviewWebsetParameters): The parameters for previewing a webset.
+        
+        Returns:
+            PreviewWebsetResponse: The preview response showing how the query will be decomposed.
+        """
+        response = self.request("/v0/websets/preview", data=params)
+        return PreviewWebsetResponse.model_validate(response)
+
     def get(self, id: str, *, expand: Optional[List[Literal["items"]]] = None) -> GetWebsetResponse:
         """Get a Webset by ID.
         

{exa_py-1.14.16 → exa_py-1.14.18}/exa_py/websets/types.py

@@ -171,6 +171,10 @@ class CreateWebsetSearchParameters(ExaBaseModel):
     """
     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.
     """
+    scope: Optional[List[ScopeItem]] = None
+    """
+    Limit the search to specific sources (existing imports or websets). Any results found within these sources matching the search criteria will be included in the Webset.
+    """
     behavior: Optional[WebsetSearchBehavior] = WebsetSearchBehavior.override
     """
     The behavior of the Search when it is added to a Webset.
@@ -296,6 +300,26 @@ class ImportSource(Enum):
     webset = 'webset'
 
 
+class ScopeSourceType(Enum):
+    """
+    The source type for scope filtering.
+    """
+    import_ = 'import'
+    webset = 'webset'
+
+
+class PreviewWebsetResponseEnrichmentsFormat(Enum):
+    """
+    Format of the enrichment in preview response.
+    """
+    text = 'text'
+    date = 'date'
+    number = 'number'
+    options = 'options'
+    email = 'email'
+    phone = 'phone'
+
+
 class ListEventsResponse(ExaBaseModel):
     data: List[Annotated[
       Union[
@@ -443,6 +467,121 @@ class ExcludeItem(ExaBaseModel):
     """
 
 
+class ScopeRelationship(ExaBaseModel):
+    """
+    Represents the relationship between entities for scoped searches.
+    """
+    definition: str
+    """
+    What the relationship of the entities you hope to find is relative to the entities contained in the provided source
+    """
+    limit: Optional[PositiveInt] = None
+    """
+    Optional limit on the number of related entities to find
+    """
+
+
+class ScopeItem(ExaBaseModel):
+    """
+    Represents a source to limit search scope to.
+    """
+    source: ScopeSourceType
+    """
+    The type of source (import)
+    """
+    id: str
+    """
+    The ID of the source to search within
+    """
+    relationship: Optional[ScopeRelationship] = None
+    """
+    Optional relationship definition for hop searches
+    """
+
+
+class PreviewWebsetParameters(ExaBaseModel):
+    """
+    Parameters for previewing a webset query.
+    """
+    query: str
+    """
+    Natural language search query describing what you are looking for.
+    """
+    entity: Optional[Union[
+        WebsetCompanyEntity,
+        WebsetPersonEntity,
+        WebsetArticleEntity,
+        WebsetResearchPaperEntity,
+        WebsetCustomEntity,
+    ]] = None
+    """
+    Entity used to inform the decomposition. Not required - we automatically detect 
+    the entity from the query. Only use when you need more fine control.
+    """
+
+
+class PreviewWebsetResponseEnrichment(ExaBaseModel):
+    """
+    Detected enrichment in preview response.
+    """
+    description: str
+    """
+    Description of the enrichment.
+    """
+    format: PreviewWebsetResponseEnrichmentsFormat
+    """
+    Format of the enrichment.
+    """
+    options: Optional[List[Option]] = None
+    """
+    When format is options, the options detected from the query.
+    """
+
+
+class PreviewWebsetResponseSearchCriterion(ExaBaseModel):
+    """
+    Detected search criterion in preview response.
+    """
+    description: str
+    """
+    Description of the criterion.
+    """
+
+
+class PreviewWebsetResponseSearch(ExaBaseModel):
+    """
+    Search information in preview response.
+    """
+    entity: Union[
+        WebsetCompanyEntity,
+        WebsetPersonEntity,
+        WebsetArticleEntity,
+        WebsetResearchPaperEntity,
+        WebsetCustomEntity,
+    ]
+    """
+    Detected entity from the query.
+    """
+    criteria: List[PreviewWebsetResponseSearchCriterion]
+    """
+    Detected criteria from the query.
+    """
+
+
+class PreviewWebsetResponse(ExaBaseModel):
+    """
+    Response from previewing a webset query.
+    """
+    search: PreviewWebsetResponseSearch
+    """
+    Search analysis from the query.
+    """
+    enrichments: List[PreviewWebsetResponseEnrichment]
+    """
+    Detected enrichments from the query.
+    """
+
+
 class CsvImportConfig(ExaBaseModel):
     """
     Configuration for CSV imports.
@@ -758,6 +897,10 @@ class CreateWebsetParametersSearch(ExaBaseModel):
     """
     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.
     """
+    scope: Optional[List[ScopeItem]] = None
+    """
+    Limit the search to specific sources (existing imports or websets). Any results found within these sources matching the search criteria will be included in the Webset.
+    """
 
 
 class Source(Enum):
@@ -1538,12 +1681,53 @@ class WebsetResearchPaperEntity(ExaBaseModel):
     type: Literal['research_paper']
 
 
+class WebsetSearchRecallConfidence(Enum):
+    """
+    Confidence level for search recall estimates.
+    """
+    high = 'high'
+    medium = 'medium'
+    low = 'low'
+
+
+class WebsetSearchRecallExpected(ExaBaseModel):
+    """
+    Expected search recall information.
+    """
+    total: int
+    """
+    Total expected matches
+    """
+    confidence: WebsetSearchRecallConfidence
+    """
+    Confidence level of the estimate
+    """
+
+
+class WebsetSearchRecall(ExaBaseModel):
+    """
+    Search recall estimate information.
+    """
+    expected: WebsetSearchRecallExpected
+    """
+    Expected recall information
+    """
+    reasoning: str
+    """
+    Reasoning for the recall estimate
+    """
+
+
 class WebsetSearch(ExaBaseModel):
     id: str
     """
     The unique identifier for the search
     """
     object: Literal['webset_search']
+    webset_id: Annotated[str, Field(alias='websetId')]
+    """
+    The unique identifier for the Webset this search belongs to
+    """
     status: WebsetSearchStatus = Field(..., title='WebsetSearchStatus')
     """
     The status of the search
@@ -1579,10 +1763,22 @@ class WebsetSearch(ExaBaseModel):
     - `override`: the search will replace 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.
     - `append`: the search will add the new Items found to the existing Webset. Any Items that don't match the new criteria will be discarded.
     """
+    exclude: Optional[List[ExcludeItem]] = None
+    """
+    Sources (existing imports or websets) used to omit certain results to be found during the search.
+    """
+    scope: Optional[List[ScopeItem]] = None
+    """
+    The scope of the search. By default, there is no scope - thus searching the web. If provided during creation, the search will only be performed on the sources provided.
+    """
     progress: Progress
     """
     The progress of the search
     """
+    recall: Optional[WebsetSearchRecall] = None
+    """
+    Estimate of total potential matches (if requested)
+    """
     metadata: Optional[Dict[str, Any]] = {}
     """
     Set of key-value pairs you want to associate with this object.

{exa_py-1.14.16 → exa_py-1.14.18}/pyproject.toml

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