fix(api): syntactical sugar for json types (#37)

Author: windsornguyen

CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## 0.2.0 (2025-12-18)
+
+Full Changelog: [v0.2.0...v0.2.0](https://github.com/dedalus-labs/dedalus-sdk-python/compare/v0.2.0...v0.2.0)
+
+### Features
+
+* add image edits/variation and vision format support ([f8a8c84](https://github.com/dedalus-labs/dedalus-sdk-python/commit/f8a8c84f3379d92619de56929d6ad3048989b18c))
+* **api:** add endpoints ([c10d7b5](https://github.com/dedalus-labs/dedalus-sdk-python/commit/c10d7b55a8ec6bb82556b3efe4db20c91959131d))
+* **api:** add streaming ([745c331](https://github.com/dedalus-labs/dedalus-sdk-python/commit/745c33166a671b79a978961d576064618cc80bcb))
+* **api:** add streaming configuration ([0172ad5](https://github.com/dedalus-labs/dedalus-sdk-python/commit/0172ad5175dd15650252a084f213b16c56b8befc))
+* **api:** api update ([280a595](https://github.com/dedalus-labs/dedalus-sdk-python/commit/280a595b3d3900625cfdf26be12027a88eff9618))
+* **api:** auto exec tools ([780162b](https://github.com/dedalus-labs/dedalus-sdk-python/commit/780162b01d27703bb873488702ebede232791ed2))
+* **api:** config update for dedalus-ai/dev ([34e7a71](https://github.com/dedalus-labs/dedalus-sdk-python/commit/34e7a7167f6db94bb7c8c10a7c11746656aec5a6))
+* **api:** config update for dedalus-ai/dev ([197d11b](https://github.com/dedalus-labs/dedalus-sdk-python/commit/197d11bf57da500e05cde2861146da9e3ec278f3))
+* **api:** convenient bug reporting ux ([5aa032f](https://github.com/dedalus-labs/dedalus-sdk-python/commit/5aa032f24a9fe44d23cfbf83f12fc79104529c8d))
+* **api:** image support ([ca28133](https://github.com/dedalus-labs/dedalus-sdk-python/commit/ca281334db05ac2e939436050d1cf70ca5359ab4))
+* **api:** improve types ([62cf7e1](https://github.com/dedalus-labs/dedalus-sdk-python/commit/62cf7e1a643cda58ee5112a1a8fc35253fe50f07))
+* **api:** manual updates ([9bb6d0d](https://github.com/dedalus-labs/dedalus-sdk-python/commit/9bb6d0d0433111d177410f7ff21d3de254d899a0))
+* **api:** manual updates ([9b2851a](https://github.com/dedalus-labs/dedalus-sdk-python/commit/9b2851a6bdbf861c0db0b01aa3e7a8f5a45bfa77))
+* **api:** mcp server params ([bf78aad](https://github.com/dedalus-labs/dedalus-sdk-python/commit/bf78aad94d159622460b3a9ecddb9c5d1e1c82bb))
+* **api:** messages param nullable ([e905235](https://github.com/dedalus-labs/dedalus-sdk-python/commit/e9052357b7efa9d49b4f8b8d4c7dfc026d69414b))
+* **api:** response format ([660ac29](https://github.com/dedalus-labs/dedalus-sdk-python/commit/660ac2954efc08eaed5212da934203b5b80f522e))
+* **api:** revert streaming for now ([56d57d5](https://github.com/dedalus-labs/dedalus-sdk-python/commit/56d57d5a19034eec13d5a98a86d133d36ac2830a))
+* **api:** schema compiler landed ([9aeb7a7](https://github.com/dedalus-labs/dedalus-sdk-python/commit/9aeb7a78bfaa81c07e920268afcacbba4a4ff9c9))
+* **api:** standardize name casing with stainless initialism ([ba1e188](https://github.com/dedalus-labs/dedalus-sdk-python/commit/ba1e188beb62f6def79720d7d2ec8e22853fadaf))
+* **api:** stream helper for pydantic ([c4ab8b0](https://github.com/dedalus-labs/dedalus-sdk-python/commit/c4ab8b0d911b92afe76de99143567e6898e9e95c))
+* **api:** streaming support for structured output ([48ddd0a](https://github.com/dedalus-labs/dedalus-sdk-python/commit/48ddd0a996e99b65fb4635f276a5562ef567ed26))
+* **api:** update via SDK Studio ([9407b44](https://github.com/dedalus-labs/dedalus-sdk-python/commit/9407b44fa8dbd4df7c18c36eab95a5573399810a))
+* **client:** support file upload requests ([caadecd](https://github.com/dedalus-labs/dedalus-sdk-python/commit/caadecdf5c75297819cd41fe3adcc5f7af3de772))
+* encryption ([d72d130](https://github.com/dedalus-labs/dedalus-sdk-python/commit/d72d130279b78fb4f946199a003032001b9c162e))
+* flexible input params for .parse() ([b208fbe](https://github.com/dedalus-labs/dedalus-sdk-python/commit/b208fbed8300526b323ac7c935d6d50bb652f0d3))
+* structured outputs for tools ([b0434ca](https://github.com/dedalus-labs/dedalus-sdk-python/commit/b0434ca32e43dc5ef254e3fecb5493a2d3896384))
+
+
+### Bug Fixes
+
+* **api:** add shared DedalusModel type ([8855a07](https://github.com/dedalus-labs/dedalus-sdk-python/commit/8855a07e4ea638102e71a049e182891e76e3d34d))
+* **api:** add thought signature ([d2203b1](https://github.com/dedalus-labs/dedalus-sdk-python/commit/d2203b129e6b64bbae0b1966654723c2f1ca1159))
+* **api:** docstring truncation ([699f8b9](https://github.com/dedalus-labs/dedalus-sdk-python/commit/699f8b962472ddb4ff2514cc1e515f76ccae5c21))
+* **api:** hardened _compat types ([312b628](https://github.com/dedalus-labs/dedalus-sdk-python/commit/312b628b48d15aaae5b4d2765a75d2b6b830e318))
+* **api:** mcp credential types ([3cdef11](https://github.com/dedalus-labs/dedalus-sdk-python/commit/3cdef112c7f647bcdcca903be56cf89115d47c0a))
+* **api:** relocate parts of auth logic ([a0d8615](https://github.com/dedalus-labs/dedalus-sdk-python/commit/a0d8615f237331f8b79012e9cb5991dc929711d1))
+* **api:** standardize to use automatic_tool_execution ([731f753](https://github.com/dedalus-labs/dedalus-sdk-python/commit/731f753421de4a90b775fff8bee210d3aaf29a21))
+* **api:** typed json objects ([db161b2](https://github.com/dedalus-labs/dedalus-sdk-python/commit/db161b27ca2608d08a915323ced9d76fab6263bb))
+* **api:** typed json objects ([6dbc75d](https://github.com/dedalus-labs/dedalus-sdk-python/commit/6dbc75dc331cd2542e19aa7d2cc530dd091d7e65))
+* **client:** close streams without requiring full consumption ([24c4190](https://github.com/dedalus-labs/dedalus-sdk-python/commit/24c4190ccb71d2c369b3d79f5764be31f2e8ead7))
+* compat with Python 3.14 ([aacb192](https://github.com/dedalus-labs/dedalus-sdk-python/commit/aacb192910f8bdd09625f098874cf54d3c0c0971))
+* **compat:** update signatures of `model_dump` and `model_dump_json` for Pydantic v1 ([bd1df12](https://github.com/dedalus-labs/dedalus-sdk-python/commit/bd1df12d6c26ad35101bd7b181f33ee8f7fe75ce))
+* ensure streams are always closed ([e0e6406](https://github.com/dedalus-labs/dedalus-sdk-python/commit/e0e6406dc5faeaae21286324d4d247e2706481e1))
+* import paths and tests ([70c967f](https://github.com/dedalus-labs/dedalus-sdk-python/commit/70c967f97d9479307128d6215731a8296bf3fa18))
+* mcp auth types ([7eca858](https://github.com/dedalus-labs/dedalus-sdk-python/commit/7eca858a6967eb789ef1282b28ec63971c2975dd))
+* runner tool calling mechanics ([a07f8eb](https://github.com/dedalus-labs/dedalus-sdk-python/commit/a07f8ebd7d65d9a054bba7838443da90f396762d))
+* **runner:** import and dict issues ([fd500d6](https://github.com/dedalus-labs/dedalus-sdk-python/commit/fd500d6c9ba7c503bfecbf7a3c53b8eaef149d59))
+* **runner:** narrow mcp types ([172b56b](https://github.com/dedalus-labs/dedalus-sdk-python/commit/172b56b0ff518004f1bfb65fd0c28dca3215b026))
+* **runner:** use TypeAlias from typing_extensions for py3.9+ support ([0625b2c](https://github.com/dedalus-labs/dedalus-sdk-python/commit/0625b2c9cd7569140fb81848b9d77bbbfbe256b9))
+* **streaming:** correct stream type detection ([7b6576c](https://github.com/dedalus-labs/dedalus-sdk-python/commit/7b6576c23400bca2420e6782defa633b0f3dbff9))
+* **tests:** update bug reporting parameters/paths ([3838ebe](https://github.com/dedalus-labs/dedalus-sdk-python/commit/3838ebe4db440a852c233cd2a96c2b7a4f0c4082))
+* tool call format and custom_auth validation ([b822aa2](https://github.com/dedalus-labs/dedalus-sdk-python/commit/b822aa214cbf0f735c4480a156639888a80956b1))
+* **types:** allow pyright to infer TypedDict types within SequenceNotStr ([624e2b6](https://github.com/dedalus-labs/dedalus-sdk-python/commit/624e2b67c3b784d64548fb6a3ebde7283b593279))
+* **types:** remove manual DedalusModel ([e1ce236](https://github.com/dedalus-labs/dedalus-sdk-python/commit/e1ce236b931b0715b9fa280ef329bfa451eb05c1))
+* use async_to_httpx_files in patch method ([056ef78](https://github.com/dedalus-labs/dedalus-sdk-python/commit/056ef7802bda00b3037af8d745776e4aa836ba8c))
+
+
+### Chores
+
+* add missing docstrings ([52ded59](https://github.com/dedalus-labs/dedalus-sdk-python/commit/52ded5987a0cd141499157a3bf9804fe342e5494))
+* **api:** point local dev to 4010 port for prism ([ad0ec37](https://github.com/dedalus-labs/dedalus-sdk-python/commit/ad0ec3766423c5e6374a96afe55bf415a9c2792c))
+* **api:** rename MCPToolExecution -> MCPToolResult ([973611a](https://github.com/dedalus-labs/dedalus-sdk-python/commit/973611a9f411002a00f5b703b30d44c3b2de450a))
+* **auth:** add minor auth params ([c39bcfc](https://github.com/dedalus-labs/dedalus-sdk-python/commit/c39bcfc6366411658cc12e81b5f473176a26fad3))
+* bump `httpx-aiohttp` version to 0.1.9 ([6b5f606](https://github.com/dedalus-labs/dedalus-sdk-python/commit/6b5f60653d76bfe6b4a85d841f115d59c5eba976))
+* bump required `uv` version ([cb3f674](https://github.com/dedalus-labs/dedalus-sdk-python/commit/cb3f674dbc9f6392493de7984bcd5fee385adfa0))
+* **deps:** mypy 1.18.1 has a regression, pin to 1.17 ([cb4d323](https://github.com/dedalus-labs/dedalus-sdk-python/commit/cb4d3232c845b60eeccd23efa06057c8408085f5))
+* **docs:** use environment variables for authentication in code snippets ([e4330c0](https://github.com/dedalus-labs/dedalus-sdk-python/commit/e4330c0db0f371c49f320ffb6f8238da0229f890))
+* **internal/tests:** avoid race condition with implicit client cleanup ([0854f1d](https://github.com/dedalus-labs/dedalus-sdk-python/commit/0854f1d8f52ad5d75c2da1781358f96543793c02))
+* **internal:** add missing files argument to base client ([f3a6008](https://github.com/dedalus-labs/dedalus-sdk-python/commit/f3a60083b1a37c3bb798e8c07b97af5f04c16b0d))
+* **internal:** avoid using unstable Python versions in tests ([5905b55](https://github.com/dedalus-labs/dedalus-sdk-python/commit/5905b553aaacf8ef4512d851d68b0e0eb7bc647c))
+* **internal:** codegen related update ([d288b0b](https://github.com/dedalus-labs/dedalus-sdk-python/commit/d288b0b4f8098c0aab0d79d45f27fd7b7cd8d127))
+* **internal:** detect missing future annotations with ruff ([6909c09](https://github.com/dedalus-labs/dedalus-sdk-python/commit/6909c09996be7fe019ec6737a18b7e330b325c4a))
+* **internal:** grammar fix (it's -> its) ([f0c5880](https://github.com/dedalus-labs/dedalus-sdk-python/commit/f0c58800e495c0cd5c1f13a9799e8e2025154a1c))
+* **package:** drop Python 3.8 support ([ef5e794](https://github.com/dedalus-labs/dedalus-sdk-python/commit/ef5e794d49c800706eeb693170ea4a3ac0245290))
+* remove custom code ([81f922b](https://github.com/dedalus-labs/dedalus-sdk-python/commit/81f922b8eabc571abf4cfd1b87e08517b4564128))
+* **repo:** update contributing doc and mock test script ([fd52f5a](https://github.com/dedalus-labs/dedalus-sdk-python/commit/fd52f5acd095279bd26d647ee3f93c2daf7977df))
+* tidy protocol docstrings ([99c65f6](https://github.com/dedalus-labs/dedalus-sdk-python/commit/99c65f6f3f89f1958a94f5aaa0daf9511aafbcd1))
+* tidying ([354f95b](https://github.com/dedalus-labs/dedalus-sdk-python/commit/354f95b1efde6b3df27275b3b8a36510f28d1858))
+* update lockfile ([46f1379](https://github.com/dedalus-labs/dedalus-sdk-python/commit/46f13790651a2c284d50c414556fee925c7ff089))
+
+
+### Refactors
+
+* **api:** types for mcp server serialization ([2f614ca](https://github.com/dedalus-labs/dedalus-sdk-python/commit/2f614ca5493c9d57807aea9105e77a66c4703130))
+* **api:** update auth types ([9b17190](https://github.com/dedalus-labs/dedalus-sdk-python/commit/9b17190b28400652ccbdb3f60499a163168e0b80))
+* **api:** update types ([584fe2a](https://github.com/dedalus-labs/dedalus-sdk-python/commit/584fe2aa544ce99955d1d0a712cb51267e06357d))
+
 ## 0.2.0 (2025-12-12)
 
 Full Changelog: [v0.2.0...v0.2.0](https://github.com/dedalus-labs/dedalus-sdk-python/compare/v0.2.0...v0.2.0)

src/dedalus_labs/_models.py

@@ -23,6 +23,7 @@
 import pydantic
 from pydantic.fields import FieldInfo
 
+
 from ._types import (
     Body,
     IncEx,
@@ -65,6 +66,12 @@
 )
 from ._constants import RAW_RESPONSE_HEADER
 
+# RootModel only exists in Pydantic v2
+if not PYDANTIC_V1:
+    from pydantic import RootModel as _RootModel
+else:
+    _RootModel = None  # type: ignore[assignment]
+
 if TYPE_CHECKING:
     from pydantic_core.core_schema import ModelField, ModelSchema, LiteralSchema, ModelFieldsSchema
 
@@ -541,6 +548,14 @@ def construct_type(*, value: object, type_: object, metadata: Optional[List[Any]
         _, items_type = get_args(type_)  # Dict[_, items_type]
         return {key: construct_type(value=item, type_=items_type) for key, item in value.items()}
 
+    # Handle RootModel specially. It needs value in 'root', not spread as kwargs.
+    if (
+        _RootModel is not None
+        and inspect.isclass(origin)
+        and issubclass(origin, _RootModel)
+    ):
+        return origin.model_construct(root=value)
+
     if (
         not is_literal_type(type_)
         and inspect.isclass(origin)

src/dedalus_labs/lib/mcp/request.py

@@ -17,9 +17,10 @@
 import copy
 import logging
 from dataclasses import dataclass
-from typing import Any, Dict, List, Optional, Sequence, Union
+from typing import Any, Dict, List, Optional, Sequence
 
-from typing_extensions import TypeAlias, TypedDict
+from dedalus_labs.types.shared_params.mcp_server_spec import MCPServerSpec
+from dedalus_labs.types.shared_params.mcp_servers import MCPServerItem
 
 from ..crypto import encrypt_credentials, fetch_encryption_key, fetch_encryption_key_sync
 from .protocols import CredentialProtocol
@@ -34,28 +35,6 @@
 ]
 
 
-# ---------------------------------------------------------------------------
-# Wire format types (TODO: will be replaced post-SDK-regen)
-# ---------------------------------------------------------------------------
-
-
-class MCPServerSpecWire(TypedDict, total=False):
-    """Wire format for MCPServerSpec matching API schema.
-
-    Either slug or url is required. Name is required when credentials are embedded.
-    """
-
-    slug: str
-    url: str
-    name: str
-    version: str
-    credentials: Dict[str, str]  # Encrypted credential blobs keyed by connection name
-
-
-# Serialized server: either a slug string or a structured spec
-MCPServerWire: TypeAlias = Union[str, MCPServerSpecWire]
-
-
 @dataclass(frozen=True)
 class EncryptedCredentials:
     """Map of connection names to encrypted envelopes (base64url).
@@ -188,9 +167,9 @@ def _encrypt_credentials(
 
 
 def _embed_credentials(
-    servers: List[MCPServerWire],
+    servers: List[MCPServerItem],
     encrypted: EncryptedCredentials,
-) -> List[MCPServerSpecWire]:
+) -> List[MCPServerSpec]:
     """Embed encrypted credentials into each server spec.
 
     Converts slug strings to full specs and adds credentials to all servers.
@@ -200,11 +179,11 @@ def _embed_credentials(
         encrypted: EncryptedCredentials instance.
 
     Returns:
-        List of MCPServerSpecWire dicts with credentials embedded.
+        List of MCPServerSpec dicts with credentials embedded.
 
     """
     creds_dict = encrypted.to_dict()
-    result: List[MCPServerSpecWire] = []
+    result: List[MCPServerSpec] = []
 
     for server in servers:
         if isinstance(server, str):
@@ -217,7 +196,7 @@ def _embed_credentials(
         elif isinstance(server, dict):
             # Existing spec -> add name (if missing) and credentials
             name = server.get("name") or server.get("slug") or server.get("url") or ""
-            spec: MCPServerSpecWire = {**server, "name": name, "credentials": creds_dict}
+            spec: MCPServerSpec = {**server, "name": name, "credentials": creds_dict}
             result.append(spec)
 
     return result

src/dedalus_labs/lib/runner/core.py

@@ -28,7 +28,8 @@
 
 from ..._client import Dedalus, AsyncDedalus
 
-from .types import Message, ToolCall, JsonValue, ToolResult, PolicyInput, PolicyContext, MCPToolResult
+from .types import Message, ToolCall, JsonValue, ToolResult, PolicyInput, PolicyContext
+from ...types.shared import MCPToolResult
 from ..mcp import serialize_mcp_servers, MCPServerProtocol
 
 # Type alias for mcp_servers parameter - accepts strings, server objects, or mixed lists
@@ -65,41 +66,14 @@ def _process_policy(
 
 
 def _extract_mcp_results(response: Any) -> list[MCPToolResult]:
-    """Extract MCP tool execution results from API response."""
-    mcp_execs = getattr(response, 'mcp_tool_executions', None)
-    if not mcp_execs:
-        # Try __pydantic_extra__ for extra fields not in schema
-        extra = getattr(response, '__pydantic_extra__', None)
-        if isinstance(extra, dict):
-            mcp_execs = extra.get('mcp_tool_executions')
-    if not mcp_execs:
+    """Extract MCP tool results from API response."""
+    mcp_results = getattr(response, 'mcp_tool_results', None)
+    if not mcp_results:
         return []
-
-    results: list[MCPToolResult] = []
-    for exec_data in mcp_execs:
-        try:
-            # Handle both dict and object access
-            if isinstance(exec_data, dict):
-                results.append(MCPToolResult(
-                    tool_name=exec_data.get('tool_name', ''),
-                    server_name=exec_data.get('server_name', ''),
-                    arguments=exec_data.get('arguments', {}),
-                    result=exec_data.get('result'),
-                    is_error=exec_data.get('is_error', False),
-                    duration_ms=exec_data.get('duration_ms'),
-                ))
-            else:
-                results.append(MCPToolResult(
-                    tool_name=getattr(exec_data, 'tool_name', ''),
-                    server_name=getattr(exec_data, 'server_name', ''),
-                    arguments=getattr(exec_data, 'arguments', {}),
-                    result=getattr(exec_data, 'result', None),
-                    is_error=getattr(exec_data, 'is_error', False),
-                    duration_ms=getattr(exec_data, 'duration_ms', None),
-                ))
-        except Exception:
-            continue
-    return results
+    return [
+        item if isinstance(item, MCPToolResult) else MCPToolResult.model_validate(item)
+        for item in mcp_results
+    ]
 
 
 class _ToolHandler(Protocol):
@@ -198,7 +172,7 @@ class _RunResult:
     intents: list[Dict[str, JsonValue]] | None = None
     tools_called: list[str] = field(default_factory=list)
     mcp_results: list[MCPToolResult] = field(default_factory=list)
-    """MCP tool execution results from server-side tool calls."""
+    """MCP tool results from server-side tool calls."""
 
     @property
     def output(self) -> str:

src/dedalus_labs/lib/runner/types/__init__.py

@@ -6,7 +6,7 @@
 
 from __future__ import annotations
 
-from .tools import Tool, ToolCall, JsonValue, ToolResult, ToolHandler, MCPToolResult
+from .tools import Tool, ToolCall, JsonValue, ToolResult, ToolHandler
 from .policy import PolicyInput, PolicyContext, PolicyFunction
 from .messages import Message
 
@@ -19,7 +19,6 @@
     "PolicyInput",
     # Tools
     "JsonValue",
-    "MCPToolResult",
     "Tool",
     "ToolCall",
     "ToolHandler",

src/dedalus_labs/lib/runner/types/tools.py

@@ -6,7 +6,6 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
 from typing import Any, Dict, List, Union, Callable, Protocol
 from typing_extensions import TypeAlias
 
@@ -16,7 +15,6 @@
     "ToolResult",
     "ToolHandler",
     "JsonValue",
-    "MCPToolResult",
 ]
 
 JsonValue: TypeAlias = Union[str, int, float, bool, None, Dict[str, Any], List[Any]]
@@ -26,34 +24,6 @@
 ToolResult = Dict[str, Union[str, int, JsonValue]]
 
 
-@dataclass
-class MCPToolResult:
-    """Result of an MCP tool execution from the API.
-
-    Provides visibility into server-side MCP tool calls including
-    the tool name, server name, input arguments, structured result,
-    error status, and execution timing.
-    """
-
-    tool_name: str
-    """Name of the MCP tool that was executed."""
-
-    server_name: str
-    """Name of the MCP server that handled the tool."""
-
-    arguments: Dict[str, Any]
-    """Input arguments passed to the tool."""
-
-    result: Union[Dict[str, Any], List[Any], str, None]
-    """Structured result from the tool."""
-
-    is_error: bool
-    """Whether the tool execution resulted in an error."""
-
-    duration_ms: int | None = None
-    """Execution time in milliseconds."""
-
-
 class ToolHandler(Protocol):
     """Protocol for tool handlers."""
     def schemas(self) -> List[Dict[str, Any]]: ...