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

exa_py/api.py

@@ -1965,7 +1965,7 @@ class AsyncExa(Exa):
         res = await self.client.post(
             self.base_url + endpoint, json=data, headers=self.headers
         )
-        if res.status_code != 200:
+        if res.status_code != 200 and res.status_code != 201:
             raise ValueError(
                 f"Request failed with status code {res.status_code}: {res.text}"
             )

exa_py/research/__init__.py

@@ -1,9 +1,10 @@
 from .client import ResearchClient, AsyncResearchClient
-from .models import ResearchTask
+from .models import ResearchTask, ListResearchTasksResponse, ResearchTaskId
 
 __all__ = [
     "ResearchClient",
     "AsyncResearchClient",
     "ResearchTaskId",
     "ResearchTask",
+    "ListResearchTasksResponse",
 ]

exa_py/research/client.py

@@ -9,14 +9,18 @@ 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
+from typing import TYPE_CHECKING, Any, Dict, Optional
 
 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 ResearchTask, ResearchTaskId  # noqa: F401
+    from .models import (
+        ResearchTask,
+        ResearchTaskId,
+        ListResearchTasksResponse,
+    )  # noqa: F401
 
 # ---------------------------------------------------------------------------
 # Public, user-facing clients
@@ -34,16 +38,20 @@ class ResearchClient:
     def create_task(
         self,
         *,
-        input_instructions: str,
+        instructions: str,
+        model: str = "exa-research",
         output_schema: Dict[str, Any],
     ) -> "ResearchTaskId":
         """Submit a research request and return the *task identifier*."""
         payload = {
-            "input": {"instructions": input_instructions},
+            "instructions": instructions,
+            "model": model,
             "output": {"schema": output_schema},
         }
 
-        raw_response: Dict[str, Any] = self._client.request("/research/tasks", payload)
+        raw_response: Dict[str, Any] = self._client.request(
+            "/research/v0/tasks", payload
+        )
 
         # Defensive checks so that we fail loudly if the contract changes.
         if not isinstance(raw_response, dict) or "id" not in raw_response:
@@ -60,7 +68,7 @@ class ResearchClient:
         self, id: str
     ) -> "ResearchTask":  # noqa: D401 – imperative mood is fine
         """Fetch the current status / result for a research task."""
-        endpoint = f"/research/tasks/{id}"
+        endpoint = f"/research/v0/tasks/{id}"
 
         # The new endpoint is a simple GET.
         raw_response: Dict[str, Any] = self._client.request(endpoint, method="GET")
@@ -108,6 +116,54 @@ class ResearchClient:
 
             time.sleep(poll_interval)
 
+    # ------------------------------------------------------------------
+    # Listing helpers
+    # ------------------------------------------------------------------
+
+    def list(
+        self,
+        *,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> "ListResearchTasksResponse":
+        """List research tasks with optional pagination.
+
+        Parameters
+        ----------
+        cursor:
+            Pagination cursor returned by a previous call (optional).
+        limit:
+            Maximum number of tasks to return (optional).
+        """
+
+        params = {
+            k: v for k, v in {"cursor": cursor, "limit": limit}.items() if v is not None
+        }
+
+        raw_response: Dict[str, Any] = self._client.request(
+            "/research/v0/tasks",
+            data=None,
+            method="GET",
+            params=params or None,
+        )
+
+        # Defensive checks so that we fail loudly if the contract changes.
+        if not isinstance(raw_response, dict) or "data" not in raw_response:
+            raise RuntimeError(
+                f"Unexpected response while listing research tasks: {raw_response}"
+            )
+
+        tasks = [_build_research_task(t) for t in raw_response.get("data", [])]
+
+        # Lazy import to avoid cycles.
+        from .models import ListResearchTasksResponse  # noqa: WPS433 – runtime import
+
+        return ListResearchTasksResponse(
+            data=tasks,
+            has_more=raw_response.get("hasMore", False),
+            next_cursor=raw_response.get("nextCursor"),
+        )
+
 
 class AsyncResearchClient:
     """Async counterpart used via :pyattr:`AsyncExa.research`."""
@@ -118,18 +174,20 @@ class AsyncResearchClient:
     async def create_task(
         self,
         *,
-        input_instructions: str,
+        instructions: str,
+        model: str = "exa-research",
         output_schema: Dict[str, Any],
     ) -> "ResearchTaskId":
         """Submit a research request and return the *task identifier* (async)."""
 
         payload = {
-            "input": {"instructions": input_instructions},
+            "instructions": instructions,
+            "model": model,
             "output": {"schema": output_schema},
         }
 
         raw_response: Dict[str, Any] = await self._client.async_request(
-            "/research/tasks", payload
+            "/research/v0/tasks", payload
         )
 
         # Defensive checks so that we fail loudly if the contract changes.
@@ -146,7 +204,7 @@ class AsyncResearchClient:
     async def get_task(self, id: str) -> "ResearchTask":  # noqa: D401
         """Fetch the current status / result for a research task (async)."""
 
-        endpoint = f"/research/tasks/{id}"
+        endpoint = f"/research/v0/tasks/{id}"
 
         # Perform GET using the underlying HTTP client because `async_request`
         # only supports POST semantics.
@@ -199,6 +257,50 @@ class AsyncResearchClient:
 
             await asyncio.sleep(poll_interval)
 
+    # ------------------------------------------------------------------
+    # Listing helpers
+    # ------------------------------------------------------------------
+
+    async def list(
+        self,
+        *,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> "ListResearchTasksResponse":
+        """Async list of research tasks with optional pagination."""
+
+        params = {
+            k: v for k, v in {"cursor": cursor, "limit": limit}.items() if v is not None
+        }
+
+        resp = await self._client.client.get(
+            self._client.base_url + "/research/v0/tasks",
+            headers=self._client.headers,
+            params=params or None,
+        )
+
+        if resp.status_code >= 400:
+            raise RuntimeError(
+                f"Request failed with status code {resp.status_code}: {resp.text}"
+            )
+
+        raw_response: Dict[str, Any] = resp.json()
+
+        if not isinstance(raw_response, dict) or "data" not in raw_response:
+            raise RuntimeError(
+                f"Unexpected response while listing research tasks: {raw_response}"
+            )
+
+        tasks = [_build_research_task(t) for t in raw_response.get("data", [])]
+
+        from .models import ListResearchTasksResponse  # noqa: WPS433 – runtime import
+
+        return ListResearchTasksResponse(
+            data=tasks,
+            has_more=raw_response.get("hasMore", False),
+            next_cursor=raw_response.get("nextCursor"),
+        )
+
 
 # ---------------------------------------------------------------------------
 # Internal helpers (lazy imports to avoid cycles)

exa_py/research/models.py

@@ -92,7 +92,29 @@ class ResearchTask:
         )
 
 
+@dataclass
+class ListResearchTasksResponse:
+    """Paginated list of research tasks."""
+
+    data: List[ResearchTask]
+    has_more: bool
+    next_cursor: Optional[str]
+
+    # -----------------------------------------------------------------
+    # Pretty representation helpers
+    # -----------------------------------------------------------------
+    def __str__(self) -> str:  # pragma: no cover – convenience only
+        tasks_repr = "\n\n".join(str(task) for task in self.data)
+        cursor_repr = self.next_cursor or "None"
+        return (
+            f"Tasks:\n{tasks_repr}\n\n"
+            f"Has more: {self.has_more}\n"
+            f"Next cursor: {cursor_repr}"
+        )
+
+
 __all__ = [
     "ResearchTaskId",
     "ResearchTask",
+    "ListResearchTasksResponse",
 ]

{exa_py-1.13.2.dist-info → exa_py-1.14.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exa-py
-Version: 1.13.2
+Version: 1.14.0
 Summary: Python SDK for Exa API.
 License: MIT
 Author: Exa AI
@@ -126,7 +126,8 @@ exa = Exa(api_key="your-api-key")
       },
   }
   resp = exa.research.create_task(
-      input_instructions=QUESTION,
+      instructions=QUESTION,
+      model="exa-research",
       output_schema=OUTPUT_SCHEMA,
   )
 ```

{exa_py-1.13.2.dist-info → exa_py-1.14.0.dist-info}/RECORD

@@ -1,9 +1,9 @@
 exa_py/__init__.py,sha256=M2GC9oSdoV6m2msboW0vMWWl8wrth4o6gmEV4MYLGG8,66
-exa_py/api.py,sha256=Bn7h_eRvXmwBUmJi2B2JpHAQPrHfbwKf0A-XVXLjqa0,84876
+exa_py/api.py,sha256=zwTEiIkWa6Gynx5NW9VMMY4Nws63gVDRSmzKdT4v2aY,84903
 exa_py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-exa_py/research/__init__.py,sha256=D1xgm4VlbWtRb1cMgshcW4dIyR7IXhOW2s7ihxcE1Jc,195
-exa_py/research/client.py,sha256=Zno5xblfwhX8gWgc4OvI24a-ZS7_g1b32_tr6j7C7Jg,8217
-exa_py/research/models.py,sha256=WXTnALhM9FcVQ95Tzzc5EDKU48hyPhu8RSMmipqCjOk,2982
+exa_py/research/__init__.py,sha256=QeY-j6bP4QP5tF9ytX0IeQhJvd0Wn4cJCD69U8pP7kA,271
+exa_py/research/client.py,sha256=oFQpczMcfA20Sn_yq36As8GlFo2u8B77IqVMMRqt3qE,11481
+exa_py/research/models.py,sha256=j7YgRoMRp2MLgnaij7775x_hJEeV5gksKpfLwmawqxY,3704
 exa_py/utils.py,sha256=Rc1FJjoR9LQ7L_OJM91Sd1GNkbHjcLyEvJENhRix6gc,2405
 exa_py/websets/__init__.py,sha256=uOBAb9VrIHrPKoddGOp2ai2KgWlyUVCLMZqfbGOlboA,70
 exa_py/websets/_generator/pydantic/BaseModel.jinja2,sha256=RUDCmPZVamoVx1WudylscYFfDhGoNNtRYlpTvKjAiuA,1276
@@ -23,6 +23,6 @@ exa_py/websets/streams/runs/client.py,sha256=ja63-G0Y74YDgsWq30aoa0llIx8I9mIwbCb
 exa_py/websets/types.py,sha256=-KmC6N9LMh5fPhhXZslmUyQcSmBqIdPF-qQ27qS4GEw,34756
 exa_py/websets/webhooks/__init__.py,sha256=iTPBCxFd73z4RifLQMX6iRECx_6pwlI5qscLNjMOUHE,77
 exa_py/websets/webhooks/client.py,sha256=zsIRMTeJU65yj-zo7Zz-gG02Prtzgcx6utGFSoY4HQQ,4222
-exa_py-1.13.2.dist-info/METADATA,sha256=kvXQv5_-4BJ0uIYLfZ-c9aJOfqE_0STUZ3oM-GX2Jfs,4098
-exa_py-1.13.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-exa_py-1.13.2.dist-info/RECORD,,
+exa_py-1.14.0.dist-info/METADATA,sha256=jOIKH214iEOdk7HE46-tyhST5d9iGvgCaaff12tPxiY,4120
+exa_py-1.14.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+exa_py-1.14.0.dist-info/RECORD,,