ctxprotocol 0.15.0__tar.gz → 0.17.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.15.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
@@ -125,12 +125,12 @@ result = await client.tools.execute(
 print(result.session)  # method_price, spent, remaining, max_spend, ...
 ```
 
-**Query mode** gives you a managed librarian contract — the server runs the live pipeline (`discover -> select -> iterative execute -> synthesize -> settle`) with model-aware context budgeting and can return plain answers or structured evidence packages for one flat fee:
+**Query mode** gives you a managed librarian contract — the server runs the live pipeline (`discover -> select -> iterative execute -> synthesize -> settle`) with model-aware context budgeting and returns structured evidence packages for one flat fee:
 ```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
-    response_shape="answer_with_evidence",  # optional: answer | answer_with_evidence | evidence_only
+    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**.
@@ -156,9 +165,8 @@ print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 
 `response_shape` options:
 
-- `answer`: backward-compatible prose answer
-- `answer_with_evidence`: prose plus `summary`, `evidence`, `artifacts`, `freshness`, `confidence`, `usage`, `outcome`, and `controller`
-- `evidence_only`: machine-friendly summary plus the same evidence package for downstream agents
+- `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)
 
 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`.
 
@@ -298,9 +306,9 @@ 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`, `answer_with_evidence`, or `evidence_only`).
+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`).
 
 `client.query.run()` buffers the same SSE transport used by `client.query.stream()` and returns the final `done` result. This keeps Python aligned with the TypeScript SDK and the live query runtime.
 
@@ -318,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
@@ -341,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.15.0 → ctxprotocol-0.17.0}/README.md

@@ -87,12 +87,12 @@ result = await client.tools.execute(
 print(result.session)  # method_price, spent, remaining, max_spend, ...
 ```
 
-**Query mode** gives you a managed librarian contract — the server runs the live pipeline (`discover -> select -> iterative execute -> synthesize -> settle`) with model-aware context budgeting and can return plain answers or structured evidence packages for one flat fee:
+**Query mode** gives you a managed librarian contract — the server runs the live pipeline (`discover -> select -> iterative execute -> synthesize -> settle`) with model-aware context budgeting and returns structured evidence packages for one flat fee:
 ```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
-    response_shape="answer_with_evidence",  # optional: answer | answer_with_evidence | evidence_only
+    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**.
@@ -118,9 +127,8 @@ print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 
 `response_shape` options:
 
-- `answer`: backward-compatible prose answer
-- `answer_with_evidence`: prose plus `summary`, `evidence`, `artifacts`, `freshness`, `confidence`, `usage`, `outcome`, and `controller`
-- `evidence_only`: machine-friendly summary plus the same evidence package for downstream agents
+- `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)
 
 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`.
 
@@ -260,9 +268,9 @@ 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`, `answer_with_evidence`, or `evidence_only`).
+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`).
 
 `client.query.run()` buffers the same SSE transport used by `client.query.stream()` and returns the final `done` result. This keeps Python aligned with the TypeScript SDK and the live query runtime.
 
@@ -280,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
@@ -303,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.15.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.15.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.15.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,8 +216,9 @@ 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
-            response_shape: Structured response mode for query answers
+            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
             include_data_url: Persist execution data to blob and return URL
             include_developer_trace: Include machine-readable Developer Mode traces
@@ -252,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,
@@ -281,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,
@@ -303,8 +305,9 @@ 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
-            response_shape: Structured response mode for query answers
+            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
             include_data_url: Persist execution data to blob and return URL
             include_developer_trace: Include machine-readable Developer Mode traces
@@ -343,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.15.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):
@@ -601,7 +628,7 @@ class ExecuteSessionResult(BaseModel):
 # from the query; this is a soft hint rather than a hard switch.
 QueryDepth = Literal["fast", "auto", "deep"]
 QueryOutcomeType = Literal["answer", "capability_miss"]
-QueryResponseShape = Literal["answer", "answer_with_evidence", "evidence_only"]
+QueryResponseShape = Literal["answer_with_evidence", "evidence_only"]
 QueryAttemptForkReason = Literal[
     "manual_fork",
     "bounded_rediscovery",
@@ -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,22 +730,27 @@ 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,
         alias="responseShape",
         description=(
-            "Structured response mode. The runtime always produces a grounded "
-            "result (raw data + computed artifacts + provenance); this controls "
-            "whether a prose synthesis layer is added on top. "
+            "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. "
             "`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); `answer` is the legacy prose-only shape."
+            "grounding by default)."
         ),
     )
     include_data: bool | None = Field(

{ctxprotocol-0.15.0 → ctxprotocol-0.17.0}/examples/server/hummingbot-contributor/requirements.txt

@@ -14,7 +14,7 @@ uvicorn[standard]>=0.30.0
 hummingbot-api-client>=1.2.6
 
 # Context Protocol SDK for payment verification
-ctxprotocol>=0.8.3
+ctxprotocol>=0.16.0
 
 # Environment management
 python-dotenv>=1.0.0

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

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