exa-py 1.9.0__py3-none-any.whl → 1.10.0__py3-none-any.whl

exa_py/__init__.py

@@ -1 +1,2 @@
 from .api import Exa as Exa
+from .api import AsyncExa as AsyncExa

exa_py/api.py

@@ -22,6 +22,7 @@ from typing import (
     overload,
 )
 
+import httpx
 import requests
 from openai import OpenAI
 from openai.types.chat.chat_completion_message_param import ChatCompletionMessageParam
@@ -34,6 +35,7 @@ from exa_py.utils import (
     format_exa_result,
     maybe_get_query,
 )
+from .websets import WebsetsClient
 
 is_beta = os.getenv("IS_BETA") == "True"
 
@@ -729,6 +731,56 @@ class StreamAnswerResponse:
         self._raw_response.close()
 
 
+class AsyncStreamAnswerResponse:
+    """A class representing a streaming answer response."""
+
+    def __init__(self, raw_response: httpx.Response):
+        self._raw_response = raw_response
+        self._ensure_ok_status()
+
+    def _ensure_ok_status(self):
+        if self._raw_response.status_code != 200:
+            raise ValueError(
+                f"Request failed with status code {self._raw_response.status_code}: {self._raw_response.text}"
+            )
+
+    def __aiter__(self):
+        async def generator():
+            async for line in self._raw_response.aiter_lines():
+                if not line:
+                    continue
+                decoded_line = line.removeprefix("data: ")
+                try:
+                    chunk = json.loads(decoded_line)
+                except json.JSONDecodeError:
+                    continue
+
+                content = None
+                citations = None
+
+                if "choices" in chunk and chunk["choices"]:
+                    if "delta" in chunk["choices"][0]:
+                        content = chunk["choices"][0]["delta"].get("content")
+
+                if (
+                        "citations" in chunk
+                        and chunk["citations"]
+                        and chunk["citations"] != "null"
+                ):
+                    citations = [
+                        AnswerResult(**to_snake_case(s)) for s in chunk["citations"]
+                    ]
+
+                stream_chunk = StreamChunk(content=content, citations=citations)
+                if stream_chunk.has_data():
+                    yield stream_chunk
+        return generator()
+
+    def close(self) -> None:
+        """Close the underlying raw response to release the network socket."""
+        self._raw_response.close()
+
+
 T = TypeVar("T")
 
 
@@ -788,7 +840,7 @@ class Exa:
         self,
         api_key: Optional[str],
         base_url: str = "https://api.exa.ai",
-        user_agent: str = "exa-py 1.9.0",
+        user_agent: str = "exa-py 1.10.0",
     ):
         """Initialize the Exa client with the provided API key and optional base URL and user agent.
 
@@ -806,13 +858,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.
@@ -821,14 +876,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}"
             )
@@ -1815,3 +1888,333 @@ class Exa:
         options["stream"] = True
         raw_response = self.request("/answer", options)
         return StreamAnswerResponse(raw_response)
+
+class AsyncExa(Exa):
+    def __init__(self, api_key: str, api_base: str = "https://api.exa.ai"):
+        super().__init__(api_key, api_base)
+        self._client = None
+
+    @property
+    def client(self) -> httpx.AsyncClient:
+        # this may only be a
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                headers=self.headers,
+                timeout=60
+            )
+        return self._client
+
+    async def async_request(self, endpoint: str, data):
+        """Send a POST 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.
+
+        Returns:
+            Union[dict, requests.Response]: If streaming, returns the Response object.
+            Otherwise, returns the JSON-decoded response as a dict.
+
+        Raises:
+            ValueError: If the request fails (non-200 status code).
+        """
+        if data.get("stream"):
+            request = httpx.Request(
+                'POST',
+                self.base_url + endpoint,
+                json=data,
+                headers=self.headers
+            )
+            res = await self.client.send(request, stream=True)
+            return res
+
+        res = await self.client.post(self.base_url + endpoint, json=data, headers=self.headers)
+        if res.status_code != 200:
+            raise ValueError(
+                f"Request failed with status code {res.status_code}: {res.text}"
+            )
+        return res.json()
+
+    async def search(
+        self,
+        query: str,
+        *,
+        num_results: Optional[int] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        start_crawl_date: Optional[str] = None,
+        end_crawl_date: Optional[str] = None,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
+        use_autoprompt: Optional[bool] = None,
+        type: Optional[str] = None,
+        category: Optional[str] = None,
+        flags: Optional[List[str]] = None,
+        moderation: Optional[bool] = None,
+    ) -> SearchResponse[_Result]:
+        """Perform a search with a prompt-engineered query to retrieve relevant results.
+
+        Args:
+            query (str): The query string.
+            num_results (int, optional): Number of search results to return (default 10).
+            include_domains (List[str], optional): Domains to include in the search.
+            exclude_domains (List[str], optional): Domains to exclude from the search.
+            start_crawl_date (str, optional): Only links crawled after this date.
+            end_crawl_date (str, optional): Only links crawled before this date.
+            start_published_date (str, optional): Only links published after this date.
+            end_published_date (str, optional): Only links published before this date.
+            include_text (List[str], optional): Strings that must appear in the page text.
+            exclude_text (List[str], optional): Strings that must not appear in the page text.
+            use_autoprompt (bool, optional): Convert query to Exa (default False).
+            type (str, optional): 'keyword' or 'neural' (default 'neural').
+            category (str, optional): e.g. 'company'
+            flags (List[str], optional): Experimental flags for Exa usage.
+            moderation (bool, optional): If True, the search results will be moderated for safety.
+
+        Returns:
+            SearchResponse: The response containing search results, etc.
+        """
+        options = {k: v for k, v in locals().items() if k != "self" and v is not None}
+        validate_search_options(options, SEARCH_OPTIONS_TYPES)
+        options = to_camel_case(options)
+        data = await self.async_request("/search", options)
+        cost_dollars = parse_cost_dollars(data.get("costDollars"))
+        return SearchResponse(
+            [Result(**to_snake_case(result)) for result in data["results"]],
+            data["autopromptString"] if "autopromptString" in data else None,
+            data["resolvedSearchType"] if "resolvedSearchType" in data else None,
+            data["autoDate"] if "autoDate" in data else None,
+            cost_dollars=cost_dollars,
+        )
+
+    async def search_and_contents(self, query: str, **kwargs):
+        options = {k: v for k, v in {"query": query, **kwargs}.items() if v is not None}
+        # If user didn't ask for any particular content, default to text
+        if (
+            "text" not in options
+            and "highlights" not in options
+            and "summary" not in options
+            and "extras" not in options
+        ):
+            options["text"] = True
+
+        validate_search_options(
+            options,
+            {
+                **SEARCH_OPTIONS_TYPES,
+                **CONTENTS_OPTIONS_TYPES,
+                **CONTENTS_ENDPOINT_OPTIONS_TYPES,
+            },
+        )
+
+        # Nest the appropriate fields under "contents"
+        options = nest_fields(
+            options,
+            [
+                "text",
+                "highlights",
+                "summary",
+                "subpages",
+                "subpage_target",
+                "livecrawl",
+                "livecrawl_timeout",
+                "extras",
+            ],
+            "contents",
+        )
+        options = to_camel_case(options)
+        data = await self.async_request("/search", options)
+        cost_dollars = parse_cost_dollars(data.get("costDollars"))
+        return SearchResponse(
+            [Result(**to_snake_case(result)) for result in data["results"]],
+            data["autopromptString"] if "autopromptString" in data else None,
+            data["resolvedSearchType"] if "resolvedSearchType" in data else None,
+            data["autoDate"] if "autoDate" in data else None,
+            cost_dollars=cost_dollars,
+        )
+
+    async def get_contents(self, urls: Union[str, List[str], List[_Result]], **kwargs):
+        options = {
+            k: v
+            for k, v in {"urls": urls, **kwargs}.items()
+            if k != "self" and v is not None
+        }
+        if (
+            "text" not in options
+            and "highlights" not in options
+            and "summary" not in options
+            and "extras" not in options
+        ):
+            options["text"] = True
+
+        validate_search_options(
+            options,
+            {**CONTENTS_OPTIONS_TYPES, **CONTENTS_ENDPOINT_OPTIONS_TYPES},
+        )
+        options = to_camel_case(options)
+        data = await self.async_request("/contents", options)
+        cost_dollars = parse_cost_dollars(data.get("costDollars"))
+        return SearchResponse(
+            [Result(**to_snake_case(result)) for result in data["results"]],
+            data.get("autopromptString"),
+            data.get("resolvedSearchType"),
+            data.get("autoDate"),
+            cost_dollars=cost_dollars,
+        )
+
+    async def find_similar(
+        self,
+        url: str,
+        *,
+        num_results: Optional[int] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        start_crawl_date: Optional[str] = None,
+        end_crawl_date: Optional[str] = None,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
+        exclude_source_domain: Optional[bool] = None,
+        category: Optional[str] = None,
+        flags: Optional[List[str]] = None,
+    ) -> SearchResponse[_Result]:
+        """Finds similar pages to a given URL, potentially with domain filters and date filters.
+
+        Args:
+            url (str): The URL to find similar pages for.
+            num_results (int, optional): Number of results to return. Default is None (server default).
+            include_domains (List[str], optional): Domains to include in the search.
+            exclude_domains (List[str], optional): Domains to exclude from the search.
+            start_crawl_date (str, optional): Only links crawled after this date.
+            end_crawl_date (str, optional): Only links crawled before this date.
+            start_published_date (str, optional): Only links published after this date.
+            end_published_date (str, optional): Only links published before this date.
+            include_text (List[str], optional): Strings that must appear in the page text.
+            exclude_text (List[str], optional): Strings that must not appear in the page text.
+            exclude_source_domain (bool, optional): Whether to exclude the source domain.
+            category (str, optional): A data category to focus on.
+            flags (List[str], optional): Experimental flags.
+
+        Returns:
+            SearchResponse[_Result]
+        """
+        options = {k: v for k, v in locals().items() if k != "self" and v is not None}
+        validate_search_options(options, FIND_SIMILAR_OPTIONS_TYPES)
+        options = to_camel_case(options)
+        data = await self.async_request("/findSimilar", options)
+        cost_dollars = parse_cost_dollars(data.get("costDollars"))
+        return SearchResponse(
+            [Result(**to_snake_case(result)) for result in data["results"]],
+            data.get("autopromptString"),
+            data.get("resolvedSearchType"),
+            data.get("autoDate"),
+            cost_dollars=cost_dollars,
+        )
+
+    async def find_similar_and_contents(self, url: str, **kwargs):
+        options = {k: v for k, v in {"url": url, **kwargs}.items() if v is not None}
+        # Default to text if none specified
+        if (
+            "text" not in options
+            and "highlights" not in options
+            and "summary" not in options
+        ):
+            options["text"] = True
+
+        validate_search_options(
+            options,
+            {
+                **FIND_SIMILAR_OPTIONS_TYPES,
+                **CONTENTS_OPTIONS_TYPES,
+                **CONTENTS_ENDPOINT_OPTIONS_TYPES,
+            },
+        )
+        # We nest the content fields
+        options = nest_fields(
+            options,
+            [
+                "text",
+                "highlights",
+                "summary",
+                "subpages",
+                "subpage_target",
+                "livecrawl",
+                "livecrawl_timeout",
+                "extras",
+            ],
+            "contents",
+        )
+        options = to_camel_case(options)
+        data = await self.async_request("/findSimilar", options)
+        cost_dollars = parse_cost_dollars(data.get("costDollars"))
+        return SearchResponse(
+            [Result(**to_snake_case(result)) for result in data["results"]],
+            data.get("autopromptString"),
+            data.get("resolvedSearchType"),
+            data.get("autoDate"),
+            cost_dollars=cost_dollars,
+        )
+
+    async def answer(
+        self,
+        query: str,
+        *,
+        stream: Optional[bool] = False,
+        text: Optional[bool] = False,
+        model: Optional[Literal["exa", "exa-pro"]] = None,
+    ) -> Union[AnswerResponse, StreamAnswerResponse]:
+        """Generate an answer to a query using Exa's search and LLM capabilities.
+
+        Args:
+            query (str): The query to answer.
+            text (bool, optional): Whether to include full text in the results. Defaults to False.
+            model (str, optional): The model to use for answering. Either "exa" or "exa-pro". Defaults to None.
+
+        Returns:
+            AnswerResponse: An object containing the answer and citations.
+
+        Raises:
+            ValueError: If stream=True is provided. Use stream_answer() instead for streaming responses.
+        """
+        if stream:
+            raise ValueError(
+                "stream=True is not supported in `answer()`. "
+                "Please use `stream_answer(...)` for streaming."
+            )
+
+        options = {k: v for k, v in locals().items() if k != "self" and v is not None}
+        options = to_camel_case(options)
+        response = await self.async_request("/answer", options)
+
+        return AnswerResponse(
+            response["answer"],
+            [AnswerResult(**to_snake_case(result)) for result in response["citations"]],
+        )
+
+    async def stream_answer(
+        self,
+        query: str,
+        *,
+        text: bool = False,
+        model: Optional[Literal["exa", "exa-pro"]] = None,
+    ) -> AsyncStreamAnswerResponse:
+        """Generate a streaming answer response.
+
+        Args:
+            query (str): The query to answer.
+            text (bool): Whether to include full text in the results. Defaults to False.
+            model (str, optional): The model to use for answering. Either "exa" or "exa-pro". Defaults to None.
+
+        Returns:
+            AsyncStreamAnswerResponse: An object that can be iterated over to retrieve (partial text, partial citations).
+                Each iteration yields a tuple of (Optional[str], Optional[List[AnswerResult]]).
+        """
+        options = {k: v for k, v in locals().items() if k != "self" and v is not None}
+        options = to_camel_case(options)
+        options["stream"] = True
+        raw_response = await self.async_request("/answer", options)
+        return AsyncStreamAnswerResponse(raw_response)

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')
+]