ctxprotocol 0.18.0__tar.gz → 0.19.1__tar.gz

ctxprotocol-0.19.1/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.19.1
+
+- Fixed `client.query.start()` returning `400 "Invalid query job request"` when called without explicit `tools`. The request body builder now omits optional fields (notably `tools`) when unset instead of serializing them as JSON `null`; the durable jobs endpoint's Zod schema rejects `null` for optional fields. `client.query.run()` and `client.query.stream()` were not failing (the `/api/v1/query` endpoint tolerates `null`), but are now consistent with the TS SDK and MCP behavior.
+
+## 0.19.0
+
+- Fixed `client.query.run()`/`client.query.stream()` raising a `ValidationError` on queries that returned a rendered image artifact (e.g. server-rendered chart PNGs). `computedArtifacts` now accepts both `chart` (structured spec + data) and `image` (hosted URL) variants.
+- Added `QueryImageArtifact` (`kind: "image"` with `url`, `alt`, `title`, `content_hash`, `bytes`, `width`, `height`) and made `QueryComputedArtifact` a discriminated union over `kind`.
+- Exported `QueryImageArtifact` from the client entry point alongside `QueryChartArtifact`.
+
+## 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.18.0 → ctxprotocol-0.19.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.18.0
+Version: 0.19.1
 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.18.0 → ctxprotocol-0.19.1}/ctxprotocol/__init__.py

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

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

@@ -44,6 +44,7 @@ from ctxprotocol.client.types import (
     QueryChartType,
     QueryChartValueFormat,
     QueryComputedArtifact,
+    QueryImageArtifact,
     QueryCost,
     QueryCompletenessRepairEvent,
     QueryDeveloperTrace,
@@ -133,6 +134,7 @@ __all__ = [
     "QueryChartType",
     "QueryChartValueFormat",
     "QueryComputedArtifact",
+    "QueryImageArtifact",
     "QueryStreamToolStatusEvent",
     "QueryStreamTextDeltaEvent",
     "QueryStreamDeveloperTraceEvent",

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

@@ -62,8 +62,9 @@ class Query:
     ) -> dict[str, Any]:
         request_body: dict[str, Any] = {
             "query": query,
-            "tools": tools,
         }
+        if tools is not None:
+            request_body["tools"] = tools
         if stream is not None:
             request_body["stream"] = stream
         if resume_from is not None:
@@ -443,9 +444,10 @@ class Query:
         """
         request_body: dict[str, Any] = {
             "query": query,
-            "tools": tools,
             "stream": True,
         }
+        if tools is not None:
+            request_body["tools"] = tools
         if resume_from is not None:
             request_body["resumeFrom"] = (
                 resume_from.model_dump(by_alias=True, exclude_none=True)

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

@@ -6,7 +6,7 @@ This module contains all Pydantic models and type definitions used by the client
 
 from __future__ import annotations
 
-from typing import Any, Literal, Union
+from typing import Annotated, Any, Literal, Union
 
 from pydantic import BaseModel, Field
 
@@ -929,7 +929,31 @@ class QueryChartArtifact(BaseModel):
     title: str | None = None
 
 
-QueryComputedArtifact = QueryChartArtifact
+class QueryImageArtifact(BaseModel):
+    """Rendered image artifact (e.g. a server-rendered chart PNG).
+
+    Emitted by the code interpreter alongside or instead of the structured
+    ``chart`` spec. ``url`` points at a hosted, already-rendered image so
+    consumers that cannot render a chart spec (image-first surfaces such as
+    social posting) can attach it directly.
+    """
+
+    kind: Literal["image"]
+    url: str
+    alt: str | None = None
+    title: str | None = None
+    content_hash: str | None = Field(default=None, alias="contentHash")
+    bytes: int | None = None
+    width: int | None = None
+    height: int | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+QueryComputedArtifact = Annotated[
+    Union[QueryChartArtifact, QueryImageArtifact],
+    Field(discriminator="kind"),
+]
 
 
 class QueryToolCallFailureSample(BaseModel):

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

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

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

@@ -420,7 +420,6 @@ class TestQueryRun:
             method="POST",
             json_body={
                 "query": "What are the top whale movements?",
-                "tools": None,
                 "stream": True,
             },
             extra_headers=None,
@@ -480,7 +479,6 @@ class TestQueryRun:
             method="POST",
             json_body={
                 "query": "Analyze whale activity",
-                "tools": None,
                 "stream": True,
                 "agentModelId": "kimi-k2.6-model",
                 "responseShape": "answer_with_evidence",
@@ -897,6 +895,41 @@ class TestQueryRun:
         assert mixed_axis.spec.series[1].y_axis == "right"
         assert mixed_axis.spec.series[1].satisfies == "volume"
 
+    async def test_parses_rendered_image_artifact(self) -> None:
+        """Rendered image artifacts (kind: image) deserialize without error."""
+        client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
+        response = {
+            **MOCK_SUCCESS_RESPONSE,
+            "computedArtifacts": [
+                {
+                    "kind": "image",
+                    "url": "https://blob.example.com/charts/abc123.png",
+                    "alt": "Sector ETF YTD normalized performance chart",
+                    "title": "Sector ETF YTD Performance",
+                    "contentHash": "abc123",
+                    "bytes": 320749,
+                    "width": 1926,
+                    "height": 1030,
+                },
+            ],
+        }
+        with patch.object(
+            client, "fetch_stream", new_callable=AsyncMock
+        ) as mock_stream:
+            mock_stream.return_value = _make_done_stream_response(response)
+            result = await client.query.run("Render a chart image")
+
+        assert result.computed_artifacts is not None
+        assert len(result.computed_artifacts) == 1
+        image = result.computed_artifacts[0]
+        assert image.kind == "image"
+        assert image.url == "https://blob.example.com/charts/abc123.png"
+        assert image.title == "Sector ETF YTD Performance"
+        assert image.content_hash == "abc123"
+        assert image.bytes == 320749
+        assert image.width == 1926
+        assert image.height == 1030
+
     async def test_parses_shared_ungrounded_capability_miss_fixture(self) -> None:
         """Ungrounded runtime outcomes deserialize as capability_miss."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
@@ -1056,7 +1089,6 @@ class TestQueryStream:
             method="POST",
             json_body={
                 "query": "What are whale movements?",
-                "tools": None,
                 "stream": True,
             },
             extra_headers=None,
@@ -1499,7 +1531,6 @@ class TestQueryJobs:
             method="POST",
             json_body={
                 "query": "long query",
-                "tools": None,
                 "stream": False,
                 "responseShape": "evidence_only",
                 "includeDataUrl": True,
@@ -1509,6 +1540,39 @@ class TestQueryJobs:
             },
         )
 
+    async def test_start_omits_null_optional_fields(self) -> None:
+        """Regression: optional fields must be absent (not JSON null) in the job body.
+
+        The /api/v1/query/jobs endpoint validates the body with a Zod schema whose
+        optional fields accept `undefined`/absent but reject `null`. Sending
+        `"tools": null` (as the SDK previously did) made query.start() 400 with
+        "Invalid query job request". Optional fields must be omitted when unset,
+        matching the TS SDK (JSON.stringify drops undefined keys).
+        """
+        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
+            await client.query.start(query="long query")
+
+        body = mock_fetch.call_args.kwargs["json_body"]
+        # No optional field may serialize to JSON null.
+        assert all(value is not None for value in body.values()), body
+        # tools specifically must be omitted when not supplied (was the 400 trigger).
+        assert "tools" not in body, body
+        # query is always present and non-null.
+        assert body["query"] == "long query"
+
     async def test_get_status_fetches_query_job(self) -> None:
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
         payload = {

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

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

ctxprotocol-0.18.0/CHANGELOG.md

@@ -1,7 +0,0 @@
-# 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.