fix gameplay heuristic fallback, add per-bot model runtime, and normalize web sfx asset paths

Author: Dieg0Code

src/api/modules/gameplay/router.py

@@ -10,6 +10,7 @@
     Depends,
     HTTPException,
     Query,
+    Request,
     WebSocket,
     WebSocketDisconnect,
     status,
@@ -49,6 +50,15 @@
 logger = logging.getLogger(__name__)
 
 
+def _resolve_inference_service(request: Request) -> InferenceService:
+    """Resolve inference service honoring FastAPI dependency overrides in tests."""
+    provider = request.app.dependency_overrides.get(
+        get_inference_service_dep,
+        get_inference_service_dep,
+    )
+    return provider()
+
+
 async def _to_game_response(
     gameplay_service: GameplayService,
     game: Game,
@@ -115,7 +125,7 @@ async def _broadcast_move_applied(
 )
 def post_move(
     request: MoveRequest,
-    inference_service: InferenceService = INFERENCE_SERVICE_DEP,
+    http_request: Request,
 ) -> MoveResponse:
     try:
         board = board_from_state(request.board.model_dump())
@@ -127,6 +137,7 @@ def post_move(
 
     mode = request.mode
     if mode in {"fast", "strong"}:
+        inference_service = _resolve_inference_service(http_request)
         result = inference_service.predict(board=board, mode=mode)
         move_payload: MovePayload | None = None
         if result.move is not None:

src/api/modules/identity/repository.py

@@ -23,6 +23,23 @@ async def create(self, user: User) -> User:
     async def get_by_id(self, user_id: UUID) -> User | None:
         return await self.session.get(User, user_id)
 
+    async def save_user(self, user: User) -> User:
+        self.session.add(user)
+        await self.session.commit()
+        await self.session.refresh(user)
+        return user
+
+    async def get_bot_profile(self, user_id: UUID) -> BotProfile | None:
+        stmt = select(BotProfile).where(col(BotProfile.user_id) == user_id)
+        result = await self.session.execute(stmt)
+        return result.scalars().first()
+
+    async def save_bot_profile(self, profile: BotProfile) -> BotProfile:
+        self.session.add(profile)
+        await self.session.commit()
+        await self.session.refresh(profile)
+        return profile
+
     async def count_users(self) -> int:
         stmt = select(func.count()).select_from(User)
         result = await self.session.execute(stmt)

src/api/modules/identity/router.py

@@ -9,6 +9,8 @@
 from api.deps.identity import get_identity_service_dep
 from api.modules.identity.schemas import (
     BotProfileListResponse,
+    BotProfileResponse,
+    BotProfileUpsertRequest,
     PublicPlayerListResponse,
     UserCreateRequest,
     UserListResponse,
@@ -51,6 +53,34 @@ async def post_user(
     return UserResponse.model_validate(user)
 
 
+@router.post(
+    "/bot-profiles",
+    response_model=BotProfileResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create/Update Bot Profile (Admin)",
+    description="Upserts bot behavior for a user account (heuristic/model). Requires admin privileges.",
+    responses={
+        201: {"description": "Bot profile stored successfully."},
+        401: {"description": "Missing or invalid access token."},
+        403: {"description": "Admin privileges required."},
+        404: {"description": "User not found."},
+    },
+)
+async def post_bot_profile(
+    request: BotProfileUpsertRequest,
+    identity_service: IdentityService = IDENTITY_SERVICE_DEP,
+    admin_user: User = ADMIN_USER_DEP,
+) -> BotProfileResponse:
+    del admin_user
+    try:
+        return await identity_service.upsert_bot_profile(request)
+    except LookupError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(exc),
+        ) from exc
+
+
 @router.get(
     "/users/{user_id}",
     response_model=UserResponse,

src/api/modules/identity/schemas.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from datetime import datetime
+from typing import Literal
 from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field
@@ -111,6 +112,7 @@ class BotProfileResponse(BaseModel):
                 "agent_type": "heuristic",
                 "heuristic_level": "normal",
                 "model_mode": None,
+                "model_version_id": None,
                 "enabled": True,
             }
         }
@@ -122,9 +124,31 @@ class BotProfileResponse(BaseModel):
     agent_type: str
     heuristic_level: str | None
     model_mode: str | None
+    model_version_id: UUID | None
     enabled: bool
 
 
+class BotProfileUpsertRequest(BaseModel):
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "user_id": "5f6e8d34-292d-434f-a8ff-f48f4f3040f9",
+                "agent_type": "model",
+                "model_mode": "fast",
+                "model_version_id": "1932ac4a-5dcf-4dc9-8f99-fdf7ef20cc99",
+                "enabled": True,
+            }
+        }
+    )
+
+    user_id: UUID
+    agent_type: Literal["heuristic", "model"]
+    heuristic_level: Literal["easy", "normal", "hard"] | None = None
+    model_mode: Literal["fast", "strong"] | None = None
+    model_version_id: UUID | None = None
+    enabled: bool = True
+
+
 class BotProfileListResponse(BaseModel):
     model_config = ConfigDict(
         json_schema_extra={
@@ -156,6 +180,7 @@ class PublicPlayerResponse(BaseModel):
                 "agent_type": "heuristic",
                 "heuristic_level": "hard",
                 "model_mode": None,
+                "model_version_id": None,
                 "enabled": True,
             }
         }
@@ -168,6 +193,7 @@ class PublicPlayerResponse(BaseModel):
     agent_type: str | None
     heuristic_level: str | None
     model_mode: str | None
+    model_version_id: UUID | None
     enabled: bool | None
 
 

src/api/modules/identity/service.py

@@ -5,10 +5,12 @@
 
 from sqlalchemy.exc import IntegrityError
 
-from api.db.models import User
+from api.db.enums import AgentType, BotKind
+from api.db.models import BotProfile, User
 from api.modules.identity.repository import UserRepository
 from api.modules.identity.schemas import (
     BotProfileResponse,
+    BotProfileUpsertRequest,
     PublicPlayerResponse,
     UserCreateRequest,
 )
@@ -68,12 +70,54 @@ async def list_playable_bots(
                 agent_type=profile.agent_type.value,
                 heuristic_level=profile.heuristic_level,
                 model_mode=profile.model_mode,
+                model_version_id=user.model_version_id,
                 enabled=profile.enabled,
             )
             for user, profile in rows
         ]
         return total, items
 
+    async def upsert_bot_profile(self, payload: BotProfileUpsertRequest) -> BotProfileResponse:
+        user = await self.user_repository.get_by_id(payload.user_id)
+        if user is None:
+            raise LookupError(f"User not found: {payload.user_id}")
+
+        profile = await self.user_repository.get_bot_profile(payload.user_id)
+        if profile is None:
+            profile = BotProfile(user_id=payload.user_id, agent_type=AgentType.HEURISTIC)
+
+        # Promote the account into bot mode so matchmaking/listing sees it.
+        user.is_bot = True
+        user.is_hidden_bot = False
+
+        if payload.agent_type == "heuristic":
+            profile.agent_type = AgentType.HEURISTIC
+            profile.heuristic_level = payload.heuristic_level or "normal"
+            profile.model_mode = None
+            user.bot_kind = BotKind.HEURISTIC
+            if payload.model_version_id is not None:
+                user.model_version_id = payload.model_version_id
+        else:
+            profile.agent_type = AgentType.MODEL
+            profile.model_mode = payload.model_mode or "fast"
+            profile.heuristic_level = None
+            user.bot_kind = BotKind.MODEL
+            user.model_version_id = payload.model_version_id
+
+        profile.enabled = payload.enabled
+        await self.user_repository.save_user(user)
+        profile = await self.user_repository.save_bot_profile(profile)
+        return BotProfileResponse(
+            user_id=user.id,
+            username=user.username,
+            bot_kind=user.bot_kind,
+            agent_type=profile.agent_type.value,
+            heuristic_level=profile.heuristic_level,
+            model_mode=profile.model_mode,
+            model_version_id=user.model_version_id,
+            enabled=profile.enabled,
+        )
+
     async def list_public_players(
         self, *, limit: int = 50, offset: int = 0, query: str | None = None
     ) -> tuple[int, list[PublicPlayerResponse]]:
@@ -95,6 +139,7 @@ async def list_public_players(
                 agent_type=profile.agent_type.value if profile else None,
                 heuristic_level=profile.heuristic_level if profile else None,
                 model_mode=profile.model_mode if profile else None,
+                model_version_id=user.model_version_id,
                 enabled=profile.enabled if profile else None,
             )
             for user, profile in rows

src/api/modules/matches/model_runtime.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from urllib.parse import unquote, urlparse
+
+from api.db.models import ModelVersion
+from inference.service import InferenceService
+
+
+def _normalize_local_artifact_path(uri: str | None) -> str | None:
+    if uri is None:
+        return None
+    cleaned = uri.strip()
+    if cleaned == "":
+        return None
+
+    parsed = urlparse(cleaned)
+    if parsed.scheme in {"", "file"}:
+        if parsed.scheme == "file":
+            if parsed.netloc not in {"", "localhost"}:
+                raise ValueError(f"Unsupported artifact URI host: {cleaned}")
+            path = unquote(parsed.path)
+            if path == "":
+                raise ValueError(f"Invalid artifact URI (empty path): {cleaned}")
+            return path
+        return cleaned
+
+    raise ValueError(
+        f"Unsupported artifact URI scheme '{parsed.scheme}'. Use local paths or file:// URIs."
+    )
+
+
+def _runtime_config_from_base(base_service: InferenceService | None) -> tuple[str, int, float, bool]:
+    if base_service is None:
+        return "auto", 160, 1.5, True
+    return (
+        base_service.device,
+        base_service.mcts_sims,
+        base_service.c_puct,
+        base_service.prefer_onnx,
+    )
+
+
+@lru_cache(maxsize=32)
+def _build_cached_inference_service(
+    checkpoint_path: str,
+    onnx_path: str,
+    device: str,
+    mcts_sims: int,
+    c_puct: float,
+    prefer_onnx: bool,
+) -> InferenceService:
+    return InferenceService(
+        checkpoint_path=checkpoint_path,
+        onnx_path=onnx_path if onnx_path else None,
+        device=device,
+        mcts_sims=mcts_sims,
+        c_puct=c_puct,
+        prefer_onnx=prefer_onnx,
+    )
+
+
+def resolve_model_inference_service(
+    *,
+    version: ModelVersion,
+    base_service: InferenceService | None,
+) -> InferenceService:
+    checkpoint_path = _normalize_local_artifact_path(version.checkpoint_uri)
+    onnx_path = _normalize_local_artifact_path(version.onnx_uri)
+    if checkpoint_path is None and onnx_path is None:
+        raise ValueError(
+            f"Model version '{version.name}' has no local checkpoint_uri/onnx_uri configured."
+        )
+
+    # Keep runtime knobs aligned with the API default inference service so
+    # per-account model selection does not silently change move quality.
+    device, mcts_sims, c_puct, prefer_onnx = _runtime_config_from_base(base_service)
+    return _build_cached_inference_service(
+        checkpoint_path=checkpoint_path or "",
+        onnx_path=onnx_path or "",
+        device=device,
+        mcts_sims=mcts_sims,
+        c_puct=c_puct,
+        prefer_onnx=prefer_onnx,
+    )
+
+
+__all__ = ["resolve_model_inference_service"]

src/api/modules/matches/repository.py

@@ -7,7 +7,7 @@
 from sqlmodel import desc, select
 
 from api.db.enums import AgentType, GameStatus, QueueType
-from api.db.models import BotProfile, Game, GameMove, User
+from api.db.models import BotProfile, Game, GameMove, ModelVersion, User
 
 
 class MatchesRepository:
@@ -26,6 +26,9 @@ async def get_game(self, game_id: UUID) -> Game | None:
     async def get_user(self, user_id: UUID) -> User | None:
         return await self.session.get(User, user_id)
 
+    async def get_model_version(self, version_id: UUID) -> ModelVersion | None:
+        return await self.session.get(ModelVersion, version_id)
+
     async def get_bot_profile(self, user_id: UUID) -> BotProfile | None:
         stmt = select(BotProfile).where(BotProfile.user_id == user_id)
         result = await self.session.execute(stmt)