refactor(BA-6040): unify per-mount option DTOs and expose subpath in CreationConfigV7 (#11608)

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

Author: jopemachine

changes/11608.enhance.md

@@ -0,0 +1 @@
+Unify per-vfolder mount-option DTOs into a single `MountOption` type and formally declare `subpath` / `mount_destination` on the session-creation wire schema (`CreationConfigV*.mount_options`). The previously separate SDK `ExtraMountOption` and `ExtraMountModel` types are removed; both session creation and inference service creation now share the same `MountOption`.

src/ai/backend/client/cli/service.py

@@ -14,12 +14,12 @@
 )
 from ai.backend.client.compat import asyncio_run
 from ai.backend.client.exceptions import BackendError
-from ai.backend.client.func.service import ExtraMountOption
 from ai.backend.client.output.fields import routing_fields, service_fields
 from ai.backend.client.output.types import FieldSpec
 from ai.backend.client.session import AsyncSession, Session
 from ai.backend.common.arch import DEFAULT_IMAGE_ARCH
 from ai.backend.common.bgtask.types import BgtaskStatus
+from ai.backend.common.dto.manager.session.types import MountOption
 from ai.backend.common.types import ClusterMode, RuntimeVariant
 
 from .extensions import pass_ctx_obj
@@ -326,7 +326,7 @@ def create(
     parsed_resources = prepare_resource_arg(resources)
     parsed_resource_opts = prepare_resource_arg(resource_opts)
     extra_mount_options = {
-        key: ExtraMountOption.model_validate(opts) for key, opts in mount_options.items()
+        key: MountOption.model_validate(opts) for key, opts in mount_options.items()
     }
     body = {
         "service_name": name,

src/ai/backend/client/cli/session/execute.py

@@ -41,6 +41,7 @@
 if TYPE_CHECKING:
     from ai.backend.client.func.session import ComputeSession
 from ai.backend.common.arch import DEFAULT_IMAGE_ARCH
+from ai.backend.common.dto.manager.session.types import MountOption
 from ai.backend.common.types import ClusterMode, MountExpression
 
 from .args import click_start_option
@@ -474,7 +475,10 @@ def run(
     envs = prepare_env_arg(env)
     resources = prepare_resource_arg(resources)
     resource_opts = prepare_resource_arg(resource_opts)
-    mount, mount_map, mount_options = prepare_mount_arg(mount, escape=True)
+    mount, mount_map, raw_mount_options = prepare_mount_arg(mount, escape=True)
+    mount_options = {
+        key: MountOption.model_validate(opts) for key, opts in raw_mount_options.items()
+    }
 
     env_ranges: dict[str, Any] = {v: r for v, r in env_range}  # type: ignore[has-type]
     build_ranges: dict[str, Any] = {v: r for v, r in build_range}  # type: ignore[has-type]

src/ai/backend/client/cli/session/lifecycle.py

@@ -43,6 +43,7 @@
 from ai.backend.client.session import AsyncSession, Session
 from ai.backend.common.arch import DEFAULT_IMAGE_ARCH
 from ai.backend.common.bgtask.types import BgtaskStatus
+from ai.backend.common.dto.manager.session.types import MountOption
 from ai.backend.common.types import ClusterMode
 
 from .args import click_start_option
@@ -196,7 +197,10 @@ def create(
         envs = prepare_env_arg(env)
         parsed_resources = prepare_resource_arg(resources)
         parsed_resource_opts = prepare_resource_arg(resource_opts)
-        mount, mount_map, mount_options = prepare_mount_arg(mount, escape=True)
+        mount, mount_map, raw_mount_options = prepare_mount_arg(mount, escape=True)
+        mount_options = {
+            key: MountOption.model_validate(opts) for key, opts in raw_mount_options.items()
+        }
 
         preopen_ports = preopen
         assigned_agent_list = assign_agent

src/ai/backend/client/func/service.py

@@ -13,31 +13,13 @@
 from ai.backend.client.session import api_session
 from ai.backend.client.utils import dedent as _d
 from ai.backend.common.arch import DEFAULT_IMAGE_ARCH
+from ai.backend.common.dto.manager.session.types import MountOption
 from ai.backend.common.typed_validators import SESSION_NAME_MAX_LENGTH
-from ai.backend.common.types import BackendAISchema, RuntimeVariant
+from ai.backend.common.types import RuntimeVariant
 
 from .base import BaseFunction, api_function
 
-__all__ = (
-    "ExtraMountOption",
-    "Service",
-)
-
-
-class ExtraMountOption(BackendAISchema):
-    """Per-vfolder option overrides for ``Service.create`` extra mounts.
-
-    Keys in the parent mapping must match the entries passed to
-    ``extra_mounts`` (either a vfolder UUID string or a vfolder name).
-
-    Note: ``mount_destination`` lives on the separate ``extra_mount_map``
-    parameter, not here — keeping the destination override outside this
-    model leaves a single source of truth on the SDK surface.
-    """
-
-    type: str | None = None
-    permission: str | None = None
-    subpath: str | None = None
+__all__ = ("Service",)
 
 
 _default_fields: Sequence[FieldSpec] = (
@@ -122,7 +104,7 @@ async def create(
         scaling_group: str,
         extra_mounts: Sequence[str] | None = None,
         extra_mount_map: Mapping[str, str] | None = None,
-        extra_mount_options: Mapping[str, ExtraMountOption] | None = None,
+        extra_mount_options: Mapping[str, MountOption] | None = None,
         service_name: str | None = None,
         model_version: str | None = None,
         _dependencies: Sequence[str] | None = None,
@@ -201,7 +183,7 @@ async def create(
                     if mount not in vfolder_name_to_id:
                         raise BackendClientError(f"VFolder (name: {mount}) not found") from e
                     vfolder_id = vfolder_name_to_id[mount]
-                options = extra_mount_options.get(mount) or ExtraMountOption()
+                options = extra_mount_options.get(mount) or MountOption()
                 body = options.model_dump(exclude_none=True)
                 if (dest := extra_mount_map.get(mount)) is not None:
                     body["mount_destination"] = dest

src/ai/backend/client/func/session.py

@@ -44,6 +44,7 @@
 from ai.backend.client.utils import dedent as _d
 from ai.backend.client.versioning import get_id_or_name, get_naming
 from ai.backend.common.arch import DEFAULT_IMAGE_ARCH
+from ai.backend.common.dto.manager.session.types import MountOption
 from ai.backend.common.types import ClusterMode, SessionTypes
 
 from .base import BaseFunction, api_function
@@ -210,7 +211,7 @@ async def get_or_create(
         mount_map: Mapping[str, str] | None = None,
         mount_ids: list[UUID] | None = None,
         mount_id_map: Mapping[UUID, str] | None = None,
-        mount_options: Mapping[str, Mapping[str, str]] | None = None,
+        mount_options: Mapping[str, MountOption] | None = None,
         envs: Mapping[str, str] | None = None,
         startup_command: str | None = None,
         batch_timeout: str | int | None = None,
@@ -365,7 +366,9 @@ async def get_or_create(
             params["config"].update({
                 "mount_map": mount_map,
                 "mount_id_map": mount_id_map,
-                "mount_options": mount_options,
+                "mount_options": {
+                    k: v.model_dump(exclude_none=True) for k, v in mount_options.items()
+                },
                 "preopen_ports": preopen_ports,
             })
             if assign_agent is not None:
@@ -1421,7 +1424,7 @@ async def get_or_create(
         callback_url: str | None = None,
         mounts: list[str] | None = None,
         mount_map: Mapping[str, str] | None = None,
-        mount_options: Mapping[str, Mapping[str, str]] | None = None,
+        mount_options: Mapping[str, MountOption] | None = None,
         mount_ids: list[UUID] | None = None,
         mount_id_map: Mapping[UUID, str] | None = None,
         envs: Mapping[str, str] | None = None,

src/ai/backend/common/dto/manager/model_serving/request.py

@@ -21,7 +21,8 @@
 from ai.backend.common import typed_validators as tv
 from ai.backend.common.api_handlers import BaseRequestModel
 from ai.backend.common.dto.manager.query import StringFilter
-from ai.backend.common.types import MountPermission, MountTypes, RuntimeVariant
+from ai.backend.common.dto.manager.session.types import MountOption
+from ai.backend.common.types import RuntimeVariant
 
 __all__ = (
     # Path param models
@@ -31,7 +32,6 @@
     "ListServeRequestModel",
     "ServiceFilterModel",
     "SearchServicesRequestModel",
-    "ExtraMountModel",
     "ServiceConfigModel",
     "NewServiceRequestModel",
     "ScaleRequestModel",
@@ -63,33 +63,6 @@ class SearchServicesRequestModel(BaseRequestModel):
     limit: int = Field(default=20, ge=1, le=100)
 
 
-class ExtraMountModel(BaseRequestModel):
-    """Per-vfolder extra mount options for model service session creation."""
-
-    mount_destination: str | None = Field(
-        default=None,
-        description="Mount destination inside the container. Defaults to ``/home/work/{folder_name}``.",
-    )
-    type: MountTypes = Field(
-        default=MountTypes.BIND,
-        description="Mount type. Defaults to ``bind``.",
-    )
-    permission: MountPermission | None = Field(
-        default=None,
-        description=(
-            "Permission override. ``null`` (default) inherits the vfolder's stored permission."
-        ),
-    )
-    subpath: str | None = Field(
-        default=None,
-        min_length=1,
-        description=(
-            "Subpath within the vfolder to mount. ``null`` (default) mounts the vfolder root."
-            " Empty string is rejected; omit the field to mount the root."
-        ),
-    )
-
-
 class ServiceConfigModel(BaseRequestModel):
     model_config = ConfigDict(protected_namespaces=())
 
@@ -122,7 +95,7 @@ class ServiceConfigModel(BaseRequestModel):
         alias="vfolderSubpath",
     )
 
-    extra_mounts: dict[uuid.UUID, ExtraMountModel] = Field(
+    extra_mounts: dict[uuid.UUID, MountOption] = Field(
         description=(
             "Specifications about extra VFolders mounted to model service session. "
             "MODEL type VFolders are not allowed to be attached to model service session"

src/ai/backend/common/dto/manager/session/types.py

@@ -145,13 +145,30 @@ class ResourceOpts(BaseFieldModel):
 
 
 class MountOption(BaseFieldModel):
-    """Per-mount option used inside ``mount_options`` mapping."""
+    """Per-mount option used inside ``mount_options`` mapping.
 
+    Single source of truth for per-vfolder mount overrides — used by both
+    session creation (``CreationConfigV*.mount_options``) and inference
+    service creation (``ServiceConfigModel.extra_mounts``).
+    """
+
+    mount_destination: str | None = Field(
+        default=None,
+        description="Mount destination inside the container. Defaults to ``/home/work/{folder_name}``.",
+    )
     type: MountTypes = MountTypes.BIND
     permission: MountPermission | None = Field(
         default=None,
         validation_alias=AliasChoices("permission", "perm"),
     )
+    subpath: str | None = Field(
+        default=None,
+        min_length=1,
+        description=(
+            "Subpath within the vfolder to mount. ``null`` (default) mounts the vfolder root."
+            " Empty string is rejected; omit the field to mount the root."
+        ),
+    )
     model_config = ConfigDict(extra="allow")
 
 

src/ai/backend/manager/api/rest/service/handler.py

@@ -675,7 +675,7 @@ async def _run_validation(
                 model_mount_destination=params.config.model_mount_destination,
                 vfolder_subpath=params.config.vfolder_subpath,
                 extra_mounts={
-                    k: MountOption.from_model(v) for k, v in params.config.extra_mounts.items()
+                    k: MountOption.from_dto(v) for k, v in params.config.extra_mounts.items()
                 },
                 environ=params.config.environ,
                 scaling_group=params.config.scaling_group,
@@ -777,7 +777,7 @@ def _to_start_action(
                 model_mount_destination=params.config.model_mount_destination,
                 vfolder_subpath=params.config.vfolder_subpath,
                 extra_mounts={
-                    k: MountOption.from_model(v) for k, v in params.config.extra_mounts.items()
+                    k: MountOption.from_dto(v) for k, v in params.config.extra_mounts.items()
                 },
                 environ=params.config.environ,
                 scaling_group=params.config.scaling_group,

src/ai/backend/manager/data/model_serving/types.py

@@ -13,7 +13,7 @@
 from ai.backend.common.config import ModelDefinition
 from ai.backend.common.data.endpoint.types import EndpointLifecycle, ScalingState
 from ai.backend.common.data.user.types import UserRole
-from ai.backend.common.dto.manager.model_serving.request import ExtraMountModel
+from ai.backend.common.dto.manager.session.types import MountOption as MountOptionDTO
 from ai.backend.common.identifier.deployment import DeploymentID
 from ai.backend.common.identifier.runtime_variant import RuntimeVariantID
 from ai.backend.common.identifier.vfolder import VFolderUUID
@@ -197,13 +197,13 @@ class MountOption:
     subpath: str | None = None
 
     @classmethod
-    def from_model(cls, model: ExtraMountModel) -> MountOption:
-        """Convert a wire-level ``ExtraMountModel`` (DTO) into a ``MountOption``."""
+    def from_dto(cls, dto: MountOptionDTO) -> MountOption:
+        """Convert the wire-level :class:`MountOption` DTO into a data-layer dataclass."""
         return cls(
-            mount_destination=model.mount_destination,
-            type=model.type,
-            permission=model.permission,
-            subpath=model.subpath,
+            mount_destination=dto.mount_destination,
+            type=dto.type,
+            permission=dto.permission,
+            subpath=dto.subpath,
         )
 
     def to_dict(self) -> dict[str, Any]: