ctxprotocol 0.19.0__tar.gz → 0.20.0__tar.gz

{ctxprotocol-0.19.0 → ctxprotocol-0.20.0}/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.19.1
+
+- Fixed `client.query.start()` returning `400 "Invalid query job request"` when called without explicit `tools`. The request body builder now omits optional fields (notably `tools`) when unset instead of serializing them as JSON `null`; the durable jobs endpoint's Zod schema rejects `null` for optional fields. `client.query.run()` and `client.query.stream()` were not failing (the `/api/v1/query` endpoint tolerates `null`), but are now consistent with the TS SDK and MCP behavior.
+
 ## 0.19.0
 
 - Fixed `client.query.run()`/`client.query.stream()` raising a `ValidationError` on queries that returned a rendered image artifact (e.g. server-rendered chart PNGs). `computedArtifacts` now accepts both `chart` (structured spec + data) and `image` (hosted URL) variants.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.19.0
+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.0 → 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.0 → ctxprotocol-0.20.0}/ctxprotocol/__init__.py

@@ -31,7 +31,7 @@ Example:
 For more information, visit: https://ctxprotocol.com
 """
 
-__version__ = "0.19.0"
+__version__ = "0.19.1"
 
 # Re-export everything from client module
 from ctxprotocol.client import (

{ctxprotocol-0.19.0 → 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."""
@@ -62,8 +75,9 @@ class Query:
     ) -> dict[str, Any]:
         request_body: dict[str, Any] = {
             "query": query,
-            "tools": tools,
         }
+        if tools is not None:
+            request_body["tools"] = tools
         if stream is not None:
             request_body["stream"] = stream
         if resume_from is not None:
@@ -375,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
 
@@ -388,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,
@@ -443,9 +514,10 @@ class Query:
         """
         request_body: dict[str, Any] = {
             "query": query,
-            "tools": tools,
             "stream": True,
         }
+        if tools is not None:
+            request_body["tools"] = tools
         if resume_from is not None:
             request_body["resumeFrom"] = (
                 resume_from.model_dump(by_alias=True, exclude_none=True)

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ctxprotocol"
-version = "0.19.0"
+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.0 → 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
@@ -420,7 +420,6 @@ class TestQueryRun:
             method="POST",
             json_body={
                 "query": "What are the top whale movements?",
-                "tools": None,
                 "stream": True,
             },
             extra_headers=None,
@@ -480,7 +479,6 @@ class TestQueryRun:
             method="POST",
             json_body={
                 "query": "Analyze whale activity",
-                "tools": None,
                 "stream": True,
                 "agentModelId": "kimi-k2.6-model",
                 "responseShape": "answer_with_evidence",
@@ -1091,7 +1089,6 @@ class TestQueryStream:
             method="POST",
             json_body={
                 "query": "What are whale movements?",
-                "tools": None,
                 "stream": True,
             },
             extra_headers=None,
@@ -1534,7 +1531,6 @@ class TestQueryJobs:
             method="POST",
             json_body={
                 "query": "long query",
-                "tools": None,
                 "stream": False,
                 "responseShape": "evidence_only",
                 "includeDataUrl": True,
@@ -1544,6 +1540,39 @@ class TestQueryJobs:
             },
         )
 
+    async def test_start_omits_null_optional_fields(self) -> None:
+        """Regression: optional fields must be absent (not JSON null) in the job body.
+
+        The /api/v1/query/jobs endpoint validates the body with a Zod schema whose
+        optional fields accept `undefined`/absent but reject `null`. Sending
+        `"tools": null` (as the SDK previously did) made query.start() 400 with
+        "Invalid query job request". Optional fields must be omitted when unset,
+        matching the TS SDK (JSON.stringify drops undefined keys).
+        """
+        client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
+        payload = {
+            "status": "running",
+            "jobId": "11111111-1111-4111-8111-111111111111",
+            "pollingTool": "context_query_status",
+            "message": "running",
+            "progress": None,
+            "querySession": None,
+            "createdAt": "2026-06-14T00:00:00.000Z",
+            "updatedAt": "2026-06-14T00:00:00.000Z",
+        }
+
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.return_value = payload
+            await client.query.start(query="long query")
+
+        body = mock_fetch.call_args.kwargs["json_body"]
+        # No optional field may serialize to JSON null.
+        assert all(value is not None for value in body.values()), body
+        # tools specifically must be omitted when not supplied (was the 400 trigger).
+        assert "tools" not in body, body
+        # query is always present and non-null.
+        assert body["query"] == "long query"
+
     async def test_get_status_fetches_query_job(self) -> None:
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
         payload = {
@@ -1602,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.0 → ctxprotocol-0.20.0}/uv.lock

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