Define a structured JSON schema for transporting kernel status data to backend.ai-webui
- 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
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