ctxprotocol 0.16.0__tar.gz → 0.18.0__tar.gz

{ctxprotocol-0.16.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.16.0 → ctxprotocol-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.16.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
@@ -129,7 +129,7 @@ print(result.session)  # method_price, spent, remaining, max_spend, ...
 ```python
 answer = await client.query.run(
     query="What are the top whale movements on Base?",
-    answer_model_id="glm-model",  # optional: choose the final synthesis model
+    agent_model_id="kimi-k2.6-model",  # optional: choose the main librarian agent model
     response_shape="answer_with_evidence",  # optional: answer_with_evidence (default) | evidence_only
     include_data_url=True,     # optional: persist full execution data to blob
     include_developer_trace=True,  # optional: include runtime developer trace
@@ -149,6 +149,33 @@ 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
+from ctxprotocol import AGENT_MODEL_IDS, DEFAULT_AGENT_MODEL_ID
+
+print(DEFAULT_AGENT_MODEL_ID)  # "kimi-k2.6-model"
+print(AGENT_MODEL_IDS)         # Supported agent_model_id values
+```
+
 > Mixed listings are first-class: one listing can expose methods to both surfaces. Methods without `_meta.pricing.executeUsd` remain query-only until priced.
 >
 > Compatibility: SDK/API payload fields such as `price` and `price_per_query` are retained for backward compatibility. In Query mode, they represent listing-level **price per response turn**.
@@ -157,7 +184,7 @@ print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 `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`.
 
@@ -297,7 +324,7 @@ closed = await client.tools.close_session("sess_123")
 
 ### Query (Pay-Per-Response)
 
-#### `client.query.run(query, tools?, answer_model_id?, include_data?, include_data_url?, include_developer_trace?, idempotency_key?)`
+#### `client.query.run(query, tools?, agent_model_id?, include_data?, include_data_url?, include_developer_trace?, idempotency_key?)`
 
 Run an agentic query. The server applies the live librarian pipeline (`discover -> select -> iterative execute -> synthesize -> settle`) with up to 100 MCP calls per response turn, then returns the selected Query response contract (`answer_with_evidence` or `evidence_only`, default `answer_with_evidence`).
 
@@ -317,8 +344,8 @@ answer = await client.query.run("What are the top whale movements on Base?")
 answer = await client.query.run(
     query="Analyze whale activity on Base",
     tools=["tool-uuid-1", "tool-uuid-2"],  # optional — auto-discover if omitted
-    answer_model_id="kimi-model-thinking",   # optional final synthesis model
-    include_data=True,                       # optional: include execution data inline
+    agent_model_id="kimi-k2.6-model",        # optional main librarian agent model
+    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
 )
@@ -327,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(
@@ -338,9 +365,9 @@ 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?, answer_model_id?, include_data?, include_data_url?, include_developer_trace?, idempotency_key?)`
+#### `client.query.stream(query, tools?, agent_model_id?, include_data?, include_data_url?, include_developer_trace?, idempotency_key?)`
 
 Same as `run()` but streams events in real-time via SSE.
 

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

@@ -91,7 +91,7 @@ print(result.session)  # method_price, spent, remaining, max_spend, ...
 ```python
 answer = await client.query.run(
     query="What are the top whale movements on Base?",
-    answer_model_id="glm-model",  # optional: choose the final synthesis model
+    agent_model_id="kimi-k2.6-model",  # optional: choose the main librarian agent model
     response_shape="answer_with_evidence",  # optional: answer_with_evidence (default) | evidence_only
     include_data_url=True,     # optional: persist full execution data to blob
     include_developer_trace=True,  # optional: include runtime developer trace
@@ -111,6 +111,33 @@ 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
+from ctxprotocol import AGENT_MODEL_IDS, DEFAULT_AGENT_MODEL_ID
+
+print(DEFAULT_AGENT_MODEL_ID)  # "kimi-k2.6-model"
+print(AGENT_MODEL_IDS)         # Supported agent_model_id values
+```
+
 > Mixed listings are first-class: one listing can expose methods to both surfaces. Methods without `_meta.pricing.executeUsd` remain query-only until priced.
 >
 > Compatibility: SDK/API payload fields such as `price` and `price_per_query` are retained for backward compatibility. In Query mode, they represent listing-level **price per response turn**.
@@ -119,7 +146,7 @@ print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 `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`.
 
@@ -259,7 +286,7 @@ closed = await client.tools.close_session("sess_123")
 
 ### Query (Pay-Per-Response)
 
-#### `client.query.run(query, tools?, answer_model_id?, include_data?, include_data_url?, include_developer_trace?, idempotency_key?)`
+#### `client.query.run(query, tools?, agent_model_id?, include_data?, include_data_url?, include_developer_trace?, idempotency_key?)`
 
 Run an agentic query. The server applies the live librarian pipeline (`discover -> select -> iterative execute -> synthesize -> settle`) with up to 100 MCP calls per response turn, then returns the selected Query response contract (`answer_with_evidence` or `evidence_only`, default `answer_with_evidence`).
 
@@ -279,8 +306,8 @@ answer = await client.query.run("What are the top whale movements on Base?")
 answer = await client.query.run(
     query="Analyze whale activity on Base",
     tools=["tool-uuid-1", "tool-uuid-2"],  # optional — auto-discover if omitted
-    answer_model_id="kimi-model-thinking",   # optional final synthesis model
-    include_data=True,                       # optional: include execution data inline
+    agent_model_id="kimi-k2.6-model",        # optional main librarian agent model
+    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
 )
@@ -289,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(
@@ -300,9 +327,9 @@ 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?, answer_model_id?, include_data?, include_data_url?, include_developer_trace?, idempotency_key?)`
+#### `client.query.stream(query, tools?, agent_model_id?, include_data?, include_data_url?, include_developer_trace?, idempotency_key?)`
 
 Same as `run()` but streams events in real-time via SSE.
 

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

@@ -31,7 +31,7 @@ Example:
 For more information, visit: https://ctxprotocol.com
 """
 
-__version__ = "0.15.0"
+__version__ = "0.18.0"
 
 # Re-export everything from client module
 from ctxprotocol.client import (
@@ -43,8 +43,10 @@ from ctxprotocol.client import (
     Tools,
 )
 from ctxprotocol.client.types import (
+    AGENT_MODEL_IDS,
     ContextClientOptions,
     ContextErrorCode,
+    DEFAULT_AGENT_MODEL_ID,
     ExecuteApiErrorResponse,
     ExecuteApiSuccessResponse,
     ExecuteMethodInfo,
@@ -68,6 +70,9 @@ from ctxprotocol.client.types import (
     QueryDeveloperTraceSummary,
     QueryDeveloperTraceStep,
     QueryDeveloperTraceToolRef,
+    QueryJobStartResult,
+    QueryJobStatus,
+    QueryJobStatusResult,
     QueryOrchestrationMetrics,
     QueryDeveloperTraceLoopInfo,
     QueryStreamDeveloperTraceEvent,
@@ -83,6 +88,7 @@ from ctxprotocol.client.types import (
     SearchResponse,
     Tool,
     ToolInfo,
+    AgentModelId,
 )
 
 # Context types for portfolio injection
@@ -178,6 +184,9 @@ __all__ = [
     "ExecuteApiErrorResponse",
     "ExecuteSessionApiSuccessResponse",
     "ToolInfo",
+    "AGENT_MODEL_IDS",
+    "DEFAULT_AGENT_MODEL_ID",
+    "AgentModelId",
     # Query types (pay-per-response)
     "QueryOptions",
     "QueryResult",
@@ -189,6 +198,9 @@ __all__ = [
     "QueryDeveloperTraceSummary",
     "QueryDeveloperTraceStep",
     "QueryDeveloperTraceToolRef",
+    "QueryJobStartResult",
+    "QueryJobStatus",
+    "QueryJobStatusResult",
     "QueryOrchestrationMetrics",
     "QueryDeveloperTraceLoopInfo",
     "QueryApiSuccessResponse",

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

@@ -10,9 +10,11 @@ from ctxprotocol.client.resources.discovery import Discovery
 from ctxprotocol.client.resources.query import Query
 from ctxprotocol.client.resources.tools import Tools
 from ctxprotocol.client.types import (
+    AGENT_MODEL_IDS,
     ContextClientOptions,
     ContextError,
     ContextErrorCode,
+    DEFAULT_AGENT_MODEL_ID,
     ExecuteApiErrorResponse,
     ExecuteApiSuccessResponse,
     ExecuteMethodInfo,
@@ -49,6 +51,9 @@ from ctxprotocol.client.types import (
     QueryDeveloperTraceSummary,
     QueryDeveloperTraceStep,
     QueryDeveloperTraceToolRef,
+    QueryJobStartResult,
+    QueryJobStatus,
+    QueryJobStatusResult,
     QueryOrchestrationMetrics,
     QueryDeveloperTraceLoopInfo,
     QueryStreamDeveloperTraceEvent,
@@ -64,6 +69,7 @@ from ctxprotocol.client.types import (
     SearchResponse,
     Tool,
     ToolInfo,
+    AgentModelId,
 )
 
 __all__ = [
@@ -76,6 +82,9 @@ __all__ = [
     "Query",
     # Types
     "ContextClientOptions",
+    "AGENT_MODEL_IDS",
+    "DEFAULT_AGENT_MODEL_ID",
+    "AgentModelId",
     "Tool",
     "McpTool",
     "McpToolMeta",
@@ -105,6 +114,9 @@ __all__ = [
     "QueryDeveloperTraceSummary",
     "QueryDeveloperTraceStep",
     "QueryDeveloperTraceToolRef",
+    "QueryJobStartResult",
+    "QueryJobStatus",
+    "QueryJobStatusResult",
     "QueryOrchestrationMetrics",
     "QueryDeveloperTraceLoopInfo",
     "QueryApiSuccessResponse",

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

@@ -9,14 +9,18 @@ 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
 
 from ctxprotocol.client.types import (
     ContextError,
+    AgentModelId,
     QueryAttemptReference,
     QueryDeveloperTrace,
     QueryForkReference,
+    QueryJobStartResult,
+    QueryJobStatusResult,
     QueryResponseShape,
     QueryResult,
     QueryStreamDeveloperTraceEvent,
@@ -42,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,
@@ -193,7 +243,7 @@ class Query:
         query: str,
         tools: list[str] | None = None,
         favorites_only: bool | None = None,
-        answer_model_id: str | 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,
@@ -215,7 +265,7 @@ class Query:
             query: The natural-language question to answer
             tools: Optional tool IDs to use (auto-discover if not provided)
             favorites_only: Restrict auto-discovery to favorite tools for this request
-            answer_model_id: Optional answer model ID for final synthesis
+            agent_model_id: Optional model ID for the main librarian agent loop
             response_shape: Structured response mode (`answer_with_evidence` or
                 `evidence_only`; server default `answer_with_evidence`)
             include_data: Include execution data inline in the query response
@@ -253,7 +303,7 @@ class Query:
             query=query,
             tools=tools,
             favorites_only=favorites_only,
-            answer_model_id=answer_model_id,
+            agent_model_id=agent_model_id,
             response_shape=response_shape,
             include_data=include_data,
             include_data_url=include_data_url,
@@ -277,12 +327,77 @@ 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,
         tools: list[str] | None = None,
         favorites_only: bool | None = None,
-        answer_model_id: str | 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,
@@ -304,7 +419,7 @@ class Query:
             query: The natural-language question to answer
             tools: Optional tool IDs to use (auto-discover if not provided)
             favorites_only: Restrict auto-discovery to favorite tools for this request
-            answer_model_id: Optional answer model ID for final synthesis
+            agent_model_id: Optional model ID for the main librarian agent loop
             response_shape: Structured response mode (`answer_with_evidence` or
                 `evidence_only`; server default `answer_with_evidence`)
             include_data: Include execution data inline in the query response
@@ -345,8 +460,8 @@ class Query:
             )
         if favorites_only is not None:
             request_body["favoritesOnly"] = favorites_only
-        if answer_model_id is not None:
-            request_body["answerModelId"] = answer_model_id
+        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:

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

@@ -43,6 +43,27 @@ McpToolSurface = Literal["answer", "execute", "both"]
 McpToolLatencyClass = Literal["instant", "fast", "slow", "streaming"]
 ExecuteSessionStatus = Literal["open", "closed", "expired"]
 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",
+    "qwen-3.7-plus-model",
+    "qwen-3.7-max-model",
+    "gpt-5.5-model",
+    "claude-opus-model",
+)
+AgentModelId = Literal[
+    "kimi-k2.6-model",
+    "glm-5.2-model",
+    "deepseek-v4-pro-model",
+    "deepseek-v4-flash-model",
+    "qwen-3.7-plus-model",
+    "qwen-3.7-max-model",
+    "gpt-5.5-model",
+    "claude-opus-model",
+]
 
 
 class McpToolRateLimitHints(BaseModel):
@@ -674,7 +695,7 @@ class QueryOptions(BaseModel):
     Attributes:
         query: The natural-language question to answer
         tools: Optional tool IDs to use (auto-discover if not provided)
-        answer_model_id: Optional answer model ID for final synthesis
+        agent_model_id: Optional model ID for the main librarian agent loop
         include_data: Include execution data inline in the query response
         include_data_url: Persist execution data to blob and return URL
         include_developer_trace: Include machine-readable developer runtime traces
@@ -703,10 +724,14 @@ class QueryOptions(BaseModel):
             "Ignored when explicit tools are provided."
         ),
     )
-    answer_model_id: str | None = Field(
+    agent_model_id: AgentModelId | str | None = Field(
         default=None,
-        alias="answerModelId",
-        description="Optional answer model ID for final synthesis",
+        alias="agentModelId",
+        description=(
+            "Optional model ID for the main librarian agent loop. Controls the "
+            "merged iterative execution + final response stage; internal tool "
+            "selection remains managed by the server."
+        ),
     )
     response_shape: QueryResponseShape | None = Field(
         default=None,
@@ -714,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(
@@ -1672,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
@@ -1690,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(
@@ -1861,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.16.0 → ctxprotocol-0.18.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ctxprotocol"
-version = "0.16.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.16.0 → ctxprotocol-0.18.0}/tests/test_query.py

@@ -468,7 +468,7 @@ class TestQueryRun:
             mock_stream.return_value = _make_done_stream_response(success_with_data)
             result = await client.query.run(
                 query="Analyze whale activity",
-                answer_model_id="glm-model",
+                agent_model_id="kimi-k2.6-model",
                 response_shape="answer_with_evidence",
                 include_data=True,
                 include_data_url=True,
@@ -482,7 +482,7 @@ class TestQueryRun:
                 "query": "Analyze whale activity",
                 "tools": None,
                 "stream": True,
-                "answerModelId": "glm-model",
+                "agentModelId": "kimi-k2.6-model",
                 "responseShape": "answer_with_evidence",
                 "includeData": True,
                 "includeDataUrl": True,
@@ -571,7 +571,9 @@ class TestQueryRun:
     def test_query_options_supports_public_aliases(self) -> None:
         """QueryOptions accepts supported public aliases."""
         trace_alias = QueryOptions(query="test", includeDeveloperTrace=True)
-        answer_model_alias = QueryOptions(query="test", answerModelId="glm-model")
+        agent_model_alias = QueryOptions(
+            query="test", agentModelId="kimi-k2.6-model"
+        )
         resume_alias = QueryOptions(
             query="test",
             resumeFrom={
@@ -596,10 +598,10 @@ class TestQueryRun:
         assert (
             trace_alias.model_dump(by_alias=True)["includeDeveloperTrace"] is True
         )
-        assert answer_model_alias.answer_model_id == "glm-model"
+        assert agent_model_alias.agent_model_id == "kimi-k2.6-model"
         assert (
-            answer_model_alias.model_dump(by_alias=True)["answerModelId"]
-            == "glm-model"
+            agent_model_alias.model_dump(by_alias=True)["agentModelId"]
+            == "kimi-k2.6-model"
         )
         assert response_shape_alias.response_shape == "evidence_only"
         assert (
@@ -1216,7 +1218,7 @@ class TestQueryStream:
             events = []
             async for event in client.query.stream(
                 query="test",
-                answer_model_id="claude-sonnet-model",
+                agent_model_id="claude-sonnet-model",
                 include_data=True,
                 include_data_url=True,
                 include_developer_trace=True,
@@ -1225,7 +1227,7 @@ class TestQueryStream:
 
         call_kwargs = mock_stream.call_args
         assert (
-            call_kwargs[1]["json_body"]["answerModelId"]
+            call_kwargs[1]["json_body"]["agentModelId"]
             == "claude-sonnet-model"
         )
         assert call_kwargs[1]["json_body"]["includeData"] is True
@@ -1464,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.16.0 → ctxprotocol-0.18.0}/uv.lock

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