feat(BA-3917): Define `KernelV2` GraphQL schema types with structured fields #8079

jopemachine · 2026-01-16T04:49:49Z

Resolves #8082 (BA-3917)

Checklist: (if applicable)

Milestone metadata specifying the target backport version
Mention to the original issue
Installer updates including:
- Fixtures for db schema changes
- New mandatory config options
Update of end-to-end CLI integration tests in ai.backend.test
API server-client counterparts (e.g., manager API -> client SDK)
Test case(s) to:
- Demonstrate the difference of before/after
- Demonstrate the flow of abstract/conceptual models with a concrete implementation
Documentation
- Contents in the docs directory
- docstrings in public interfaces and type annotations

Summary

Add strawberry-based KernelV2 GraphQL types replacing legacy KernelNode
Introduce structured types to replace JSON scalar fields:
- ResourceOptsGQL, ServicePortsGQL, StatusHistoryGQL, AttachedDevicesGQL, VFolderMountGQL
Add proper enum types: SessionTypesGQL, SessionResultGQL, MountPermissionGQL, VFolderUsageModeGQL
Add Relay pagination types with filtering and ordering support
Add KernelOrders.created_at() and KernelOrders.id() for ordering support

🤖 Generated with Claude Code

📚 Documentation preview 📚: https://sorna--8079.org.readthedocs.build/en/8079/

📚 Documentation preview 📚: https://sorna-ko--8079.org.readthedocs.build/ko/8079/

Copilot

Pull request overview

This pull request adds new strawberry-based GraphQL types for kernel management (KernelV2) to replace the legacy KernelNode. The changes introduce:

Changes:

Structured GraphQL types to replace JSON scalar fields (ResourceOpts, ServicePorts, StatusHistory, AttachedDevices, VFolderMount)
Enum types for SessionTypes, SessionResult, MountPermission, and VFolderUsageMode
Relay pagination support with filtering and ordering capabilities via KernelFilterGQL and KernelOrderByGQL
Two new order methods in KernelOrders: created_at() and id() for ordering support

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
src/ai/backend/manager/repositories/scheduler/options.py	Adds `created_at()` and `id()` order methods to KernelOrders class for query ordering
src/ai/backend/manager/api/gql/kernel/types.py	Defines comprehensive KernelV2 GraphQL types with structured fields, enums, filtering, and pagination support
src/ai/backend/manager/api/gql/kernel/init.py	Exports the new kernel GraphQL types for use throughout the application

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-16T04:56:57Z

src/ai/backend/manager/api/gql/kernel/types.py

+            case KernelOrderFieldGQL.CREATED_AT:
+                return KernelOrders.created_at(ascending)
+            case KernelOrderFieldGQL.ID:
+                return KernelOrders.id(ascending)


The to_query_order method doesn't handle all possible enum cases and has no default/fallback, which could cause a runtime error if a new enum value is added. Add a default case or raise an explicit error for unhandled values.

Suggested change

return KernelOrders.id(ascending)

return KernelOrders.id(ascending)

case _:

raise ValueError(f"Unhandled KernelOrderFieldGQL value: {self.field!r}")

Copilot · 2026-01-16T04:56:58Z

src/ai/backend/manager/api/gql/kernel/types.py

+                entries.append(
+                    ServicePortEntryGQL(
+                        name=name,
+                        protocol=ServicePortProtocolGQL(port_info.get("protocol", "tcp")),


Potential ValueError if the protocol string from port_info is not a valid ServicePortProtocolGQL enum value. Wrap this in a try-except or validate the value before creating the enum.

Suggested change

entries.append(

ServicePortEntryGQL(

name=name,

protocol=ServicePortProtocolGQL(port_info.get("protocol", "tcp")),

protocol_value = port_info.get("protocol", "tcp")

try:

protocol = ServicePortProtocolGQL(protocol_value)

except ValueError:

# Fallback to the default protocol if the provided value is invalid.

try:

protocol = ServicePortProtocolGQL("tcp")

except ValueError:

# If even the default is invalid, skip this entry to avoid runtime errors.

continue

entries.append(

ServicePortEntryGQL(

name=name,

protocol=protocol,

Copilot · 2026-01-16T04:56:58Z

src/ai/backend/manager/api/gql/kernel/types.py

+        return cls(
+            name=data.get("name", ""),
+            vfid=str(data.get("vfid", "")),
+            vfsubpath=str(data.get("vfsubpath", ".")),
+            host_path=str(data.get("host_path", "")),
+            kernel_path=str(data.get("kernel_path", "")),
+            mount_perm=MountPermissionGQL(data.get("mount_perm", "ro")),
+            usage_mode=VFolderUsageModeGQL(data.get("usage_mode", "general")),


Potential ValueError if mount_perm or usage_mode values from data are not valid enum values. Add error handling or validation before creating these enum instances.

Suggested change

return cls(

name=data.get("name", ""),

vfid=str(data.get("vfid", "")),

vfsubpath=str(data.get("vfsubpath", ".")),

host_path=str(data.get("host_path", "")),

kernel_path=str(data.get("kernel_path", "")),

mount_perm=MountPermissionGQL(data.get("mount_perm", "ro")),

usage_mode=VFolderUsageModeGQL(data.get("usage_mode", "general")),

raw_mount_perm = data.get("mount_perm", "ro")

if isinstance(raw_mount_perm, MountPermissionGQL):

mount_perm = raw_mount_perm

elif raw_mount_perm in {m.value for m in MountPermissionGQL}:

mount_perm = MountPermissionGQL(raw_mount_perm)

else:

# Fallback to default permission if an invalid value is provided.

mount_perm = MountPermissionGQL("ro")

raw_usage_mode = data.get("usage_mode", "general")

if isinstance(raw_usage_mode, VFolderUsageModeGQL):

usage_mode = raw_usage_mode

elif raw_usage_mode in {m.value for m in VFolderUsageModeGQL}:

usage_mode = VFolderUsageModeGQL(raw_usage_mode)

else:

# Fallback to default usage mode if an invalid value is provided.

usage_mode = VFolderUsageModeGQL("general")

return cls(

name=data.get("name", ""),

vfid=str(data.get("vfid", "")),

vfsubpath=str(data.get("vfsubpath", ".")),

host_path=str(data.get("host_path", "")),

kernel_path=str(data.get("kernel_path", "")),

mount_perm=mount_perm,

usage_mode=usage_mode,

Copilot · 2026-01-16T04:56:58Z

src/ai/backend/manager/api/gql/kernel/types.py

+                    entries.append(
+                        StatusHistoryEntryGQL(
+                            status=status,
+                            timestamp=datetime.fromisoformat(timestamp),


The datetime.fromisoformat() can raise ValueError if the timestamp string is not in the correct ISO format. Add error handling to gracefully handle malformed timestamps.

Suggested change

entries.append(

StatusHistoryEntryGQL(

status=status,

timestamp=datetime.fromisoformat(timestamp),

try:

parsed_timestamp = datetime.fromisoformat(timestamp)

except ValueError:

# Skip entries with malformed timestamp strings

continue

entries.append(

StatusHistoryEntryGQL(

status=status,

timestamp=parsed_timestamp,

Copilot · 2026-01-16T04:56:58Z

src/ai/backend/manager/api/gql/kernel/types.py

+    count: int
+
+    def __init__(self, *args, count: int, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.count = count


The count field is defined twice - once as a class attribute and once set in __init__. This is redundant. Consider using a strawberry field with a resolver or removing the __init__ method and properly initializing the count field through the Connection initialization.

Suggested change

count: int

def __init__(self, *args, count: int, **kwargs) -> None:

super().__init__(*args, **kwargs)

self.count = count

count: int = strawberry.field(

description="Total number of kernels matching the filter, ignoring pagination."

)

src/ai/backend/manager/api/gql/kernel/types.py

src/ai/backend/manager/api/gql/common/types.py

src/ai/backend/manager/api/gql/kernel/fetcher/kernel.py

src/ai/backend/manager/api/gql/kernel/types.py

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

src/ai/backend/manager/api/gql/common/types.py

HyeockJinKim

Please separate PR and write a BEP for this job.

src/ai/backend/manager/api/gql/kernel/types.py

src/ai/backend/manager/api/gql/common/types.py

src/ai/backend/manager/api/gql/kernel/types.py

HyeockJinKim · 2026-01-20T07:27:32Z

src/ai/backend/manager/api/gql/kernel/types.py

+    occupied_slots: ResourceSlotGQL = strawberry.field(
+        description=dedent_strip("""
+            The resource slots currently occupied by this kernel.
+            Contains entries with resource types (e.g., cpu, mem, cuda.shares) and their quantities.
+        """)
+    )
+    requested_slots: ResourceSlotGQL = strawberry.field(
+        description=dedent_strip("""
+            The resource slots originally requested for this kernel.
+            May differ from occupied_slots due to scheduling adjustments.
+        """)
+    )
+    occupied_shares: ResourceSlotGQL = strawberry.field(
+        description="The fractional resource shares occupied by this kernel."


Please refer to https://teams.microsoft.com/l/message/19:2806b848642744138244b7358cd282d9@thread.skype/1758248624511?tenantId=13c6a44d-9b52-4b9e-aa34-0513ee7131f2&groupId=ea5c466a-2dcf-4ea7-88f8-a9a797f66903&parentMessageId=1756700519568&teamName=Lablup&channelName=UX%20Ideas%2C%20References%2C%20and%20Questions&createdTime=1758248624511.

jopemachine · 2026-01-29T05:27:09Z

Please separate PR and write a BEP for this job.

The contents of the BEP have been reflected in this PR (See BEP-1034 for this)

Could you please review it once more? @HyeockJinKim

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

src/ai/backend/manager/api/gql/kernel/types.py

src/ai/backend/manager/models/kernel/row.py

Co-authored-by: octodog <mu001@lablup.com>

Copilot AI review requested due to automatic review settings January 16, 2026 04:49

github-actions bot assigned jopemachine Jan 16, 2026

github-actions bot added size:XL 500~ LoC comp:manager Related to Manager component labels Jan 16, 2026

Copilot started reviewing on behalf of jopemachine January 16, 2026 04:50 View session

jopemachine mentioned this pull request Jan 16, 2026

feat(BA-3173): Add kernels resolver to AgentV2 GQL type #8080

Open

7 tasks

Copilot AI reviewed Jan 16, 2026

View reviewed changes

jopemachine changed the title ~~feat: Add KernelV2 GraphQL types with structured fields~~ feat(BA-3917): Add KernelV2 GraphQL types with structured fields Jan 16, 2026

jopemachine added this to the 26.1 milestone Jan 16, 2026

jopemachine marked this pull request as draft January 16, 2026 05:18

jopemachine force-pushed the feat/kernel-v2-types branch from d3547fa to 2ff01ca Compare January 16, 2026 05:43

jopemachine requested review from HyeockJinKim and seedspirit January 16, 2026 07:25

jopemachine marked this pull request as ready for review January 16, 2026 07:26

github-actions bot added the area:docs Documentations label Jan 16, 2026

jopemachine changed the title ~~feat(BA-3917): Add KernelV2 GraphQL types with structured fields~~ feat(BA-3917): Define KernelV2 GraphQL schema types with structured fields Jan 16, 2026

seedspirit reviewed Jan 16, 2026

View reviewed changes

jopemachine force-pushed the feat/kernel-v2-types branch from d61149d to b9d629b Compare January 19, 2026 02:54

jopemachine requested a review from seedspirit January 19, 2026 04:22

jopemachine force-pushed the feat/kernel-v2-types branch from db70579 to 9ce6282 Compare January 19, 2026 07:56

HyeockJinKim reviewed Jan 20, 2026

View reviewed changes

src/ai/backend/manager/api/gql/common/types.py Outdated Show resolved Hide resolved

jopemachine requested a review from HyeockJinKim January 20, 2026 02:14

jopemachine force-pushed the feat/kernel-v2-types branch from 9ce6282 to c39103c Compare January 20, 2026 02:17

HyeockJinKim requested changes Jan 20, 2026

View reviewed changes

jopemachine modified the milestones: 26.1, 26.2 Jan 26, 2026

jopemachine force-pushed the feat/kernel-v2-types branch from c39103c to 407aa5e Compare January 29, 2026 04:35

jopemachine requested a review from HyeockJinKim January 29, 2026 05:23

HyeockJinKim requested changes Jan 29, 2026

View reviewed changes

src/ai/backend/manager/api/gql/kernel/resolver/kernel.py Outdated Show resolved Hide resolved

src/ai/backend/manager/api/gql/kernel/types.py Outdated Show resolved Hide resolved

src/ai/backend/manager/models/kernel/row.py Show resolved Hide resolved

jopemachine added 18 commits February 3, 2026 00:55

fix: WIP

a2025d5

fix: WIP

7020538

fix: WIP

d4de52d

fix: WIP

97592a6

misc:

396a144

wip

05d91dc

fix: Move ResourceOptsInput, ResourceOptsEntryInput type to common

147980e

WIP

ba50652

wip

5c2d8c5

fix: Apply BEP schema

c933b73

fix: Use UUIDFilter

aea0edd

fix: Apply BEP schema

a2c8b0f

fix: Apply BEP schema

573ad9d

fix: Apply BEP schema

8378771

fix: Revert wrong change

f942bfb

fix: Use factory pattern

78f7932

feat: Add kernel dataloader

13a90de

test: Add dataloader test

4b229b1

jopemachine force-pushed the feat/kernel-v2-types branch from cc36dee to 4b229b1 Compare February 3, 2026 00:57

wip

837e998

jopemachine force-pushed the feat/kernel-v2-types branch from 13ff92f to 837e998 Compare February 3, 2026 01:11

jopemachine added 2 commits February 3, 2026 01:15

fix: Add explict KernelStatusGQL type

ffe0291

feat: Add image field to Kernel schema

1c18bdb

jopemachine marked this pull request as ready for review February 3, 2026 03:26

jopemachine requested a review from HyeockJinKim February 3, 2026 03:27

feat: Add explicit ServicePortProtocolGQL enum type

1b45b18

jopemachine force-pushed the feat/kernel-v2-types branch 2 times, most recently from 4b96036 to 1b45b18 Compare February 3, 2026 03:41

chore: update api schema dump

493d33a

Co-authored-by: octodog <mu001@lablup.com>

jopemachine dismissed HyeockJinKim’s stale review via 493d33a February 3, 2026 05:49

-                entries.append(
-                    ServicePortEntryGQL(
-                        name=name,
-                        protocol=ServicePortProtocolGQL(port_info.get("protocol", "tcp")),
+                protocol_value = port_info.get("protocol", "tcp")
+                try:
+                    protocol = ServicePortProtocolGQL(protocol_value)
+                except ValueError:
+                    # Fallback to the default protocol if the provided value is invalid.
+                    try:
+                        protocol = ServicePortProtocolGQL("tcp")
+                    except ValueError:
+                        # If even the default is invalid, skip this entry to avoid runtime errors.
+                        continue
+                entries.append(
+                    ServicePortEntryGQL(
+                        name=name,
+                        protocol=protocol,

-        return cls(
-            name=data.get("name", ""),
-            vfid=str(data.get("vfid", "")),
-            vfsubpath=str(data.get("vfsubpath", ".")),
-            host_path=str(data.get("host_path", "")),
-            kernel_path=str(data.get("kernel_path", "")),
-            mount_perm=MountPermissionGQL(data.get("mount_perm", "ro")),
-            usage_mode=VFolderUsageModeGQL(data.get("usage_mode", "general")),
+        raw_mount_perm = data.get("mount_perm", "ro")
+        if isinstance(raw_mount_perm, MountPermissionGQL):
+            mount_perm = raw_mount_perm
+        elif raw_mount_perm in {m.value for m in MountPermissionGQL}:
+            mount_perm = MountPermissionGQL(raw_mount_perm)
+        else:
+            # Fallback to default permission if an invalid value is provided.
+            mount_perm = MountPermissionGQL("ro")
+        raw_usage_mode = data.get("usage_mode", "general")
+        if isinstance(raw_usage_mode, VFolderUsageModeGQL):
+            usage_mode = raw_usage_mode
+        elif raw_usage_mode in {m.value for m in VFolderUsageModeGQL}:
+            usage_mode = VFolderUsageModeGQL(raw_usage_mode)
+        else:
+            # Fallback to default usage mode if an invalid value is provided.
+            usage_mode = VFolderUsageModeGQL("general")
+        return cls(
+            name=data.get("name", ""),
+            vfid=str(data.get("vfid", "")),
+            vfsubpath=str(data.get("vfsubpath", ".")),
+            host_path=str(data.get("host_path", "")),
+            kernel_path=str(data.get("kernel_path", "")),
+            mount_perm=mount_perm,
+            usage_mode=usage_mode,

feat(BA-3917): Define KernelV2 GraphQL schema types with structured fields #8079

Are you sure you want to change the base?

feat(BA-3917): Define KernelV2 GraphQL schema types with structured fields #8079

Conversation

jopemachine commented Jan 16, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

HyeockJinKim left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

HyeockJinKim Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

jopemachine commented Jan 29, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat(BA-3917): Define `KernelV2` GraphQL schema types with structured fields #8079

feat(BA-3917): Define `KernelV2` GraphQL schema types with structured fields #8079

jopemachine commented Jan 16, 2026 •

edited by github-actions bot

Loading