ctxprotocol 0.19.1__tar.gz → 0.20.0__tar.gz

{ctxprotocol-0.19.1 → ctxprotocol-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.19.1
+Version: 0.20.0
 Summary: Official Python SDK for the Context Protocol - Discover and execute AI tools programmatically
 Project-URL: Homepage, https://ctxprotocol.com
 Project-URL: Documentation, https://docs.ctxprotocol.com
@@ -149,21 +149,35 @@ print(
 print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
-For long-running questions, start a durable job and poll until it completes:
+For long-running questions from LLM agents, use `run_or_poll()` so the entire wait happens inside one SDK call (one model turn):
 
 ```python
-job = await client.query.start(
+answer = await client.query.run_or_poll(
     query="Build a chart-ready dataset of Base whale movements over the last 30 days",
     response_shape="evidence_only",
     include_data_url=True,
 )
 
-completed = await client.query.poll(
-    job.job_id,
-    interval_ms=2000,
-    timeout_ms=15 * 60_000,
+print(answer.data_url)
+```
+
+The defaults are already agent-friendly: the SDK checks status every 5 seconds
+over plain HTTP (this costs no model tokens — token cost comes from model
+*turns*, not HTTP polls) and waits up to 31 minutes, slightly beyond the
+hosted 1800-second compute ceiling that bounds every query path. Treat a
+failed job-window status as terminal and start a fresh query.
+
+For programmatic workflows that want the job handle, start a durable job and poll until it completes:
+
+```python
+job = await client.query.start(
+    query="Build a chart-ready dataset of Base whale movements over the last 30 days",
+    response_shape="evidence_only",
+    include_data_url=True,
 )
 
+completed = await client.query.poll(job.job_id)
+
 print(completed.result.data_url if completed.result else None)
 ```
 

{ctxprotocol-0.19.1 → ctxprotocol-0.20.0}/README.md

@@ -111,21 +111,35 @@ print(
 print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
-For long-running questions, start a durable job and poll until it completes:
+For long-running questions from LLM agents, use `run_or_poll()` so the entire wait happens inside one SDK call (one model turn):
 
 ```python
-job = await client.query.start(
+answer = await client.query.run_or_poll(
     query="Build a chart-ready dataset of Base whale movements over the last 30 days",
     response_shape="evidence_only",
     include_data_url=True,
 )
 
-completed = await client.query.poll(
-    job.job_id,
-    interval_ms=2000,
-    timeout_ms=15 * 60_000,
+print(answer.data_url)
+```
+
+The defaults are already agent-friendly: the SDK checks status every 5 seconds
+over plain HTTP (this costs no model tokens — token cost comes from model
+*turns*, not HTTP polls) and waits up to 31 minutes, slightly beyond the
+hosted 1800-second compute ceiling that bounds every query path. Treat a
+failed job-window status as terminal and start a fresh query.
+
+For programmatic workflows that want the job handle, start a durable job and poll until it completes:
+
+```python
+job = await client.query.start(
+    query="Build a chart-ready dataset of Base whale movements over the last 30 days",
+    response_shape="evidence_only",
+    include_data_url=True,
 )
 
+completed = await client.query.poll(job.job_id)
+
 print(completed.result.data_url if completed.result else None)
 ```
 

{ctxprotocol-0.19.1 → ctxprotocol-0.20.0}/ctxprotocol/client/resources/query.py

@@ -11,11 +11,12 @@ from __future__ import annotations
 
 import asyncio
 import json
-from typing import TYPE_CHECKING, Any, AsyncGenerator
+from collections.abc import AsyncGenerator
+from typing import TYPE_CHECKING, Any
 
 from ctxprotocol.client.types import (
-    ContextError,
     AgentModelId,
+    ContextError,
     QueryAttemptReference,
     QueryDeveloperTrace,
     QueryForkReference,
@@ -34,6 +35,18 @@ from ctxprotocol.client.types import (
 if TYPE_CHECKING:
     from ctxprotocol.client.client import ContextClient
 
+# Internal HTTP status-check cadence for poll()/run_or_poll(). This is plain
+# HTTP polling below any LLM boundary — it costs no model tokens no matter how
+# frequent it is; a slower interval only delays completion detection. To keep
+# LLM-agent token costs down, minimize *model turns* (use run_or_poll()), not
+# HTTP polls.
+DEFAULT_QUERY_POLL_INTERVAL_MS = 5_000
+# Default client-side wait: slightly beyond the hosted 1800s compute ceiling
+# (Vercel extended max duration) that bounds every query path, so the client
+# observes the job's terminal state instead of giving up while the server is
+# still legitimately working.
+DEFAULT_QUERY_POLL_TIMEOUT_MS = 31 * 60_000
+
 
 class Query:
     """Query resource for pay-per-response agentic queries."""
@@ -376,10 +389,18 @@ class Query:
     async def poll(
         self,
         job_id: str,
-        interval_ms: int = 2000,
-        timeout_ms: int = 15 * 60_000,
+        interval_ms: int = DEFAULT_QUERY_POLL_INTERVAL_MS,
+        timeout_ms: int = DEFAULT_QUERY_POLL_TIMEOUT_MS,
     ) -> QueryJobStatusResult:
-        """Poll a durable async query job until completion or failure."""
+        """Poll a durable async query job until completion or failure.
+
+        ``timeout_ms`` controls how long this client waits; the hosted job
+        itself is bounded by the 1800s server compute ceiling. If the status
+        endpoint reports the job exceeded the server-side window, the job is
+        terminal and should not be polled again. ``interval_ms`` is an HTTP
+        check cadence with no effect on LLM token usage — leave it at the
+        fast default.
+        """
         loop = asyncio.get_running_loop()
         deadline = loop.time() + timeout_ms / 1000
 
@@ -389,10 +410,59 @@ class Query:
                 return status
             if status.status == "failed":
                 raise ContextError(status.error or "Context query job failed")
-            await asyncio.sleep(interval_ms / 1000)
+            remaining_s = deadline - loop.time()
+            if remaining_s <= 0:
+                break
+            await asyncio.sleep(min(interval_ms / 1000, remaining_s))
 
         raise ContextError(f"Context query job polling timed out after {timeout_ms}ms")
 
+    async def run_or_poll(
+        self,
+        query: str,
+        tools: list[str] | None = None,
+        favorites_only: bool | None = None,
+        agent_model_id: AgentModelId | str | None = None,
+        response_shape: QueryResponseShape | None = None,
+        include_data: bool | None = None,
+        include_data_url: bool | None = None,
+        include_developer_trace: bool | None = None,
+        resume_from: QueryAttemptReference | dict[str, Any] | None = None,
+        fork_from: QueryForkReference | dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        interval_ms: int = DEFAULT_QUERY_POLL_INTERVAL_MS,
+        timeout_ms: int = DEFAULT_QUERY_POLL_TIMEOUT_MS,
+    ) -> QueryResult:
+        """Run a durable query job and wait internally for completion.
+
+        This is the recommended one-call helper for LLM agents: the entire
+        wait happens inside this single call (one model turn), instead of one
+        turn per ``get_status()`` check. It also avoids starting a duplicate
+        paid query after a client-side streaming timeout. The job is bounded
+        by the 1800s hosted compute ceiling.
+        """
+        job = await self.start(
+            query=query,
+            tools=tools,
+            favorites_only=favorites_only,
+            agent_model_id=agent_model_id,
+            response_shape=response_shape,
+            include_data=include_data,
+            include_data_url=include_data_url,
+            include_developer_trace=include_developer_trace,
+            resume_from=resume_from,
+            fork_from=fork_from,
+            idempotency_key=idempotency_key,
+        )
+        completed = await self.poll(
+            job.job_id,
+            interval_ms=interval_ms,
+            timeout_ms=timeout_ms,
+        )
+        if completed.status == "completed" and completed.result is not None:
+            return completed.result
+        raise ContextError(completed.error or "Context query job completed without a result")
+
     async def stream(
         self,
         query: str,

{ctxprotocol-0.19.1 → ctxprotocol-0.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ctxprotocol"
-version = "0.19.1"
+version = "0.20.0"
 description = "Official Python SDK for the Context Protocol - Discover and execute AI tools programmatically"
 readme = "README.md"
 license = "MIT"

{ctxprotocol-0.19.1 → ctxprotocol-0.20.0}/tests/test_query.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 import json
 from pathlib import Path
 from typing import Any
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import AsyncMock, patch
 
 import httpx
 import pytest
@@ -1631,3 +1631,43 @@ class TestQueryJobs:
 
         assert status.status == "completed"
         assert mock_fetch.await_count == 2
+
+    async def test_run_or_poll_returns_completed_query_result(self) -> None:
+        client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
+        start_payload = {
+            "status": "running",
+            "jobId": "11111111-1111-4111-8111-111111111111",
+            "pollingTool": "context_query_poll",
+            "message": "running",
+            "progress": None,
+            "querySession": None,
+            "createdAt": "2026-06-14T00:00:00.000Z",
+            "updatedAt": "2026-06-14T00:00:00.000Z",
+        }
+        completed_payload = {
+            "status": "completed",
+            "jobId": "11111111-1111-4111-8111-111111111111",
+            "progress": None,
+            "querySession": None,
+            "result": MOCK_SUCCESS_RESPONSE,
+            "error": None,
+            "createdAt": "2026-06-14T00:00:00.000Z",
+            "updatedAt": "2026-06-14T00:01:00.000Z",
+            "completedAt": "2026-06-14T00:01:00.000Z",
+        }
+
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = [start_payload, completed_payload]
+            result = await client.query.run_or_poll(
+                "Analyze whale activity",
+                interval_ms=1,
+                timeout_ms=1000,
+            )
+
+        assert result.response == MOCK_SUCCESS_RESPONSE["response"]
+        assert mock_fetch.await_count == 2
+        assert mock_fetch.await_args_list[0].args[0] == "/api/v1/query/jobs"
+        assert (
+            mock_fetch.await_args_list[1].args[0]
+            == "/api/v1/query/jobs/11111111-1111-4111-8111-111111111111"
+        )

{ctxprotocol-0.19.1 → ctxprotocol-0.20.0}/uv.lock

@@ -205,7 +205,7 @@ wheels = [
 
 [[package]]
 name = "ctxprotocol"
-version = "0.19.1"
+version = "0.20.0"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },