exa-py 1.13.0__py3-none-any.whl → 1.13.2__py3-none-any.whl

exa_py/websets/types.py

@@ -1,20 +1,34 @@
+# generated by datamodel-codegen:
+#   filename:  schema.json
+#   timestamp: 2025-05-30T02:51:12+00:00
+
 from __future__ import annotations
 
 from datetime import datetime
 from enum import Enum
 from typing import Any, Dict, List, Literal, Optional, Union
 
-from pydantic import AnyUrl, Field, confloat, constr
+from pydantic import AnyUrl, Field, PositiveInt, confloat, constr
 from .core.base import ExaBaseModel
 
-
-class CanceledReason(Enum):
+class StreamBehaviorSearchConfig(ExaBaseModel):
+    query: constr(min_length=2, max_length=10000)
+    criteria: List[SearchCriterion] = Field(..., max_items=5)
+    entity: Union[
+        WebsetCompanyEntity,
+        WebsetPersonEntity,
+        WebsetArticleEntity,
+        WebsetResearchPaperEntity,
+        WebsetCustomEntity,
+    ] = Field(..., title='WebsetEntity')
+    count: PositiveInt
     """
-    The reason the search was canceled
+    The maximum number of results to find
+    """
+    behavior: Optional[WebsetSearchBehavior] = 'append'
+    """
+    The behaviour of the Search when it is added to a Webset.
     """
-
-    webset_deleted = 'webset_deleted'
-    webset_canceled = 'webset_canceled'
 
 
 class CreateCriterionParameters(ExaBaseModel):
@@ -45,6 +59,24 @@ class CreateEnrichmentParameters(ExaBaseModel):
     """
 
 
+class CreateStreamParameters(ExaBaseModel):
+    webset_id: str = Field(..., alias='websetId')
+    """
+    The id of the Webset
+    """
+    cadence: StreamCadence
+    """
+    How often the stream will run
+    """
+    behavior: Union[StreamBehaviorSearch, StreamBehaviorRefresh] = Field(
+        ..., discriminator='type'
+    )
+    """
+    Behavior to perform when stream runs
+    """
+    metadata: Optional[Dict[str, Any]] = None
+
+
 class CreateWebhookParameters(ExaBaseModel):
     events: List[EventType] = Field(..., max_items=12, min_items=1)
     """
@@ -61,11 +93,11 @@ class CreateWebhookParameters(ExaBaseModel):
 
 
 class CreateWebsetParameters(ExaBaseModel):
-    search: Search
+    search: CreateWebsetParametersSearch
     """
     Create initial search for the Webset.
     """
-    enrichments: Optional[List[CreateEnrichmentParameters]] = Field(None, max_items=10)
+    enrichments: Optional[List[CreateEnrichmentParameters]] = None
     """
     Add Enrichments for the Webset.
     """
@@ -82,7 +114,7 @@ class CreateWebsetParameters(ExaBaseModel):
 
 
 class CreateWebsetSearchParameters(ExaBaseModel):
-    count: confloat(ge=1.0)
+    count: PositiveInt
     """
     Number of Items the Search will attempt to find.
 
@@ -121,13 +153,12 @@ 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.
     """
-    behaviour: Optional[WebsetSearchBehaviour] = Field(
-        'override', title='WebsetSearchBehaviour'
-    )
+    behavior: Optional[WebsetSearchBehavior] = 'override'
     """
-    The behaviour of the Search when it is added to a Webset.
+    The behavior of the Search when it is added to a Webset.
 
-    - `override`: the search will reuse 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.
+    - `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.
     """
     metadata: Optional[Dict[str, Any]] = None
     """
@@ -135,7 +166,7 @@ class CreateWebsetSearchParameters(ExaBaseModel):
     """
 
 
-class Criterion(ExaBaseModel):
+class WebsetSearchCriterion(ExaBaseModel):
     description: constr(min_length=1)
     """
     The description of the criterion
@@ -146,6 +177,10 @@ class Criterion(ExaBaseModel):
     """
 
 
+class SearchCriterion(ExaBaseModel):
+    description: constr(min_length=2)
+
+
 class EnrichmentResult(ExaBaseModel):
     object: Literal['enrichment_result']
     format: WebsetEnrichmentFormat
@@ -167,6 +202,14 @@ class EnrichmentResult(ExaBaseModel):
     """
 
 
+class StreamRefreshBehaviorEnrichmentsConfigEnrichments(ExaBaseModel):
+    """
+    Only refresh specific enrichments
+    """
+
+    ids: Optional[List[str]] = None
+
+
 class EventType(Enum):
     webset_created = 'webset.created'
     webset_deleted = 'webset.deleted'
@@ -181,8 +224,6 @@ class EventType(Enum):
     webset_item_created = 'webset.item.created'
     webset_item_enriched = 'webset.item.enriched'
 
-
-
 class Format(Enum):
     """
     Format of the enrichment response.
@@ -220,7 +261,37 @@ class ListEventsResponse(ExaBaseModel):
     """
     Whether there are more results to paginate through
     """
-    next_cursor: Optional[str] = Field(..., alias='nextCursor')
+    next_cursor: Optional[str] = Field(None, alias='nextCursor')
+    """
+    The cursor to paginate through the next set of results
+    """
+
+
+class ListStreamRunsResponse(ExaBaseModel):
+    data: List[StreamRun]
+    """
+    The list of stream runs
+    """
+    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 paginate through the next set of results
+    """
+
+
+class ListStreamsResponse(ExaBaseModel):
+    data: List[Stream]
+    """
+    The list of streams
+    """
+    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 paginate through the next set of results
     """
@@ -235,7 +306,7 @@ class ListWebhookAttemptsResponse(ExaBaseModel):
     """
     Whether there are more results to paginate through
     """
-    next_cursor: Optional[str] = Field(..., alias='nextCursor')
+    next_cursor: Optional[str] = Field(None, alias='nextCursor')
     """
     The cursor to paginate through the next set of results
     """
@@ -250,7 +321,7 @@ class ListWebhooksResponse(ExaBaseModel):
     """
     Whether there are more results to paginate through
     """
-    next_cursor: Optional[str] = Field(..., alias='nextCursor')
+    next_cursor: Optional[str] = Field(None, alias='nextCursor')
     """
     The cursor to paginate through the next set of results
     """
@@ -265,7 +336,7 @@ class ListWebsetItemResponse(ExaBaseModel):
     """
     Whether there are more Items to paginate through
     """
-    next_cursor: Optional[str] = Field(..., alias='nextCursor')
+    next_cursor: Optional[str] = Field(None, alias='nextCursor')
     """
     The cursor to paginate through the next set of Items
     """
@@ -280,19 +351,17 @@ class ListWebsetsResponse(ExaBaseModel):
     """
     Whether there are more results to paginate through
     """
-    next_cursor: Optional[str] = Field(..., alias='nextCursor')
+    next_cursor: Optional[str] = Field(None, alias='nextCursor')
     """
     The cursor to paginate through the next set of results
     """
 
-
 class Option(ExaBaseModel):
     label: str
     """
     The label of the option
     """
 
-
 class Progress(ExaBaseModel):
     """
     The progress of the search
@@ -333,7 +402,7 @@ class Satisfied(Enum):
     unclear = 'unclear'
 
 
-class Search(ExaBaseModel):
+class CreateWebsetParametersSearch(ExaBaseModel):
     """
     Create initial search for the Webset.
     """
@@ -351,7 +420,7 @@ class Search(ExaBaseModel):
 
     Any URL provided will be crawled and used as context for the search.
     """
-    count: Optional[confloat(ge=1.0)] = 10
+    count: Optional[PositiveInt] = 10
     """
     Number of Items the Webset will attempt to find.
 
@@ -365,7 +434,7 @@ class Search(ExaBaseModel):
             WebsetResearchPaperEntity,
             WebsetCustomEntity,
         ]
-    ] = Field(None, discriminator='type')
+    ] = None
     """
     Entity the Webset will return results for.
 
@@ -387,6 +456,174 @@ class Source(Enum):
     """
 
     search = 'search'
+    import_ = 'import'
+
+
+class StreamRunStatus(Enum):
+    """
+    The status of the Stream Run
+    """
+
+    created = 'created'
+    running = 'running'
+    completed = 'completed'
+    canceled = 'canceled'
+
+
+class StreamStatus(Enum):
+    """
+    The status of the Stream
+    """
+
+    open = 'open'
+    closed = 'closed'
+
+
+class Stream(ExaBaseModel):
+    id: str
+    """
+    The unique identifier for the Stream
+    """
+    object: str = 'stream'
+    """
+    The type of object
+    """
+    status: StreamStatus
+    """
+    The status of the Stream
+    """
+    webset_id: str = Field(..., alias='websetId')
+    """
+    The id of the Webset the Stream belongs to
+    """
+    cadence: StreamCadence
+    """
+    How often the stream will run
+    """
+    behavior: Union[StreamBehaviorSearch, StreamBehaviorRefresh] = Field(
+        ..., discriminator='type'
+    )
+    """
+    Behavior to perform when stream runs
+    """
+    last_run: Optional[StreamRun] = Field(None, alias='lastRun', title='StreamRun')
+    """
+    The last run of the stream
+    """
+    next_run_at: Optional[datetime] = Field(None, alias='nextRunAt')
+    """
+    When the next run will occur
+    """
+    metadata: Dict[str, constr(max_length=1000)]
+    """
+    Set of key-value pairs you want to associate with this object.
+    """
+    created_at: datetime = Field(..., alias='createdAt')
+    """
+    When the stream was created
+    """
+    updated_at: datetime = Field(..., alias='updatedAt')
+    """
+    When the stream was last updated
+    """
+
+
+class StreamBehaviorRefresh(ExaBaseModel):
+    type: Literal['refresh']
+    config: Union[
+        StreamRefreshBehaviorEnrichmentsConfig, StreamRefreshBehaviorContentsConfig
+    ] = Field(..., discriminator='target')
+    """
+    Specify the target of the refresh
+    """
+
+
+class StreamBehaviorSearch(ExaBaseModel):
+    type: Literal['search']
+    config: StreamBehaviorSearchConfig
+
+
+class StreamCadence(ExaBaseModel):
+    cron: str
+    """
+    Cron expression for stream cadence (must be a valid Unix cron with 5 fields). The schedule must trigger at most once per day.
+    """
+    timezone: Optional[str] = 'Etc/UTC'
+    """
+    IANA timezone (e.g., "America/New_York")
+    """
+
+
+class StreamRefreshBehaviorContentsConfig(ExaBaseModel):
+    target: Literal['contents']
+
+
+class StreamRefreshBehaviorEnrichmentsConfig(ExaBaseModel):
+    target: Literal['enrichments']
+    enrichments: Optional[StreamRefreshBehaviorEnrichmentsConfigEnrichments] = None
+    """
+    Only refresh specific enrichments
+    """
+
+
+class StreamRun(ExaBaseModel):
+    id: str
+    """
+    The unique identifier for the Stream Run
+    """
+    object: str = 'stream_run'
+    """
+    The type of object
+    """
+    status: StreamRunStatus
+    """
+    The status of the Stream Run
+    """
+    stream_id: str = Field(..., alias='streamId')
+    """
+    The stream that the run is associated with
+    """
+    type: Type
+    """
+    The type of the Stream Run
+    """
+    completed_at: Optional[datetime] = Field(None, alias='completedAt')
+    """
+    When the run completed
+    """
+    failed_at: Optional[datetime] = Field(None, alias='failedAt')
+    """
+    When the run failed
+    """
+    canceled_at: Optional[datetime] = Field(None, alias='canceledAt')
+    """
+    When the run was canceled
+    """
+    created_at: datetime = Field(..., alias='createdAt')
+    """
+    When the run was created
+    """
+    updated_at: datetime = Field(..., alias='updatedAt')
+    """
+    When the run was last updated
+    """
+
+
+class Type(Enum):
+    """
+    The type of the Stream Run
+    """
+
+    search = 'search'
+    refresh = 'refresh'
+
+
+class UpdateStream(ExaBaseModel):
+    status: Optional[StreamStatus] = None
+    """
+    The status of the stream.
+    """
+    metadata: Optional[Dict[str, str]] = None
 
 
 class UpdateWebhookParameters(ExaBaseModel):
@@ -477,7 +714,7 @@ class WebhookAttempt(ExaBaseModel):
     """
     The headers of the response
     """
-    response_body: str = Field(..., alias='responseBody')
+    response_body: Optional[str] = Field(None, alias='responseBody')
     """
     The body of the response
     """
@@ -514,7 +751,7 @@ class Webset(ExaBaseModel):
     """
     The status of the webset
     """
-    external_id: Optional[str] = Field(..., alias='externalId')
+    external_id: Optional[str] = Field(None, alias='externalId')
     """
     The external identifier for the webset
     """
@@ -526,6 +763,10 @@ class Webset(ExaBaseModel):
     """
     The Enrichments to apply to the Webset Items.
     """
+    streams: List[Stream]
+    """
+    The Streams for the Webset.
+    """
     metadata: Optional[Dict[str, Any]] = {}
     """
     Set of key-value pairs you want to associate with this object.
@@ -615,7 +856,7 @@ class WebsetEnrichment(ExaBaseModel):
     The format of the enrichment response.
     """
     options: Optional[List[WebsetEnrichmentOption]] = Field(
-        ..., title='WebsetEnrichmentOptions'
+        None, title='WebsetEnrichmentOptions'
     )
     """
     When the format is options, the different options for the enrichment agent to choose from.
@@ -747,7 +988,7 @@ class WebsetItemArticlePropertiesFields(ExaBaseModel):
     """
     The author(s) of the article
     """
-    published_at: Optional[str] = Field(..., alias='publishedAt')
+    published_at: Optional[str] = Field(None, alias='publishedAt')
     """
     The date and time the article was published
     """
@@ -793,7 +1034,7 @@ class WebsetItemCompanyPropertiesFields(ExaBaseModel):
     """
     A short description of the company
     """
-    logo_url: Optional[AnyUrl] = Field(..., alias='logoUrl')
+    logo_url: Optional[AnyUrl] = Field(None, alias='logoUrl')
     """
     The logo URL of the company
     """
@@ -837,12 +1078,11 @@ class WebsetItemCustomPropertiesFields(ExaBaseModel):
     """
     The author(s) of the website
     """
-    published_at: Optional[str] = Field(..., alias='publishedAt')
+    published_at: Optional[str] = Field(None, alias='publishedAt')
     """
     The date and time the website was published
     """
 
-
 class WebsetItemEnrichedEvent(ExaBaseModel):
     id: str
     """
@@ -870,9 +1110,9 @@ class WebsetItemEvaluation(ExaBaseModel):
     """
     The satisfaction of the criterion
     """
-    references: List[Reference] = []
+    references: Optional[List[Reference]] = []
     """
-    The references used to generate the result. `null` if the evaluation is not yet completed.
+    The references used to generate the result.
     """
 
 
@@ -904,7 +1144,7 @@ class WebsetItemPersonPropertiesFields(ExaBaseModel):
     """
     The current work position of the person
     """
-    picture_url: Optional[AnyUrl] = Field(..., alias='pictureUrl')
+    picture_url: Optional[AnyUrl] = Field(None, alias='pictureUrl')
     """
     The image URL of the person
     """
@@ -934,7 +1174,7 @@ class WebsetItemResearchPaperPropertiesFields(ExaBaseModel):
     """
     The author(s) of the research paper
     """
-    published_at: Optional[str] = Field(..., alias='publishedAt')
+    published_at: Optional[str] = Field(None, alias='publishedAt')
     """
     The date and time the research paper was published
     """
@@ -976,26 +1216,33 @@ class WebsetSearch(ExaBaseModel):
     """
     The query used to create the search.
     """
-    entity: Union[
+    entity: Optional[Union[
         WebsetCompanyEntity,
         WebsetPersonEntity,
         WebsetArticleEntity,
         WebsetResearchPaperEntity,
         WebsetCustomEntity,
-    ]
+    ]] = None
     """
     The entity the search will return results for.
 
     When no entity is provided during creation, we will automatically select the best entity based on the query.
     """
-    criteria: List[Criterion]
+    criteria: List[WebsetSearchCriterion]
     """
     The criteria the search will use to evaluate the results. If not provided, we will automatically generate them for you.
     """
-    count: confloat(ge=1.0)
+    count: PositiveInt
     """
     The number of results the search will attempt to find. The actual number of results may be less than this number depending on the search complexity.
     """
+    behavior: Optional[WebsetSearchBehavior] = 'override'
+    """
+    The behavior of the search when it is added to a Webset.
+
+    - `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.
+    """
     progress: Progress
     """
     The progress of the search
@@ -1004,11 +1251,11 @@ class WebsetSearch(ExaBaseModel):
     """
     Set of key-value pairs you want to associate with this object.
     """
-    canceled_at: Optional[datetime] = Field(..., alias='canceledAt')
+    canceled_at: Optional[datetime] = Field(None, alias='canceledAt')
     """
     The date and time the search was canceled
     """
-    canceled_reason: Optional[CanceledReason] = Field(..., alias='canceledReason')
+    canceled_reason: Optional[WebsetSearchCanceledReason] = Field(None, alias='canceledReason')
     """
     The reason the search was canceled
     """
@@ -1022,14 +1269,15 @@ class WebsetSearch(ExaBaseModel):
     """
 
 
-class WebsetSearchBehaviour(Enum):
+class WebsetSearchBehavior(Enum):
     """
-    The behaviour of the Search when it is added to a Webset.
+    The behavior of the Search when it is added to a Webset.
 
-    - `override`: the search will reuse 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.
+    - `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.
     """
-
     override = 'override'
+    append = 'append'
 
 
 class WebsetSearchCanceledEvent(ExaBaseModel):
@@ -1046,6 +1294,11 @@ class WebsetSearchCanceledEvent(ExaBaseModel):
     """
 
 
+class WebsetSearchCanceledReason(Enum):
+    webset_deleted = 'webset_deleted'
+    webset_canceled = 'webset_canceled'
+
+
 class WebsetSearchCompletedEvent(ExaBaseModel):
     id: str
     """