feat(BA-5978): make BackendAIModel.build_validation_error overridable

Add a public ``build_validation_error`` classmethod on
``BackendAIModel`` that returns the ``BackendAIError`` instance to
raise when ``model_validate*`` fails. Default surfaces the generic
``BackendAIModelValidationFailed``; subclasses override the method to
inject a domain-specific 400 directly, without any caller-side
try/except re-wrap.

Apply the override on the two models that previously needed wrapping:

* ``ModelDefinition`` raises ``ModelDefinitionValidationError``.
  Moved that exception class from ``ai.backend.agent.errors.agent``
  to ``ai.backend.common.exception`` (and dropped the agent re-export)
  so the model — which lives in ``common.config`` — can construct it
  without an upward-layer import. The agent-specific error_type URL
  segment is dropped in the move.
* ``SessionSpec`` raises ``IncompleteSessionSpec`` with the existing
  ``extra_data["missing"]`` shape, using a module-local
  ``_format_loc`` helper.

The caller-side try/except wrappers around ``ModelDefinition.model_validate``
in ``agent/agent.py`` and ``manager/services/model_card/service.py``,
and the wrapper in
``sokovan/scheduling_controller/preparers/session_spec_preparer.py``,
are all removed — the models now raise the right domain error
directly.

Tests stay unchanged: they still expect ``IncompleteSessionSpec`` /
``ModelDefinitionValidationError`` because the override raises the
same types.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jopemachine

src/ai/backend/agent/agent.py

@@ -158,7 +158,6 @@
     AbstractEvent,
 )
 from ai.backend.common.exception import (
-    BackendAIModelValidationFailed,
     ConfigurationError,
     VolumeMountFailed,
 )
@@ -236,7 +235,6 @@
     ImagePullTimeoutError,
     ModelDefinitionEmptyError,
     ModelDefinitionNotFoundError,
-    ModelDefinitionValidationError,
     ModelFolderNotSpecifiedError,
     PortConflictError,
     ReservedPortError,
@@ -3295,13 +3293,7 @@ async def _load_model_definition(
                 f" vFolder {model_folder.name} (ID {model_folder.vfid})",
             )
 
-        try:
-            parsed = ModelDefinition.model_validate(inlined)
-        except BackendAIModelValidationFailed as e:
-            raise ModelDefinitionValidationError(
-                "Failed to validate model definition for vFolder"
-                f" {model_folder.name} (ID {model_folder.vfid})",
-            ) from e
+        parsed = ModelDefinition.model_validate(inlined)
         if not parsed.models:
             raise ModelDefinitionEmptyError
         model_definition = parsed.model_dump(mode="json")

src/ai/backend/agent/errors/__init__.py

@@ -20,7 +20,6 @@
     ModelDefinitionEmptyError,
     ModelDefinitionInvalidYAMLError,
     ModelDefinitionNotFoundError,
-    ModelDefinitionValidationError,
     ModelFolderNotSpecifiedError,
     PortConflictError,
     ReservedPortError,
@@ -64,7 +63,6 @@
     "ModelDefinitionEmptyError",
     "ModelDefinitionInvalidYAMLError",
     "ModelDefinitionNotFoundError",
-    "ModelDefinitionValidationError",
     "ModelFolderNotSpecifiedError",
     "PortConflictError",
     "ReservedPortError",

src/ai/backend/agent/errors/agent.py

@@ -169,20 +169,6 @@ def error_code(self) -> ErrorCode:
         )
 
 
-class ModelDefinitionValidationError(BackendAIError, web.HTTPBadRequest):
-    """Raised when model definition validation fails."""
-
-    error_type = "https://api.backend.ai/probs/agent/model-definition-validation-failed"
-    error_title = "Model definition validation failed."
-
-    def error_code(self) -> ErrorCode:
-        return ErrorCode(
-            domain=ErrorDomain.MODEL_SERVICE,
-            operation=ErrorOperation.ACCESS,
-            error_detail=ErrorDetail.INVALID_PARAMETERS,
-        )
-
-
 class ModelFolderNotSpecifiedError(BackendAIError, web.HTTPBadRequest):
     """Raised when no model virtual folder is specified."""
 

src/ai/backend/common/config.py

@@ -5,7 +5,7 @@
 import sys
 from collections.abc import Mapping, MutableMapping
 from pathlib import Path
-from typing import Any
+from typing import Any, override
 
 import humps
 import tomli
@@ -19,8 +19,8 @@
 
 from . import validators as tx
 from .etcd import AsyncEtcd, ConfigScopes
-from .exception import ConfigurationError
-from .types import BackendAIModel, RedisHelperConfig
+from .exception import BackendAIError, ConfigurationError, ModelDefinitionValidationError
+from .types import BackendAIModel, ModelValidationFailureInfo, RedisHelperConfig
 
 __all__ = (
     "ConfigurationError",
@@ -477,6 +477,14 @@ class ModelDefinition(BaseConfigModel):
         description="List of models in the model definition.",
     )
 
+    @override
+    @classmethod
+    def build_validation_error(cls, info: ModelValidationFailureInfo) -> BackendAIError:
+        return ModelDefinitionValidationError(
+            extra_msg=info.summary,
+            extra_data={"errors": info.errors},
+        )
+
     def merge(self, override: ModelDefinition) -> ModelDefinition:
         """Merge the given override into this definition, returning a new instance."""
         return _merge_definition(self, override)

src/ai/backend/common/exception.py

@@ -467,6 +467,24 @@ def error_code(self) -> ErrorCode:
         )
 
 
+class ModelDefinitionValidationError(BackendAIError, web.HTTPBadRequest):
+    """Raised by :class:`ai.backend.common.config.ModelDefinition` when
+    its ``model_validate`` call fails. Lives in ``common`` so the model
+    itself (also in ``common``) can construct it via
+    :meth:`BackendAIModel.build_validation_error`, with no caller-side
+    re-wrap needed."""
+
+    error_type = "https://api.backend.ai/probs/model-definition-validation-failed"
+    error_title = "Model definition validation failed."
+
+    def error_code(self) -> ErrorCode:
+        return ErrorCode(
+            domain=ErrorDomain.MODEL_SERVICE,
+            operation=ErrorOperation.ACCESS,
+            error_detail=ErrorDetail.INVALID_PARAMETERS,
+        )
+
+
 class DeprecatedAPI(BackendAIError, web.HTTPBadRequest):
     error_type = "https://api.backend.ai/probs/deprecated"
     error_title = "This API is deprecated."

src/ai/backend/common/types.py

@@ -51,10 +51,12 @@
     TypeAdapter,
     ValidationError,
 )
+from pydantic_core import ErrorDetails
 from redis.asyncio import Redis
 
 from .defs import UNKNOWN_CONTAINER_ID, RedisRole
 from .exception import (
+    BackendAIError,
     BackendAIModelValidationFailed,
     GenericNotImplementedError,
     InvalidIpAddressValue,
@@ -116,6 +118,7 @@
     "MetricValue",
     "ModelServiceProfile",
     "ModelServiceStatus",
+    "ModelValidationFailureInfo",
     "MountExpression",
     "MountInfoEntry",
     "MountPermission",
@@ -181,15 +184,52 @@
 )
 
 
+@dataclass(frozen=True)
+class ModelValidationFailureInfo:
+    """Stable representation of a failed pydantic ``model_validate*``
+    call. Passed to :meth:`BackendAIModel.build_validation_error` so
+    subclasses can produce a domain-specific error without depending
+    on pydantic's ``ValidationError`` internals.
+
+    ``summary`` is the multi-line human-readable form (the same string
+    ``str(pydantic.ValidationError)`` produces). ``errors`` is the
+    per-field list produced by ``exc.errors()``; each entry carries
+    ``type``/``loc``/``msg``/``input``/``ctx``/``url``.
+    """
+
+    summary: str
+    errors: list[ErrorDetails]
+
+
 class BackendAIModel(BaseModel):
     """Project-wide Pydantic base for Backend.AI models.
 
     Overrides ``model_validate`` / ``model_validate_json`` /
     ``model_validate_strings`` so a ``ValidationError`` is auto-mapped
-    to :class:`BackendAIModelValidationFailed` (HTTP 400) carrying the structured
+    to a :class:`BackendAIError` (HTTP 4xx) carrying the structured
     per-field error list. Call sites get a clean 4xx without repeating
     ``try / except ValidationError`` at every site.
 
+    The exception instance is produced by :meth:`build_validation_error`,
+    which defaults to :class:`BackendAIModelValidationFailed`. Subclasses
+    override the classmethod to surface a domain-specific 400 directly
+    (no caller-side re-wrap needed). The override receives a
+    :class:`ModelValidationFailureInfo` (not a raw ``pydantic.ValidationError``)
+    so subclasses do not depend on pydantic's exception API::
+
+        class MyConfig(BackendAIModel):
+            ...
+
+            @override
+            @classmethod
+            def build_validation_error(
+                cls, info: ModelValidationFailureInfo
+            ) -> BackendAIError:
+                return MyConfigParseError(
+                    extra_msg=info.summary,
+                    extra_data={"errors": info.errors},
+                )
+
     Notes:
 
     * Pydantic v2 routes nested validation through
@@ -202,35 +242,41 @@ class BackendAIModel(BaseModel):
       stock Pydantic.
     """
 
+    @classmethod
+    def build_validation_error(cls, info: ModelValidationFailureInfo) -> BackendAIError:
+        """Produce the :class:`BackendAIError` to raise when a
+        ``model_validate*`` call fails. Default surfaces a generic
+        :class:`BackendAIModelValidationFailed`; override on subclasses
+        to inject a domain-specific 400."""
+        return BackendAIModelValidationFailed(
+            extra_msg=info.summary,
+            extra_data={"errors": info.errors},
+        )
+
+    @classmethod
+    def _validation_failure_info(cls, exc: ValidationError) -> ModelValidationFailureInfo:
+        return ModelValidationFailureInfo(summary=str(exc), errors=exc.errors())
+
     @classmethod
     def model_validate(cls, *args: Any, **kwargs: Any) -> Self:
         try:
             return super().model_validate(*args, **kwargs)
         except ValidationError as e:
-            raise BackendAIModelValidationFailed(
-                extra_msg=str(e),
-                extra_data={"errors": e.errors()},
-            ) from e
+            raise cls.build_validation_error(cls._validation_failure_info(e)) from e
 
     @classmethod
     def model_validate_json(cls, *args: Any, **kwargs: Any) -> Self:
         try:
             return super().model_validate_json(*args, **kwargs)
         except ValidationError as e:
-            raise BackendAIModelValidationFailed(
-                extra_msg=str(e),
-                extra_data={"errors": e.errors()},
-            ) from e
+            raise cls.build_validation_error(cls._validation_failure_info(e)) from e
 
     @classmethod
     def model_validate_strings(cls, *args: Any, **kwargs: Any) -> Self:
         try:
             return super().model_validate_strings(*args, **kwargs)
         except ValidationError as e:
-            raise BackendAIModelValidationFailed(
-                extra_msg=str(e),
-                extra_data={"errors": e.errors()},
-            ) from e
+            raise cls.build_validation_error(cls._validation_failure_info(e)) from e
 
 
 class aobject:

src/ai/backend/manager/data/session/spec.py

@@ -17,22 +17,30 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
-from typing import Any
+from typing import Any, override
 from uuid import UUID
 
 import yarl
 from pydantic import ConfigDict, Field
 
+from ai.backend.common.exception import BackendAIError
 from ai.backend.common.identifier.domain import DomainName
 from ai.backend.common.identifier.project import ProjectID
 from ai.backend.common.identifier.resource_group import ResourceGroupName
 from ai.backend.common.identifier.session import SessionID
-from ai.backend.common.types import AccessKey, BackendAIModel, SessionTypes, VFolderMount
+from ai.backend.common.types import (
+    AccessKey,
+    BackendAIModel,
+    ModelValidationFailureInfo,
+    SessionTypes,
+    VFolderMount,
+)
 from ai.backend.manager.data.session.options import (
     InternalDataExtras,
     KernelExecutionSpec,
     SessionOptions,
 )
+from ai.backend.manager.errors.kernel import IncompleteSessionSpec
 from ai.backend.manager.models.network import NetworkType
 
 
@@ -138,3 +146,22 @@ class SessionSpec(_SpecBaseModel):
     options: SessionOptions
     kernel_specs: tuple[KernelSpec, ...]
     internal_data_extras: InternalDataExtras = Field(default_factory=InternalDataExtras)
+
+    @override
+    @classmethod
+    def build_validation_error(cls, info: ModelValidationFailureInfo) -> BackendAIError:
+        missing_paths = [cls._format_loc(tuple(err["loc"])) for err in info.errors]
+        return IncompleteSessionSpec(
+            extra_msg="SessionSpec fields not resolved: " + ", ".join(missing_paths),
+            extra_data={"missing": missing_paths},
+        )
+
+    @staticmethod
+    def _format_loc(loc: tuple[object, ...]) -> str:
+        parts: list[str] = []
+        for item in loc:
+            if isinstance(item, int):
+                parts.append(f"[{item}]")
+            else:
+                parts.append(f".{item}" if parts else str(item))
+        return "".join(parts)

src/ai/backend/manager/services/model_card/service.py

@@ -4,7 +4,6 @@
 from ruamel.yaml import YAML
 
 from ai.backend.common.config import ModelDefinition
-from ai.backend.common.exception import BackendAIModelValidationFailed
 from ai.backend.common.types import VFolderID
 from ai.backend.logging.utils import BraceStyleAdapter
 from ai.backend.manager.clients.storage_proxy.session_manager import StorageSessionManager
@@ -182,12 +181,7 @@ async def _scan_vfolder(
         except Exception as e:
             raise ModelCardParseError(extra_msg=f"invalid YAML in {model_def_filename}: {e}") from e
 
-        try:
-            model_def = ModelDefinition.model_validate(parsed)
-        except BackendAIModelValidationFailed as e:
-            raise ModelCardParseError(
-                extra_msg=f"invalid model definition in {model_def_filename}: {e}"
-            ) from e
+        model_def = ModelDefinition.model_validate(parsed)
         if not model_def.models:
             raise ModelCardParseError(extra_msg=f"no models defined in {model_def_filename}")
 

src/ai/backend/manager/sokovan/scheduling_controller/preparers/session_spec_preparer.py

@@ -6,9 +6,9 @@
 feeds :meth:`SessionSpec.model_validate`, so the spec schema is the
 single source of truth for both "what must be set" and error-path
 reporting. Any field that should have been resolved but still sits at
-``None`` surfaces as a ``ValidationError`` entry whose ``loc`` is the
-exact attribute path, re-wrapped into :class:`IncompleteSessionSpec`
-without any hand-maintained path strings.
+``None`` is surfaced by ``BackendAIModel.model_validate`` as a
+:class:`BackendAIModelValidationFailed` (HTTP 400) whose ``loc``
+carries the exact attribute path — no hand-maintained path strings.
 
 The prior dict-based ``SessionPreparer`` (producing ``SessionEnqueueData``)
 has been retired — this runner is the only path from caller input
@@ -19,10 +19,8 @@
 
 from collections.abc import Iterable
 
-from ai.backend.common.exception import BackendAIModelValidationFailed
 from ai.backend.manager.data.session.draft import SessionSpecDraft
 from ai.backend.manager.data.session.spec import SessionSpec
-from ai.backend.manager.errors.kernel import IncompleteSessionSpec
 from ai.backend.manager.sokovan.scheduling_controller.preparers.draft_rule import (
     SessionSpecDraftRule,
     SessionSpecPreparationContext,
@@ -59,26 +57,8 @@ def _finalize(self, draft: SessionSpecDraft) -> SessionSpec:
         """Project a fully-prepared draft into a frozen ``SessionSpec``.
 
         Draft fields left at ``None`` (never populated by a rule) drop
-        out of the dump and surface as ``ValidationError`` entries
-        pointing at the exact attribute path on the spec. Those are
-        collected and re-raised as :class:`IncompleteSessionSpec`.
+        out of the dump and surface as a
+        :class:`BackendAIModelValidationFailed` entry whose ``loc`` is
+        the exact attribute path on the spec.
         """
-        try:
-            return SessionSpec.model_validate(draft.model_dump(exclude_none=True))
-        except BackendAIModelValidationFailed as exc:
-            errors = (exc.extra_data or {}).get("errors", [])
-            missing_paths = [self._format_loc(err["loc"]) for err in errors]
-            raise IncompleteSessionSpec(
-                extra_msg="SessionSpec fields not resolved: " + ", ".join(missing_paths),
-                extra_data={"missing": missing_paths},
-            ) from exc
-
-    @staticmethod
-    def _format_loc(loc: tuple[object, ...]) -> str:
-        parts: list[str] = []
-        for item in loc:
-            if isinstance(item, int):
-                parts.append(f"[{item}]")
-            else:
-                parts.append(f".{item}" if parts else str(item))
-        return "".join(parts)
+        return SessionSpec.model_validate(draft.model_dump(exclude_none=True))