ctxprotocol 0.17.0__tar.gz → 0.18.0__tar.gz

{ctxprotocol-0.17.0 → ctxprotocol-0.18.0}/.gitignore

@@ -43,6 +43,7 @@ htmlcov/
 # md files
 *.md
 !README.md
+!CHANGELOG.md
 !docs/mcp-builder-template.md
 !docs/mcp-server-analysis-prompt.md
 !docs/mcp-contributor-deep-validation-system-prompt.md

ctxprotocol-0.18.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.18.0
+
+- Added durable async Query jobs with `client.query.start()`, `client.query.get_status()`, and `client.query.poll()`.
+- Exported `QueryJobStartResult`, `QueryJobStatusResult`, and `QueryJobStatus` from the root and client entry points.
+- Kept existing `client.query.run()` and `client.query.stream()` behavior unchanged.

{ctxprotocol-0.17.0 → ctxprotocol-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.17.0
+Version: 0.18.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,6 +149,24 @@ print(
 print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
+For long-running questions, 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,
+    interval_ms=2000,
+    timeout_ms=15 * 60_000,
+)
+
+print(completed.result.data_url if completed.result else None)
+```
+
 To see valid model slugs without guessing:
 
 ```python
@@ -166,7 +184,7 @@ print(AGENT_MODEL_IDS)         # Supported agent_model_id values
 `response_shape` options:
 
 - `answer_with_evidence` (default): prose plus `summary`, `evidence`, `artifacts`, `freshness`, `confidence`, `usage`, `outcome`, and `controller`
-- `evidence_only`: raw fetched data, computed artifacts, and provenance for downstream agents (no prose synthesis)
+- `evidence_only`: bounded evidence, computed artifacts, and full-data references for downstream agents (no prose synthesis)
 
 Premium wedge answers can also expose `evidence.market_intelligence`, `view.rows`, `view.columns`, and the top-level controller fields `stop_reason`, `issue_class`, and `actions_taken`.
 
@@ -327,7 +345,7 @@ answer = await client.query.run(
     query="Analyze whale activity on Base",
     tools=["tool-uuid-1", "tool-uuid-2"],  # optional — auto-discover if omitted
     agent_model_id="kimi-k2.6-model",        # optional main librarian agent model
-    include_data=True,                       # optional: include execution data inline
+    include_data=True,                       # optional: include bounded execution data inline
     include_data_url=True,                   # optional: include blob URL for full data
     include_developer_trace=True,            # optional: include Developer Mode trace
 )
@@ -336,7 +354,7 @@ print(answer.response)      # response text or summary
 print(answer.tools_used)    # [QueryToolUsage(id, name, skill_calls)]
 print(answer.cost)          # QueryCost(model_cost_usd, tool_cost_usd, total_cost_usd)
 print(answer.duration_ms)   # Total time
-print(answer.data)          # Optional execution data (when include_data=True)
+print(answer.data)          # Optional bounded data or truncation preview
 print(answer.data_url)      # Optional blob URL (when include_data_url=True)
 print(answer.developer_trace.summary if answer.developer_trace else None)
 print(
@@ -347,7 +365,7 @@ print(
 print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
-When retrieval-first synthesis rollout is enabled server-side, full-data or truncation-sensitive query requests can switch to retrieval-first context assembly using private stage artifacts and canonical execution data slices. `include_data` and `include_data_url` continue to reference the same canonical dataset used for synthesis.
+When retrieval-first synthesis rollout is enabled server-side, full-data or truncation-sensitive query requests can switch to retrieval-first context assembly using private stage artifacts and canonical execution data slices. `include_data` returns a bounded inline preview when needed, and `include_data_url`/`artifacts.canonical_data_ref` reference the same canonical dataset used for synthesis.
 
 #### `client.query.stream(query, tools?, agent_model_id?, include_data?, include_data_url?, include_developer_trace?, idempotency_key?)`
 

{ctxprotocol-0.17.0 → ctxprotocol-0.18.0}/README.md

@@ -111,6 +111,24 @@ print(
 print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
+For long-running questions, 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,
+    interval_ms=2000,
+    timeout_ms=15 * 60_000,
+)
+
+print(completed.result.data_url if completed.result else None)
+```
+
 To see valid model slugs without guessing:
 
 ```python
@@ -128,7 +146,7 @@ print(AGENT_MODEL_IDS)         # Supported agent_model_id values
 `response_shape` options:
 
 - `answer_with_evidence` (default): prose plus `summary`, `evidence`, `artifacts`, `freshness`, `confidence`, `usage`, `outcome`, and `controller`
-- `evidence_only`: raw fetched data, computed artifacts, and provenance for downstream agents (no prose synthesis)
+- `evidence_only`: bounded evidence, computed artifacts, and full-data references for downstream agents (no prose synthesis)
 
 Premium wedge answers can also expose `evidence.market_intelligence`, `view.rows`, `view.columns`, and the top-level controller fields `stop_reason`, `issue_class`, and `actions_taken`.
 
@@ -289,7 +307,7 @@ answer = await client.query.run(
     query="Analyze whale activity on Base",
     tools=["tool-uuid-1", "tool-uuid-2"],  # optional — auto-discover if omitted
     agent_model_id="kimi-k2.6-model",        # optional main librarian agent model
-    include_data=True,                       # optional: include execution data inline
+    include_data=True,                       # optional: include bounded execution data inline
     include_data_url=True,                   # optional: include blob URL for full data
     include_developer_trace=True,            # optional: include Developer Mode trace
 )
@@ -298,7 +316,7 @@ print(answer.response)      # response text or summary
 print(answer.tools_used)    # [QueryToolUsage(id, name, skill_calls)]
 print(answer.cost)          # QueryCost(model_cost_usd, tool_cost_usd, total_cost_usd)
 print(answer.duration_ms)   # Total time
-print(answer.data)          # Optional execution data (when include_data=True)
+print(answer.data)          # Optional bounded data or truncation preview
 print(answer.data_url)      # Optional blob URL (when include_data_url=True)
 print(answer.developer_trace.summary if answer.developer_trace else None)
 print(
@@ -309,7 +327,7 @@ print(
 print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
-When retrieval-first synthesis rollout is enabled server-side, full-data or truncation-sensitive query requests can switch to retrieval-first context assembly using private stage artifacts and canonical execution data slices. `include_data` and `include_data_url` continue to reference the same canonical dataset used for synthesis.
+When retrieval-first synthesis rollout is enabled server-side, full-data or truncation-sensitive query requests can switch to retrieval-first context assembly using private stage artifacts and canonical execution data slices. `include_data` returns a bounded inline preview when needed, and `include_data_url`/`artifacts.canonical_data_ref` reference the same canonical dataset used for synthesis.
 
 #### `client.query.stream(query, tools?, agent_model_id?, include_data?, include_data_url?, include_developer_trace?, idempotency_key?)`
 

{ctxprotocol-0.17.0 → ctxprotocol-0.18.0}/ctxprotocol/__init__.py

@@ -31,7 +31,7 @@ Example:
 For more information, visit: https://ctxprotocol.com
 """
 
-__version__ = "0.17.0"
+__version__ = "0.18.0"
 
 # Re-export everything from client module
 from ctxprotocol.client import (
@@ -70,6 +70,9 @@ from ctxprotocol.client.types import (
     QueryDeveloperTraceSummary,
     QueryDeveloperTraceStep,
     QueryDeveloperTraceToolRef,
+    QueryJobStartResult,
+    QueryJobStatus,
+    QueryJobStatusResult,
     QueryOrchestrationMetrics,
     QueryDeveloperTraceLoopInfo,
     QueryStreamDeveloperTraceEvent,
@@ -195,6 +198,9 @@ __all__ = [
     "QueryDeveloperTraceSummary",
     "QueryDeveloperTraceStep",
     "QueryDeveloperTraceToolRef",
+    "QueryJobStartResult",
+    "QueryJobStatus",
+    "QueryJobStatusResult",
     "QueryOrchestrationMetrics",
     "QueryDeveloperTraceLoopInfo",
     "QueryApiSuccessResponse",

{ctxprotocol-0.17.0 → ctxprotocol-0.18.0}/ctxprotocol/client/__init__.py

@@ -51,6 +51,9 @@ from ctxprotocol.client.types import (
     QueryDeveloperTraceSummary,
     QueryDeveloperTraceStep,
     QueryDeveloperTraceToolRef,
+    QueryJobStartResult,
+    QueryJobStatus,
+    QueryJobStatusResult,
     QueryOrchestrationMetrics,
     QueryDeveloperTraceLoopInfo,
     QueryStreamDeveloperTraceEvent,
@@ -111,6 +114,9 @@ __all__ = [
     "QueryDeveloperTraceSummary",
     "QueryDeveloperTraceStep",
     "QueryDeveloperTraceToolRef",
+    "QueryJobStartResult",
+    "QueryJobStatus",
+    "QueryJobStatusResult",
     "QueryOrchestrationMetrics",
     "QueryDeveloperTraceLoopInfo",
     "QueryApiSuccessResponse",

{ctxprotocol-0.17.0 → ctxprotocol-0.18.0}/ctxprotocol/client/resources/query.py

@@ -9,6 +9,7 @@ execute -> synthesize -> settle) and AI synthesis — all for one flat fee.
 
 from __future__ import annotations
 
+import asyncio
 import json
 from typing import TYPE_CHECKING, Any, AsyncGenerator
 
@@ -18,6 +19,8 @@ from ctxprotocol.client.types import (
     QueryAttemptReference,
     QueryDeveloperTrace,
     QueryForkReference,
+    QueryJobStartResult,
+    QueryJobStatusResult,
     QueryResponseShape,
     QueryResult,
     QueryStreamDeveloperTraceEvent,
@@ -43,6 +46,52 @@ class Query:
         """
         self._client = client
 
+    @staticmethod
+    def _build_request_body(
+        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,
+        stream: bool | None = None,
+    ) -> dict[str, Any]:
+        request_body: dict[str, Any] = {
+            "query": query,
+            "tools": tools,
+        }
+        if stream is not None:
+            request_body["stream"] = stream
+        if resume_from is not None:
+            request_body["resumeFrom"] = (
+                resume_from.model_dump(by_alias=True, exclude_none=True)
+                if isinstance(resume_from, QueryAttemptReference)
+                else resume_from
+            )
+        if fork_from is not None:
+            request_body["forkFrom"] = (
+                fork_from.model_dump(by_alias=True, exclude_none=True)
+                if isinstance(fork_from, QueryForkReference)
+                else fork_from
+            )
+        if favorites_only is not None:
+            request_body["favoritesOnly"] = favorites_only
+        if agent_model_id is not None:
+            request_body["agentModelId"] = agent_model_id
+        if response_shape is not None:
+            request_body["responseShape"] = response_shape
+        if include_data is not None:
+            request_body["includeData"] = include_data
+        if include_data_url is not None:
+            request_body["includeDataUrl"] = include_data_url
+        if include_developer_trace is not None:
+            request_body["includeDeveloperTrace"] = include_developer_trace
+        return request_body
+
     @staticmethod
     def _merge_developer_trace(
         first: QueryDeveloperTrace | None,
@@ -278,6 +327,71 @@ class Query:
 
         raise ContextError("Streaming query ended before done event")
 
+    async def start(
+        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,
+    ) -> QueryJobStartResult:
+        """Start a durable async query job and return its job id immediately."""
+        request_body = self._build_request_body(
+            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,
+            stream=False,
+        )
+        response = await self._client.fetch(
+            "/api/v1/query/jobs",
+            method="POST",
+            json_body=request_body,
+            extra_headers=(
+                {"Idempotency-Key": idempotency_key}
+                if idempotency_key
+                else None
+            ),
+        )
+        return QueryJobStartResult.model_validate(response)
+
+    async def get_status(self, job_id: str) -> QueryJobStatusResult:
+        """Fetch the current status for a durable async query job."""
+        response = await self._client.fetch(f"/api/v1/query/jobs/{job_id}")
+        return QueryJobStatusResult.model_validate(response)
+
+    async def poll(
+        self,
+        job_id: str,
+        interval_ms: int = 2000,
+        timeout_ms: int = 15 * 60_000,
+    ) -> QueryJobStatusResult:
+        """Poll a durable async query job until completion or failure."""
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout_ms / 1000
+
+        while loop.time() <= deadline:
+            status = await self.get_status(job_id)
+            if status.status == "completed":
+                return status
+            if status.status == "failed":
+                raise ContextError(status.error or "Context query job failed")
+            await asyncio.sleep(interval_ms / 1000)
+
+        raise ContextError(f"Context query job polling timed out after {timeout_ms}ms")
+
     async def stream(
         self,
         query: str,

{ctxprotocol-0.17.0 → ctxprotocol-0.18.0}/ctxprotocol/client/types.py

@@ -46,12 +46,9 @@ SuggestedPromptSource = Literal["contributor", "platform", "sdk"]
 DEFAULT_AGENT_MODEL_ID = "kimi-k2.6-model"
 AGENT_MODEL_IDS = (
     "kimi-k2.6-model",
+    "glm-5.2-model",
     "deepseek-v4-pro-model",
     "deepseek-v4-flash-model",
-    "gemini-3.5-flash-model",
-    "gemini-flash-model",
-    "gemini-lite-model",
-    "minimax-m3-model",
     "qwen-3.7-plus-model",
     "qwen-3.7-max-model",
     "gpt-5.5-model",
@@ -59,12 +56,9 @@ AGENT_MODEL_IDS = (
 )
 AgentModelId = Literal[
     "kimi-k2.6-model",
+    "glm-5.2-model",
     "deepseek-v4-pro-model",
     "deepseek-v4-flash-model",
-    "gemini-3.5-flash-model",
-    "gemini-flash-model",
-    "gemini-lite-model",
-    "minimax-m3-model",
     "qwen-3.7-plus-model",
     "qwen-3.7-max-model",
     "gpt-5.5-model",
@@ -745,21 +739,21 @@ class QueryOptions(BaseModel):
         description=(
             "Structured response mode. Defaults to `answer_with_evidence` on the "
             "server when omitted. The runtime always produces a grounded result "
-            "(raw data + computed artifacts + provenance); this controls whether "
-            "a prose synthesis layer is added on top. "
+            "(bounded evidence + computed artifacts + full-data references); "
+            "this controls whether a prose synthesis layer is added on top. "
             "`answer_with_evidence` returns prose plus the structured grounding "
             "(chat parity); `evidence_only` returns grounding only with no prose "
-            "(the agent-harness shape, with raw data + computed_artifacts + "
-            "grounding by default)."
+            "(the agent-harness shape, with bounded evidence, computed_artifacts, "
+            "and data_url/canonical_data_ref references)."
         ),
     )
     include_data: bool | None = Field(
         default=None,
         alias="includeData",
         description=(
-            "Include raw execution data inline. Defaults to true for "
-            "response_shape `evidence_only` (its primary payload is the raw "
-            "fetched data); false otherwise. Set explicitly to override."
+            "Include bounded execution data inline. Defaults to false for every "
+            "response_shape. Large payloads are returned as a preview object "
+            "with fullData.dataUrl/canonicalDataRef instead of unbounded raw rows."
         ),
     )
     include_data_url: bool | None = Field(
@@ -1703,7 +1697,7 @@ class QueryResult(BaseModel):
         tools_used: Tools that were used to answer the query
         cost: Cost breakdown
         duration_ms: Total duration in milliseconds
-        data: Raw execution data (default for evidence_only; else when include_data is enabled)
+        data: Bounded execution data when include_data is enabled
         data_url: Optional blob URL for execution data (when include_data_url is enabled)
         computed_artifacts: Optional chart artifacts emitted by code interpreter
         developer_trace: Optional machine-readable Developer Mode trace
@@ -1721,9 +1715,9 @@ class QueryResult(BaseModel):
     data: Any | None = Field(
         default=None,
         description=(
-            "Raw execution data from tools. Returned by default for "
-            "response_shape `evidence_only` (its primary payload); otherwise "
-            "only when include_data is true."
+            "Bounded execution data from tools. Returned only when include_data "
+            "is true. Small payloads may be direct data; large payloads are a "
+            "truncation object with preview and fullData references."
         ),
     )
     data_url: str | None = Field(
@@ -1892,6 +1886,40 @@ class QueryApiSuccessResponse(BaseModel):
     model_config = {"populate_by_name": True}
 
 
+QueryJobStatus = Literal["queued", "running", "completed", "failed"]
+
+
+class QueryJobStartResult(BaseModel):
+    """Response from starting a durable async query job."""
+
+    status: QueryJobStatus
+    job_id: str = Field(..., alias="jobId")
+    polling_tool: str | None = Field(default=None, alias="pollingTool")
+    message: str | None = None
+    progress: Any | None = None
+    query_session: Any | None = Field(default=None, alias="querySession")
+    created_at: str = Field(..., alias="createdAt")
+    updated_at: str = Field(..., alias="updatedAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class QueryJobStatusResult(BaseModel):
+    """Current status for a durable async query job."""
+
+    status: QueryJobStatus
+    job_id: str = Field(..., alias="jobId")
+    progress: Any | None = None
+    query_session: Any | None = Field(default=None, alias="querySession")
+    result: QueryResult | None = None
+    error: str | None = None
+    created_at: str = Field(..., alias="createdAt")
+    updated_at: str = Field(..., alias="updatedAt")
+    completed_at: str | None = Field(default=None, alias="completedAt")
+
+    model_config = {"populate_by_name": True}
+
+
 class QueryStreamToolStatusEvent(BaseModel):
     """Emitted when a tool starts or changes execution status."""
 

{ctxprotocol-0.17.0 → ctxprotocol-0.18.0}/pyproject.toml

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

{ctxprotocol-0.17.0 → ctxprotocol-0.18.0}/tests/test_query.py

@@ -1466,3 +1466,104 @@ class TestQueryStream:
                 events.append(event)
 
         assert len(events) == 1
+
+
+class TestQueryJobs:
+    """Tests for durable async query job helpers."""
+
+    async def test_start_creates_query_job(self) -> None:
+        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
+            job = await client.query.start(
+                query="long query",
+                response_shape="evidence_only",
+                include_data_url=True,
+                idempotency_key="21118fda-33be-4d66-8df5-0e50b3371f54",
+            )
+
+        assert job.job_id == "11111111-1111-4111-8111-111111111111"
+        mock_fetch.assert_called_once_with(
+            "/api/v1/query/jobs",
+            method="POST",
+            json_body={
+                "query": "long query",
+                "tools": None,
+                "stream": False,
+                "responseShape": "evidence_only",
+                "includeDataUrl": True,
+            },
+            extra_headers={
+                "Idempotency-Key": "21118fda-33be-4d66-8df5-0e50b3371f54",
+            },
+        )
+
+    async def test_get_status_fetches_query_job(self) -> None:
+        client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
+        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.return_value = payload
+            status = await client.query.get_status(
+                "11111111-1111-4111-8111-111111111111"
+            )
+
+        assert status.status == "completed"
+        assert status.result is not None
+        assert status.result.response == MOCK_SUCCESS_RESPONSE["response"]
+        mock_fetch.assert_called_once_with(
+            "/api/v1/query/jobs/11111111-1111-4111-8111-111111111111"
+        )
+
+    async def test_poll_waits_until_query_job_completes(self) -> None:
+        client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
+        running_payload = {
+            "status": "running",
+            "jobId": "11111111-1111-4111-8111-111111111111",
+            "progress": None,
+            "querySession": None,
+            "result": None,
+            "error": None,
+            "createdAt": "2026-06-14T00:00:00.000Z",
+            "updatedAt": "2026-06-14T00:00:30.000Z",
+            "completedAt": None,
+        }
+        completed_payload = {
+            **running_payload,
+            "status": "completed",
+            "result": MOCK_SUCCESS_RESPONSE,
+            "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 = [running_payload, completed_payload]
+            status = await client.query.poll(
+                "11111111-1111-4111-8111-111111111111",
+                interval_ms=1,
+                timeout_ms=1000,
+            )
+
+        assert status.status == "completed"
+        assert mock_fetch.await_count == 2

{ctxprotocol-0.17.0 → ctxprotocol-0.18.0}/uv.lock

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