perf(types): defer pydantic core-schema builds to cut import memory

Add defer_build=True to AdCPBaseModel so each generated model's
pydantic-core validator/serializer is built lazily on first use rather
than at class definition. With ~1500 generated model classes, eager
builds dominate `import adcp` memory; deferring builds only the working
set (18 of 1564 classes build at import).

Because model_dump forces serialize_as_any=True, pydantic-core dispatches
serialization to each nested instance's own class serializer, which under
defer_build stays a placeholder and bypasses the lazy-build trigger. Walk
the instance graph on that error and rebuild the still-deferred classes,
then retry, so only models that appear in real payloads get built.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: andybevan-scope3

src/adcp/types/base.py

@@ -38,6 +38,36 @@ def _resolve_extra_policy() -> Literal["ignore", "forbid"]:
 _EXTRA_POLICY: Literal["ignore", "forbid"] = _resolve_extra_policy()
 
 
+def _build_deferred_serializers(value: Any, seen: set[int]) -> None:
+    """Force lazy core-schema builds for every model instance in a graph.
+
+    With ``defer_build=True`` a model class used only as a nested field keeps a
+    placeholder serializer until it is first built. ``serialize_as_any=True``
+    (set by :meth:`AdCPBaseModel.model_dump`) makes pydantic-core dispatch
+    serialization to each nested instance's *own* class serializer, a path that
+    does not trigger the lazy build. This walks the instance graph and rebuilds
+    any class whose core schema is still deferred, so only the model classes
+    that actually appear in serialized payloads get built — preserving the
+    import-time memory saving while keeping serialization correct.
+    """
+    if isinstance(value, BaseModel):
+        ident = id(value)
+        if ident in seen:
+            return
+        seen.add(ident)
+        cls = type(value)
+        if not cls.__pydantic_complete__:
+            cls.model_rebuild(force=False)
+        for field_value in value.__dict__.values():
+            _build_deferred_serializers(field_value, seen)
+    elif isinstance(value, (list, tuple, set, frozenset)):
+        for item in value:
+            _build_deferred_serializers(item, seen)
+    elif isinstance(value, dict):
+        for item in value.values():
+            _build_deferred_serializers(item, seen)
+
+
 def _pluralize(count: int, singular: str, plural: str | None = None) -> str:
     """Return singular or plural form based on count."""
     if count == 1:
@@ -229,7 +259,12 @@ class AdCPBaseModel(BaseModel):
     ``model_config`` on their subclass.
     """
 
-    model_config = ConfigDict(extra=_EXTRA_POLICY)
+    # ``defer_build=True`` skips building each model's pydantic-core
+    # validator/serializer at class-definition time. With ~700 generated model
+    # modules, eager builds dominate ``import adcp`` memory; deferring means each
+    # model's core schema is built lazily on first validate/serialize, so only
+    # the handful of models actually used are paid for.
+    model_config = ConfigDict(extra=_EXTRA_POLICY, defer_build=True)
 
     def model_dump(self, **kwargs: Any) -> dict[str, Any]:
         # ``serialize_as_any=True`` makes Pydantic dispatch on the runtime type of
@@ -243,14 +278,26 @@ def model_dump(self, **kwargs: Any) -> dict[str, Any]:
             kwargs["exclude_none"] = True
         if "serialize_as_any" not in kwargs:
             kwargs["serialize_as_any"] = True
-        return super().model_dump(**kwargs)
+        try:
+            return super().model_dump(**kwargs)
+        except TypeError as exc:
+            if "MockValSer" not in str(exc):
+                raise
+            _build_deferred_serializers(self, set())
+            return super().model_dump(**kwargs)
 
     def model_dump_json(self, **kwargs: Any) -> str:
         if "exclude_none" not in kwargs:
             kwargs["exclude_none"] = True
         if "serialize_as_any" not in kwargs:
             kwargs["serialize_as_any"] = True
-        return super().model_dump_json(**kwargs)
+        try:
+            return super().model_dump_json(**kwargs)
+        except TypeError as exc:
+            if "MockValSer" not in str(exc):
+                raise
+            _build_deferred_serializers(self, set())
+            return super().model_dump_json(**kwargs)
 
     def model_summary(self) -> str:
         """Human-readable summary for protocol responses.

tests/test_serialize_as_any_default.py

@@ -127,6 +127,32 @@ def test_caller_can_opt_out_with_explicit_kwarg() -> None:
     assert "seller_extension" not in dumped["child"]
 
 
+class _DeferredChild(AdCPBaseModel):
+    spec_field: str
+
+
+class _DeferredParent(AdCPBaseModel):
+    child: _DeferredChild
+    children: list[_DeferredChild] = Field(default_factory=list)
+
+
+def test_serialize_as_any_builds_deferred_nested_serializer() -> None:
+    """``defer_build=True`` leaves a nested-only model's serializer as a
+    placeholder until first built. ``serialize_as_any=True`` dispatches to that
+    placeholder and would raise ``TypeError: 'MockValSer' object is not an
+    instance of 'SchemaSerializer'``. The model is built from a dict so the
+    child class is never validated or dumped on its own — exactly the path that
+    leaves its serializer deferred. ``model_dump``/``model_dump_json`` must
+    build it on demand."""
+    parent = _DeferredParent.model_validate(
+        {"child": {"spec_field": "ok"}, "children": [{"spec_field": "a"}]}
+    )
+    dumped = parent.model_dump()
+    assert dumped["child"] == {"spec_field": "ok"}
+    assert dumped["children"] == [{"spec_field": "a"}]
+    assert json.loads(parent.model_dump_json())["child"] == {"spec_field": "ok"}
+
+
 def test_caller_can_still_pass_exclude_none_false() -> None:
     """The two defaults are independent — overriding one doesn't disturb
     the other."""