telem-sdk 0.2.0__tar.gz → 0.2.2__tar.gz

{telem_sdk-0.2.0 → telem_sdk-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: telem-sdk
-Version: 0.2.0
+Version: 0.2.2
 Summary: Python SDK for the Telem search orchestration API.
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -176,7 +176,7 @@ A monitor runs a query on a schedule. Poll it to get the results that are new si
 your last poll. `poll` returns a `SearchResponse`:
 
 ```python
-monitor = client.monitors.create("Nvidia files a new 8-K with the SEC", frequency="1h")
+monitor = client.monitors.create("Nvidia files a new 8-K with the SEC", frequency="1h", ttl="7d")
 response = client.monitors.poll(monitor.id)
 client.monitors.update(monitor.id, status="paused")
 client.monitors.delete(monitor.id)

{telem_sdk-0.2.0 → telem_sdk-0.2.2}/README.md

@@ -156,7 +156,7 @@ A monitor runs a query on a schedule. Poll it to get the results that are new si
 your last poll. `poll` returns a `SearchResponse`:
 
 ```python
-monitor = client.monitors.create("Nvidia files a new 8-K with the SEC", frequency="1h")
+monitor = client.monitors.create("Nvidia files a new 8-K with the SEC", frequency="1h", ttl="7d")
 response = client.monitors.poll(monitor.id)
 client.monitors.update(monitor.id, status="paused")
 client.monitors.delete(monitor.id)

{telem_sdk-0.2.0 → telem_sdk-0.2.2}/telem/_base.py

@@ -167,6 +167,7 @@ class BaseClient:
         topic: str | None = None,
         published_after: str | date | None = None,
         published_before: str | date | None = None,
+        include_domains: list[str] | None = None,
     ) -> dict[str, Any]:
         """Resolve call arguments against the client defaults into the wire ``search`` block.
 
@@ -250,6 +251,8 @@ class BaseClient:
             block["published_after"] = _iso(published_after)
         if published_before is not None:
             block["published_before"] = _iso(published_before)
+        if include_domains is not None:
+            block["include_domains"] = include_domains
         return block
 
     def _search_body(
@@ -269,6 +272,7 @@ class BaseClient:
         topic: str | None = None,
         published_after: str | date | None = None,
         published_before: str | date | None = None,
+        include_domains: list[str] | None = None,
         goal: str | None = None,
         context: str | None = None,
         session: str | None = None,
@@ -332,6 +336,7 @@ class BaseClient:
             topic=topic,
             published_after=published_after,
             published_before=published_before,
+            include_domains=include_domains,
         )
         if search:
             body["search"] = search

{telem_sdk-0.2.0 → telem_sdk-0.2.2}/telem/_version.py

@@ -13,4 +13,4 @@ one-line change; if you are editing a version string anywhere else, something ha
 regressed back to the shape that caused that.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{telem_sdk-0.2.0 → telem_sdk-0.2.2}/telem/async_client.py

@@ -122,6 +122,7 @@ class AsyncTelem(BaseClient):
         topic: str | None = None,
         published_after: str | date | None = None,
         published_before: str | date | None = None,
+        include_domains: list[str] | None = None,
         goal: str | None = None,
         context: str | None = None,
         session: str | None = None,
@@ -157,6 +158,9 @@ class AsyncTelem(BaseClient):
                 with no known publication date are kept.
             published_before: Only return results published before this date or
                 date-time. A date with no time includes that whole day.
+            include_domains: Only return results from these domains, at most 20
+                hostnames such as ``"linkedin.com"``. A subdomain such as
+                ``"uk.linkedin.com"`` matches its domain.
             goal: Optional agent goal, merged into request metadata.
             context: Optional context string, merged into request metadata.
             session: Optional session id to continue an existing session.
@@ -180,6 +184,7 @@ class AsyncTelem(BaseClient):
             topic=topic,
             published_after=published_after,
             published_before=published_before,
+            include_domains=include_domains,
             goal=goal,
             context=context,
             session=session,

{telem_sdk-0.2.0 → telem_sdk-0.2.2}/telem/client.py

@@ -122,6 +122,7 @@ class Telem(BaseClient):
         topic: str | None = None,
         published_after: str | date | None = None,
         published_before: str | date | None = None,
+        include_domains: list[str] | None = None,
         goal: str | None = None,
         context: str | None = None,
         session: str | None = None,
@@ -157,6 +158,9 @@ class Telem(BaseClient):
                 with no known publication date are kept.
             published_before: Only return results published before this date or
                 date-time. A date with no time includes that whole day.
+            include_domains: Only return results from these domains, at most 20
+                hostnames such as ``"linkedin.com"``. A subdomain such as
+                ``"uk.linkedin.com"`` matches its domain.
             goal: Optional agent goal, merged into request metadata.
             context: Optional context string, merged into request metadata.
             session: Optional session id to continue an existing session.
@@ -180,6 +184,7 @@ class Telem(BaseClient):
             topic=topic,
             published_after=published_after,
             published_before=published_before,
+            include_domains=include_domains,
             goal=goal,
             context=context,
             session=session,

{telem_sdk-0.2.0 → telem_sdk-0.2.2}/telem/models.py

@@ -186,6 +186,8 @@ class Monitor(BaseModel):
     session_id: str
     created_at: str
     last_polled_at: str | None = None
+    #: When Telem deletes the monitor; ``None``: never.
+    expires_at: str | None = None
     webhook_url: str | None = None
     #: Signs the webhook deliveries. Only in the response that set ``webhook_url``.
     webhook_secret: str | None = None

{telem_sdk-0.2.0 → telem_sdk-0.2.2}/telem/resources/monitors.py

@@ -17,18 +17,43 @@ if TYPE_CHECKING:
 
 def _create_body(
     query: str,
-    frequency: str,
+    frequency: str | None,
     metadata: dict[str, Any] | None,
     webhook_url: str | None,
+    ttl: str | None,
+    search: dict[str, Any] | None,
+    include_domains: list[str] | None,
 ) -> dict[str, Any]:
-    body: dict[str, Any] = {"query": query, "options": {"frequency": frequency}}
+    options: dict[str, Any] = {}
+    if frequency is not None:
+        options["frequency"] = frequency
+    if include_domains is not None:
+        options["include_domains"] = include_domains
+    if search is not None:
+        options["search"] = _search_block(search)
+    body: dict[str, Any] = {"query": query, "options": options}
     if metadata is not None:
         body["metadata"] = metadata
     if webhook_url is not None:
         body["webhook_url"] = webhook_url
+    if ttl is not None:
+        body["ttl"] = ttl
     return body
 
 
+def _search_block(search: dict[str, Any]) -> dict[str, Any]:
+    """The monitor's search options for the wire: the keys of ``search()``, with
+    ``providers_include``/``providers_exclude`` as ``providers``. No client
+    default applies: a monitor's search is set on the monitor alone."""
+    block = {k: v for k, v in search.items() if not k.startswith("providers_")}
+    providers = {
+        k.removeprefix("providers_"): v for k, v in search.items() if k.startswith("providers_")
+    }
+    if providers:
+        block["providers"] = providers
+    return block
+
+
 def _update_body(
     status: str | None,
     frequency: str | None,
@@ -96,23 +121,34 @@ class MonitorsResource:
         self,
         query: str,
         *,
-        frequency: str,
+        frequency: str | None = None,
         metadata: dict[str, Any] | None = None,
         webhook_url: str | None = None,
+        ttl: str | None = None,
+        search: dict[str, Any] | None = None,
+        include_domains: list[str] | None = None,
     ) -> Monitor:
         """Create a monitor. Telem runs ``query`` on the schedule.
 
         Args:
             query: What to watch for, as a plain sentence.
-            frequency: ``"1h"``, ``"6h"``, ``"1d"`` or ``"7d"``.
+            frequency: ``"1h"``, ``"6h"``, ``"12h"``, ``"1d"`` or ``"7d"``. If you leave it
+                out, the monitor runs once a day.
             metadata: Request metadata (query lineage keys), as in a search.
             webhook_url: An ``https`` URL that receives the new results.
+            ttl: Delete the monitor after this long, such as ``"12h"`` or ``"7d"``
+                (at most ``"30d"``). Without it, the monitor never expires.
+            search: Also run a web search for ``query`` on the schedule, with these
+                search options, named as in :meth:`Telem.search`: ``num_results`` and ``tier``.
+                ``{}`` uses the defaults.
+            include_domains: Only results from these sites and their subdomains, such as
+                ``["sec.gov"]``, from every source of the monitor.
 
         Returns:
             The new :class:`Monitor`. With ``webhook_url``, its ``webhook_secret``
             signs the deliveries; Telem shows it only in this response.
         """
-        body = _create_body(query, frequency, metadata, webhook_url)
+        body = _create_body(query, frequency, metadata, webhook_url, ttl, search, include_domains)
         return Monitor.model_validate(self._client._post("/v1/monitors", body))
 
     def list(self, *, limit: int | None = None) -> list[Monitor]:
@@ -185,12 +221,15 @@ class AsyncMonitorsResource:
         self,
         query: str,
         *,
-        frequency: str,
+        frequency: str | None = None,
         metadata: dict[str, Any] | None = None,
         webhook_url: str | None = None,
+        ttl: str | None = None,
+        search: dict[str, Any] | None = None,
+        include_domains: list[str] | None = None,
     ) -> Monitor:
         """Create a monitor. See :meth:`MonitorsResource.create`."""
-        body = _create_body(query, frequency, metadata, webhook_url)
+        body = _create_body(query, frequency, metadata, webhook_url, ttl, search, include_domains)
         return Monitor.model_validate(await self._client._post("/v1/monitors", body))
 
     async def list(self, *, limit: int | None = None) -> list[Monitor]: