release: 0.51.0

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
     runs-on: ${{ github.repository == 'stainless-sdks/mixedbread-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     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
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install Rye
         run: |
@@ -46,7 +46,7 @@ jobs:
       id-token: write
     runs-on: ${{ github.repository == 'stainless-sdks/mixedbread-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install Rye
         run: |
@@ -67,7 +67,7 @@ jobs:
           github.repository == 'stainless-sdks/mixedbread-python' &&
           !startsWith(github.ref, 'refs/heads/stl/')
         id: github-oidc
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           script: core.setOutput('github_token', await core.getIDToken());
 
@@ -87,7 +87,7 @@ jobs:
     runs-on: ${{ github.repository == 'stainless-sdks/mixedbread-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install Rye
         run: |

.github/workflows/publish-pypi.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install Rye
         run: |

.github/workflows/release-doctor.yml

@@ -12,7 +12,7 @@ jobs:
     if: github.repository == 'mixedbread-ai/mixedbread-python' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next')
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Check release environment
         run: |

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.50.0"
+  ".": "0.51.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 55
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/mixedbread%2Fmixedbread-ebd391dad1252eb00dd69ac50455b93bcdcd2cf0177d678e160e47f1d017287f.yml
-openapi_spec_hash: 3bfd5f9eb34711238caef851aa81f5c0
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/mixedbread/mixedbread-b6c2a38a4d1a997676f8b4a63ec3c68ea0c7d72434543e7dcf8bdb5840f31d62.yml
+openapi_spec_hash: 175d3caf13620efd764ff33d192b2d2a
 config_hash: 594a43c9cb8089f079bb9c5442646791

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.51.0 (2026-05-14)
+
+Full Changelog: [v0.50.0...v0.51.0](https://github.com/mixedbread-ai/mixedbread-python/compare/v0.50.0...v0.51.0)
+
+### Features
+
+* **api:** api update ([842efa8](https://github.com/mixedbread-ai/mixedbread-python/commit/842efa840415d1a6d8f754f9c1594655283858c9))
+* **api:** api update ([6fe066e](https://github.com/mixedbread-ai/mixedbread-python/commit/6fe066e17443211a47a21f677344bf8c349e6fde))
+* **api:** api update ([eac4b8f](https://github.com/mixedbread-ai/mixedbread-python/commit/eac4b8f34275c9377765cfe62f677d5ca36cf061))
+* **api:** api update ([66aa7dc](https://github.com/mixedbread-ai/mixedbread-python/commit/66aa7dc394357766b869a3d067e4c130cdf482e8))
+* **internal/types:** support eagerly validating pydantic iterators ([3e9c5ac](https://github.com/mixedbread-ai/mixedbread-python/commit/3e9c5ac9ab56db4eddf8a6a2f219a8789c9c45ac))
+* support setting headers via env ([38de0ee](https://github.com/mixedbread-ai/mixedbread-python/commit/38de0ee2781d9e27d6aecafe89f5a5b5baaed75c))
+
+
+### Bug Fixes
+
+* **client:** add missing f-string prefix in file type error message ([fe74792](https://github.com/mixedbread-ai/mixedbread-python/commit/fe74792cd81bb58bd62e58c086d6d1ee6c233c25))
+* use correct field name format for multipart file arrays ([361fcd6](https://github.com/mixedbread-ai/mixedbread-python/commit/361fcd66f8422020375b076d4c70a83c2b82241d))
+
+
+### Chores
+
+* **internal:** reformat pyproject.toml ([8802c53](https://github.com/mixedbread-ai/mixedbread-python/commit/8802c53023895e9248f03b92477c9a17013ec7b7))
+
 ## 0.50.0 (2026-04-23)
 
 Full Changelog: [v0.49.0...v0.50.0](https://github.com/mixedbread-ai/mixedbread-python/compare/v0.49.0...v0.50.0)

api.md

@@ -1,7 +1,7 @@
 # Shared Types
 
 ```python
-from mixedbread.types import SearchFilter, SearchFilterCondition, Usage
+from mixedbread.types import SearchFilterCondition, Usage
 ```
 
 # Mixedbread

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mixedbread"
-version = "0.50.0"
+version = "0.51.0"
 description = "The official Python library for the Mixedbread API"
 dynamic = ["readme"]
 license = "Apache-2.0"
@@ -168,7 +168,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/mixedbread/_files.py', '_dev/.*.py', 'tests/.*']
+exclude = ["src/mixedbread/_files.py", "_dev/.*.py", "tests/.*"]
 
 strict_equality = true
 implicit_reexport = true

src/mixedbread/_client.py

@@ -27,6 +27,7 @@
 )
 from ._utils import (
     is_given,
+    is_mapping_t,
     maybe_transform,
     get_async_library,
     async_maybe_transform,
@@ -150,6 +151,15 @@ def __init__(
             except KeyError as exc:
                 raise ValueError(f"Unknown environment: {environment}") from exc
 
+        custom_headers_env = os.environ.get("MIXEDBREAD_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,
@@ -547,6 +557,15 @@ def __init__(
             except KeyError as exc:
                 raise ValueError(f"Unknown environment: {environment}") from exc
 
+        custom_headers_env = os.environ.get("MIXEDBREAD_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/mixedbread/_files.py

@@ -99,7 +99,7 @@ async def async_to_httpx_files(files: RequestFiles | None) -> HttpxRequestFiles
     elif is_sequence_t(files):
         files = [(key, await _async_transform_file(file)) for key, file in files]
     else:
-        raise TypeError("Unexpected file type input {type(files)}, expected mapping or sequence")
+        raise TypeError(f"Unexpected file type input {type(files)}, expected mapping or sequence")
 
     return files
 

src/mixedbread/_models.py

@@ -25,7 +25,9 @@
     ClassVar,
     Protocol,
     Required,
+    Annotated,
     ParamSpec,
+    TypeAlias,
     TypedDict,
     TypeGuard,
     final,
@@ -79,7 +81,15 @@
 from ._constants import RAW_RESPONSE_HEADER
 
 if TYPE_CHECKING:
+    from pydantic import GetCoreSchemaHandler, ValidatorFunctionWrapHandler
+    from pydantic_core import CoreSchema, core_schema
     from pydantic_core.core_schema import ModelField, ModelSchema, LiteralSchema, ModelFieldsSchema
+else:
+    try:
+        from pydantic_core import CoreSchema, core_schema
+    except ImportError:
+        CoreSchema = None
+        core_schema = None
 
 __all__ = ["BaseModel", "GenericModel"]
 
@@ -396,6 +406,76 @@ def model_dump_json(
             )
 
 
+class _EagerIterable(list[_T], Generic[_T]):
+    """
+    Accepts any Iterable[T] input (including generators), consumes it
+    eagerly, and validates all items upfront.
+
+    Validation preserves the original container type where possible
+    (e.g. a set[T] stays a set[T]).  Serialization (model_dump / JSON)
+    always emits a list — round-tripping through model_dump() will not
+    restore the original container type.
+    """
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls,
+        source_type: Any,
+        handler: GetCoreSchemaHandler,
+    ) -> CoreSchema:
+        (item_type,) = get_args(source_type) or (Any,)
+        item_schema: CoreSchema = handler.generate_schema(item_type)
+        list_of_items_schema: CoreSchema = core_schema.list_schema(item_schema)
+
+        return core_schema.no_info_wrap_validator_function(
+            cls._validate,
+            list_of_items_schema,
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                cls._serialize,
+                info_arg=False,
+            ),
+        )
+
+    @staticmethod
+    def _validate(v: Iterable[_T], handler: "ValidatorFunctionWrapHandler") -> Any:
+        original_type: type[Any] = type(v)
+
+        # Normalize to list so list_schema can validate each item
+        if isinstance(v, list):
+            items: list[_T] = v
+        else:
+            try:
+                items = list(v)
+            except TypeError as e:
+                raise TypeError("Value is not iterable") from e
+
+        # Validate items against the inner schema
+        validated: list[_T] = handler(items)
+
+        # Reconstruct original container type
+        if original_type is list:
+            return validated
+        # str(list) produces the list's repr, not a string built from items,
+        # so skip reconstruction for str and its subclasses.
+        if issubclass(original_type, str):
+            return validated
+        try:
+            return original_type(validated)
+        except (TypeError, ValueError):
+            # If the type cannot be reconstructed, just return the validated list
+            return validated
+
+    @staticmethod
+    def _serialize(v: Iterable[_T]) -> list[_T]:
+        """Always serialize as a list so Pydantic's JSON encoder is happy."""
+        if isinstance(v, list):
+            return v
+        return list(v)
+
+
+EagerIterable: TypeAlias = Annotated[Iterable[_T], _EagerIterable]
+
+
 def _construct_field(value: object, field: FieldInfo, key: str) -> object:
     if value is None:
         return field_get_default(field)

src/mixedbread/_qs.py

@@ -2,17 +2,13 @@
 
 from typing import Any, List, Tuple, Union, Mapping, TypeVar
 from urllib.parse import parse_qs, urlencode
-from typing_extensions import Literal, get_args
+from typing_extensions import get_args
 
-from ._types import NotGiven, not_given
+from ._types import NotGiven, ArrayFormat, NestedFormat, not_given
 from ._utils import flatten
 
 _T = TypeVar("_T")
 
-
-ArrayFormat = Literal["comma", "repeat", "indices", "brackets"]
-NestedFormat = Literal["dots", "brackets"]
-
 PrimitiveData = Union[str, int, float, bool, None]
 # this should be Data = Union[PrimitiveData, "List[Data]", "Tuple[Data]", "Mapping[str, Data]"]
 # https://github.com/microsoft/pyright/issues/3555

src/mixedbread/_types.py

@@ -47,6 +47,9 @@
 ModelT = TypeVar("ModelT", bound=pydantic.BaseModel)
 _T = TypeVar("_T")
 
+ArrayFormat = Literal["comma", "repeat", "indices", "brackets"]
+NestedFormat = Literal["dots", "brackets"]
+
 
 # Approximates httpx internal ProxiesTypes and RequestFiles types
 # while adding support for `PathLike` instances