exa-py 1.8.9__py3-none-any.whl → 1.9.1__py3-none-any.whl

exa_py/api.py

@@ -34,6 +34,7 @@ from exa_py.utils import (
     format_exa_result,
     maybe_get_query,
 )
+from .websets import WebsetsClient
 
 is_beta = os.getenv("IS_BETA") == "True"
 
@@ -47,6 +48,12 @@ def snake_to_camel(snake_str: str) -> str:
     Returns:
         str: The string converted to camelCase format.
     """
+    # Handle special cases where the field should start with non-alphanumeric characters
+    if snake_str == "schema_":
+        return "$schema"
+    if snake_str == "not_":
+        return "not"
+        
     components = snake_str.split("_")
     return components[0] + "".join(x.title() for x in components[1:])
 
@@ -247,15 +254,38 @@ class HighlightsContentsOptions(TypedDict, total=False):
     highlights_per_url: int
 
 
+class JSONSchema(TypedDict, total=False):
+    """Represents a JSON Schema definition used for structured summary output.
+    To learn more visit https://json-schema.org/overview/what-is-jsonschema.
+    """
+    schema_: str  # This will be converted to "$schema" in JSON
+    title: str
+    description: str
+    type: Literal["object", "array", "string", "number", "boolean", "null", "integer"]
+    properties: Dict[str, JSONSchema]
+    items: Union[JSONSchema, List[JSONSchema]]
+    required: List[str]
+    enum: List
+    additionalProperties: Union[bool, JSONSchema]
+    definitions: Dict[str, JSONSchema]
+    patternProperties: Dict[str, JSONSchema]
+    allOf: List[JSONSchema]
+    anyOf: List[JSONSchema]
+    oneOf: List[JSONSchema]
+    not_: JSONSchema  # This will be converted to "not" in JSON
+
+
 class SummaryContentsOptions(TypedDict, total=False):
     """A class representing the options that you can specify when requesting summary
 
     Attributes:
         query (str): The query string for the summary. Summary will bias towards answering the query.
+        schema (JSONSchema): JSON schema for structured output from summary.
     """
 
     query: str
-
+    schema: JSONSchema
+    
 
 class ExtrasOptions(TypedDict, total=False):
     """A class representing additional extraction fields (e.g. links, images)"""
@@ -759,7 +789,7 @@ class Exa:
         self,
         api_key: Optional[str],
         base_url: str = "https://api.exa.ai",
-        user_agent: str = "exa-py 1.8.9",
+        user_agent: str = "exa-py 1.9.1",
     ):
         """Initialize the Exa client with the provided API key and optional base URL and user agent.
 
@@ -777,13 +807,16 @@ class Exa:
                 )
         self.base_url = base_url
         self.headers = {"x-api-key": api_key, "User-Agent": user_agent}
+        self.websets = WebsetsClient(self)
 
-    def request(self, endpoint: str, data):
-        """Send a POST request to the Exa API, optionally streaming if data['stream'] is True.
+    def request(self, endpoint: str, data=None, method="POST", params=None):
+        """Send a request to the Exa API, optionally streaming if data['stream'] is True.
 
         Args:
             endpoint (str): The API endpoint (path).
-            data (dict): The JSON payload to send.
+            data (dict, optional): The JSON payload to send. Defaults to None.
+            method (str, optional): The HTTP method to use. Defaults to "POST".
+            params (dict, optional): Query parameters to include. Defaults to None.
 
         Returns:
             Union[dict, requests.Response]: If streaming, returns the Response object.
@@ -792,14 +825,32 @@ class Exa:
         Raises:
             ValueError: If the request fails (non-200 status code).
         """
-        if data.get("stream"):
+        if data and data.get("stream"):
             res = requests.post(
                 self.base_url + endpoint, json=data, headers=self.headers, stream=True
             )
             return res
 
-        res = requests.post(self.base_url + endpoint, json=data, headers=self.headers)
-        if res.status_code != 200:
+        if method.upper() == "GET":
+            res = requests.get(
+                self.base_url + endpoint, headers=self.headers, params=params
+            )
+        elif method.upper() == "POST":
+            res = requests.post(
+                self.base_url + endpoint, json=data, headers=self.headers
+            )
+        elif method.upper() == "PATCH":
+            res = requests.patch(
+                self.base_url + endpoint, json=data, headers=self.headers
+            )
+        elif method.upper() == "DELETE":
+            res = requests.delete(
+                self.base_url + endpoint, headers=self.headers
+            )
+        else:
+            raise ValueError(f"Unsupported HTTP method: {method}")
+
+        if res.status_code >= 400:
             raise ValueError(
                 f"Request failed with status code {res.status_code}: {res.text}"
             )

exa_py/websets/__init__.py

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

exa_py/websets/_generator/pydantic/BaseModel.jinja2

@@ -0,0 +1,42 @@
+{% for decorator in decorators -%}
+{{ decorator }}
+{% endfor -%}
+class {{ class_name }}({{ base_class }}):{% if comment is defined %}  # {{ comment }}{% endif %}
+{%- if description %}
+    """
+    {{ description | indent(4) }}
+    """
+{%- endif %}
+{%- if not fields and not description %}
+    pass
+{%- endif %}
+{%- if config %}
+{%- filter indent(4) %}
+{%- endfilter %}
+{%- endif %}
+{%- for field in fields -%}
+    {%- if field.name == "type" and field.field %}
+    type: Literal['{{ field.default }}']
+    {%- elif field.name == "object" and field.field %}
+    object: Literal['{{ field.default }}']
+    {%- elif not field.annotated and field.field %}
+    {{ field.name }}: {{ field.type_hint }} = {{ field.field }}
+    {%- else %}
+    {%- if field.annotated %}
+    {{ field.name }}: {{ field.annotated }}
+    {%- else %}
+    {{ field.name }}: {{ field.type_hint }}
+    {%- endif %}
+    {%- if not (field.required or (field.represented_default == 'None' and field.strip_default_none)) or field.data_type.is_optional
+            %} = {{ field.represented_default }}
+    {%- endif -%}
+    {%- endif %}
+    {%- if field.docstring %}
+    """
+    {{ field.docstring | indent(4) }}
+    """
+    {%- endif %}
+{%- for method in methods -%}
+    {{ method }}
+{%- endfor -%}
+{%- endfor -%}

exa_py/websets/client.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import time
+from datetime import datetime
+from typing import List, Optional, Literal
+
+from .types import (
+    Webset,
+    ListWebsetsResponse,
+    GetWebsetResponse,
+    UpdateWebsetRequest,
+    WebsetStatus,
+    CreateWebsetParameters,
+)
+from .core.base import WebsetsBaseClient
+from .items import WebsetItemsClient
+from .searches import WebsetSearchesClient
+from .enrichments import WebsetEnrichmentsClient
+from .webhooks import WebsetWebhooksClient
+
+class WebsetsClient(WebsetsBaseClient):
+    """Client for managing Websets."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+        self.items = WebsetItemsClient(client)
+        self.searches = WebsetSearchesClient(client)
+        self.enrichments = WebsetEnrichmentsClient(client)
+        self.webhooks = WebsetWebhooksClient(client)
+
+    def create(self, params: CreateWebsetParameters) -> Webset:
+        """Create a new Webset.
+        
+        Args:
+            params (CreateWebsetRequest): The parameters for creating a webset.
+        
+        Returns:
+            Webset: The created webset.
+        """
+        response = self.request("/v0/websets", data=params.model_dump(by_alias=True, exclude_none=True))
+        return Webset.model_validate(response)
+
+    def get(self, id: str, *, expand: Optional[List[Literal["items"]]] = None) -> GetWebsetResponse:
+        """Get a Webset by ID.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+            expand (List[Literal["items"]], optional): Expand the response with specified resources.
+                Allowed values: ["items"]
+        
+        Returns:
+            GetWebsetResponse: The retrieved webset.
+        """
+        params = {"expand": expand} if expand else {}
+        response = self.request(f"/v0/websets/{id}", params=params, method="GET")
+        return GetWebsetResponse.model_validate(response)
+
+    def list(self, *, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListWebsetsResponse:
+        """List all Websets.
+        
+        Args:
+            cursor (str, optional): The cursor to paginate through the results.
+            limit (int, optional): The number of results to return (max 200).
+        
+        Returns:
+            ListWebsetsResponse: List of websets.
+        """
+        params = {k: v for k, v in {"cursor": cursor, "limit": limit}.items() if v is not None}
+        response = self.request("/v0/websets", params=params, method="GET")
+        return ListWebsetsResponse.model_validate(response)
+
+    def update(self, id: str, params: UpdateWebsetRequest) -> Webset:
+        """Update a Webset.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+            params (UpdateWebsetRequest): The parameters for updating a webset.
+        
+        Returns:
+            Webset: The updated webset.
+        """
+        response = self.request(f"/v0/websets/{id}", data=params.model_dump(by_alias=True, exclude_none=True), method="POST")
+        return Webset.model_validate(response)
+
+    def delete(self, id: str) -> Webset:
+        """Delete a Webset.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+        
+        Returns:
+            Webset: The deleted webset.
+        """
+        response = self.request(f"/v0/websets/{id}", method="DELETE")
+        return Webset.model_validate(response)
+
+    def cancel(self, id: str) -> Webset:
+        """Cancel a running Webset.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+        
+        Returns:
+            Webset: The canceled webset.
+        """
+        response = self.request(f"/v0/websets/{id}/cancel", method="POST")
+        return Webset.model_validate(response) 
+    
+    def wait_until_idle(self, id: str, *, timeout: Optional[int] = None) -> Webset:
+        """Wait until a Webset is idle.
+        
+        Args:
+            id (str): The id or externalId of the Webset.
+        
+        Returns:
+            Webset: The webset.
+        """
+        start_time = time.time()
+        while True:
+            webset = self.get(id)
+            if webset.status == WebsetStatus.idle:
+                break
+            time.sleep(1)
+            if timeout and time.time() - start_time > timeout:
+                raise Exception("Webset timed out")
+        return webset

exa_py/websets/core/__init__.py

@@ -0,0 +1,9 @@
+from ..types import *
+import sys
+
+# Get all public names from model module that don't start with underscore
+model_module = sys.modules[__name__]
+__all__ = ['WebsetsBaseClient', 'ExaBaseModel'] + [
+    name for name in dir(model_module)
+    if not name.startswith('_') and name not in ('WebsetsBaseClient', 'ExaBaseModel')
+]

exa_py/websets/core/base.py

@@ -0,0 +1,41 @@
+
+from __future__ import annotations
+
+from pydantic import ConfigDict
+
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel
+
+class ExaBaseModel(BaseModel):
+    """Base model for all Exa models with common configuration."""
+    model_config = ConfigDict(populate_by_name=True)
+
+class WebsetsBaseClient:
+    base_url: str
+
+    """Base client for Exa API resources."""
+
+    def __init__(self, client):
+        """Initialize the client.
+        
+        Args:
+            client: The parent Exa client.
+        """
+        self._client = client
+        
+    def request(self, endpoint: str, data: Optional[Dict[str, Any]] = None, 
+                method: str = "POST", params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Make a request to the Exa API.
+        
+        Args:
+            endpoint (str): The API endpoint to request.
+            data (Dict[str, Any], optional): The request data. Defaults to None.
+            method (str, optional): The HTTP method. Defaults to "POST".
+            params (Dict[str, Any], optional): The query parameters. Defaults to None.
+            
+        Returns:
+            Dict[str, Any]: The API response.
+        """
+        return self._client.request("/websets/" + endpoint, data=data, method=method, params=params) 
+    

exa_py/websets/enrichments/__init__.py

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

exa_py/websets/enrichments/client.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from ..types import (
+    CreateEnrichmentParameters,
+    WebsetEnrichment,
+)
+from ..core.base import WebsetsBaseClient
+
+class WebsetEnrichmentsClient(WebsetsBaseClient):
+    """Client for managing Webset Enrichments."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+
+    def create(self, webset_id: str, params: CreateEnrichmentParameters) -> WebsetEnrichment:
+        """Create an Enrichment for a Webset.
+        
+        Args:
+            webset_id (str): The id of the Webset.
+            params (CreateEnrichmentParameters): The parameters for creating an enrichment.
+        
+        Returns:
+            WebsetEnrichment: The created enrichment.
+        """
+        response = self.request(f"/v0/websets/{webset_id}/enrichments", data=params.model_dump(by_alias=True, exclude_none=True))
+        return WebsetEnrichment.model_validate(response)
+
+    def get(self, webset_id: str, id: str) -> WebsetEnrichment:
+        """Get an Enrichment by ID.
+        
+        Args:
+            webset_id (str): The id of the Webset.
+            id (str): The id of the Enrichment.
+        
+        Returns:
+            WebsetEnrichment: The retrieved enrichment.
+        """
+        response = self.request(f"/v0/websets/{webset_id}/enrichments/{id}", method="GET")
+        return WebsetEnrichment.model_validate(response)
+
+    def delete(self, webset_id: str, id: str) -> WebsetEnrichment:
+        """Delete an Enrichment.
+        
+        Args:
+            webset_id (str): The id of the Webset.
+            id (str): The id of the Enrichment.
+        
+        Returns:
+            WebsetEnrichment: The deleted enrichment.
+        """
+        response = self.request(f"/v0/websets/{webset_id}/enrichments/{id}", method="DELETE")
+        return WebsetEnrichment.model_validate(response)
+
+    def cancel(self, webset_id: str, id: str) -> WebsetEnrichment:
+        """Cancel a running Enrichment.
+        
+        Args:
+            webset_id (str): The id of the Webset.
+            id (str): The id of the Enrichment.
+        
+        Returns:
+            WebsetEnrichment: The canceled enrichment.
+        """
+        response = self.request(f"/v0/websets/{webset_id}/enrichments/{id}/cancel", method="POST")
+        return WebsetEnrichment.model_validate(response) 

exa_py/websets/items/__init__.py

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

exa_py/websets/items/client.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import  Optional, Iterator
+
+from ..types import (
+    WebsetItem,
+    ListWebsetItemResponse,
+)
+from ..core.base import WebsetsBaseClient
+
+class WebsetItemsClient(WebsetsBaseClient):
+    """Client for managing Webset Items."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+
+    def list(self, webset_id: str, *, cursor: Optional[str] = None, 
+             limit: Optional[int] = 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).
+        
+        Returns:
+            ListWebsetItemResponse: List of webset items.
+        """
+        params = {k: v for k, v in {"cursor": cursor, "limit": limit}.items() if v is not None}
+        response = self.request(f"/v0/websets/{webset_id}/items", params=params, method="GET")
+        return ListWebsetItemResponse.model_validate(response)
+
+    def list_all(self, webset_id: str, *, limit: Optional[int] = None) -> Iterator[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).
+            
+        Yields:
+            WebsetItem: Each item in the webset.
+        """
+        cursor = None
+        while True:
+            response = self.list(webset_id, cursor=cursor, limit=limit)
+            for item in response.data:
+                yield item
+            
+            if not response.has_more or not response.next_cursor:
+                break
+                
+            cursor = response.next_cursor
+
+    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 = self.request(f"/v0/websets/{webset_id}/items/{id}", method="GET")
+        return WebsetItem.model_validate(response)
+
+    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 = self.request(f"/v0/websets/{webset_id}/items/{id}", method="DELETE")
+        return WebsetItem.model_validate(response) 

exa_py/websets/searches/__init__.py

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

exa_py/websets/searches/client.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from ..types import (
+    CreateWebsetSearchParameters,
+    WebsetSearch,
+)
+from ..core.base import WebsetsBaseClient
+
+class WebsetSearchesClient(WebsetsBaseClient):
+    """Client for managing Webset Searches."""
+    
+    def __init__(self, client):
+        super().__init__(client)
+
+    def create(self, webset_id: str, params: 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 = self.request(f"/v0/websets/{webset_id}/searches", data=params.model_dump(by_alias=True, exclude_none=True))
+        return WebsetSearch.model_validate(response)
+
+    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 = self.request(f"/v0/websets/{webset_id}/searches/{id}", method="GET")
+        return WebsetSearch.model_validate(response)
+
+    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 = self.request(f"/v0/websets/{webset_id}/searches/{id}/cancel", method="POST")
+        return WebsetSearch.model_validate(response)