ctxprotocol 0.21.0__tar.gz → 0.22.0__tar.gz

{ctxprotocol-0.21.0 → ctxprotocol-0.22.0}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.22.0
+
+- Added `bounded_explicit_empty_result_guardrail` to the query controller stop-reason literal type so strict consumers no longer fail validation when the platform returns that live stop reason.
+- Platform note (no type change): `computed_artifacts` is now capped at 4 per response by the shared artifact emission policy, so SDK/MCP consumers receive exactly the artifact list the web app displays for the identical run.
+
 ## 0.21.0
 
 - `client.query.run()` is now backed by the durable job path (`start()` + `poll()`) instead of a held-open SSE connection. One call now reliably covers the full 1800s hosted compute ceiling and survives transient connection drops — the "sometimes works, sometimes times out on hard queries" failure mode is gone. `run()` accepts optional `interval_ms` / `timeout_ms` keyword arguments.

{ctxprotocol-0.21.0 → ctxprotocol-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.21.0
+Version: 0.22.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

{ctxprotocol-0.21.0 → ctxprotocol-0.22.0}/ctxprotocol/__init__.py

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

{ctxprotocol-0.21.0 → ctxprotocol-0.22.0}/ctxprotocol/client/types.py

@@ -47,6 +47,7 @@ DEFAULT_AGENT_MODEL_ID = "kimi-k2.6-model"
 AGENT_MODEL_IDS = (
     "kimi-k2.6-model",
     "glm-5.2-model",
+    "grok-4.5-model",
     "deepseek-v4-pro-model",
     "deepseek-v4-flash-model",
     "qwen-3.7-plus-model",
@@ -57,6 +58,7 @@ AGENT_MODEL_IDS = (
 AgentModelId = Literal[
     "kimi-k2.6-model",
     "glm-5.2-model",
+    "grok-4.5-model",
     "deepseek-v4-pro-model",
     "deepseek-v4-flash-model",
     "qwen-3.7-plus-model",
@@ -1461,6 +1463,7 @@ QueryControllerStopReason = Literal[
     "bounded_runtime_budget",
     "bounded_same_endpoint_guardrail",
     "bounded_upstream_abort_guardrail",
+    "bounded_explicit_empty_result_guardrail",
     "capability_miss",
 ]
 QueryControllerIssueClass = Literal[

{ctxprotocol-0.21.0 → ctxprotocol-0.22.0}/pyproject.toml

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

ctxprotocol-0.22.0/scripts/hermes-parity-sanity-check.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""Throwaway Hermes-parity sanity check for ctxprotocol 0.21.0.
+
+Mirrors ~/.hermes/workspace/ctx-gtm/scripts/ctxprotocol-query.py:
+  - same ContextClient timeouts
+  - same query.run() kwargs (no agent_model_id)
+  - same output contract (JSON + CHART_URL + COST_USD)
+
+Reads CONTEXT_API_KEY from context-sdk/.env.local (or env).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+import sys
+
+SDK_QUERY_TIMEOUT = 1860  # Hermes: 1800s ceiling + 60s grace
+FAVORITES_ONLY = os.environ.get("CTX_FAVORITES_ONLY", "true").strip().lower() in (
+    "true",
+    "1",
+    "yes",
+)
+
+DEFAULT_QUERY = (
+    "What is the current price of Bitcoin? One sentence answer, no charts needed."
+)
+
+
+def load_api_key() -> str:
+    candidates = [
+        os.environ.get("CONTEXT_API_KEY"),
+        _read_env_file(
+            os.path.join(
+                os.path.dirname(__file__),
+                "..",
+                "..",
+                "context-sdk",
+                ".env.local",
+            )
+        ),
+        _read_env_file(
+            os.path.expanduser("~/.hermes/.env"),
+        ),
+    ]
+    for value in candidates:
+        if value:
+            return value
+    print(
+        "ERROR: CONTEXT_API_KEY not found in env, context-sdk/.env.local, or ~/.hermes/.env",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+def _read_env_file(path: str) -> str | None:
+    try:
+        with open(os.path.abspath(path)) as handle:
+            for line in handle:
+                line = line.strip()
+                if line.startswith("CONTEXT_API_KEY="):
+                    return line.split("=", 1)[1].strip().strip('"').strip("'")
+    except OSError:
+        return None
+    return None
+
+
+def _chart_urls_from_result(ans) -> list[str]:
+    urls: list[str] = []
+    for art in getattr(ans, "computed_artifacts", None) or []:
+        if getattr(art, "kind", None) == "image":
+            url = getattr(art, "url", None)
+            if url:
+                urls.append(url)
+    if not urls:
+        for text in (getattr(ans, "response", None), getattr(ans, "summary", None)):
+            if not text:
+                continue
+            for match in re.finditer(r"!\[.*?\]\((https?://[^)\s]+)\)", text):
+                urls.append(match.group(1))
+    seen: set[str] = set()
+    deduped: list[str] = []
+    for url in urls:
+        if url not in seen:
+            seen.add(url)
+            deduped.append(url)
+    return deduped
+
+
+def emit(ans) -> None:
+    cost = getattr(ans, "cost", None)
+    total = getattr(cost, "total_cost_usd", None) if cost else None
+    payload = {
+        "response": getattr(ans, "response", None),
+        "summary": getattr(ans, "summary", None),
+        "cost_usd": total,
+        "data_url": getattr(ans, "data_url", None),
+        "tools_used": [
+            {"name": getattr(tool, "name", None), "id": getattr(tool, "id", None)}
+            for tool in (getattr(ans, "tools_used", None) or [])
+        ],
+        "outcome_type": getattr(ans, "outcome_type", None),
+        "stop_reason": getattr(ans, "stop_reason", None),
+        "duration_ms": getattr(ans, "duration_ms", None),
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+    chart_urls = _chart_urls_from_result(ans)
+    if chart_urls:
+        for index, url in enumerate(chart_urls, start=1):
+            print(f"CHART_URL_{index}: {url}")
+    else:
+        print("CHART_URL_1: none")
+    print(f"COST_USD: {total if total is not None else 'unknown'}")
+
+
+async def run_hermes_style_query(question: str) -> None:
+    from ctxprotocol import ContextClient, __version__
+
+    print(f"ctxprotocol version: {__version__}", file=sys.stderr)
+    print(f"favorites_only: {FAVORITES_ONLY}", file=sys.stderr)
+    print(f"query: {question[:120]}{'...' if len(question) > 120 else ''}", file=sys.stderr)
+
+    async with ContextClient(
+        api_key=load_api_key(),
+        request_timeout_seconds=float(SDK_QUERY_TIMEOUT),
+        stream_timeout_seconds=float(SDK_QUERY_TIMEOUT),
+    ) as client:
+        answer = await client.query.run(
+            query=question,
+            response_shape="answer_with_evidence",
+            include_data=False,
+            include_data_url=True,
+            favorites_only=FAVORITES_ONLY,
+        )
+    emit(answer)
+
+
+def main() -> None:
+    question = sys.argv[1] if len(sys.argv) > 1 else DEFAULT_QUERY
+    try:
+        asyncio.run(run_hermes_style_query(question))
+    except Exception as exc:  # noqa: BLE001
+        print(json.dumps({"error": f"{type(exc).__name__}: {exc}"}, indent=2))
+        print("CHART_URL_1: none")
+        print("COST_USD: unknown")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

ctxprotocol-0.22.0/scripts/hermes-parity-stream-check.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Throwaway: same Hermes kwargs but via stream() (direct /api/v1/query SSE).
+
+Use to compare job-backed run() vs held-open sync path on long queries.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+import time
+
+SDK_QUERY_TIMEOUT = 1860
+FAVORITES_ONLY = True
+
+
+def load_api_key() -> str:
+    path = os.path.abspath(
+        os.path.join(os.path.dirname(__file__), "..", "..", "context-sdk", ".env.local")
+    )
+    with open(path) as handle:
+        for line in handle:
+            if line.startswith("CONTEXT_API_KEY="):
+                return line.split("=", 1)[1].strip().strip('"').strip("'")
+    raise SystemExit("CONTEXT_API_KEY missing")
+
+
+async def main() -> None:
+    query_path = sys.argv[1] if len(sys.argv) > 1 else os.path.join(
+        os.path.dirname(__file__), "saudi-oil-query.txt"
+    )
+    with open(query_path) as handle:
+        query = handle.read().strip()
+
+    from ctxprotocol import ContextClient, __version__
+
+    print(f"stream path | ctxprotocol {__version__}", file=sys.stderr)
+    started = time.time()
+    async with ContextClient(
+        api_key=load_api_key(),
+        request_timeout_seconds=float(SDK_QUERY_TIMEOUT),
+        stream_timeout_seconds=float(SDK_QUERY_TIMEOUT),
+    ) as client:
+        result = None
+        async for event in client.query.stream(
+            query=query,
+            response_shape="answer_with_evidence",
+            include_data=False,
+            include_data_url=True,
+            favorites_only=FAVORITES_ONLY,
+        ):
+            if event.type == "done":
+                result = event.result
+            elif event.type == "error":
+                raise RuntimeError(getattr(event, "message", str(event)))
+
+    elapsed = time.time() - started
+    cost = getattr(getattr(result, "cost", None), "total_cost_usd", None)
+    charts = [
+        getattr(art, "url", None)
+        for art in (getattr(result, "computed_artifacts", None) or [])
+        if getattr(art, "kind", None) == "image" and getattr(art, "url", None)
+    ]
+    print(
+        json.dumps(
+            {
+                "elapsed_s": round(elapsed, 1),
+                "stop_reason": getattr(result, "stop_reason", None),
+                "cost_usd": cost,
+                "chart_count": len(charts),
+                "tools_used": [
+                    getattr(t, "name", None)
+                    for t in (getattr(result, "tools_used", None) or [])
+                ],
+                "response_preview": (getattr(result, "response", None) or "")[:800],
+            },
+            indent=2,
+        )
+    )
+    for index, url in enumerate(charts, start=1):
+        print(f"CHART_URL_{index}: {url}")
+    if not charts:
+        print("CHART_URL_1: none")
+    print(f"COST_USD: {cost}")
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except Exception as exc:  # noqa: BLE001
+        print(json.dumps({"error": f"{type(exc).__name__}: {exc}"}, indent=2))
+        print("CHART_URL_1: none")
+        print("COST_USD: unknown")
+        sys.exit(1)

ctxprotocol-0.22.0/scripts/medium-query.txt

@@ -0,0 +1 @@
+Compare the current price and 7-day trend of Bitcoin and Ethereum, and find one prediction market related to Bitcoin's price this year with its current odds. Provide a short verdict on whether crypto positioning looks bullish or bearish. Text only, no charts needed.

ctxprotocol-0.22.0/scripts/saudi-oil-query.txt

@@ -0,0 +1,16 @@
+A news outlet reported: Saudi Arabia slashed the August price of its flagship Arab Light crude for Asia by $11 a barrel — the biggest reduction in at least 26 years. The move reflects weaker oil markets, rising global supply, and intensifying competition among Gulf producers.
+
+I'm crafting a single tweet for a data-driven Twitter account (@ctxprotocol). The tweet needs one compelling data point and a chart that makes someone stop scrolling.
+
+Search your available tools for data relevant to this story. Use whatever tools fit best — prediction markets, equities intelligence, crypto data, crypto positioning, trading intelligence, or any combination. You don't need to use every tool; pick the ones that produce the most insight for THIS specific story.
+
+For each relevant market or asset you find, I need:
+- Current key metrics (oil price, energy stock price, odds, spread, flow — whatever the tool provides)
+- How has the key metric moved over the market's lifetime or let the backend determine the meaningful time range
+- Positioning/flow: who is on which side? Is smart money aligned with or against the narrative?
+- Catalyst date: when does this market resolve, or when is the next event that could move it? Include for every market/asset found.
+- Follow-up assessment: is this worth revisiting in a future post? What event would trigger a followup?
+
+Deliver a verdict: Was the market surprised by this news, or was it already priced in? What is the single most surprising data point? If you synthesized across multiple tools, what does the combined picture reveal that no single tool shows alone?
+
+Analysis and Chart: You are a master quantitative analyst. Based on all the data you've gathered, what is the most meaningful analysis? Create the most compelling possible chart(s). When the data spans multiple distinct dimensions, splitting into focused charts often produces clearer visuals. Each chart should capture one dimension of the story clearly. Charts must have clean labels, readable legends, and professional styling. Include a labeled chart summary for EACH chart produced, describing what data it shows and the key visual takeaway.