feat(BA-5982): expose revision_number, separate Spec/Data on DeploymentInfo read path (#11529)

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

Author: 3 people

changes/11529.feature.md

@@ -0,0 +1 @@
+Expose the per-deployment `revision_number` on `ModelRevision` GraphQL nodes and REST v2 revision responses so clients can render "Revision #N" labels and order revisions without an extra round-trip.

docs/manager/graphql-reference/supergraph.graphql

@@ -9635,6 +9635,11 @@ type ModelRevision implements Node
   id: ID!
   imageId: ID!
 
+  """
+  Added in UNRELEASED. Per-deployment sequential revision number assigned at insert time (UNIQUE per deployment). Use this to surface 'Revision #N' labels and to order revisions client-side.
+  """
+  revisionNumber: Int!
+
   """Cluster configuration for replica distribution."""
   clusterConfig: ClusterConfig!
 

docs/manager/graphql-reference/v2-schema.graphql

@@ -6404,6 +6404,11 @@ type ModelRevision implements Node {
   id: ID!
   imageId: ID!
 
+  """
+  Added in UNRELEASED. Per-deployment sequential revision number assigned at insert time (UNIQUE per deployment). Use this to surface 'Revision #N' labels and to order revisions client-side.
+  """
+  revisionNumber: Int!
+
   """Cluster configuration for replica distribution."""
   clusterConfig: ClusterConfig!
 

src/ai/backend/common/dto/manager/v2/deployment/response.py

@@ -100,6 +100,13 @@ class RevisionNode(BaseResponseModel):
     """Node model representing a deployment revision."""
 
     id: UUID = Field(description="Revision ID")
+    revision_number: int = Field(
+        description=(
+            "Per-deployment sequential revision number assigned at insert "
+            "time (UNIQUE per deployment). Stable across the lifetime of the "
+            "row and suitable for surfacing 'Revision #N' labels."
+        ),
+    )
     # ``image_id`` is null when the referenced image row has been deleted
     # (``deployment_revisions.image`` SET NULL FK); the revision is kept for
     # history but cannot be redeployed in that state.

src/ai/backend/manager/api/adapters/deployment/adapter.py

@@ -136,6 +136,7 @@
     ResourceOptsInfoDTO,
 )
 from ai.backend.common.identifier.deployment import DeploymentID
+from ai.backend.common.identifier.deployment_revision import DeploymentRevisionID
 from ai.backend.manager.api.adapter_options.deployment.options import (
     deployment_options_from_input,
     deployment_options_to_info,
@@ -666,24 +667,24 @@ def _by_project_id() -> sa.sql.expression.ColumnElement[bool]:
             has_previous_page=action_result.has_previous_page,
         )
 
-    async def get(self, deployment_id: UUID) -> DeploymentNode:
+    async def get(self, deployment_id: DeploymentID) -> DeploymentNode:
         """Retrieve a single deployment by ID."""
         action_result = await self._processors.deployment.get_deployment_by_id.wait_for_complete(
             GetDeploymentByIdAction(deployment_id=deployment_id)
         )
         return self._deployment_data_to_dto(action_result.data)
 
-    async def get_current_revision(self, deployment_id: UUID) -> RevisionNode:
+    async def get_current_revision(self, deployment_id: DeploymentID) -> RevisionNode:
         """Retrieve the current active revision of a deployment."""
         deployment = await self.get(deployment_id)
         if deployment.current_revision_id is None:
             raise DeploymentRevisionNotFound(f"Deployment {deployment_id} has no current revision")
-        return await self.get_revision(deployment.current_revision_id)
+        return await self.get_revision(DeploymentRevisionID(deployment.current_revision_id))
 
     async def update(
         self,
         input: UpdateDeploymentInput,
-        deployment_id: UUID,
+        deployment_id: DeploymentID,
     ) -> UpdateDeploymentPayload:
         """Update deployment metadata and configuration."""
         metadata_spec: DeploymentMetadataUpdaterSpec | None = None
@@ -766,16 +767,16 @@ async def replace_options(
     async def sync_replicas(self, input: SyncReplicaInput) -> SyncReplicaPayload:
         """Force sync replica information for a deployment."""
         await self._processors.deployment.sync_replicas.wait_for_complete(
-            SyncReplicaAction(deployment_id=input.model_deployment_id)
+            SyncReplicaAction(deployment_id=DeploymentID(input.model_deployment_id))
         )
         return SyncReplicaPayload(success=True)
 
     async def activate_revision(self, input: ActivateRevisionInput) -> ActivateRevisionPayload:
         """Activate a specific revision as the current revision."""
         action_result = await self._processors.deployment.activate_revision.wait_for_complete(
             ActivateRevisionAction(
-                deployment_id=input.deployment_id,
-                revision_id=input.revision_id,
+                deployment_id=DeploymentID(input.deployment_id),
+                revision_id=DeploymentRevisionID(input.revision_id),
             )
         )
         return ActivateRevisionPayload(
@@ -823,7 +824,7 @@ async def create_access_token(
     ) -> CreateAccessTokenPayload:
         """Create a new access token for a deployment."""
         creator = ModelDeploymentAccessTokenCreator(
-            model_deployment_id=input.model_deployment_id,
+            model_deployment_id=DeploymentID(input.model_deployment_id),
             expires_at=input.expires_at,
         )
         action_result = await self._processors.deployment.create_access_token.wait_for_complete(
@@ -1007,10 +1008,10 @@ async def bulk_delete_rules(
     # Deployment policy operations
     # ------------------------------------------------------------------
 
-    async def get_policy(self, deployment_id: UUID) -> GetDeploymentPolicyPayload:
+    async def get_policy(self, deployment_id: DeploymentID) -> GetDeploymentPolicyPayload:
         """Retrieve a deployment policy by deployment ID."""
         action_result = await self._processors.deployment.get_deployment_policy.wait_for_complete(
-            GetDeploymentPolicyAction(deployment_id=DeploymentID(deployment_id))
+            GetDeploymentPolicyAction(deployment_id=deployment_id)
         )
         return GetDeploymentPolicyPayload(policy=self._policy_data_to_dto(action_result.data))
 
@@ -1115,14 +1116,14 @@ async def add_revision(
         )
         action_result = await self._processors.deployment.add_model_revision.wait_for_complete(
             AddModelRevisionAction(
-                model_deployment_id=input.deployment_id,
+                model_deployment_id=DeploymentID(input.deployment_id),
                 adder=adder,
                 auto_activate=options.auto_activate,
             )
         )
         return AddRevisionPayload(revision=self._revision_data_to_dto(action_result.revision))
 
-    async def get_revision(self, revision_id: UUID) -> RevisionNode:
+    async def get_revision(self, revision_id: DeploymentRevisionID) -> RevisionNode:
         """Retrieve a single revision by ID."""
         action_result = await self._processors.deployment.get_revision_by_id.wait_for_complete(
             GetRevisionByIdAction(revision_id=revision_id)
@@ -1168,7 +1169,7 @@ async def admin_search_revisions(
 
     async def search_revision_resource_slots(
         self,
-        revision_id: UUID,
+        revision_id: DeploymentRevisionID,
         input: SearchAllocatedResourceSlotsInput,
     ) -> SearchAllocatedResourceSlotsPayload:
         """Search resource slots allocated to a deployment revision."""
@@ -1317,7 +1318,9 @@ async def batch_load_revisions_by_ids(
         action_result = await self._processors.deployment.search_revisions.wait_for_complete(
             SearchRevisionsAction(querier=querier)
         )
-        revision_map = {data.id: self._revision_data_to_dto(data) for data in action_result.data}
+        revision_map: dict[uuid.UUID, RevisionNode] = {
+            data.id: self._revision_data_to_dto(data) for data in action_result.data
+        }
         return [revision_map.get(revision_id) for revision_id in revision_ids]
 
     async def batch_load_replicas_by_ids(
@@ -2005,7 +2008,7 @@ def _build_replica_querier(
     def _build_revision_resource_slot_querier(
         self,
         input: SearchAllocatedResourceSlotsInput,
-        revision_id: UUID,
+        revision_id: DeploymentRevisionID,
     ) -> BatchQuerier:
         conditions: list[QueryCondition] = [
             RevisionResourceSlotConditions.by_revision_id(revision_id),
@@ -2215,6 +2218,7 @@ def _revision_data_to_dto(data: ModelRevisionData) -> RevisionNode:
             )
         return RevisionNode(
             id=data.id,
+            revision_number=data.revision_number,
             image_id=data.image_id,
             cluster_config=ClusterConfigInfoDTO(
                 mode=data.cluster_config.mode.name,
@@ -2263,9 +2267,9 @@ def _revision_data_to_dto(data: ModelRevisionData) -> RevisionNode:
                     mount_destination=m.mount_destination,
                     mount_perm=m.mount_perm,
                 )
-                for m in data.extra_vfolder_mounts
+                for m in data.model_mount_config.extra_mounts
             ],
-            revision_preset_id=data.revision_preset_id,
+            revision_preset_id=data.preset.preset_id,
         )
 
     @staticmethod

src/ai/backend/manager/api/gql/deployment/resolver/deployment.py

@@ -13,6 +13,7 @@
     AdminSearchDeploymentsInput,
     ReplaceDeploymentOptionsInput,
 )
+from ai.backend.common.identifier.deployment import DeploymentID
 from ai.backend.common.meta import NEXT_RELEASE_VERSION
 from ai.backend.manager.api.gql.base import encode_cursor, resolve_global_id
 from ai.backend.manager.api.gql.decorators import (
@@ -196,7 +197,7 @@ async def my_deployments(
 async def deployment(id: ID, info: Info[StrawberryGQLContext]) -> ModelDeployment | None:
     """Get a specific deployment by ID."""
     _, deployment_id = resolve_global_id(id)
-    node = await info.context.adapters.deployment.get(UUID(deployment_id))
+    node = await info.context.adapters.deployment.get(DeploymentID(UUID(deployment_id)))
     return ModelDeployment.from_pydantic(node)
 
 
@@ -220,7 +221,9 @@ async def update_model_deployment(
     input: UpdateDeploymentInput, info: Info[StrawberryGQLContext]
 ) -> UpdateDeploymentPayload | None:
     """Update an existing model deployment."""
-    payload = await info.context.adapters.deployment.update(input.to_pydantic(), UUID(input.id))
+    payload = await info.context.adapters.deployment.update(
+        input.to_pydantic(), DeploymentID(UUID(input.id))
+    )
     return UpdateDeploymentPayload(deployment=ModelDeployment.from_pydantic(payload.deployment))
 
 

src/ai/backend/manager/api/gql/deployment/resolver/revision.py

@@ -15,6 +15,7 @@
 from ai.backend.common.dto.manager.v2.deployment.request import (
     AdminSearchRevisionsInput,
 )
+from ai.backend.common.identifier.deployment_revision import DeploymentRevisionID
 from ai.backend.manager.api.gql.base import encode_cursor, resolve_global_id
 from ai.backend.manager.api.gql.decorators import (
     BackendAIGQLMeta,
@@ -97,7 +98,9 @@ async def revisions(
 async def revision(id: ID, info: Info[StrawberryGQLContext]) -> ModelRevision | None:
     """Get a specific revision by ID."""
     _, revision_id = resolve_global_id(id)
-    node = await info.context.adapters.deployment.get_revision(UUID(revision_id))
+    node = await info.context.adapters.deployment.get_revision(
+        DeploymentRevisionID(UUID(revision_id))
+    )
     return ModelRevision.from_pydantic(node)
 
 

src/ai/backend/manager/api/gql/deployment/types/revision.py

@@ -101,6 +101,7 @@
     PreStartActionInfoDTO,
     ResourceConfigInfoDTO,
 )
+from ai.backend.common.identifier.deployment_revision import DeploymentRevisionID
 from ai.backend.common.meta import NEXT_RELEASE_VERSION
 from ai.backend.common.types import MountPermission as CommonMountPermission
 from ai.backend.manager.api.gql.base import (
@@ -452,6 +453,16 @@ class ModelDefinitionGQL:
 class ModelRevision(PydanticNodeMixin[RevisionNodeDTO]):
     image_id: ID
     id: NodeID[str]
+    revision_number: int = gql_added_field(
+        BackendAIGQLMeta(
+            added_version=NEXT_RELEASE_VERSION,
+            description=(
+                "Per-deployment sequential revision number assigned at "
+                "insert time (UNIQUE per deployment). Use this to surface "
+                "'Revision #N' labels and to order revisions client-side."
+            ),
+        ),
+    )
     cluster_config: ClusterConfig = gql_field(
         description="Cluster configuration for replica distribution."
     )
@@ -558,7 +569,7 @@ async def resource_slots(
         )
 
         payload = await info.context.adapters.deployment.search_revision_resource_slots(
-            revision_id=UUID(str(self.id)),
+            revision_id=DeploymentRevisionID(UUID(str(self.id))),
             input=SearchAllocatedResourceSlotsInput(
                 filter=filter.to_pydantic() if filter else None,
                 order=[o.to_pydantic() for o in order_by] if order_by else None,

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

@@ -44,6 +44,7 @@
 )
 from ai.backend.common.dto.manager.deployment.response import DeploymentDTO, RevisionDTO
 from ai.backend.common.identifier.deployment import DeploymentID
+from ai.backend.common.identifier.deployment_revision import DeploymentRevisionID
 from ai.backend.common.identifier.runtime_variant import RuntimeVariantID
 from ai.backend.common.types import RuntimeVariant
 from ai.backend.manager.api.adapters.runtime_variant.adapter import RuntimeVariantAdapter
@@ -223,7 +224,7 @@ async def get_deployment(
         """Get a specific deployment."""
         # Call service action - raises EndpointNotFound if not found
         action_result = await self._deployment.get_deployment_by_id.wait_for_complete(
-            GetDeploymentByIdAction(deployment_id=path.parsed.deployment_id)
+            GetDeploymentByIdAction(deployment_id=DeploymentID(path.parsed.deployment_id))
         )
 
         # Build response
@@ -302,7 +303,7 @@ async def add_revision(
         # Call service action
         action_result = await self._deployment.add_model_revision.wait_for_complete(
             AddModelRevisionAction(
-                model_deployment_id=path.parsed.deployment_id,
+                model_deployment_id=DeploymentID(path.parsed.deployment_id),
                 adder=revision_creator,
                 auto_activate=body.parsed.options.auto_activate,
             )
@@ -349,7 +350,7 @@ async def get_revision(
         """Get a specific revision."""
         # Call service action - raises DeploymentRevisionNotFound if not found
         action_result = await self._deployment.get_revision_by_id.wait_for_complete(
-            GetRevisionByIdAction(revision_id=path.parsed.revision_id)
+            GetRevisionByIdAction(revision_id=DeploymentRevisionID(path.parsed.revision_id))
         )
 
         # Build response
@@ -364,8 +365,8 @@ async def activate_revision(
         # Call service action
         await self._deployment.activate_revision.wait_for_complete(
             ActivateRevisionAction(
-                deployment_id=path.parsed.deployment_id,
-                revision_id=path.parsed.revision_id,
+                deployment_id=DeploymentID(path.parsed.deployment_id),
+                revision_id=DeploymentRevisionID(path.parsed.revision_id),
             )
         )
 

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

@@ -68,7 +68,7 @@
     DeploymentNetworkSpec,
     ExecutionSpec,
     ImageIdentifierDraft,
-    ModelRevisionSpec,
+    ModelRevisionData,
     ModelRevisionSpecDraft,
     MountMetadata,
     ReplicaSpec,
@@ -168,12 +168,12 @@ def _serve_info_from_dto(dto: ServiceInfo, runtime_variant_name: RuntimeVariant)
     )
 
 
-def _resolve_target_revision_spec(info: DeploymentInfo) -> ModelRevisionSpec | None:
-    """Resolve the target revision spec by id (current first, then deploying)."""
+def _resolve_target_revision_data(info: DeploymentInfo) -> ModelRevisionData | None:
+    """Resolve the target revision data by id (current first, then deploying)."""
     target_id = info.current_revision_id or info.deploying_revision_id
     if target_id is None:
         return None
-    return next((r for r in info.model_revisions if r.revision_id == target_id), None)
+    return next((r for r in info.model_revisions if r.id == target_id), None)
 
 
 def _serve_info_from_deployment_info(
@@ -186,22 +186,22 @@ def _serve_info_from_deployment_info(
     active revision's ``runtime_variant_id`` (internal data types are
     id-only; the legacy REST response still exposes the name string).
     """
-    model_revision = _resolve_target_revision_spec(deployment_info)
+    model_revision = _resolve_target_revision_data(deployment_info)
 
     return ServeInfoModel(
         endpoint_id=deployment_info.id,
         # ``None`` here covers two cases: no revision exists, or the revision's
         # model vfolder has been deleted (SET NULL FK).
-        model_id=model_revision.mounts.model_vfolder_id if model_revision else None,
-        extra_mounts=[m.vfolder_id for m in model_revision.mounts.extra_mounts]
+        model_id=model_revision.model_mount_config.vfolder_id if model_revision else None,
+        extra_mounts=[m.vfolder_id for m in model_revision.model_mount_config.extra_mounts]
         if model_revision
         else [],
         name=deployment_info.metadata.name,
-        model_definition_path=model_revision.mounts.model_definition_path
+        model_definition_path=model_revision.model_mount_config.definition_path
         if model_revision
         else None,
-        replicas=deployment_info.replica_spec.replica_count,
-        desired_session_count=deployment_info.replica_spec.replica_count,
+        replicas=deployment_info.replica.replica_count,
+        desired_session_count=deployment_info.replica.replica_count,
         active_routes=[],
         service_endpoint=HttpUrl(deployment_info.network.url)
         if deployment_info.network.url
@@ -387,11 +387,11 @@ async def create(self, body: BodyParam[NewServiceRequestModel], req: RequestCtx)
             await self._deployment.create_legacy_deployment.wait_for_complete(deployment_action)
         )
         deployment_info = deployment_result.data
-        model_revision = _resolve_target_revision_spec(deployment_info)
+        model_revision = _resolve_target_revision_data(deployment_info)
         if model_revision is None:
             raise RuntimeVariantNotFound()
         runtime_variant_name = await self._resolve_runtime_variant_name(
-            model_revision.execution.runtime_variant_id
+            model_revision.model_runtime_config.runtime_variant_id
         )
         resp = _serve_info_from_deployment_info(deployment_info, runtime_variant_name)
         return APIResponse.build(HTTPStatus.CREATED, resp)