release: 0.4.0

.github/workflows/ci.yml

@@ -1,12 +1,14 @@
 name: CI
 on:
   push:
-    branches-ignore:
-      - 'generated'
-      - 'codegen/**'
-      - 'integrated/**'
-      - 'stl-preview-head/**'
-      - 'stl-preview-base/**'
+    branches:
+      - '**'
+      - '!integrated/**'
+      - '!stl-preview-head/**'
+      - '!stl-preview-base/**'
+      - '!generated'
+      - '!codegen/**'
+      - 'codegen/stl/**'
   pull_request:
     branches-ignore:
       - 'stl-preview-head/**'
@@ -17,7 +19,7 @@ jobs:
     timeout-minutes: 10
     name: lint
     runs-on: ${{ github.repository == 'stainless-sdks/dedalus-sdk-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     steps:
       - uses: actions/checkout@v6
 
@@ -33,7 +35,7 @@ jobs:
         run: ./scripts/lint
 
   build:
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     timeout-minutes: 10
     name: build
     permissions:
@@ -55,14 +57,18 @@ jobs:
         run: uv build
 
       - name: Get GitHub OIDC Token
-        if: github.repository == 'stainless-sdks/dedalus-sdk-python'
+        if: |-
+          github.repository == 'stainless-sdks/dedalus-sdk-python' &&
+          !startsWith(github.ref, 'refs/heads/stl/')
         id: github-oidc
         uses: actions/github-script@v8
         with:
           script: core.setOutput('github_token', await core.getIDToken());
 
       - name: Upload tarball
-        if: github.repository == 'stainless-sdks/dedalus-sdk-python'
+        if: |-
+          github.repository == 'stainless-sdks/dedalus-sdk-python' &&
+          !startsWith(github.ref, 'refs/heads/stl/')
         env:
           URL: https://pkg.stainless.com/s
           AUTH: ${{ steps.github-oidc.outputs.github_token }}

.gitignore

@@ -1,4 +1,5 @@
 .prism.log
+.stdy.log
 _dev
 
 __pycache__

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.3.0"
+  ".": "0.4.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 12
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/dedalus-labs%2Fdedalus-sdk-78928123e88f6699e87022537ef23c34c0a802c5b78ac0c5259b30b59371492e.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/dedalus-labs/dedalus-sdk-c82d44d0a47f030d4de74379ae24619a50ace0d8740ccbd92b2a1a98db054e94.yml
 openapi_spec_hash: 50b6107b70d1a6367726f78a04af5493
-config_hash: b57dddec045c6790044b72c73f0d1891
+config_hash: bd51a8c451379aa0f2d3030a24074a3f

CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 0.4.0 (2026-04-30)
+
+Full Changelog: [v0.3.0...v0.4.0](https://github.com/dedalus-labs/dedalus-sdk-python/compare/v0.3.0...v0.4.0)
+
+### Features
+
+* **internal:** implement indices array format for query and form serialization ([04ba964](https://github.com/dedalus-labs/dedalus-sdk-python/commit/04ba9644e8c73b3eff7b8ad01211d90e354a889d))
+* support setting headers via env ([e773bb2](https://github.com/dedalus-labs/dedalus-sdk-python/commit/e773bb29d5221a76cdc2b8a38f430920dd821b13))
+
+
+### Bug Fixes
+
+* **client:** preserve hardcoded query params when merging with user params ([80f3981](https://github.com/dedalus-labs/dedalus-sdk-python/commit/80f3981cb6e10bd7a9dbe39412abbd6277b0ab64))
+* **deps:** bump minimum typing-extensions version ([23ea212](https://github.com/dedalus-labs/dedalus-sdk-python/commit/23ea21291b2cf443c594661acfc6e19e95077162))
+* ensure file data are only sent as 1 parameter ([721e574](https://github.com/dedalus-labs/dedalus-sdk-python/commit/721e5748d4843fe0f6dbf07c34766550d09ab05e))
+* **pydantic:** do not pass `by_alias` unless set ([b098b05](https://github.com/dedalus-labs/dedalus-sdk-python/commit/b098b05e30ec6487a6467bd928ce3c725d3f2aa0))
+* sanitize endpoint path params ([e385e21](https://github.com/dedalus-labs/dedalus-sdk-python/commit/e385e215a38c3141ff675a58799511a306d2c879))
+* use correct field name format for multipart file arrays ([a6664c3](https://github.com/dedalus-labs/dedalus-sdk-python/commit/a6664c3564abb8c0e50bd11b36477875f328a88b))
+
+
+### Performance Improvements
+
+* **client:** optimize file structure copying in multipart requests ([43970d6](https://github.com/dedalus-labs/dedalus-sdk-python/commit/43970d6a440ff547be0c90130b75b7483ad7711e))
+
+
+### Chores
+
+* **ci:** remove release-doctor workflow ([5903593](https://github.com/dedalus-labs/dedalus-sdk-python/commit/5903593748f7cf140310fb0fe057879323e12d67))
+* **ci:** skip lint on metadata-only changes ([e11e58f](https://github.com/dedalus-labs/dedalus-sdk-python/commit/e11e58faac2c22be4f6e642b7313d09286b4a651))
+* **ci:** skip uploading artifacts on stainless-internal branches ([e3ed836](https://github.com/dedalus-labs/dedalus-sdk-python/commit/e3ed83614aa445a6af6d48fbab67edd96d651123))
+* **internal:** more robust bootstrap script ([a84687b](https://github.com/dedalus-labs/dedalus-sdk-python/commit/a84687b42b2b794198e05bb48f61d163fa3ed2c2))
+* **internal:** reformat pyproject.toml ([84db3a8](https://github.com/dedalus-labs/dedalus-sdk-python/commit/84db3a8481a68a4e26b7694578e5c77f76d21972))
+* **internal:** tweak CI branches ([1fc1ee4](https://github.com/dedalus-labs/dedalus-sdk-python/commit/1fc1ee460877941fb648448a415b37f868093058))
+* **internal:** update gitignore ([97672af](https://github.com/dedalus-labs/dedalus-sdk-python/commit/97672afab610a2fa4dcc7224dbad013b10553089))
+* update placeholder string ([3a623d4](https://github.com/dedalus-labs/dedalus-sdk-python/commit/3a623d4779430378efe9ceb6540ba6fddbc70041))
+
+
+### Documentation
+
+* improve examples ([5207295](https://github.com/dedalus-labs/dedalus-sdk-python/commit/5207295286986023ba1afbf6219a88dab046b439))
+* update examples ([62a7347](https://github.com/dedalus-labs/dedalus-sdk-python/commit/62a7347483733a1cdf57454a38af1f521f13ef4d))
+
+
+### Refactors
+
+* **types:** use `extra_items` from PEP 728 ([de6e4e4](https://github.com/dedalus-labs/dedalus-sdk-python/commit/de6e4e466ad9e9f40be8d8d4f7ea6208c076267e))
+
 ## 0.3.0 (2026-02-28)
 
 Full Changelog: [v0.2.0...v0.3.0](https://github.com/dedalus-labs/dedalus-sdk-python/compare/v0.2.0...v0.3.0)

README.md

@@ -219,8 +219,8 @@ client = Dedalus()
 chat_completion = client.chat.completions.create(
     model="openai/gpt-5",
     audio={
-        "format": "wav",
-        "voice": "string",
+        "format": "mp3",
+        "voice": "alloy",
     },
 )
 print(chat_completion.audio)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dedalus_labs"
-version = "0.3.0"
+version = "0.4.0"
 description = "The official Python library for the Dedalus API"
 dynamic = ["readme"]
 license = "MIT"
@@ -11,7 +11,7 @@ authors = [
 dependencies = [
   "httpx>=0.23.0, <1",
   "pydantic>=1.9.0, <3",
-  "typing-extensions>=4.10, <5",
+  "typing-extensions>=4.14, <5",
   "anyio>=3.5.0, <5",
   "distro>=1.7.0, <2",
   "sniffio",
@@ -156,7 +156,7 @@ show_error_codes = true
 #
 # We also exclude our `tests` as mypy doesn't always infer
 # types correctly and Pyright will still catch any type errors.
-exclude = ['src/dedalus_labs/_files.py', '_dev/.*.py', 'tests/.*']
+exclude = ["src/dedalus_labs/_files.py", "_dev/.*.py", "tests/.*"]
 
 strict_equality = true
 implicit_reexport = true

scripts/bootstrap

@@ -4,7 +4,7 @@ set -e
 
 cd "$(dirname "$0")/.."
 
-if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "$SKIP_BREW" != "1" ] && [ -t 0 ]; then
+if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "${SKIP_BREW:-}" != "1" ] && [ -t 0 ]; then
   brew bundle check >/dev/null 2>&1 || {
     echo -n "==> Install Homebrew dependencies? (y/N): "
     read -r response

src/dedalus_labs/_base_client.py

@@ -540,6 +540,10 @@ def _build_request(
                 files = cast(HttpxRequestFiles, ForceMultipartDict())
 
         prepared_url = self._prepare_url(options.url)
+        # preserve hard-coded query params from the url
+        if params and prepared_url.query:
+            params = {**dict(prepared_url.params.items()), **params}
+            prepared_url = prepared_url.copy_with(raw_path=prepared_url.raw_path.split(b"?", 1)[0])
         if "_" in prepared_url.host:
             # work around https://github.com/encode/httpx/discussions/2880
             kwargs["extensions"] = {"sni_hostname": prepared_url.host.replace("_", "-")}

src/dedalus_labs/_client.py

@@ -20,7 +20,11 @@
     RequestOptions,
     not_given,
 )
-from ._utils import is_given, get_async_library
+from ._utils import (
+    is_given,
+    is_mapping_t,
+    get_async_library,
+)
 from ._compat import cached_property
 from ._models import FinalRequestOptions
 from ._version import __version__
@@ -168,6 +172,15 @@ def __init__(
             except KeyError as exc:
                 raise ValueError(f"Unknown environment: {environment}") from exc
 
+        custom_headers_env = os.environ.get("DEDALUS_CUSTOM_HEADERS")
+        if custom_headers_env is not None:
+            parsed: dict[str, str] = {}
+            for line in custom_headers_env.split("\n"):
+                colon = line.find(":")
+                if colon >= 0:
+                    parsed[line[:colon].strip()] = line[colon + 1 :].strip()
+            default_headers = {**parsed, **(default_headers if is_mapping_t(default_headers) else {})}
+
         super().__init__(
             version=__version__,
             base_url=base_url,
@@ -495,6 +508,15 @@ def __init__(
             except KeyError as exc:
                 raise ValueError(f"Unknown environment: {environment}") from exc
 
+        custom_headers_env = os.environ.get("DEDALUS_CUSTOM_HEADERS")
+        if custom_headers_env is not None:
+            parsed: dict[str, str] = {}
+            for line in custom_headers_env.split("\n"):
+                colon = line.find(":")
+                if colon >= 0:
+                    parsed[line[:colon].strip()] = line[colon + 1 :].strip()
+            default_headers = {**parsed, **(default_headers if is_mapping_t(default_headers) else {})}
+
         super().__init__(
             version=__version__,
             base_url=base_url,

src/dedalus_labs/_compat.py

@@ -2,7 +2,7 @@
 
 from typing import TYPE_CHECKING, Any, Union, Generic, TypeVar, Callable, cast, overload
 from datetime import date, datetime
-from typing_extensions import Self, Literal
+from typing_extensions import Self, Literal, TypedDict
 
 import pydantic
 from pydantic.fields import FieldInfo
@@ -131,6 +131,10 @@ def model_json(model: pydantic.BaseModel, *, indent: int | None = None) -> str:
     return model.model_dump_json(indent=indent)
 
 
+class _ModelDumpKwargs(TypedDict, total=False):
+    by_alias: bool
+
+
 def model_dump(
     model: pydantic.BaseModel,
     *,
@@ -142,14 +146,17 @@ def model_dump(
     by_alias: bool | None = None,
 ) -> dict[str, Any]:
     if (not PYDANTIC_V1) or hasattr(model, "model_dump"):
+        kwargs: _ModelDumpKwargs = {}
+        if by_alias is not None:
+            kwargs["by_alias"] = by_alias
         return model.model_dump(
             mode=mode,
             exclude=exclude,
             exclude_unset=exclude_unset,
             exclude_defaults=exclude_defaults,
             # warnings are not supported in Pydantic v1
             warnings=True if PYDANTIC_V1 else warnings,
-            by_alias=by_alias,
+            **kwargs,
         )
     return cast(
         "dict[str, Any]",

src/dedalus_labs/_files.py

@@ -3,8 +3,8 @@
 import io
 import os
 import pathlib
-from typing import overload
-from typing_extensions import TypeGuard
+from typing import Sequence, cast, overload
+from typing_extensions import TypeVar, TypeGuard
 
 import anyio
 
@@ -17,7 +17,9 @@
     HttpxFileContent,
     HttpxRequestFiles,
 )
-from ._utils import is_tuple_t, is_mapping_t, is_sequence_t
+from ._utils import is_list, is_mapping, is_tuple_t, is_mapping_t, is_sequence_t
+
+_T = TypeVar("_T")
 
 
 def is_base64_file_input(obj: object) -> TypeGuard[Base64FileInput]:
@@ -121,3 +123,51 @@ async def async_read_file_content(file: FileContent) -> HttpxFileContent:
         return await anyio.Path(file).read_bytes()
 
     return file
+
+
+def deepcopy_with_paths(item: _T, paths: Sequence[Sequence[str]]) -> _T:
+    """Copy only the containers along the given paths.
+
+    Used to guard against mutation by extract_files without copying the entire structure.
+    Only dicts and lists that lie on a path are copied; everything else
+    is returned by reference.
+
+    For example, given paths=[["foo", "files", "file"]] and the structure:
+        {
+            "foo": {
+                "bar": {"baz": {}},
+                "files": {"file": <content>}
+            }
+        }
+    The root dict, "foo", and "files" are copied (they lie on the path).
+    "bar" and "baz" are returned by reference (off the path).
+    """
+    return _deepcopy_with_paths(item, paths, 0)
+
+
+def _deepcopy_with_paths(item: _T, paths: Sequence[Sequence[str]], index: int) -> _T:
+    if not paths:
+        return item
+    if is_mapping(item):
+        key_to_paths: dict[str, list[Sequence[str]]] = {}
+        for path in paths:
+            if index < len(path):
+                key_to_paths.setdefault(path[index], []).append(path)
+
+        # if no path continues through this mapping, it won't be mutated and copying it is redundant
+        if not key_to_paths:
+            return item
+
+        result = dict(item)
+        for key, subpaths in key_to_paths.items():
+            if key in result:
+                result[key] = _deepcopy_with_paths(result[key], subpaths, index + 1)
+        return cast(_T, result)
+    if is_list(item):
+        array_paths = [path for path in paths if index < len(path) and path[index] == "<array>"]
+
+        # if no path expects a list here, nothing will be mutated inside it - return by reference
+        if not array_paths:
+            return cast(_T, item)
+        return cast(_T, [_deepcopy_with_paths(entry, array_paths, index + 1) for entry in item])
+    return item