feat(BA-6891): add kernel scheduling-history v2 DTOs and service actions

Add the v2 DTOs and the service layer for kernel scheduling history.

The DTOs are the schema shared by REST v2 and GraphQL, so BA-6883 builds its
GraphQL types on these rather than defining its own.

KernelHistoryScopeDTO carries both scope axes as optional and rejects an empty
scope in a model_validator, so the rule lives with the schema both surfaces
share instead of being restated per surface.

KernelHistoryNode has no sub_steps: kernel_scheduling_history defines no such
column, unlike the session/deployment/route tables. BEP-1061 and BA-6852 both
describe kernel as carrying sub_steps, which does not match the schema; that
belongs to the writer side and is left alone here.

Only the two inputs that get wired are added. There is no offset-only
SearchKernelHistoryInput mirroring SearchSessionHistoryInput, as that one has
no callers.

The adapter that converts these DTOs and drives the processors lands in
BA-6892.

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

Author: jopemachine

src/ai/backend/common/dto/manager/v2/scheduling_history/__init__.py

@@ -4,12 +4,16 @@
 
 from ai.backend.common.dto.manager.v2.scheduling_history.request import (
     AdminSearchDeploymentHistoriesInput,
+    AdminSearchKernelHistoriesInput,
     AdminSearchRouteHistoriesInput,
     AdminSearchSessionHistoriesInput,
     DeploymentHistoryFilter,
     DeploymentHistoryOrder,
+    KernelHistoryFilter,
+    KernelHistoryOrder,
     RouteHistoryFilter,
     RouteHistoryOrder,
+    ScopedSearchKernelHistoriesInput,
     SearchDeploymentHistoryInput,
     SearchRouteHistoryInput,
     SearchSessionHistoryInput,
@@ -18,9 +22,11 @@
 )
 from ai.backend.common.dto.manager.v2.scheduling_history.response import (
     AdminSearchDeploymentHistoriesPayload,
+    AdminSearchKernelHistoriesPayload,
     AdminSearchRouteHistoriesPayload,
     AdminSearchSessionHistoriesPayload,
     DeploymentHistoryNode,
+    KernelHistoryNode,
     ListDeploymentHistoryPayload,
     ListRouteHistoryPayload,
     ListSessionHistoryPayload,
@@ -30,6 +36,8 @@
 from ai.backend.common.dto.manager.v2.scheduling_history.types import (
     DeploymentHistoryOrderField,
     DeploymentHistoryScopeDTO,
+    KernelHistoryOrderField,
+    KernelHistoryScopeDTO,
     OrderDirection,
     RouteHistoryOrderField,
     RouteHistoryScopeDTO,
@@ -43,6 +51,8 @@
     # Types
     "DeploymentHistoryOrderField",
     "DeploymentHistoryScopeDTO",
+    "KernelHistoryOrderField",
+    "KernelHistoryScopeDTO",
     "OrderDirection",
     "RouteHistoryOrderField",
     "RouteHistoryScopeDTO",
@@ -52,22 +62,28 @@
     "SubStepResultInfo",
     # Input models (request)
     "AdminSearchDeploymentHistoriesInput",
+    "AdminSearchKernelHistoriesInput",
     "AdminSearchRouteHistoriesInput",
     "AdminSearchSessionHistoriesInput",
     "DeploymentHistoryFilter",
     "DeploymentHistoryOrder",
+    "KernelHistoryFilter",
+    "KernelHistoryOrder",
     "RouteHistoryFilter",
     "RouteHistoryOrder",
+    "ScopedSearchKernelHistoriesInput",
     "SearchDeploymentHistoryInput",
     "SearchRouteHistoryInput",
     "SearchSessionHistoryInput",
     "SessionHistoryFilter",
     "SessionHistoryOrder",
     # Response models
     "AdminSearchDeploymentHistoriesPayload",
+    "AdminSearchKernelHistoriesPayload",
     "AdminSearchRouteHistoriesPayload",
     "AdminSearchSessionHistoriesPayload",
     "DeploymentHistoryNode",
+    "KernelHistoryNode",
     "ListDeploymentHistoryPayload",
     "ListRouteHistoryPayload",
     "ListSessionHistoryPayload",

src/ai/backend/common/dto/manager/v2/scheduling_history/request.py

@@ -11,6 +11,8 @@
 
 from .types import (
     DeploymentHistoryOrderField,
+    KernelHistoryOrderField,
+    KernelHistoryScopeDTO,
     OrderDirection,
     RouteHistoryOrderField,
     SchedulingResultType,
@@ -19,13 +21,17 @@
 
 __all__ = (
     "AdminSearchDeploymentHistoriesInput",
+    "AdminSearchKernelHistoriesInput",
     "AdminSearchRouteHistoriesInput",
     "AdminSearchSessionHistoriesInput",
     "DeploymentHistoryFilter",
     "DeploymentHistoryOrder",
+    "KernelHistoryFilter",
+    "KernelHistoryOrder",
     "RouteHistoryFilter",
     "RouteHistoryOrder",
     "SchedulingResultFilter",
+    "ScopedSearchKernelHistoriesInput",
     "SearchDeploymentHistoryInput",
     "SearchRouteHistoryInput",
     "SearchSessionHistoryInput",
@@ -86,6 +92,37 @@ class SearchSessionHistoryInput(BaseRequestModel):
     offset: int = Field(default=0, ge=0, description="Number of items to skip")
 
 
+class KernelHistoryFilter(BaseRequestModel):
+    """Filter conditions for kernel scheduling history search."""
+
+    id: UUIDFilter | None = Field(default=None, description="Filter by history record ID")
+    kernel_id: UUIDFilter | None = Field(default=None, description="Filter by kernel ID")
+    session_id: UUIDFilter | None = Field(default=None, description="Filter by session ID")
+    phase: StringFilter | None = Field(default=None, description="Filter by scheduling phase")
+    from_status: list[str] | None = Field(default=None, description="Filter by from_status values")
+    to_status: list[str] | None = Field(default=None, description="Filter by to_status values")
+    result: SchedulingResultFilter | None = Field(
+        default=None, description="Filter by scheduling result"
+    )
+    error_code: StringFilter | None = Field(default=None, description="Filter by error code")
+    message: StringFilter | None = Field(default=None, description="Filter by message")
+    created_at: DateTimeFilter | None = Field(default=None, description="Filter by created_at")
+    updated_at: DateTimeFilter | None = Field(default=None, description="Filter by updated_at")
+    AND: list[KernelHistoryFilter] | None = Field(default=None, description="AND conjunction.")
+    OR: list[KernelHistoryFilter] | None = Field(default=None, description="OR conjunction.")
+    NOT: list[KernelHistoryFilter] | None = Field(default=None, description="NOT negation.")
+
+
+KernelHistoryFilter.model_rebuild()
+
+
+class KernelHistoryOrder(BaseRequestModel):
+    """Order specification for kernel scheduling history."""
+
+    field: KernelHistoryOrderField = Field(description="Field to order by")
+    direction: OrderDirection = Field(default=OrderDirection.DESC, description="Order direction")
+
+
 class DeploymentHistoryFilter(BaseRequestModel):
     """Filter conditions for deployment scheduling history search."""
 
@@ -182,6 +219,37 @@ class AdminSearchSessionHistoriesInput(BaseRequestModel):
     offset: int | None = Field(default=None, description="Offset pagination: number to skip")
 
 
+class AdminSearchKernelHistoriesInput(BaseRequestModel):
+    """Input for admin search of kernel scheduling histories."""
+
+    filter: KernelHistoryFilter | None = Field(default=None, description="Filter conditions")
+    order: list[KernelHistoryOrder] | None = Field(default=None, description="Order specifications")
+    first: int | None = Field(default=None, description="Cursor pagination: number of items")
+    after: str | None = Field(default=None, description="Cursor pagination: after cursor")
+    last: int | None = Field(default=None, description="Cursor pagination: last N items")
+    before: str | None = Field(default=None, description="Cursor pagination: before cursor")
+    limit: int | None = Field(default=None, description="Offset pagination: maximum items")
+    offset: int | None = Field(default=None, description="Offset pagination: number to skip")
+
+
+class ScopedSearchKernelHistoriesInput(BaseRequestModel):
+    """Input for scoped search of kernel scheduling histories.
+
+    Unlike the session/deployment/route scoped searches, the scope is carried in the body
+    because a kernel query may be scoped by session_id, kernel_id, or both.
+    """
+
+    scope: KernelHistoryScopeDTO = Field(description="Required. Restricts the rows returned.")
+    filter: KernelHistoryFilter | None = Field(default=None, description="Filter conditions")
+    order: list[KernelHistoryOrder] | None = Field(default=None, description="Order specifications")
+    first: int | None = Field(default=None, description="Cursor pagination: number of items")
+    after: str | None = Field(default=None, description="Cursor pagination: after cursor")
+    last: int | None = Field(default=None, description="Cursor pagination: last N items")
+    before: str | None = Field(default=None, description="Cursor pagination: before cursor")
+    limit: int | None = Field(default=None, description="Offset pagination: maximum items")
+    offset: int | None = Field(default=None, description="Offset pagination: number to skip")
+
+
 class AdminSearchDeploymentHistoriesInput(BaseRequestModel):
     """Input for admin search of deployment histories."""
 

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

@@ -16,9 +16,11 @@
 
 __all__ = (
     "AdminSearchDeploymentHistoriesPayload",
+    "AdminSearchKernelHistoriesPayload",
     "AdminSearchRouteHistoriesPayload",
     "AdminSearchSessionHistoriesPayload",
     "DeploymentHistoryNode",
+    "KernelHistoryNode",
     "ListDeploymentHistoryPayload",
     "ListRouteHistoryPayload",
     "ListSessionHistoryPayload",
@@ -46,6 +48,26 @@ class SessionHistoryNode(BaseResponseModel):
     updated_at: datetime = Field(description="Timestamp when the history record was last updated")
 
 
+class KernelHistoryNode(BaseResponseModel):
+    """Node model representing a kernel scheduling history record.
+
+    Has no ``sub_steps``: the ``kernel_scheduling_history`` table carries no such column.
+    """
+
+    id: UUID = Field(description="History record ID")
+    kernel_id: UUID = Field(description="Kernel ID this history belongs to")
+    session_id: UUID = Field(description="Session owning the kernel")
+    phase: str = Field(description="Scheduling phase")
+    from_status: str | None = Field(default=None, description="Status before transition")
+    to_status: str | None = Field(default=None, description="Status after transition")
+    result: str = Field(description="Result of the scheduling attempt")
+    error_code: str | None = Field(default=None, description="Error code if scheduling failed")
+    message: str | None = Field(default=None, description="Human-readable message or error detail")
+    attempts: int = Field(description="Number of scheduling attempts made")
+    created_at: datetime = Field(description="Timestamp when the history record was created")
+    updated_at: datetime = Field(description="Timestamp when the history record was last updated")
+
+
 class DeploymentHistoryNode(BaseResponseModel):
     """Node model representing a deployment scheduling history record.
 
@@ -127,6 +149,15 @@ class AdminSearchSessionHistoriesPayload(BaseResponseModel):
     has_previous_page: bool = Field(description="Whether there is a previous page.")
 
 
+class AdminSearchKernelHistoriesPayload(BaseResponseModel):
+    """Payload for admin and scoped search of kernel scheduling histories."""
+
+    items: list[KernelHistoryNode] = Field(description="List of kernel history nodes.")
+    total_count: int = Field(description="Total number of records matching the filter.")
+    has_next_page: bool = Field(description="Whether there is a next page.")
+    has_previous_page: bool = Field(description="Whether there is a previous page.")
+
+
 class AdminSearchDeploymentHistoriesPayload(BaseResponseModel):
     """Payload for admin search of deployment histories."""
 

src/ai/backend/common/dto/manager/v2/scheduling_history/types.py

@@ -8,7 +8,7 @@
 from enum import StrEnum
 from uuid import UUID
 
-from pydantic import Field
+from pydantic import Field, model_validator
 
 from ai.backend.common.api_handlers import BaseRequestModel, BaseResponseModel
 from ai.backend.common.dto.manager.v2.common import OrderDirection
@@ -17,6 +17,7 @@
     "DeploymentHistoryOrderField",
     "DeploymentHistoryScopeDTO",
     "KernelHistoryOrderField",
+    "KernelHistoryScopeDTO",
     "OrderDirection",
     "RouteHistoryOrderField",
     "RouteHistoryScopeDTO",
@@ -84,6 +85,25 @@ class SessionHistoryScopeDTO(BaseRequestModel):
     session_id: UUID = Field(description="Session ID to get history for.")
 
 
+class KernelHistoryScopeDTO(BaseRequestModel):
+    """Scope for kernel scheduling history queries.
+
+    Unlike the single-entity scopes above, a kernel query may be scoped either by the
+    owning session (all of its kernels) or by one kernel. At least one must be given.
+    """
+
+    session_id: UUID | None = Field(
+        default=None, description="Restrict to the kernels of this session."
+    )
+    kernel_id: UUID | None = Field(default=None, description="Restrict to this kernel.")
+
+    @model_validator(mode="after")
+    def _check_non_empty(self) -> KernelHistoryScopeDTO:
+        if self.session_id is None and self.kernel_id is None:
+            raise ValueError("At least one of session_id or kernel_id must be given.")
+        return self
+
+
 class DeploymentHistoryScopeDTO(BaseRequestModel):
     """Scope for deployment scheduling history queries."""
 

src/ai/backend/manager/services/scheduling_history/actions/__init__.py

@@ -9,6 +9,14 @@
     SearchDeploymentScopedHistoryAction,
     SearchDeploymentScopedHistoryActionResult,
 )
+from .search_kernel_history import (
+    SearchKernelHistoryAction,
+    SearchKernelHistoryActionResult,
+)
+from .search_kernel_scoped_history import (
+    SearchKernelScopedHistoryAction,
+    SearchKernelScopedHistoryActionResult,
+)
 from .search_route_history import (
     SearchRouteHistoryAction,
     SearchRouteHistoryActionResult,
@@ -31,13 +39,17 @@
     # Admin actions
     "SearchSessionHistoryAction",
     "SearchSessionHistoryActionResult",
+    "SearchKernelHistoryAction",
+    "SearchKernelHistoryActionResult",
     "SearchDeploymentHistoryAction",
     "SearchDeploymentHistoryActionResult",
     "SearchRouteHistoryAction",
     "SearchRouteHistoryActionResult",
     # Scoped actions (added in 26.2.0)
     "SearchSessionScopedHistoryAction",
     "SearchSessionScopedHistoryActionResult",
+    "SearchKernelScopedHistoryAction",
+    "SearchKernelScopedHistoryActionResult",
     "SearchDeploymentScopedHistoryAction",
     "SearchDeploymentScopedHistoryActionResult",
     "SearchRouteScopedHistoryAction",

src/ai/backend/manager/services/scheduling_history/actions/search_kernel_history.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import override
+
+from ai.backend.common.data.permission.types import EntityType
+from ai.backend.manager.actions.action import BaseActionResult
+from ai.backend.manager.actions.types import ActionOperationType
+from ai.backend.manager.data.kernel.types import KernelSchedulingHistoryData
+from ai.backend.manager.repositories.base import BatchQuerier
+
+from .base import SchedulingHistoryAction
+
+
+@dataclass
+class SearchKernelHistoryAction(SchedulingHistoryAction):
+    """Action to search kernel scheduling history (admin API)."""
+
+    querier: BatchQuerier
+
+    @override
+    @classmethod
+    def entity_type(cls) -> EntityType:
+        return EntityType.KERNEL_HISTORY
+
+    @override
+    @classmethod
+    def operation_type(cls) -> ActionOperationType:
+        return ActionOperationType.SEARCH
+
+    @override
+    def entity_id(self) -> str | None:
+        return None
+
+
+@dataclass
+class SearchKernelHistoryActionResult(BaseActionResult):
+    """Result of searching kernel scheduling history."""
+
+    histories: list[KernelSchedulingHistoryData]
+    total_count: int
+    has_next_page: bool
+    has_previous_page: bool
+
+    @override
+    def entity_id(self) -> str | None:
+        return None