From defce57d5b9087415bb71ad7362a614fba2d4917 Mon Sep 17 00:00:00 2001 From: Hamilton Truong Date: Thu, 12 Nov 2026 18:40:25 -0800 Subject: [PATCH 1/2] sdk-types: build models on first use (defer_build) Set Pydantic's defer_build on TurnkeyBaseModel so each generated model builds its validator and serializer on first use instead of at import. Only enabled on Pydantic 2.5+; older versions keep the current behavior. Co-Authored-By: Claude Opus 5.5 --- .changeset/sdk-types-defer-build.yml | 10 ++++++++++ codegen/types/generate_types.py | 7 ++++++- .../sdk-types/src/turnkey_sdk_types/generated/types.py | 6 +++++- 3 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 .changeset/sdk-types-defer-build.yml diff --git a/.changeset/sdk-types-defer-build.yml b/.changeset/sdk-types-defer-build.yml new file mode 100644 index 0000000..f958369 --- /dev/null +++ b/.changeset/sdk-types-defer-build.yml @@ -0,0 +1,10 @@ +type: minor +packages: [ sdk-types ] +changelog: |- + Importing `turnkey_sdk_types` is much faster and uses much less memory: each generated model now builds its validator and serializer the first time it's used, instead of all of them at import (Pydantic `defer_build`). On Pydantic 2.14, import takes about 0.2s instead of 2-3s, and memory after import drops from about 276MB to about 50MB. + + This is only enabled on Pydantic 2.5 and later. Behavior is unchanged, with a few things to know: + - The first use of each model takes slightly longer, usually a few milliseconds. Activity response models take about 20ms. + - A process that uses most of the activity response types builds a separate copy of the activity schema for each, so its peak memory can be higher than before (about 520MB with every model built, compared with about 280MB). + - On Pydantic 2.10 and earlier, `Model.model_fields[...].annotation` can show an unresolved `ForwardRef` until the model is first used. Field names, aliases, and defaults are unaffected. Call `Model.model_rebuild()` first if you inspect annotations right after import. + - A model that can't be built would now fail on first use instead of at import. Every current model builds. diff --git a/codegen/types/generate_types.py b/codegen/types/generate_types.py index fe70093..6bf6cae 100644 --- a/codegen/types/generate_types.py +++ b/codegen/types/generate_types.py @@ -441,10 +441,15 @@ def main(): output += "from __future__ import annotations\n" output += "from typing import Any, Dict, List, Optional\n" output += "from enum import Enum\n" + output += "from pydantic import VERSION as _PYDANTIC_VERSION\n" output += "from pydantic import BaseModel, Field, ConfigDict\n\n" + output += ( + "# Build models on first use, not at import. Needs Pydantic 2.5+.\n" + '_DEFER_BUILD = tuple(int(p) for p in _PYDANTIC_VERSION.split(".")[:2]) >= (2, 5)\n\n' + ) output += "\n# Base class with shared configuration\n" output += "class TurnkeyBaseModel(BaseModel):\n" - output += " model_config = ConfigDict(populate_by_name=True)\n\n" + output += " model_config = ConfigDict(populate_by_name=True, defer_build=_DEFER_BUILD)\n\n" # --- Base Types --- output += "# --- Base Types from Swagger Definitions ---\n\n" diff --git a/packages/sdk-types/src/turnkey_sdk_types/generated/types.py b/packages/sdk-types/src/turnkey_sdk_types/generated/types.py index 2483d8a..2631c16 100644 --- a/packages/sdk-types/src/turnkey_sdk_types/generated/types.py +++ b/packages/sdk-types/src/turnkey_sdk_types/generated/types.py @@ -3,12 +3,16 @@ from __future__ import annotations from typing import Any, Dict, List, Optional from enum import Enum +from pydantic import VERSION as _PYDANTIC_VERSION from pydantic import BaseModel, Field, ConfigDict +# Build models on first use, not at import. Needs Pydantic 2.5+. +_DEFER_BUILD = tuple(int(p) for p in _PYDANTIC_VERSION.split(".")[:2]) >= (2, 5) + # Base class with shared configuration class TurnkeyBaseModel(BaseModel): - model_config = ConfigDict(populate_by_name=True) + model_config = ConfigDict(populate_by_name=True, defer_build=_DEFER_BUILD) # --- Base Types from Swagger Definitions --- From cffac2d6c929ab54573fd19146677e710cc8b701 Mon Sep 17 00:00:00 2001 From: Hamilton Truong Date: Fri, 13 Nov 2026 16:06:21 -0800 Subject: [PATCH 2/2] sdk-types: add defer_build tests and run them in CI Checks that every model builds, that serializing before validating works, and that dumps, validation errors and schemas match with defer_build on and off for a sample of models. CI runs only the sdk-types tests, which need no credentials. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/python-build.yml | 3 + packages/sdk-types/tests/test_defer_build.py | 176 +++++++++++++++++++ 2 files changed, 179 insertions(+) create mode 100644 packages/sdk-types/tests/test_defer_build.py diff --git a/.github/workflows/python-build.yml b/.github/workflows/python-build.yml index 41e0107..8ea94d8 100644 --- a/.github/workflows/python-build.yml +++ b/.github/workflows/python-build.yml @@ -35,3 +35,6 @@ jobs: - name: Run type checking run: make typecheck + + - name: Run sdk-types tests + run: pytest packages/sdk-types/tests -v diff --git a/packages/sdk-types/tests/test_defer_build.py b/packages/sdk-types/tests/test_defer_build.py new file mode 100644 index 0000000..5a12338 --- /dev/null +++ b/packages/sdk-types/tests/test_defer_build.py @@ -0,0 +1,176 @@ +"""Checks for TurnkeyBaseModel's defer_build setting. + +Subprocess checks run in a fresh interpreter, so no model has been built yet. +""" + +import inspect +import json +import subprocess +import sys + +import pytest +from pydantic import BaseModel + +import turnkey_sdk_types.generated.types as T + +# Heaviest models (activity and result types) plus every Nth model by name. +HEAVY = ["v1Activity", "v1ActivityResponse", "v1Result", "v1Intent"] +SAMPLE_EVERY = 25 + +_LIST_MODELS = """ +import inspect +from pydantic import BaseModel +import turnkey_sdk_types.generated.types as T +models = sorted( + (n, o) for n, o in vars(T).items() + if inspect.isclass(o) and issubclass(o, BaseModel) and o.__module__ == T.__name__ +) +""" + + +def _models(): + return sorted( + (n, o) + for n, o in vars(T).items() + if inspect.isclass(o) + and issubclass(o, BaseModel) + and o.__module__ == T.__name__ + ) + + +def _run(code: str, *args: str) -> dict: + out = subprocess.run( + [sys.executable, "-c", code, *args], capture_output=True, text=True, check=True + ) + return json.loads(out.stdout) + + +def test_every_model_builds(): + # Definition order, so dependencies are usually built before the models using them. + models = [ + (n, o) + for n, o in vars(T).items() + if inspect.isclass(o) + and issubclass(o, BaseModel) + and o.__module__ == T.__name__ + ] + for name, cls in models: + cls.model_rebuild(force=True) + assert cls.__pydantic_complete__, name + + +def test_serialize_before_validate(): + # Pydantic 2.1-2.2 crashed here with deferred building. + code = ( + _LIST_MODELS + + """ +import json +failed = [] +for n, cls in models: + try: + cls.model_construct().model_dump(warnings=False) + except Exception as e: + failed.append([n, type(e).__name__, str(e)[:200]]) +print(json.dumps({"failed": failed})) +""" + ) + assert _run(code)["failed"] == [] + + +def _sample(schema, defs, seen=()): + """Build input data that should validate against a JSON schema.""" + if "$ref" in schema: + name = schema["$ref"].split("/")[-1] + return None if name in seen else _sample(defs[name], defs, seen + (name,)) + for key in ("allOf", "anyOf"): + if key in schema: + opts = [o for o in schema[key] if o.get("type") != "null"] + return _sample(opts[0], defs, seen) if opts else None + if "enum" in schema: + return schema["enum"][0] + if "const" in schema: # single-value enums on older Pydantic + return schema["const"] + t = schema.get("type") + if t == "object" or "properties" in schema: + out = {} + for k, v in schema.get("properties", {}).items(): + val = _sample(v, defs, seen) + if val is not None or k in schema.get("required", []): + out[k] = val + return out + if t == "array": + item = _sample(schema.get("items", {}), defs, seen) + return [] if item is None else [item] + return {"integer": 1, "number": 1.5, "boolean": True}.get(t, "x") + + +# Runs in a fresh interpreter with defer_build on or off. Validates and dumps +# first, while models are still unbuilt, then generates schemas. +_COMPARE = """ +import json, sys +import pydantic +if sys.argv[1] == "off": + pydantic.VERSION = "2.4.0" # makes _DEFER_BUILD False +from pydantic import ValidationError +import turnkey_sdk_types.generated.types as T + +def errors(cls, data): + try: + cls.model_validate(data) + except ValidationError as e: + return [[d["type"], list(d["loc"]), d["msg"]] for d in e.errors()] + return None + +samples = json.load(sys.stdin) +out = {"defer": T.TurnkeyBaseModel.model_config.get("defer_build"), "models": {}} +for n, data in samples.items(): + cls = getattr(T, n) + r = {} + try: + m = cls.model_validate(data) + r["dump"] = m.model_dump(mode="json") + r["dump_alias"] = m.model_dump(by_alias=True, exclude_none=True, mode="json") + r["dump_json"] = m.model_dump_json(by_alias=True) + except ValidationError: + r["sample_errors"] = errors(cls, data) + r["empty_errors"] = errors(cls, {}) + r["wrong_type_errors"] = errors(cls, {k: [[]] for k in data or {}}) + r["not_dict_errors"] = errors(cls, "x") + r["schemas"] = [ + cls.model_json_schema(mode="validation"), + cls.model_json_schema(mode="serialization"), + ] + out["models"][n] = r +print(json.dumps(out)) +""" + + +@pytest.mark.skipif(not T._DEFER_BUILD, reason="defer_build is off below Pydantic 2.5") +def test_same_behavior_with_defer_off(): + names = [n for i, (n, _) in enumerate(_models()) if i % SAMPLE_EVERY == 0] + names += HEAVY + samples = {} + for n in names: + schema = getattr(T, n).model_json_schema(by_alias=True) + samples[n] = _sample(schema, schema.get("$defs", {})) + + def run(mode): + out = subprocess.run( + [sys.executable, "-c", _COMPARE, mode], + input=json.dumps(samples), + capture_output=True, + text=True, + check=True, + ) + return json.loads(out.stdout) + + on, off = run("on"), run("off") + assert on["defer"] is True + assert off["defer"] is False + + # Guard against the check passing because most samples were rejected. + valid = [n for n, r in on["models"].items() if "dump" in r] + assert len(valid) >= 0.9 * len(names), sorted(set(names) - set(valid)) + + for n in names: + assert on["models"][n] == off["models"][n], n