ctxprotocol 0.16.0__tar.gz → 0.17.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.16.0
+Version: 0.17.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,15 @@ print(
 print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
+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**.
@@ -297,7 +306,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,7 +326,7 @@ 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
+    agent_model_id="kimi-k2.6-model",        # optional main librarian agent model
     include_data=True,                       # optional: include execution data inline
     include_data_url=True,                   # optional: include blob URL for full data
     include_developer_trace=True,            # optional: include Developer Mode trace
@@ -340,7 +349,7 @@ 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.
 
-#### `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.17.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,15 @@ print(
 print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
+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**.
@@ -259,7 +268,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,7 +288,7 @@ 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
+    agent_model_id="kimi-k2.6-model",        # optional main librarian agent model
     include_data=True,                       # optional: include execution data inline
     include_data_url=True,                   # optional: include blob URL for full data
     include_developer_trace=True,            # optional: include Developer Mode trace
@@ -302,7 +311,7 @@ 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.
 
-#### `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.17.0}/ctxprotocol/__init__.py

@@ -31,7 +31,7 @@ Example:
 For more information, visit: https://ctxprotocol.com
 """
 
-__version__ = "0.15.0"
+__version__ = "0.17.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,
@@ -83,6 +85,7 @@ from ctxprotocol.client.types import (
     SearchResponse,
     Tool,
     ToolInfo,
+    AgentModelId,
 )
 
 # Context types for portfolio injection
@@ -178,6 +181,9 @@ __all__ = [
     "ExecuteApiErrorResponse",
     "ExecuteSessionApiSuccessResponse",
     "ToolInfo",
+    "AGENT_MODEL_IDS",
+    "DEFAULT_AGENT_MODEL_ID",
+    "AgentModelId",
     # Query types (pay-per-response)
     "QueryOptions",
     "QueryResult",

{ctxprotocol-0.16.0 → ctxprotocol-0.17.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,
@@ -64,6 +66,7 @@ from ctxprotocol.client.types import (
     SearchResponse,
     Tool,
     ToolInfo,
+    AgentModelId,
 )
 
 __all__ = [
@@ -76,6 +79,9 @@ __all__ = [
     "Query",
     # Types
     "ContextClientOptions",
+    "AGENT_MODEL_IDS",
+    "DEFAULT_AGENT_MODEL_ID",
+    "AgentModelId",
     "Tool",
     "McpTool",
     "McpToolMeta",

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

@@ -14,6 +14,7 @@ from typing import TYPE_CHECKING, Any, AsyncGenerator
 
 from ctxprotocol.client.types import (
     ContextError,
+    AgentModelId,
     QueryAttemptReference,
     QueryDeveloperTrace,
     QueryForkReference,
@@ -193,7 +194,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 +216,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 +254,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,
@@ -282,7 +283,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,
@@ -304,7 +305,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 +346,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.17.0}/ctxprotocol/client/types.py

@@ -43,6 +43,33 @@ 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",
+    "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",
+    "claude-opus-model",
+)
+AgentModelId = Literal[
+    "kimi-k2.6-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",
+    "claude-opus-model",
+]
 
 
 class McpToolRateLimitHints(BaseModel):
@@ -674,7 +701,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 +730,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,

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ctxprotocol"
-version = "0.16.0"
+version = "0.17.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.17.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

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

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