fallback gameplay move to heuristic when inference artifacts missing

Author: Dieg0Code

src/api/modules/gameplay/router.py

@@ -137,19 +137,44 @@ 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:
-            r1, c1, r2, c2 = result.move
-            move_payload = MovePayload(r1=r1, c1=c1, r2=r2, c2=c2)
-
-        return MoveResponse(
-            move=move_payload,
-            action_idx=result.action_idx,
-            value=result.value,
-            mode=result.mode,
-        )
+        try:
+            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:
+                r1, c1, r2, c2 = result.move
+                move_payload = MovePayload(r1=r1, c1=c1, r2=r2, c2=c2)
+
+            return MoveResponse(
+                move=move_payload,
+                action_idx=result.action_idx,
+                value=result.value,
+                mode=result.mode,
+            )
+        except HTTPException as exc:
+            if exc.status_code != status.HTTP_503_SERVICE_UNAVAILABLE:
+                raise
+            # Keep PvE matches playable when model artifacts are missing in runtime.
+            logger.warning(
+                "Inference unavailable on /gameplay/move; falling back to heuristic_hard",
+                extra={"detail": exc.detail},
+            )
+            rng = np.random.default_rng()
+            fallback_move = heuristic_move(board=board, rng=rng, level="hard")
+            if fallback_move is None:
+                return MoveResponse(
+                    move=None,
+                    action_idx=ACTION_SPACE.pass_index,
+                    value=0.0,
+                    mode="heuristic_hard",
+                )
+            r1, c1, r2, c2 = fallback_move
+            return MoveResponse(
+                move=MovePayload(r1=r1, c1=c1, r2=r2, c2=c2),
+                action_idx=ACTION_SPACE.encode(fallback_move),
+                value=0.0,
+                mode="heuristic_hard",
+            )
 
     rng = np.random.default_rng()
     if mode == "random":

tests/test_api_move.py

@@ -4,6 +4,7 @@
 import unittest
 from pathlib import Path
 
+from fastapi import HTTPException, status
 from fastapi.testclient import TestClient
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
@@ -101,6 +102,27 @@ def _unavailable_inference() -> _StubInferenceService:
         self.assertEqual(body["mode"], "heuristic_normal")
         self.assertIsInstance(body["action_idx"], int)
 
+    def test_move_endpoint_falls_back_to_heuristic_when_inference_is_unavailable(self) -> None:
+        app = create_app()
+
+        def _unavailable_inference() -> _StubInferenceService:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail="Inference unavailable in test",
+            )
+
+        app.dependency_overrides[get_inference_service_dep] = _unavailable_inference
+        client = TestClient(app)
+
+        board = AtaxxBoard()
+        payload = MoveRequest(board=board_to_state(board), mode="fast").model_dump()
+        response = client.post("/api/v1/gameplay/move", json=payload)
+        self.assertEqual(response.status_code, 200)
+
+        body = response.json()
+        self.assertEqual(body["mode"], "heuristic_hard")
+        self.assertIsInstance(body["action_idx"], int)
+
 
 if __name__ == "__main__":
     unittest.main()