refactor(BA-5978): introduce BackendAISchema for per-domain validation errors (#11514)

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

Author: jopemachine

changes/11514.enhance.md

@@ -0,0 +1 @@
+Introduce `BackendAISchema`, a Pydantic base whose `model_validate` / `model_validate_json` auto-convert validation failures into a domain-specific `BackendAIError` (HTTP 400) via an overridable `build_validation_error` classmethod, so each model surfaces its own 400 with structured per-field error details instead of raw `pydantic.ValidationError`.

src/ai/backend/agent/agent.py

@@ -51,7 +51,6 @@
 import zmq.asyncio
 from async_timeout import timeout
 from cachetools import LRUCache, cached
-from pydantic import ValidationError
 from tenacity import (
     AsyncRetrying,
     RetryError,
@@ -158,7 +157,10 @@
     AbstractBroadcastEvent,
     AbstractEvent,
 )
-from ai.backend.common.exception import ConfigurationError, VolumeMountFailed
+from ai.backend.common.exception import (
+    ConfigurationError,
+    VolumeMountFailed,
+)
 from ai.backend.common.json import (
     dump_json,
     dump_json_str,
@@ -233,7 +235,6 @@
     ImagePullTimeoutError,
     ModelDefinitionEmptyError,
     ModelDefinitionNotFoundError,
-    ModelDefinitionValidationError,
     ModelFolderNotSpecifiedError,
     PortConflictError,
     ReservedPortError,
@@ -3292,13 +3293,7 @@ async def _load_model_definition(
                 f" vFolder {model_folder.name} (ID {model_folder.vfid})",
             )
 
-        try:
-            parsed = ModelDefinition.model_validate(inlined)
-        except ValidationError 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/api_handlers.py

@@ -32,6 +32,7 @@
     MiddlewareParamParsingFailed,
     ParameterNotParsedError,
 )
+from .types import BackendAISchema
 
 log = BraceStyleAdapter(logging.getLogger(__spec__.name))
 
@@ -45,21 +46,21 @@ class Sentinel(enum.Enum):
 SENTINEL = Sentinel.TOKEN
 
 
-class BaseRequestModel(BaseModel):
+class BaseRequestModel(BackendAISchema):
     model_config = ConfigDict(
         arbitrary_types_allowed=True,
         validate_by_name=True,
     )
 
 
-class BaseFieldModel(BaseModel):
+class BaseFieldModel(BackendAISchema):
     model_config = ConfigDict(
         arbitrary_types_allowed=True,
         validate_by_name=True,
     )
 
 
-class BaseResponseModel(BaseModel):
+class BaseResponseModel(BackendAISchema):
     pass
 
 

src/ai/backend/common/config.py

@@ -5,23 +5,22 @@
 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
 import trafaret as t
 from pydantic import (
     AliasChoices,
-    BaseModel,
     ConfigDict,
     Field,
     field_validator,
 )
 
 from . import validators as tx
 from .etcd import AsyncEtcd, ConfigScopes
-from .exception import ConfigurationError
-from .types import RedisHelperConfig
+from .exception import BackendAIError, ConfigurationError, ModelDefinitionValidationError
+from .types import BackendAISchema, RedisHelperConfig, SchemaValidationFailureInfo
 
 __all__ = (
     "ConfigurationError",
@@ -40,7 +39,7 @@
 )
 
 
-class BaseConfigSchema(BaseModel):
+class BaseConfigSchema(BackendAISchema):
     @staticmethod
     def snake_to_kebab_case(string: str) -> str:
         return string.replace("_", "-")
@@ -53,7 +52,7 @@ def snake_to_kebab_case(string: str) -> str:
     )
 
 
-class BaseConfigModel(BaseModel):
+class BaseConfigModel(BackendAISchema):
     @staticmethod
     def snake_to_kebab_case(string: str) -> str:
         return string.replace("_", "-")
@@ -478,6 +477,14 @@ class ModelDefinition(BaseConfigModel):
         description="List of models in the model definition.",
     )
 
+    @override
+    @classmethod
+    def build_validation_error(cls, info: SchemaValidationFailureInfo) -> 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)
@@ -532,10 +539,10 @@ class ModelHealthCheckDraft(BaseConfigModel):
     initial_delay: float | None = None
 
     def to_resolved(self) -> ModelHealthCheck:
-        if self.path is None:
-            raise ValueError("ModelHealthCheck.path is required")
         # Drop unset (None) fields so the strict type's ``Field(default=...)``
         # declarations remain the single source of truth for default values.
+        # Missing required fields (e.g. ``path``) surface as the strict
+        # type's ``BackendAISchemaValidationFailed`` via ``model_validate``.
         return ModelHealthCheck.model_validate(self.model_dump(exclude_none=True))
 
 
@@ -552,16 +559,15 @@ def _coerce_start_command(cls, value: Any) -> Any:
         return _normalize_start_command(value)
 
     def to_resolved(self) -> ModelServiceConfig:
-        if self.port is None:
-            raise ValueError("ModelServiceConfig.port is required")
         # Drop unset (None) scalars so the strict type's ``Field(default=...)``
         # declarations remain the single source of truth for default values;
         # resolve the nested ``health_check`` draft explicitly so its own
-        # required-field check (``path``) fires with a clear error message.
-        return ModelServiceConfig(
-            **self.model_dump(exclude_none=True, exclude={"health_check"}),
-            health_check=self.health_check.to_resolved() if self.health_check else None,
-        )
+        # required-field check (``path``) fires through its own
+        # ``model_validate``. Missing required fields (e.g. ``port``)
+        # surface as ``BackendAISchemaValidationFailed``.
+        payload = self.model_dump(exclude_none=True, exclude={"health_check"})
+        payload["health_check"] = self.health_check.to_resolved() if self.health_check else None
+        return ModelServiceConfig.model_validate(payload)
 
 
 class ModelConfigDraft(BaseConfigModel):
@@ -571,25 +577,18 @@ class ModelConfigDraft(BaseConfigModel):
     metadata: ModelMetadata | None = None  # ModelMetadata is already all-Optional.
 
     def to_resolved(self) -> ModelConfig:
-        if self.name is None:
-            raise ValueError("ModelConfig.name is required")
-        if self.model_path is None:
-            raise ValueError("ModelConfig.model_path is required")
         service = self.service.to_resolved() if self.service else None
-        if service is not None and service.start_command:
+        if service is not None and service.start_command and self.model_path is not None:
             # ``{model_path}`` placeholders in the variant baseline's
             # ``start_command`` are resolved here, at the same moment the
             # draft becomes a strict ``ModelConfig`` and ``model_path`` is
             # finalized. Placeholders therefore never propagate downstream.
             service.start_command = [
                 token.replace("{model_path}", self.model_path) for token in service.start_command
             ]
-        return ModelConfig(
-            name=self.name,
-            model_path=self.model_path,
-            service=service,
-            metadata=self.metadata,
-        )
+        payload = self.model_dump(exclude_none=True, exclude={"service"})
+        payload["service"] = service
+        return ModelConfig.model_validate(payload)
 
 
 def _merge_health_check_draft(
@@ -665,6 +664,14 @@ class ModelDefinitionDraft(BaseConfigModel):
 
     models: list[ModelConfigDraft] | None = None
 
+    @override
+    @classmethod
+    def build_validation_error(cls, info: SchemaValidationFailureInfo) -> BackendAIError:
+        return ModelDefinitionValidationError(
+            extra_msg=info.summary,
+            extra_data={"errors": info.errors},
+        )
+
     def merge(self, override: ModelDefinitionDraft) -> ModelDefinitionDraft:
         """Merge ``override`` over ``self`` and return a new draft.
 
@@ -689,13 +696,9 @@ def merge(self, override: ModelDefinitionDraft) -> ModelDefinitionDraft:
         return ModelDefinitionDraft.model_construct(models=merged)
 
     def to_resolved(self) -> ModelDefinition:
-        """Build the strict ``ModelDefinition`` from this draft.
-
-        Each child draft is converted via its own ``to_resolved`` and the
-        strict type's constructor performs Pydantic validation; missing
-        required fields propagate as ``pydantic.ValidationError``.
-        """
-        return ModelDefinition(models=[m.to_resolved() for m in (self.models or [])])
+        return ModelDefinition.model_validate({
+            "models": [m.to_resolved() for m in (self.models or [])],
+        })
 
 
 def find_config_file(daemon_name: str) -> Path:

src/ai/backend/common/dto/agent/request.py

@@ -1,7 +1,9 @@
-from pydantic import BaseModel, ConfigDict
+from pydantic import ConfigDict
 
+from ai.backend.common.types import BackendAISchema
 
-class BaseAgentRequestModel(BaseModel):
+
+class BaseAgentRequestModel(BackendAISchema):
     """Base class for pydantic request payloads on agent RPC v3 methods.
 
     Mirrors the role of ``ai.backend.common.api_handlers.BaseRequestModel``

src/ai/backend/common/dto/agent/response.py

@@ -6,11 +6,12 @@
 from pydantic import BaseModel, ConfigDict, Field
 
 from ai.backend.common.dto.internal.health import ConnectivityCheckResponse, HealthStatus
+from ai.backend.common.types import BackendAISchema
 
 T = TypeVar("T")
 
 
-class BaseAgentResponseModel(BaseModel):
+class BaseAgentResponseModel(BackendAISchema):
     """Base class for pydantic response payloads on agent RPC v3 methods.
 
     Counterpart to ``BaseAgentRequestModel`` on the response side.

src/ai/backend/common/exception.py

@@ -7,6 +7,7 @@
 from typing import Any, Self
 
 from aiohttp import web
+from pydantic_core import ErrorDetails
 
 from .json import dump_json
 
@@ -443,6 +444,51 @@ def error_code(self) -> ErrorCode:
         )
 
 
+class BackendAISchemaValidationFailed(BackendAIError, web.HTTPBadRequest):
+    """Default 400 raised by :class:`BackendAISchema.build_validation_error`.
+
+    Kept distinct from :class:`InvalidAPIParameters` so handlers can
+    catch one without picking up the other.
+    """
+
+    error_type = "https://api.backend.ai/probs/schema-validation-failed"
+    error_title = "Schema validation failed."
+
+    def error_code(self) -> ErrorCode:
+        return ErrorCode(
+            domain=ErrorDomain.BACKENDAI,
+            operation=ErrorOperation.PARSING,
+            error_detail=ErrorDetail.INVALID_PARAMETERS,
+        )
+
+    def errors(self) -> list[ErrorDetails]:
+        """Per-field errors in the same shape as
+        ``pydantic.ValidationError.errors()``. Empty when no
+        ``extra_data["errors"]`` is attached."""
+        if not self.extra_data:
+            return []
+        return list(self.extra_data.get("errors") or [])
+
+
+class ModelDefinitionValidationError(BackendAIError, web.HTTPBadRequest):
+    """400 raised by ``ModelDefinition.model_validate`` (via its
+    :meth:`BackendAISchema.build_validation_error` override).
+
+    Lives in ``common`` so ``ModelDefinition`` (also in ``common``) can
+    construct it without an upward-layer import.
+    """
+
+    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.PARSING,
+            error_detail=ErrorDetail.INVALID_PARAMETERS,
+        )
+
+
 class DeprecatedAPI(BackendAIError, web.HTTPBadRequest):
     error_type = "https://api.backend.ai/probs/deprecated"
     error_title = "This API is deprecated."