exa-py 1.12.0__tar.gz → 1.12.3__tar.gz

{exa_py-1.12.0 → exa_py-1.12.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exa-py
-Version: 1.12.0
+Version: 1.12.3
 Summary: Python SDK for Exa API.
 License: MIT
 Author: Exa AI
@@ -45,14 +45,12 @@ exa = Exa(api_key="your-api-key")
 ```
 
 ## Common requests
+
 ```python
 
   # basic search
   results = exa.search("This is a Exa query:")
 
-  # autoprompted search
-  results = exa.search("autopromptable query", use_autoprompt=True)
-
   # keyword search (non-neural)
   results = exa.search("Google-style query", type="keyword")
 
@@ -65,14 +63,10 @@ exa = Exa(api_key="your-api-key")
   # search and get text contents
   results = exa.search_and_contents("This is a Exa query:")
 
-  # search and get highlights
-  results = exa.search_and_contents("This is a Exa query:", highlights=True)
-
   # search and get contents with contents options
-  results = exa.search_and_contents("This is a Exa query:", 
-                                    text={"include_html_tags": True, "max_characters": 1000}, 
-                                    highlights={"highlights_per_url": 2, "num_sentences": 1, "query": "This is the highlight query:"})
-                                    
+  results = exa.search_and_contents("This is a Exa query:",
+                                    text={"include_html_tags": True, "max_characters": 1000})
+
   # find similar documents
   results = exa.find_similar("https://example.com")
 
@@ -80,18 +74,14 @@ exa = Exa(api_key="your-api-key")
   results = exa.find_similar("https://example.com", exclude_source_domain=True)
 
   # find similar with contents
-  results = exa.find_similar_and_contents("https://example.com", text=True, highlights=True)
+  results = exa.find_similar_and_contents("https://example.com", text=True)
 
   # get text contents
-  results = exa.get_contents(["urls"])
-
-  # get highlights
-  results = exa.get_contents(["urls"], highlights=True)
+  results = exa.get_contents(["tesla.com"])
 
   # get contents with contents options
-  results = exa.get_contents(["urls"], 
-                             text={"include_html_tags": True, "max_characters": 1000}, 
-                             highlights={"highlights_per_url": 2, "num_sentences": 1, "query": "This is the highlight query:"})
+  results = exa.get_contents(["urls"],
+                             text={"include_html_tags": True, "max_characters": 1000})
 
   # basic answer
   response = exa.answer("This is a query to answer a question")
@@ -106,6 +96,38 @@ exa = Exa(api_key="your-api-key")
   for chunk in response:
     print(chunk, end='', flush=True)
 
+  # research task example – answer a question with citations
+  # Example prompt & schema inspired by the TypeScript example.
+  QUESTION = (
+      "Summarize the history of San Francisco highlighting one or two major events "
+      "for each decade from 1850 to 1950"
+  )
+  OUTPUT_SCHEMA: Dict[str, Any] = {
+      "type": "object",
+      "required": ["timeline"],
+      "properties": {
+          "timeline": {
+              "type": "array",
+              "items": {
+                  "type": "object",
+                  "required": ["decade", "notableEvents"],
+                  "properties": {
+                      "decade": {
+                          "type": "string",
+                          "description": 'Decade label e.g. "1850s"',
+                      },
+                      "notableEvents": {
+                          "type": "string",
+                          "description": "A summary of notable events.",
+                      },
+                  },
+              },
+          },
+      },
+  }
+  resp = exa.research.create_task(
+      input_instructions=QUESTION,
+      output_schema=OUTPUT_SCHEMA,
+  )
 ```
 
-

{exa_py-1.12.0 → exa_py-1.12.3}/README.md

@@ -22,14 +22,12 @@ exa = Exa(api_key="your-api-key")
 ```
 
 ## Common requests
+
 ```python
 
   # basic search
   results = exa.search("This is a Exa query:")
 
-  # autoprompted search
-  results = exa.search("autopromptable query", use_autoprompt=True)
-
   # keyword search (non-neural)
   results = exa.search("Google-style query", type="keyword")
 
@@ -42,14 +40,10 @@ exa = Exa(api_key="your-api-key")
   # search and get text contents
   results = exa.search_and_contents("This is a Exa query:")
 
-  # search and get highlights
-  results = exa.search_and_contents("This is a Exa query:", highlights=True)
-
   # search and get contents with contents options
-  results = exa.search_and_contents("This is a Exa query:", 
-                                    text={"include_html_tags": True, "max_characters": 1000}, 
-                                    highlights={"highlights_per_url": 2, "num_sentences": 1, "query": "This is the highlight query:"})
-                                    
+  results = exa.search_and_contents("This is a Exa query:",
+                                    text={"include_html_tags": True, "max_characters": 1000})
+
   # find similar documents
   results = exa.find_similar("https://example.com")
 
@@ -57,18 +51,14 @@ exa = Exa(api_key="your-api-key")
   results = exa.find_similar("https://example.com", exclude_source_domain=True)
 
   # find similar with contents
-  results = exa.find_similar_and_contents("https://example.com", text=True, highlights=True)
+  results = exa.find_similar_and_contents("https://example.com", text=True)
 
   # get text contents
-  results = exa.get_contents(["urls"])
-
-  # get highlights
-  results = exa.get_contents(["urls"], highlights=True)
+  results = exa.get_contents(["tesla.com"])
 
   # get contents with contents options
-  results = exa.get_contents(["urls"], 
-                             text={"include_html_tags": True, "max_characters": 1000}, 
-                             highlights={"highlights_per_url": 2, "num_sentences": 1, "query": "This is the highlight query:"})
+  results = exa.get_contents(["urls"],
+                             text={"include_html_tags": True, "max_characters": 1000})
 
   # basic answer
   response = exa.answer("This is a query to answer a question")
@@ -83,5 +73,37 @@ exa = Exa(api_key="your-api-key")
   for chunk in response:
     print(chunk, end='', flush=True)
 
+  # research task example – answer a question with citations
+  # Example prompt & schema inspired by the TypeScript example.
+  QUESTION = (
+      "Summarize the history of San Francisco highlighting one or two major events "
+      "for each decade from 1850 to 1950"
+  )
+  OUTPUT_SCHEMA: Dict[str, Any] = {
+      "type": "object",
+      "required": ["timeline"],
+      "properties": {
+          "timeline": {
+              "type": "array",
+              "items": {
+                  "type": "object",
+                  "required": ["decade", "notableEvents"],
+                  "properties": {
+                      "decade": {
+                          "type": "string",
+                          "description": 'Decade label e.g. "1850s"',
+                      },
+                      "notableEvents": {
+                          "type": "string",
+                          "description": "A summary of notable events.",
+                      },
+                  },
+              },
+          },
+      },
+  }
+  resp = exa.research.create_task(
+      input_instructions=QUESTION,
+      output_schema=OUTPUT_SCHEMA,
+  )
 ```
-

{exa_py-1.12.0 → exa_py-1.12.3}/exa_py/api.py

@@ -38,6 +38,8 @@ from exa_py.utils import (
 )
 from .websets import WebsetsClient
 from .websets.core.base import ExaJSONEncoder
+from .research.client import ResearchClient, AsyncResearchClient
+from .research.models import ResearchTaskResponse  # noqa: E402,F401
 
 is_beta = os.getenv("IS_BETA") == "True"
 
@@ -56,7 +58,7 @@ def snake_to_camel(snake_str: str) -> str:
         return "$schema"
     if snake_str == "not_":
         return "not"
-        
+
     components = snake_str.split("_")
     return components[0] + "".join(x.title() for x in components[1:])
 
@@ -261,6 +263,7 @@ 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
@@ -288,7 +291,7 @@ class SummaryContentsOptions(TypedDict, total=False):
 
     query: str
     schema: JSONSchema
-    
+
 
 class ExtrasOptions(TypedDict, total=False):
     """A class representing additional extraction fields (e.g. links, images)"""
@@ -669,7 +672,7 @@ class AnswerResponse:
         citations (List[AnswerResult]): A list of citations used to generate the answer.
     """
 
-    answer: str
+    answer: Union[str, dict[str, Any]]
     citations: List[AnswerResult]
 
     def __str__(self):
@@ -765,9 +768,9 @@ class AsyncStreamAnswerResponse:
                         content = chunk["choices"][0]["delta"].get("content")
 
                 if (
-                        "citations" in chunk
-                        and chunk["citations"]
-                        and chunk["citations"] != "null"
+                    "citations" in chunk
+                    and chunk["citations"]
+                    and chunk["citations"] != "null"
                 ):
                     citations = [
                         AnswerResult(**to_snake_case(s)) for s in chunk["citations"]
@@ -776,6 +779,7 @@ class AsyncStreamAnswerResponse:
                 stream_chunk = StreamChunk(content=content, citations=citations)
                 if stream_chunk.has_data():
                     yield stream_chunk
+
         return generator()
 
     def close(self) -> None:
@@ -835,6 +839,37 @@ def nest_fields(original_dict: Dict, fields_to_nest: List[str], new_key: str):
     return original_dict
 
 
+@dataclass
+class ResearchTaskResponse:
+    """A class representing the response for a research task.
+
+    Attributes:
+        id (str): The unique identifier for the research request.
+        status (str): Status of the research request.
+        output (Optional[Dict[str, Any]]): The answer structured as JSON, if available.
+        citations (Optional[Dict[str, List[_Result]]]): List of citations used to generate the answer, grouped by root field in the output schema.
+    """
+
+    id: str
+    status: str
+    output: Optional[Dict[str, Any]]
+    citations: Dict[str, List[_Result]]
+
+    def __str__(self):
+        output_repr = (
+            json.dumps(self.output, indent=2, ensure_ascii=False)
+            if self.output is not None
+            else "None"
+        )
+        citations_str = "\n\n".join(str(src) for src in self.citations)
+        return (
+            f"ID: {self.id}\n"
+            f"Status: {self.status}\n"
+            f"Output: {output_repr}\n\n"
+            f"Citations:\n{citations_str}"
+        )
+
+
 class Exa:
     """A client for interacting with Exa API."""
 
@@ -842,7 +877,7 @@ class Exa:
         self,
         api_key: Optional[str],
         base_url: str = "https://api.exa.ai",
-        user_agent: str = "exa-py 1.12.0",
+        user_agent: str = "exa-py 1.12.3",
     ):
         """Initialize the Exa client with the provided API key and optional base URL and user agent.
 
@@ -859,10 +894,23 @@ class Exa:
                     "API key must be provided as an argument or in EXA_API_KEY environment variable"
                 )
         self.base_url = base_url
-        self.headers = {"x-api-key": api_key, "User-Agent": user_agent, "Content-Type": "application/json"}
+        self.headers = {
+            "x-api-key": api_key,
+            "User-Agent": user_agent,
+            "Content-Type": "application/json",
+        }
         self.websets = WebsetsClient(self)
+        # Research tasks client (new, mirrors Websets design)
+        self.research = ResearchClient(self)
 
-    def request(self, endpoint: str, data: Optional[Union[Dict[str, Any], str]] = None, method: str = "POST", params: Optional[Dict[str, Any]] = None) -> Union[Dict[str, Any], requests.Response]:
+    def request(
+        self,
+        endpoint: str,
+        data: Optional[Union[Dict[str, Any], str]] = None,
+        method: str = "POST",
+        params: Optional[Dict[str, Any]] = None,
+        force_stream: Optional[bool] = False,
+    ) -> Union[Dict[str, Any], requests.Response]:
         """Send a request to the Exa API, optionally streaming if data['stream'] is True.
 
         Args:
@@ -885,13 +933,13 @@ class Exa:
         else:
             # Otherwise, serialize the dictionary to JSON if it exists
             json_data = json.dumps(data, cls=ExaJSONEncoder) if data else None
-            
-        if data and data.get("stream"):
+
+        if (data and data.get("stream")) or force_stream:
             res = requests.post(
-                self.base_url + endpoint, 
+                self.base_url + endpoint,
                 data=json_data,
-                headers=self.headers, 
-                stream=True
+                headers=self.headers,
+                stream=True,
             )
             return res
 
@@ -901,20 +949,14 @@ class Exa:
             )
         elif method.upper() == "POST":
             res = requests.post(
-                self.base_url + endpoint, 
-                data=json_data,
-                headers=self.headers
+                self.base_url + endpoint, data=json_data, headers=self.headers
             )
         elif method.upper() == "PATCH":
             res = requests.patch(
-                self.base_url + endpoint, 
-                data=json_data,
-                headers=self.headers
+                self.base_url + endpoint, data=json_data, headers=self.headers
             )
         elif method.upper() == "DELETE":
-            res = requests.delete(
-                self.base_url + endpoint, headers=self.headers
-            )
+            res = requests.delete(self.base_url + endpoint, headers=self.headers)
         else:
             raise ValueError(f"Unsupported HTTP method: {method}")
 
@@ -1845,6 +1887,7 @@ class Exa:
         text: Optional[bool] = False,
         system_prompt: Optional[str] = None,
         model: Optional[Literal["exa", "exa-pro"]] = None,
+        output_schema: Optional[dict[str, Any]] = None,
     ) -> Union[AnswerResponse, StreamAnswerResponse]: ...
 
     def answer(
@@ -1855,6 +1898,7 @@ class Exa:
         text: Optional[bool] = False,
         system_prompt: Optional[str] = None,
         model: Optional[Literal["exa", "exa-pro"]] = None,
+        output_schema: Optional[dict[str, Any]] = None,
     ) -> Union[AnswerResponse, StreamAnswerResponse]:
         """Generate an answer to a query using Exa's search and LLM capabilities.
 
@@ -1863,6 +1907,7 @@ class Exa:
             text (bool, optional): Whether to include full text in the results. Defaults to False.
             system_prompt (str, optional): A system prompt to guide the LLM's behavior when generating the answer.
             model (str, optional): The model to use for answering. Either "exa" or "exa-pro". Defaults to None.
+            output_schema (dict[str, Any], optional): JSON schema describing the desired answer structure.
 
         Returns:
             AnswerResponse: An object containing the answer and citations.
@@ -1892,6 +1937,7 @@ class Exa:
         text: bool = False,
         system_prompt: Optional[str] = None,
         model: Optional[Literal["exa", "exa-pro"]] = None,
+        output_schema: Optional[dict[str, Any]] = None,
     ) -> StreamAnswerResponse:
         """Generate a streaming answer response.
 
@@ -1900,7 +1946,7 @@ class Exa:
             text (bool): Whether to include full text in the results. Defaults to False.
             system_prompt (str, optional): A system prompt to guide the LLM's behavior when generating the answer.
             model (str, optional): The model to use for answering. Either "exa" or "exa-pro". Defaults to None.
-
+            output_schema (dict[str, Any], optional): JSON schema describing the desired answer structure.
         Returns:
             StreamAnswerResponse: An object that can be iterated over to retrieve (partial text, partial citations).
                 Each iteration yields a tuple of (Optional[str], Optional[List[AnswerResult]]).
@@ -1911,9 +1957,12 @@ class Exa:
         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)
+        # Override the synchronous ResearchClient with its async counterpart.
+        self.research = AsyncResearchClient(self)
         self._client = None
 
     @property
@@ -1921,13 +1970,13 @@ class AsyncExa(Exa):
         # this may only be a
         if self._client is None:
             self._client = httpx.AsyncClient(
-                base_url=self.base_url,
-                headers=self.headers,
-                timeout=60
+                base_url=self.base_url, headers=self.headers, timeout=60
             )
         return self._client
 
-    async def async_request(self, endpoint: str, data):
+    async def async_request(
+        self, endpoint: str, data, force_stream: Optional[bool] = False
+    ):
         """Send a POST request to the Exa API, optionally streaming if data['stream'] is True.
 
         Args:
@@ -1941,17 +1990,16 @@ class AsyncExa(Exa):
         Raises:
             ValueError: If the request fails (non-200 status code).
         """
-        if data.get("stream"):
+        if data.get("stream") or force_stream:
             request = httpx.Request(
-                'POST',
-                self.base_url + endpoint,
-                json=data,
-                headers=self.headers
+                "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)
+        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}"
@@ -2189,6 +2237,7 @@ class AsyncExa(Exa):
         text: Optional[bool] = False,
         system_prompt: Optional[str] = None,
         model: Optional[Literal["exa", "exa-pro"]] = None,
+        output_schema: Optional[dict[str, Any]] = None,
     ) -> Union[AnswerResponse, StreamAnswerResponse]:
         """Generate an answer to a query using Exa's search and LLM capabilities.
 
@@ -2197,6 +2246,7 @@ class AsyncExa(Exa):
             text (bool, optional): Whether to include full text in the results. Defaults to False.
             system_prompt (str, optional): A system prompt to guide the LLM's behavior when generating the answer.
             model (str, optional): The model to use for answering. Either "exa" or "exa-pro". Defaults to None.
+            output_schema (dict[str, Any], optional): JSON schema describing the desired answer structure.
 
         Returns:
             AnswerResponse: An object containing the answer and citations.
@@ -2226,6 +2276,7 @@ class AsyncExa(Exa):
         text: bool = False,
         system_prompt: Optional[str] = None,
         model: Optional[Literal["exa", "exa-pro"]] = None,
+        output_schema: Optional[dict[str, Any]] = None,
     ) -> AsyncStreamAnswerResponse:
         """Generate a streaming answer response.
 
@@ -2234,7 +2285,7 @@ class AsyncExa(Exa):
             text (bool): Whether to include full text in the results. Defaults to False.
             system_prompt (str, optional): A system prompt to guide the LLM's behavior when generating the answer.
             model (str, optional): The model to use for answering. Either "exa" or "exa-pro". Defaults to None.
-
+            output_schema (dict[str, Any], optional): JSON schema describing the desired answer structure.
         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]]).

exa_py-1.12.3/exa_py/research/__init__.py

@@ -0,0 +1,8 @@
+from .client import ResearchClient, AsyncResearchClient
+from .models import ResearchTaskResponse
+
+__all__ = [
+    "ResearchClient",
+    "AsyncResearchClient",
+    "ResearchTaskResponse",
+]

exa_py-1.12.3/exa_py/research/client.py

@@ -0,0 +1,257 @@
+"""Lightweight research client wrappers for the Exa REST API.
+
+This module purposefully keeps its import surface minimal to avoid circular
+import problems with :pymod:`exa_py.api`.  Any heavy dependencies (including
+`exa_py.api` itself) are imported lazily **inside** functions.  This means
+that type-checkers still see the full, precise types via the ``TYPE_CHECKING``
+block, but at runtime we only pay the cost if/when a helper is actually used.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
+
+if TYPE_CHECKING:  # pragma: no cover – only for static analysers
+    # Import with full type info when static type-checking.  `_Result` still
+    # lives in ``exa_py.api`` but the response model moved to
+    # ``exa_py.research.models``.
+    from ..api import _Result  # noqa: F401
+    from .models import ResearchTaskResponse  # noqa: F401
+
+# ---------------------------------------------------------------------------
+# Public, user-facing clients
+# ---------------------------------------------------------------------------
+
+
+class ResearchClient:
+    """Synchronous helper namespace accessed via :pyattr:`Exa.research`."""
+
+    def __init__(self, parent_client):
+        # A reference to the *already-constructed* ``Exa`` instance so that we
+        # can piggy-back on its HTTP plumbing (headers, base URL, retries, …).
+        self._client = parent_client
+
+    # ------------------------------------------------------------------
+    # API surface
+    # ------------------------------------------------------------------
+    def create_task(
+        self,
+        *,
+        input_instructions: str,
+        output_schema: Dict[str, Any],
+    ) -> "ResearchTaskResponse":
+        """Submit a research request to the Exa backend.
+
+        The public API remains synchronous – the function only returns once
+        the task has finished and the final structured answer is available.
+        Internally, however, the endpoint now streams *progress* updates via
+        Server-Sent Events (SSE). We therefore initiate a streaming request
+        and keep reading until we receive the terminal ``{"tag": "complete"}``
+        chunk, which carries the exact same payload shape that the blocking
+        variant returned previously.  Any ``{"tag": "progress"}`` chunks are
+        ignored, while ``{"tag": "error"}`` chunks result in an exception.
+
+        Parameters
+        ----------
+        input_instructions:
+            Natural-language instructions that describe *what* should be
+            researched or extracted.
+        output_schema:
+            JSON-schema describing the desired structured output format.
+        """
+
+        import json
+
+        payload = {
+            "input": {"instructions": input_instructions},
+            "output": {"schema": output_schema},
+        }
+
+        raw_response = self._client.request(
+            "/research/tasks", payload, force_stream=True
+        )
+
+        def _handle_payload(tag: Optional[str], payload_dict: Dict[str, Any]):
+            """Inner helper handling decoded JSON chunks."""
+            if tag is None:
+                tag_local = payload_dict.get("tag")
+            else:
+                tag_local = tag
+
+            if tag_local == "progress":
+                return None  # ignore
+            if tag_local == "error":
+                msg = payload_dict.get("error", {}).get("message", "Unknown error")
+                raise RuntimeError(f"Research task failed: {msg}")
+            if tag_local == "complete":
+                data_obj = payload_dict.get("data")
+                if data_obj is None:
+                    raise RuntimeError("Malformed 'complete' chunk with no data")
+                return _parse_research_response(data_obj)
+
+            # Fallback: if looks like final object
+            if {"id", "status"}.issubset(payload_dict.keys()):
+                return _parse_research_response(payload_dict)
+            return None
+
+        # ------------------------------------------------------------------
+        # Minimal SSE parser (sync)
+        # ------------------------------------------------------------------
+        event_name: Optional[str] = None
+        data_buf: str = ""
+
+        for raw_line in raw_response.iter_lines(decode_unicode=True):
+            line = raw_line
+            if line == "":
+                if data_buf:
+                    try:
+                        payload_dict = json.loads(data_buf)
+                    except json.JSONDecodeError:
+                        data_buf = ""
+                        event_name = None
+                        continue
+                    maybe_resp = _handle_payload(event_name, payload_dict)
+                    if maybe_resp is not None:
+                        raw_response.close()
+                        return maybe_resp
+                # reset after event
+                data_buf = ""
+                event_name = None
+                continue
+
+            if line.startswith("event:"):
+                event_name = line[len("event:") :].strip()
+            elif line.startswith("data:"):
+                data_buf += line[len("data:") :].strip()
+
+        # Process any remaining buffer (in case stream closed without blank line)
+        if data_buf:
+            try:
+                payload_dict = json.loads(data_buf)
+                maybe_resp = _handle_payload(event_name, payload_dict)
+                if maybe_resp is not None:
+                    raw_response.close()
+                    return maybe_resp
+            except json.JSONDecodeError:
+                pass
+
+        raise RuntimeError("Stream ended before completion of research task")
+
+    def get_task(self, id: str):  # noqa: D401 – imperative mood is fine
+        """Placeholder endpoint – not yet implemented on the server side."""
+        raise NotImplementedError(
+            "`exa.research.get_task` is not available yet. Please open an "
+            "issue if you need this sooner."
+        )
+
+
+class AsyncResearchClient:
+    """Async counterpart used via :pyattr:`AsyncExa.research`."""
+
+    def __init__(self, parent_client):
+        self._client = parent_client
+
+    async def create_task(
+        self,
+        *,
+        input_instructions: str,
+        output_schema: Dict[str, Any],
+    ) -> "ResearchTaskResponse":
+        """Async variant mirroring the synchronous implementation above."""
+
+        import json
+
+        payload = {
+            "input": {"instructions": input_instructions},
+            "output": {"schema": output_schema},
+        }
+
+        raw_response = await self._client.async_request(
+            "/research/tasks", payload, force_stream=True
+        )
+
+        async def _handle_payload_async(
+            tag: Optional[str], payload_dict: Dict[str, Any]
+        ):
+            if tag is None:
+                tag_local = payload_dict.get("tag")
+            else:
+                tag_local = tag
+
+            if tag_local == "progress":
+                return None
+            if tag_local == "error":
+                msg = payload_dict.get("error", {}).get("message", "Unknown error")
+                raise RuntimeError(f"Research task failed: {msg}")
+            if tag_local == "complete":
+                data_obj = payload_dict.get("data")
+                if data_obj is None:
+                    raise RuntimeError("Malformed 'complete' chunk with no data")
+                return _parse_research_response(data_obj)
+            if {"id", "status"}.issubset(payload_dict.keys()):
+                return _parse_research_response(payload_dict)
+            return None
+
+        event_name: Optional[str] = None
+        data_buf: str = ""
+
+        async for line in raw_response.aiter_lines():
+            if line == "":
+                if data_buf:
+                    try:
+                        payload_dict = json.loads(data_buf)
+                    except json.JSONDecodeError:
+                        data_buf = ""
+                        event_name = None
+                        continue
+                    maybe_resp = await _handle_payload_async(event_name, payload_dict)
+                    if maybe_resp is not None:
+                        await raw_response.aclose()
+                        return maybe_resp
+                data_buf = ""
+                event_name = None
+                continue
+
+            if line.startswith("event:"):
+                event_name = line[len("event:") :].strip()
+            elif line.startswith("data:"):
+                data_buf += line[len("data:") :].strip()
+
+        if data_buf:
+            try:
+                payload_dict = json.loads(data_buf)
+                maybe_resp = await _handle_payload_async(event_name, payload_dict)
+                if maybe_resp is not None:
+                    await raw_response.aclose()
+                    return maybe_resp
+            except json.JSONDecodeError:
+                pass
+
+        raise RuntimeError("Stream ended before completion of research task")
+
+    async def get_task(self, id: str):  # noqa: D401
+        raise NotImplementedError(
+            "`exa.research.get_task` is not available yet. Please open an "
+            "issue if you need this sooner."
+        )
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers (lazy imports to avoid cycles)
+# ---------------------------------------------------------------------------
+
+
+def _parse_research_response(raw: Dict[str, Any]):
+    """Transform camel-case API payload into rich Python objects."""
+    from .models import ResearchTaskResponse
+    from ..api import _Result, to_snake_case
+
+    return ResearchTaskResponse(
+        id=raw["id"],
+        status=raw["status"],
+        output=raw.get("output"),
+        citations={
+            key: [_Result(**to_snake_case(c)) for c in citations]
+            for key, citations in raw.get("citations", {}).items()
+        },
+    )

exa_py-1.12.3/exa_py/research/models.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+# Local import placed inside TYPE_CHECKING block to avoid runtime cycles.
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover – for static analysers only
+    from ..api import _Result  # noqa: F401
+
+
+@dataclass
+class ResearchTaskResponse:
+    """Structured response returned from the /research/tasks endpoint.
+
+    Attributes
+    ----------
+    id:
+        Unique identifier for the research task.
+    status:
+        Current task status
+    output:
+        JSON-serialisable answer generated by Exa (may be ``None`` until the task
+        completes).
+    citations:
+        Mapping from *root field* in the output schema to the list of search
+        results that were used to generate that part of the answer.
+    """
+
+    id: str
+    status: str
+    output: Optional[Dict[str, Any]]
+    citations: Dict[str, List["_Result"]]
+
+    # ---------------------------------------------------------------------
+    # Pretty representation helpers
+    # ---------------------------------------------------------------------
+    def __str__(self) -> str:  # pragma: no cover – convenience only
+        output_repr = (
+            json.dumps(self.output, indent=2, ensure_ascii=False)
+            if self.output is not None
+            else "None"
+        )
+        citations_str = "\n\n".join(str(src) for src in self.citations)
+        return (
+            f"ID: {self.id}\n"
+            f"Status: {self.status}\n"
+            f"Output: {output_repr}\n\n"
+            f"Citations:\n{citations_str}"
+        )
+
+
+__all__ = [
+    "ResearchTaskResponse",
+]

{exa_py-1.12.0 → exa_py-1.12.3}/exa_py/websets/types.py

@@ -18,14 +18,14 @@ class CanceledReason(Enum):
 
 
 class CreateCriterionParameters(ExaBaseModel):
-    description: constr(min_length=1, max_length=300)
+    description: constr(min_length=1)
     """
     The description of the criterion
     """
 
 
 class CreateEnrichmentParameters(ExaBaseModel):
-    description: constr(min_length=1, max_length=5000)
+    description: constr(min_length=1)
     """
     Provide a description of the enrichment task you want to perform to each Webset Item.
     """
@@ -88,7 +88,7 @@ class CreateWebsetSearchParameters(ExaBaseModel):
 
     The actual number of Items found may be less than this number depending on the query complexity.
     """
-    query: constr(min_length=1, max_length=5000) = Field(
+    query: constr(min_length=1) = Field(
         ...,
         examples=[
             'Marketing agencies based in the US, that focus on consumer products. Get brands worked with and city'
@@ -136,7 +136,7 @@ class CreateWebsetSearchParameters(ExaBaseModel):
 
 
 class Criterion(ExaBaseModel):
-    description: constr(min_length=1, max_length=300)
+    description: constr(min_length=1)
     """
     The description of the criterion
     """
@@ -338,7 +338,7 @@ class Search(ExaBaseModel):
     Create initial search for the Webset.
     """
 
-    query: constr(min_length=1, max_length=5000) = Field(
+    query: constr(min_length=1) = Field(
         ...,
         examples=[
             'Marketing agencies based in the US, that focus on consumer products.'
@@ -405,7 +405,7 @@ class UpdateWebhookParameters(ExaBaseModel):
 
 
 class UpdateWebsetRequest(ExaBaseModel):
-    metadata: Optional[Dict[str, constr(max_length=1000)]] = None
+    metadata: Optional[Dict[str, str]] = None
     """
     Set of key-value pairs you want to associate with this object.
     """
@@ -564,7 +564,7 @@ class WebsetCreatedEvent(ExaBaseModel):
 
 class WebsetCustomEntity(ExaBaseModel):
     type: Literal['custom']
-    description: constr(min_length=2, max_length=200)
+    description: constr(min_length=2)
     """
     When you decide to use a custom entity, this is the description of the entity.
 
@@ -972,7 +972,7 @@ class WebsetSearch(ExaBaseModel):
     """
     The status of the search
     """
-    query: constr(min_length=1, max_length=5000)
+    query: constr(min_length=1)
     """
     The query used to create the search.
     """

{exa_py-1.12.0 → exa_py-1.12.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "exa-py"
-version = "1.12.0"
+version = "1.13.0"
 description = "Python SDK for Exa API."
 authors = ["Exa AI <hello@exa.ai>"]
 readme = "README.md"
@@ -32,14 +32,12 @@ in-project = true
 
 [project]
 name = "exa-py"
-version = "1.12.0"
+version = "1.12.3"
 description = "Python SDK for Exa API."
 readme = "README.md"
 requires-python = ">=3.9"
-license = {text = "MIT"}
-authors = [
-    {name = "Exa AI", email = "hello@exa.ai"}
-]
+license = { text = "MIT" }
+authors = [{ name = "Exa AI", email = "hello@exa.ai" }]
 dependencies = [
     "requests>=2.32.3",
     "typing-extensions>=4.12.2",