exa-py 1.14.20__py3-none-any.whl → 1.15.1__py3-none-any.whl

exa_py/websets/types.py

@@ -243,11 +243,15 @@ class EventType(Enum):
     webset_search_updated = 'webset.search.updated'
     import_created = 'import.created'
     import_completed = 'import.completed'
-    import_processing = 'import.processing'
-    webset_export_created = 'webset.export.created'
-    webset_export_completed = 'webset.export.completed'
     webset_item_created = 'webset.item.created'
     webset_item_enriched = 'webset.item.enriched'
+    monitor_created = 'monitor.created'
+    monitor_updated = 'monitor.updated'
+    monitor_deleted = 'monitor.deleted'
+    monitor_run_created = 'monitor.run.created'
+    monitor_run_completed = 'monitor.run.completed'
+    webset_export_created = 'webset.export.created'
+    webset_export_completed = 'webset.export.completed'
 
 
 class Format(Enum):
@@ -263,6 +267,7 @@ class Format(Enum):
     options = 'options'
     email = 'email'
     phone = 'phone'
+    url = 'url'
 
 
 class ImportFormat(Enum):
@@ -333,6 +338,13 @@ class ListEventsResponse(ExaBaseModel):
           WebsetSearchUpdatedEvent,
           WebsetSearchCanceledEvent,
           WebsetSearchCompletedEvent,
+          ImportCreatedEvent,
+          ImportCompletedEvent,
+          MonitorCreatedEvent,
+          MonitorUpdatedEvent,
+          MonitorDeletedEvent,
+          MonitorRunCreatedEvent,
+          MonitorRunCompletedEvent,
       ],
       Field(discriminator='type')
   ]]
@@ -802,6 +814,30 @@ class UpdateImport(ExaBaseModel):
     """
 
 
+class UpdateEnrichmentParameters(ExaBaseModel):
+    """
+    Parameters for updating an enrichment.
+    """
+    description: Optional[str] = None
+    """
+    Provide a description of the enrichment task you want to perform to each Webset Item.
+    """
+    format: Optional[Format] = None
+    """
+    Format of the enrichment response.
+
+    We automatically select the best format based on the description. If you want to explicitly specify the format, you can do so here.
+    """
+    options: Optional[List[Option]] = None
+    """
+    When the format is options, the different options for the enrichment agent to choose from.
+    """
+    metadata: Optional[Dict[str, Any]] = None
+    """
+    Set of key-value pairs you want to associate with this object.
+    """
+
+
 class Option(ExaBaseModel):
     label: str
     """
@@ -1336,6 +1372,7 @@ class WebsetEnrichmentFormat(Enum):
     options = 'options'
     email = 'email'
     phone = 'phone'
+    url = 'url'
 
 
 class WebsetEnrichmentOption(Option):
@@ -1873,6 +1910,104 @@ class WebsetSearchUpdatedEvent(ExaBaseModel):
     """
 
 
+class ImportCreatedEvent(ExaBaseModel):
+    id: str
+    """
+    The unique identifier for the event
+    """
+    object: Literal['event']
+    type: Literal['import.created']
+    data: Import
+    created_at: datetime = Field(..., alias='createdAt')
+    """
+    The date and time the event was created
+    """
+
+
+class ImportCompletedEvent(ExaBaseModel):
+    id: str
+    """
+    The unique identifier for the event
+    """
+    object: Literal['event']
+    type: Literal['import.completed']
+    data: Import
+    created_at: datetime = Field(..., alias='createdAt')
+    """
+    The date and time the event was created
+    """
+
+
+class MonitorCreatedEvent(ExaBaseModel):
+    id: str
+    """
+    The unique identifier for the event
+    """
+    object: Literal['event']
+    type: Literal['monitor.created']
+    data: Monitor
+    created_at: datetime = Field(..., alias='createdAt')
+    """
+    The date and time the event was created
+    """
+
+
+class MonitorUpdatedEvent(ExaBaseModel):
+    id: str
+    """
+    The unique identifier for the event
+    """
+    object: Literal['event']
+    type: Literal['monitor.updated']
+    data: Monitor
+    created_at: datetime = Field(..., alias='createdAt')
+    """
+    The date and time the event was created
+    """
+
+
+class MonitorDeletedEvent(ExaBaseModel):
+    id: str
+    """
+    The unique identifier for the event
+    """
+    object: Literal['event']
+    type: Literal['monitor.deleted']
+    data: Monitor
+    created_at: datetime = Field(..., alias='createdAt')
+    """
+    The date and time the event was created
+    """
+
+
+class MonitorRunCreatedEvent(ExaBaseModel):
+    id: str
+    """
+    The unique identifier for the event
+    """
+    object: Literal['event']
+    type: Literal['monitor.run.created']
+    data: MonitorRun
+    created_at: datetime = Field(..., alias='createdAt')
+    """
+    The date and time the event was created
+    """
+
+
+class MonitorRunCompletedEvent(ExaBaseModel):
+    id: str
+    """
+    The unique identifier for the event
+    """
+    object: Literal['event']
+    type: Literal['monitor.run.completed']
+    data: MonitorRun
+    created_at: datetime = Field(..., alias='createdAt')
+    """
+    The date and time the event was created
+    """
+
+
 class WebsetStatus(Enum):
     """
     The status of the webset

{exa_py-1.14.20.dist-info → exa_py-1.15.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exa-py
-Version: 1.14.20
+Version: 1.15.1
 Summary: Python SDK for Exa API.
 License: MIT
 Author: Exa AI

{exa_py-1.14.20.dist-info → exa_py-1.15.1.dist-info}/RECORD

@@ -1,19 +1,22 @@
 exa_py/__init__.py,sha256=M2GC9oSdoV6m2msboW0vMWWl8wrth4o6gmEV4MYLGG8,66
-exa_py/api.py,sha256=TIGTu4ITw7SrhTZjx9uQNpwi1u3nDpjtYUNXQrgg5bo,107356
+exa_py/api.py,sha256=gUvQ2NXtUgBlrFrWrCIUwiq-z2lAlo_gWVFncN68Vhw,108947
 exa_py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-exa_py/research/__init__.py,sha256=QeY-j6bP4QP5tF9ytX0IeQhJvd0Wn4cJCD69U8pP7kA,271
-exa_py/research/client.py,sha256=mnoTA4Qoa0TA5d8nVTR9tAU9LJElXV-MlPozgMxlUp4,12799
-exa_py/research/models.py,sha256=j7YgRoMRp2MLgnaij7775x_hJEeV5gksKpfLwmawqxY,3704
-exa_py/utils.py,sha256=eYnJRAFJonwKP_mCxzAB9TnLEqoF-88stg6wh-M-Ups,6424
+exa_py/research/__init__.py,sha256=qbWY5c3LYBM7L4yGVtiMs9nUg_kMcAVhMhT0DvN6EI4,1014
+exa_py/research/async_client.py,sha256=jP6BF8nc29Mt4iU2ZEQGAC5dGM-Z9I4k3pzpPcCKJIs,9436
+exa_py/research/base.py,sha256=0C52XGUMRwRox1JSVBrbiHZxqPI6Cgif7EFNqYxpc40,5451
+exa_py/research/models.py,sha256=2gu4jckbLYHlTmln8BhDzovuqg1fejTCncqi4r0oDow,9822
+exa_py/research/sync_client.py,sha256=LHMkgqUZgKCQWgLP41Fj6EWLbt_YfX4aAgvWGjNgbXM,9155
+exa_py/research/utils.py,sha256=YR61UkReyK-LrvOTaX_aG_neS1DsmCkv7B6YODpwHvU,5965
+exa_py/utils.py,sha256=1jwKwcJwHSbrzwgMkprXSEZ-xssCtXxwf-GTRgaFmz8,6395
 exa_py/websets/__init__.py,sha256=x7Dc0MS8raRXA7Ud6alKgnsUmLi6X9GTqfB8kOwC9iQ,179
 exa_py/websets/_generator/pydantic/BaseModel.jinja2,sha256=RUDCmPZVamoVx1WudylscYFfDhGoNNtRYlpTvKjAiuA,1276
 exa_py/websets/client.py,sha256=sKkji8QaPFnGM1-J5TB6yKJcGAEd6gk7lsnIebzXNQ8,5856
 exa_py/websets/core/__init__.py,sha256=xOyrFaqtBocMUu321Jpbk7IzIQRNZufSIGJXrKoG-Bg,323
 exa_py/websets/core/base.py,sha256=RldWYwBg2iVfkWmdPke7xjXdwb4JKeABIOgiZtqvz-4,4125
 exa_py/websets/enrichments/__init__.py,sha256=5dJIEKKceUost3RnI6PpCSB3VjUCBzxseEsIXu-ZY-Y,83
-exa_py/websets/enrichments/client.py,sha256=obUjn4vH6tKBMtHEBVdMzlN8in0Fx3sCP-bXx-Le1zM,2338
+exa_py/websets/enrichments/client.py,sha256=Qn6B19Gf1z4pQ5CCeXMFeTJnVi2OiVx9Ck5XlcQBZVI,2999
 exa_py/websets/events/__init__.py,sha256=aFJ9O5UudtQQzndVmdB96IaM2l07qyM1B_8xKY7rp58,60
-exa_py/websets/events/client.py,sha256=Hzatqp3X-K0ZGe36cjFMgbhnsErcDLdGWQVirhmHjvY,3622
+exa_py/websets/events/client.py,sha256=-7sQ61P0SdHj-LuYq6G0u9a_IrtmcCljyDCzZPf330U,4370
 exa_py/websets/imports/__init__.py,sha256=iEl-fZZSdcvKaqLgjMES_0RwYn7hZDCMf6BZriCrjgw,64
 exa_py/websets/imports/client.py,sha256=nJs46hxlSkZm7qjboYHNBuJ62gLmA_Yzr9fc-NDky0Y,6795
 exa_py/websets/items/__init__.py,sha256=DCWZJVtRmUjnMEkKdb5gW1LT9cHcb-J8lENMnyyBeKU,71
@@ -24,9 +27,9 @@ exa_py/websets/monitors/runs/__init__.py,sha256=TmcETf3zdQouA_vAeLiosCNL1MYJnZ0y
 exa_py/websets/monitors/runs/client.py,sha256=WnwcWCf7UKk68VCNUp8mRXBtlU8vglTSX-eoWVXzKIw,1229
 exa_py/websets/searches/__init__.py,sha256=_0Zx8ES5fFTEL3T8mhLxq_xK2t0JONx6ad6AtbvClsE,77
 exa_py/websets/searches/client.py,sha256=X3f7axWGfecmxf-2tBTX0Yf_--xToz1X8ZHbbudEzy0,1790
-exa_py/websets/types.py,sha256=DxO_T4Ijnd06gxFAX3f238Mt5P0_ulpY44M1kiT4y4U,47120
+exa_py/websets/types.py,sha256=iDZqvt22hjhkU8_AIczQ9iHexUw9C4PHh7C66ujfhk4,50523
 exa_py/websets/webhooks/__init__.py,sha256=iTPBCxFd73z4RifLQMX6iRECx_6pwlI5qscLNjMOUHE,77
 exa_py/websets/webhooks/client.py,sha256=zS1eoWKliuiY4AIeFJdpAlPZeOINyphn7KEWANF-zaE,4384
-exa_py-1.14.20.dist-info/METADATA,sha256=tkmcVljW6I0gOgd6uLMTkMXLnmJLQOSVJmeoxLW3tQw,3827
-exa_py-1.14.20.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-exa_py-1.14.20.dist-info/RECORD,,
+exa_py-1.15.1.dist-info/METADATA,sha256=6MtMgPdsfzWgOKeQtywu4aZASbZjYpetbiirn17CzjE,3826
+exa_py-1.15.1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+exa_py-1.15.1.dist-info/RECORD,,

exa_py/research/client.py

@@ -1,358 +0,0 @@
-"""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, Literal
-
-from exa_py.utils import JSONSchemaInput
-from ..api import _convert_schema_input
-
-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 .models import (
-        ResearchTask,
-        ResearchTaskId,
-        ListResearchTasksResponse,
-    )  # 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
-
-    def create_task(
-        self,
-        *,
-        instructions: str,
-        model: Literal["exa-research", "exa-research-pro"] = "exa-research",
-        output_infer_schema: bool = None,
-        output_schema: "Optional[JSONSchemaInput]" = None,
-    ) -> "ResearchTaskId":
-        """Submit a research request and return the *task identifier*."""
-        payload = {"instructions": instructions}
-        if model is not None:
-            payload["model"] = model
-        if output_schema is not None or output_infer_schema is not None:
-            payload["output"] = {}
-            if output_schema is not None:
-                payload["output"]["schema"] = _convert_schema_input(output_schema)
-            if output_infer_schema is not None:
-                payload["output"]["inferSchema"] = output_infer_schema
-
-        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:
-            raise RuntimeError(
-                f"Unexpected response while creating research task: {raw_response}"
-            )
-
-        # Lazily import to avoid circular deps at runtime.
-        from .models import ResearchTaskId  # noqa: WPS433 – runtime import
-
-        return ResearchTaskId(id=raw_response["id"])
-
-    def get_task(self, id: str) -> "ResearchTask":  # noqa: D401 – imperative mood is fine
-        """Fetch the current status / result for a research task."""
-        endpoint = f"/research/v0/tasks/{id}"
-
-        # The new endpoint is a simple GET.
-        raw_response: Dict[str, Any] = self._client.request(endpoint, method="GET")
-
-        return _build_research_task(raw_response)
-
-    # ------------------------------------------------------------------
-    # Convenience helpers
-    # ------------------------------------------------------------------
-
-    def poll_task(
-        self,
-        id: str,
-        *,
-        poll_interval: float = 1.0,
-        timeout_seconds: int = 15 * 60,
-    ) -> "ResearchTask":
-        """Blocking helper that polls until task completes or fails.
-
-        Parameters
-        ----------
-        id:
-            The ID of the research task to poll.
-        poll_interval:
-            Seconds to wait between successive polls (default 1s).
-        timeout_seconds:
-            Maximum time to wait before raising :class:`TimeoutError` (default 15 min).
-        """
-
-        import time
-
-        deadline = time.monotonic() + timeout_seconds
-
-        while True:
-            task = self.get_task(id)
-            status = task.status.lower() if isinstance(task.status, str) else ""
-
-            if status in {"completed", "failed", "complete", "finished", "done"}:
-                return task
-
-            if time.monotonic() > deadline:
-                raise TimeoutError(
-                    f"Research task {id} did not finish within {timeout_seconds} seconds"
-                )
-
-            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`."""
-
-    def __init__(self, parent_client):
-        self._client = parent_client
-
-    async def create_task(
-        self,
-        *,
-        instructions: str,
-        model: Literal["exa-research", "exa-research-pro"] = "exa-research",
-        output_schema: "JSONSchemaInput",
-    ) -> "ResearchTaskId":
-        """Submit a research request and return the *task identifier* (async)."""
-
-        # Convert schema using the same conversion logic as main API
-        from ..api import _convert_schema_input  # noqa: WPS433 – runtime import
-
-        payload = {
-            "instructions": instructions,
-            "model": model,
-            "output": {"schema": _convert_schema_input(output_schema)},
-        }
-
-        raw_response: Dict[str, Any] = await self._client.async_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:
-            raise RuntimeError(
-                f"Unexpected response while creating research task: {raw_response}"
-            )
-
-        # Lazily import to avoid circular deps at runtime.
-        from .models import ResearchTaskId  # noqa: WPS433 – runtime import
-
-        return ResearchTaskId(id=raw_response["id"])
-
-    async def get_task(self, id: str) -> "ResearchTask":  # noqa: D401
-        """Fetch the current status / result for a research task (async)."""
-
-        endpoint = f"/research/v0/tasks/{id}"
-
-        # Perform GET using the underlying HTTP client because `async_request`
-        # only supports POST semantics.
-        resp = await self._client.client.get(
-            self._client.base_url + endpoint, headers=self._client.headers
-        )
-
-        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()
-
-        return _build_research_task(raw_response)
-
-    # ------------------------------------------------------------------
-    # Convenience helpers
-    # ------------------------------------------------------------------
-
-    async def poll_task(
-        self,
-        id: str,
-        *,
-        poll_interval: float = 1.0,
-        timeout_seconds: int = 15 * 60,
-    ) -> "ResearchTask":
-        """Async helper that polls until task completes or fails.
-
-        Mirrors :py:meth:`ResearchClient.poll_task` but uses ``await`` and
-        :pyfunc:`asyncio.sleep`.  Raises :class:`TimeoutError` on timeout.
-        """
-
-        import asyncio
-        import time
-
-        deadline = time.monotonic() + timeout_seconds
-
-        while True:
-            task = await self.get_task(id)
-            status = task.status.lower() if isinstance(task.status, str) else ""
-
-            if status in {"completed", "failed", "complete", "finished", "done"}:
-                return task
-
-            if time.monotonic() > deadline:
-                raise TimeoutError(
-                    f"Research task {id} did not finish within {timeout_seconds} seconds"
-                )
-
-            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)
-# ---------------------------------------------------------------------------
-
-
-def _build_research_task(raw: Dict[str, Any]):
-    """Convert raw API response into a :class:`ResearchTask` instance."""
-
-    # Defensive check – fail loudly if the API contract changes.
-    if not isinstance(raw, dict) or "id" not in raw:
-        raise RuntimeError(f"Unexpected response while fetching research task: {raw}")
-
-    # Lazily import heavy deps to avoid cycles and unnecessary startup cost.
-    from .models import ResearchTask  # noqa: WPS433 – runtime import
-    from ..api import _Result, to_snake_case  # noqa: WPS433 – runtime import
-
-    citations_raw = raw.get("citations", {}) or {}
-    citations_parsed = {}
-    for key, cites in citations_raw.items():
-        results = []
-        for c in cites:
-            snake_c = to_snake_case(c)
-            results.append(
-                _Result(
-                    url=snake_c.get("url"),
-                    id=snake_c.get("id"),
-                    title=snake_c.get("title"),
-                    score=snake_c.get("score"),
-                    published_date=snake_c.get("published_date"),
-                    author=snake_c.get("author"),
-                    image=snake_c.get("image"),
-                    favicon=snake_c.get("favicon"),
-                    subpages=snake_c.get("subpages"),
-                    extras=snake_c.get("extras"),
-                )
-            )
-        citations_parsed[key] = results
-
-    return ResearchTask(
-        id=raw["id"],
-        status=raw["status"],
-        instructions=raw.get("instructions", ""),
-        schema=raw.get("schema", {}),
-        data=raw.get("data"),
-        citations=citations_parsed,
-    )