exa-py 1.14.16__py3-none-any.whl → 1.14.18__py3-none-any.whl

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/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.dist-info → exa_py-1.14.18.dist-info}/METADATA

@@ -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.dist-info → exa_py-1.14.18.dist-info}/RECORD

@@ -7,7 +7,7 @@ exa_py/research/models.py,sha256=j7YgRoMRp2MLgnaij7775x_hJEeV5gksKpfLwmawqxY,370
 exa_py/utils.py,sha256=eYnJRAFJonwKP_mCxzAB9TnLEqoF-88stg6wh-M-Ups,6424
 exa_py/websets/__init__.py,sha256=x7Dc0MS8raRXA7Ud6alKgnsUmLi6X9GTqfB8kOwC9iQ,179
 exa_py/websets/_generator/pydantic/BaseModel.jinja2,sha256=RUDCmPZVamoVx1WudylscYFfDhGoNNtRYlpTvKjAiuA,1276
-exa_py/websets/client.py,sha256=v8Y0p5PosjLkb7EYQ83g3nmoIIHmKaXF7JQVT8K5h2E,4967
+exa_py/websets/client.py,sha256=sKkji8QaPFnGM1-J5TB6yKJcGAEd6gk7lsnIebzXNQ8,5856
 exa_py/websets/core/__init__.py,sha256=xOyrFaqtBocMUu321Jpbk7IzIQRNZufSIGJXrKoG-Bg,323
 exa_py/websets/core/base.py,sha256=RldWYwBg2iVfkWmdPke7xjXdwb4JKeABIOgiZtqvz-4,4125
 exa_py/websets/enrichments/__init__.py,sha256=5dJIEKKceUost3RnI6PpCSB3VjUCBzxseEsIXu-ZY-Y,83
@@ -24,9 +24,9 @@ exa_py/websets/monitors/runs/__init__.py,sha256=TmcETf3zdQouA_vAeLiosCNL1MYJnZ0y
 exa_py/websets/monitors/runs/client.py,sha256=WnwcWCf7UKk68VCNUp8mRXBtlU8vglTSX-eoWVXzKIw,1229
 exa_py/websets/searches/__init__.py,sha256=_0Zx8ES5fFTEL3T8mhLxq_xK2t0JONx6ad6AtbvClsE,77
 exa_py/websets/searches/client.py,sha256=X3f7axWGfecmxf-2tBTX0Yf_--xToz1X8ZHbbudEzy0,1790
-exa_py/websets/types.py,sha256=W0ZV_ETW-sDXNh9fK9qROmPRHU_koy1rfTGhjCG3yrA,42231
+exa_py/websets/types.py,sha256=DxO_T4Ijnd06gxFAX3f238Mt5P0_ulpY44M1kiT4y4U,47120
 exa_py/websets/webhooks/__init__.py,sha256=iTPBCxFd73z4RifLQMX6iRECx_6pwlI5qscLNjMOUHE,77
 exa_py/websets/webhooks/client.py,sha256=zS1eoWKliuiY4AIeFJdpAlPZeOINyphn7KEWANF-zaE,4384
-exa_py-1.14.16.dist-info/METADATA,sha256=2prGXydJQVPWgajO8aSiUTVbjvikEteVHHItSJsf19I,3827
-exa_py-1.14.16.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-exa_py-1.14.16.dist-info/RECORD,,
+exa_py-1.14.18.dist-info/METADATA,sha256=CCJmZE-pPrWCzNvK9JJ709FwCVtHIlltGfzXdxYhsLI,3827
+exa_py-1.14.18.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+exa_py-1.14.18.dist-info/RECORD,,