lablup / lablup/backend.ai

Define a structured JSON schema for transporting kernel status data to backend.ai-webui

Open
#679 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
670
Forks
183
Avg merge
15h 13m
Merged PRs (30d)
368

Description

_Is your feature request related to a problem? Please describe._

We need to define a structured JSON schema for transporting kernel status data to [backend.ai-webui](https://github.com/lablup/backend.ai-webui). Although we already support responding to clients with kernel status data, it is hard to interpret on the client side since the structure is not unified; currently, we are sending raw format for each data which has all different shapes.

Here is an example code: [https://github.com/lablup/backend.ai-webui/blob/79eed187adf1b506f05e8417d4f223dabcc57ef7/src/components/backend-ai-session-list.ts#L1443-L1587](https://github.com/lablup/backend.ai-webui/blob/79eed187adf1b506f05e8417d4f223dabcc57ef7/src/components/backend-ai-session-list.ts#L1443-L1587)

In the code above, the layout depends on 4 types of data; `kernel`, `session`, `scheduler` and `error`. The problem is that each of these has a different shape.

```js
// Kernel
{
"kernel": {
"exit_code": 0,
}
}

// Session
{
"session": {
"status": "...",
}
}

// Scheduler
{
"scheduler": {
"msg": "...",
"retries": 0,
"last_retry": "...",
"passed_predicates": [
{
"name": "...",
},
],
"failed_predicates": [
{
"name": "...",
"msg": "...",
},
],
},
}
```

It is even worse in the case of `Error`. There are 2 types of errors;

```js
{
// Type 1
"error": {
"name": "...",
"agent_id": "...",
"repr": "...",
},
// Type 2
"error": {
"collection": [
{
"name": "...",
"agent_id": "...",
"repr": "...",
},
],
}
}
```

_Describe the solution you'd like_

Define a unified structure of JSON schema for transporting and interpreting kernel status data.

## Describe alternatives you've considered

## Additional context

JIRA Issue: BA-253

----

## Status (2026-04-27)

Partially addressed since the issue was filed:

- Typed sub-shapes exist: `ErrorDetail` / `ErrorStatusInfo` (`src/ai/backend/manager/exceptions.py:88-98`), `SchedulingPredicate` and `SchedulingFailure.to_status_data()` (`src/ai/backend/manager/sokovan/data/allocation.py:28-184`).
- v2 DTOs deliberately hide raw `status_data` and only expose `status_info: str | None` (`src/ai/backend/common/dto/manager/v2/{session,kernel}/response.py`).

Still unresolved:

- The two-form `error` payload is still produced — single `{src, name, repr, agent_id?, traceback?`} vs. collection `{src, name, repr, collection: [...]`} at `src/ai/backend/manager/exceptions.py:101-143`.
- Consumers still branch on shape at runtime — see `src/ai/backend/manager/event_dispatcher/handlers/session.py:232-235`.
- Root `status_data` is still `dict[str, Any]` in the ORM with no unified schema.
- Legacy GraphQL passes it through as `graphene.JSONString()`.

## Recommended Steps (sub-issues)

- [ ] Define `KernelStatusData` as a Pydantic model in `src/ai/backend/common/dto/manager/v2/` covering `kernel`, `session`, `scheduler`, and `error` branches.
- [ ] Normalize the `error` field to always be `list[ErrorDetail]` — eliminate the `MultiAgentError` / `collection` special case in `src/ai/backend/manager/exceptions.py:101-143`.
- [ ] Update producers (`src/ai/backend/manager/exceptions.py`, `src/ai/backend/manager/repositories/scheduler/db_source/db_source.py`, `src/ai/backend/manager/sokovan/data/allocation.py`) to emit the new schema.
- [ ] Migrate existing rows via Alembic, or add a tolerant reader that upconverts old shapes on read.
- [ ] Remove runtime shape-sniffing in `src/ai/backend/manager/event_dispatcher/handlers/session.py:232-235`.
- [ ] Expose the typed `status_data` field in v2 session/kernel REST + GraphQL DTOs.
- [ ] Coordinate with backend.ai-webui to consume the typed schema and drop legacy branching.

JIRA Issue: BA-253

Contributor guide

Open the contributing guide

Research direction

Start by reading the existing DTOs in src/ai/backend/common/dto/manager/v2/, then inspect the producers and consumer branches named in the issue, especially exceptions.py and the session event handler. Define the unified status schema, normalize error values, handle existing rows, and expose the typed field through REST and GraphQL so backend.ai-webui no longer needs shape-based branching.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend-api-design, databases
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.