chore: enforce @override via mypy explicit-override rule

changes/12451.misc.md

@@ -0,0 +1 @@
+Enable mypy's `explicit-override` error code and add the missing `@typing.override` decorators across the codebase, so every method overriding a base-class method is explicitly marked. `ai.backend.client.cli.pretty` is exempted per-module because mypy cannot recognise `@override` on a property overriding a base instance attribute.

pyproject.toml

@@ -334,7 +334,7 @@ namespace_packages = true
 explicit_package_bases = true
 python_executable = "dist/export/python/virtualenvs/python-default/3.13.7/bin/python"
 disable_error_code = ["typeddict-unknown-key", "import-untyped"]
-enable_error_code = ["possibly-undefined"]
+enable_error_code = ["possibly-undefined", "explicit-override"]
 warn_unreachable = true
 
 # Disable errors in client CLI, web server, and tests
@@ -377,6 +377,10 @@ module = [
 ]
 ignore_errors = true
 
+[[tool.mypy.overrides]]
+module = "ai.backend.client.cli.pretty"
+disable_error_code = ["explicit-override"]
+
 [tool.pyright]
 pythonVersion = "3.13"
 extraPaths = ["src"]

src/ai/backend/account_manager/config.py

@@ -8,7 +8,7 @@
 from dataclasses import dataclass
 from pathlib import Path
 from pprint import pformat
-from typing import Annotated, Any
+from typing import Annotated, Any, override
 
 import click
 from pydantic import (
@@ -59,9 +59,11 @@ class HostPortPair(BaseSchema):
     host: Annotated[str, Field(examples=["127.0.0.1"])]
     port: Annotated[int, Field(gt=0, lt=65536, examples=[8201])]
 
+    @override
     def __repr__(self) -> str:
         return f"{self.host}:{self.port}"
 
+    @override
     def __str__(self) -> str:
         return self.__repr__()
 

src/ai/backend/account_manager/exceptions.py

@@ -12,7 +12,7 @@
 from __future__ import annotations
 
 import json
-from typing import Any
+from typing import Any, override
 
 from aiohttp import web
 
@@ -51,6 +51,7 @@ def __init__(
         self.body_dict = body
         self.body = json.dumps(body).encode()
 
+    @override
     def __str__(self) -> str:
         lines = []
         if self.extra_msg:
@@ -61,6 +62,7 @@ def __str__(self) -> str:
             lines.append(" -> extra_data: " + repr(self.extra_data))
         return "\n".join(lines)
 
+    @override
     def __repr__(self) -> str:
         lines = []
         if self.extra_msg:
@@ -73,6 +75,7 @@ def __repr__(self) -> str:
             lines.append(" -> extra_data: " + repr(self.extra_data))
         return "\n".join(lines)
 
+    @override
     def __reduce__(self) -> tuple[type[BackendError], tuple[Any, ...], dict[str, Any]]:
         return (
             type(self),

src/ai/backend/account_manager/models/base.py

@@ -8,6 +8,7 @@
     Self,
     TypeVar,
     cast,
+    override,
 )
 
 import sqlalchemy as sa
@@ -55,11 +56,13 @@ class GUID[UUID_SubType: uuid.UUID](TypeDecorator[uuid.UUID]):
     uuid_subtype_func: ClassVar[Callable[[Any], Any]] = lambda v: v
     cache_ok = True
 
+    @override
     def load_dialect_impl(self, dialect: Dialect) -> TypeDecorator[Any]:
         if dialect.name == "postgresql":
             return cast(TypeDecorator[Any], dialect.type_descriptor(UUID()))
         return cast(TypeDecorator[Any], dialect.type_descriptor(CHAR(16)))
 
+    @override
     def process_bind_param(
         self, value: UUID_SubType | uuid.UUID | None, dialect: Dialect
     ) -> str | bytes | None:
@@ -73,6 +76,7 @@ def process_bind_param(
             return str(value)
         return value.bytes
 
+    @override
     def process_result_value(self, value: Any, dialect: Dialect) -> UUID_SubType | None:
         if value is None:
             return value
@@ -100,31 +104,36 @@ def __init__(self, enum_cls: type[T_StrEnum], **opts: Any) -> None:
         super().__init__(length=64, **opts)
         self._enum_cls = enum_cls
 
+    @override
     def process_bind_param(  # type: ignore[override]
         self,
         value: T_StrEnum | None,
         dialect: Dialect,
     ) -> str | None:
         return value.value if value is not None else None
 
+    @override
     def process_result_value(  # type: ignore[override]
         self,
         value: Any | None,
         dialect: Dialect,
     ) -> T_StrEnum | None:
         return self._enum_cls(value) if value is not None else None
 
+    @override
     def copy(self, **kw: Any) -> Self:
         return StrEnumType(self._enum_cls, **self._opts)  # type: ignore[return-value]
 
     @property
+    @override
     def python_type(self) -> type[T_StrEnum]:
         return self._enum_cls
 
 
 class PasswordColumn(TypeDecorator[str]):
     impl = VARCHAR
 
+    @override
     def process_bind_param(self, value: Any, dialect: Dialect) -> str:
         return hash_password(value)
 

src/ai/backend/agent/agent.py

@@ -42,6 +42,7 @@
     Literal,
     ParamSpec,
     cast,
+    override,
 )
 from uuid import UUID
 
@@ -950,6 +951,7 @@ def __init__(
         self._sync_container_lifecycle_observer = SyncContainerLifecycleObserver.instance()
         self._clean_kernel_registry_task = asyncio.create_task(self._clean_kernel_registry_loop())
 
+    @override
     async def __ainit__(self) -> None:
         """
         An implementation of AbstractAgent would define its own ``__ainit__()`` method.

src/ai/backend/agent/alloc_map.py

@@ -15,6 +15,7 @@
     Any,
     TypeVar,
     final,
+    override,
 )
 
 import attr
@@ -299,6 +300,7 @@ def __init__(
         }
         super().__init__(*args, **kwargs)
 
+    @override
     def allocate(
         self,
         slots: Mapping[SlotName, Decimal],
@@ -479,6 +481,7 @@ def _allocate_evenly(
 
         return allocation
 
+    @override
     def apply_allocation(
         self,
         existing_alloc: Mapping[SlotName, Mapping[DeviceId, Decimal]],
@@ -487,6 +490,7 @@ def apply_allocation(
             for device_id, alloc in per_device_alloc.items():
                 self.allocations[slot_name][device_id] += alloc
 
+    @override
     def free(
         self,
         existing_alloc: Mapping[SlotName, Mapping[DeviceId, Decimal]],
@@ -516,6 +520,7 @@ def __init__(
         self.digits = Decimal(10) ** -2  # decimal points that is supported by agent
         self.powers = Decimal(100)  # reciprocal of self.digits
 
+    @override
     def allocate(
         self,
         slots: Mapping[SlotName, Decimal],
@@ -917,6 +922,7 @@ def allocate_across_devices(
             self.update_affinity_hint(slot_allocation, affinity_hint)
         return allocation
 
+    @override
     def apply_allocation(
         self,
         existing_alloc: Mapping[SlotName, Mapping[DeviceId, Decimal]],
@@ -925,6 +931,7 @@ def apply_allocation(
             for device_id, alloc in per_device_alloc.items():
                 self.allocations[slot_name][device_id] += alloc
 
+    @override
     def free(
         self,
         existing_alloc: Mapping[SlotName, Mapping[DeviceId, Decimal]],

src/ai/backend/agent/cli/context.py

@@ -2,7 +2,7 @@
 
 from contextlib import AbstractContextManager
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Self
+from typing import TYPE_CHECKING, Any, Self, override
 
 import click
 
@@ -19,6 +19,7 @@ def __init__(self, log_level: LogLevel, config_path: Path | None = None) -> None
         self.config_path = config_path
         self.log_level = log_level
 
+    @override
     def __enter__(self) -> Self:
         from ai.backend.logging import LocalLogger
 
@@ -31,6 +32,7 @@ def __enter__(self) -> Self:
             self._logger.__enter__()
         return self
 
+    @override
     def __exit__(self, *exc_info: Any) -> None:
         click_ctx = click.get_current_context()
         if click_ctx.invoked_subcommand != "start-server":

src/ai/backend/agent/dependencies/bootstrap/composer.py

@@ -4,6 +4,7 @@
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from pathlib import Path
+from typing import override
 
 from ai.backend.agent.config.unified import AgentUnifiedConfig
 from ai.backend.common.configs.redis import RedisConfig
@@ -50,10 +51,12 @@ class AgentBootstrapComposer(DependencyComposer[AgentBootstrapInput, AgentBootst
     """
 
     @property
+    @override
     def stage_name(self) -> str:
         return "bootstrap"
 
     @asynccontextmanager
+    @override
     async def compose(
         self,
         stack: DependencyStack,

src/ai/backend/agent/dependencies/bootstrap/config.py

@@ -4,6 +4,7 @@
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from pathlib import Path
+from typing import override
 
 from ai.backend.agent.config.unified import AgentConfigValidationContext, AgentUnifiedConfig
 from ai.backend.common import config as common_config
@@ -35,10 +36,12 @@ class AgentConfigLoaderDependency(
     """
 
     @property
+    @override
     def stage_name(self) -> str:
         return "config-loader"
 
     @asynccontextmanager
+    @override
     async def provide(
         self, setup_input: AgentConfigLoaderInput
     ) -> AsyncIterator[AgentUnifiedConfig]:

src/ai/backend/agent/dependencies/bootstrap/etcd.py

@@ -2,6 +2,7 @@
 
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
+from typing import override
 
 from ai.backend.agent.config.unified import AgentUnifiedConfig
 from ai.backend.common.dependencies import DependencyProvider
@@ -18,10 +19,12 @@ class AgentEtcdDependency(DependencyProvider[AgentUnifiedConfig, AsyncEtcd]):
     """
 
     @property
+    @override
     def stage_name(self) -> str:
         return "etcd"
 
     @asynccontextmanager
+    @override
     async def provide(self, setup_input: AgentUnifiedConfig) -> AsyncIterator[AsyncEtcd]:
         """Initialize and provide etcd client.
 
@@ -60,6 +63,7 @@ async def provide(self, setup_input: AgentUnifiedConfig) -> AsyncIterator[AsyncE
         ) as etcd:
             yield etcd
 
+    @override
     def gen_liveness_checker(self, resource: AsyncEtcd) -> ServiceHealthChecker:
         """Liveness — stuck etcd connection observed; restart is the recovery path."""
         return EtcdHealthChecker(etcd=resource)

src/ai/backend/agent/dependencies/bootstrap/redis_config.py

@@ -2,6 +2,7 @@
 
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
+from typing import override
 
 from ai.backend.common import config as common_config
 from ai.backend.common.configs.redis import RedisConfig
@@ -16,10 +17,12 @@ class RedisConfigDependency(NonMonitorableDependencyProvider[AsyncEtcd, RedisCon
     """
 
     @property
+    @override
     def stage_name(self) -> str:
         return "redis-config (temp)"
 
     @asynccontextmanager
+    @override
     async def provide(self, setup_input: AsyncEtcd) -> AsyncIterator[RedisConfig]:
         """Read redis config from etcd.
 

src/ai/backend/agent/dependencies/composer.py

@@ -4,6 +4,7 @@
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from pathlib import Path
+from typing import override
 
 from ai.backend.common.dependencies import DependencyComposer, DependencyStack
 from ai.backend.logging.types import LogLevel
@@ -48,10 +49,12 @@ class AgentDependencyComposer(DependencyComposer[AgentDependencyInput, AgentDepe
     """
 
     @property
+    @override
     def stage_name(self) -> str:
         return "agent-dependencies"
 
     @asynccontextmanager
+    @override
     async def compose(
         self,
         stack: DependencyStack,

src/ai/backend/agent/dependencies/infrastructure/composer.py

@@ -3,6 +3,7 @@
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
+from typing import override
 
 from aiodocker import Docker
 
@@ -51,10 +52,12 @@ class AgentInfrastructureComposer(
     """
 
     @property
+    @override
     def stage_name(self) -> str:
         return "infrastructure"
 
     @asynccontextmanager
+    @override
     async def compose(
         self,
         stack: DependencyStack,