feat: Update AlphaBetaEngine to use depth_limit parameter consistently across documentation and code

Author: miskibin

docs/source/engine.rst

@@ -105,7 +105,7 @@ Basic usage::
     from draughts.engine import AlphaBetaEngine
     
     board = get_board('standard')
-    engine = AlphaBetaEngine(depth=5)
+    engine = AlphaBetaEngine(depth_limit=5)
     
     # Get best move
     best_move = engine.get_best_move(board)
@@ -118,9 +118,9 @@ Basic usage::
 With time limits::
 
     # Search with 1-second time limit instead of fixed depth
-    engine = AlphaBetaEngine(depth=20, time_limit=1.0)
+    engine = AlphaBetaEngine(depth_limit=20, time_limit=1.0)
     move, score = engine.get_best_move(board, with_evaluation=True)
-    # Engine will iteratively deepen up to depth 20 or until time expires
+    # Engine will iteratively deepen up to depth_limit or until time expires
 
 Custom Engine Implementation
 -----------------------------
@@ -183,7 +183,7 @@ Single Engine for Both Sides::
     from draughts.server import Server
     
     board = StandardBoard()
-    engine = AlphaBetaEngine(depth=6)
+    engine = AlphaBetaEngine(depth_limit=6)
     
     # Same engine plays for both colors
     server = Server(
@@ -202,8 +202,8 @@ Engine vs Engine Match::
     board = StandardBoard()
     
     # Different engines/configurations for each side
-    white_engine = AlphaBetaEngine(depth=6)
-    black_engine = AlphaBetaEngine(depth=4)
+    white_engine = AlphaBetaEngine(depth_limit=6)
+    black_engine = AlphaBetaEngine(depth_limit=4)
     
     server = Server(
         board=board,
@@ -269,12 +269,12 @@ Search Options
 Time-based search (default)::
 
     # 2 seconds per move
-    engine = HubEngine("scan.exe", time_per_move=2.0)
+    engine = HubEngine("scan.exe", time_limit=2.0)
 
 Fixed depth search::
 
     # Search to depth 15
-    engine = HubEngine("scan.exe", depth=15)
+    engine = HubEngine("scan.exe", depth_limit=15)
 
 Engine vs HubEngine Match
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -285,9 +285,9 @@ You can pit the built-in AlphaBetaEngine against an external Hub engine::
     from draughts.engine import AlphaBetaEngine
     
     board = StandardBoard()
-    alphabeta = AlphaBetaEngine(depth=6)
+    alphabeta = AlphaBetaEngine(depth_limit=6)
     
-    with HubEngine("scan.exe", time_per_move=1.0) as scan:
+    with HubEngine("scan.exe", time_limit=1.0) as scan:
         while not board.is_over():
             if board.turn.value == 0:  # White
                 move = alphabeta.get_best_move(board)

docs/source/server.rst

@@ -34,7 +34,7 @@ To enable the "Engine Move" button in the UI, pass an engine to the server::
     from draughts.server import Server
     
     board = get_board('standard')
-    engine = AlphaBetaEngine(depth=6)
+    engine = AlphaBetaEngine(depth_limit=6)
     
     # Engine plays for both sides when you click "Engine Move"
     server = Server(
@@ -57,8 +57,8 @@ for testing and comparing engine implementations::
     board = get_board('standard')
     
     # Create two engines with different configurations
-    white_engine = AlphaBetaEngine(depth=6)
-    black_engine = AlphaBetaEngine(depth=4)
+    white_engine = AlphaBetaEngine(depth_limit=6)
+    black_engine = AlphaBetaEngine(depth_limit=4)
     
     server = Server(
         board=board,

draughts/engine.py

@@ -76,7 +76,7 @@ def get_best_move(
             Either a Move object, or tuple of (Move, float) if with_evaluation=True
         
         Example:
-            >>> engine = AlphaBetaEngine(depth=3)
+            >>> engine = AlphaBetaEngine(depth_limit=3)
             >>> move = engine.get_best_move(board)
             >>> move, score = engine.get_best_move(board, with_evaluation=True)
         
@@ -99,8 +99,8 @@ class AlphaBetaEngine(Engine):
     - Advanced Evaluation (PST)
     """
 
-    def __init__(self, depth: int, time_limit: float | None = None):
-        self.depth = depth
+    def __init__(self, depth_limit: int = 6, time_limit: float | None = None):
+        self.depth_limit = depth_limit
         self.time_limit = time_limit
         self.nodes: int = 0
         self.tt: dict[int, tuple[int, int, float, Move | None]] = {}  # {hash: (depth, flag, score, best_move)}
@@ -197,7 +197,7 @@ def get_best_move(self, board: Board, with_evaluation: bool = False) -> Move | t
         best_score = -INF
 
         # Iterative Deepening
-        max_depth = self.depth
+        max_depth = self.depth_limit
 
         for d in range(1, max_depth + 1):
             try:
@@ -272,7 +272,7 @@ def negamax(self, board: Board, depth: int, alpha: float, beta: float, h: int) -
 
         legal_moves = list(board.legal_moves)
         if not legal_moves:
-            return -CHECKMATE + (self.depth - depth)
+            return -CHECKMATE + (self.depth_limit - depth)
 
         # Check for draw
         if board.is_draw:

draughts/server/server.py

@@ -20,6 +20,7 @@
 
 from draughts.boards.base import BaseBoard, Color
 from draughts.engine import Engine
+from draughts.hub import HubEngine
 
 
 class PositionResponse(BaseModel):
@@ -74,6 +75,11 @@ def __init__(
         self._lock = threading.RLock()
         self.engine_depth = 6
 
+        # Start any HubEngine instances
+        for engine in [self.white_engine, self.black_engine]:
+            if isinstance(engine, HubEngine) and not engine._started:
+                engine.start()
+        
         self._setup_routes()
 
     def _setup_routes(self) -> None:
@@ -284,10 +290,10 @@ def set_depth(self, depth: int) -> dict:
         with self._lock:
             self.engine_depth = depth
 
-            # Update depth on both engines if they have the attribute
+            # Update depth_limit on both engines if they have the attribute
             for engine in [self.white_engine, self.black_engine]:
-                if engine is not None and hasattr(engine, 'depth'):
-                    engine.depth = depth
+                if engine is not None and hasattr(engine, 'depth_limit'):
+                    engine.depth_limit = depth
 
             return {"depth": self.engine_depth}
 
@@ -304,7 +310,19 @@ def _get_engine_name(engine: Optional[Engine]) -> Optional[str]:
 
     def run(self, **kwargs):
         """Start the server."""
-        uvicorn.run(self.APP, **kwargs)
+        try:
+            uvicorn.run(self.APP, **kwargs)
+        finally:
+            self._cleanup_engines()
+    
+    def _cleanup_engines(self) -> None:
+        """Quit any HubEngine instances."""
+        for engine in [self.white_engine, self.black_engine]:
+            if isinstance(engine, HubEngine):
+                try:
+                    engine.quit()
+                except Exception:
+                    pass
 
 
 if __name__ == "__main__":
@@ -314,11 +332,11 @@ def run(self, **kwargs):
     logger.add(sys.stderr, level="DEBUG")
 
     from draughts.engine import AlphaBetaEngine
-    from draughts import get_board
+    from draughts import get_board , HubEngine
 
     # Example: Two engines playing against each other
-    white_engine = AlphaBetaEngine(depth=6)
-    black_engine = AlphaBetaEngine(depth=6)
+    white_engine = AlphaBetaEngine(depth_limit=6)
+    black_engine = HubEngine('./scan_engine/scan.exe', depth_limit=6)
 
     board = get_board("standard")
     server = Server(

examples/alphabeta_vs_scan.py

@@ -34,7 +34,7 @@ def play_game(scan_path: str, max_moves: int = 100) -> None:
     board = StandardBoard()
 
     # AlphaBeta plays White
-    alphabeta = AlphaBetaEngine(depth=9)
+    alphabeta = AlphaBetaEngine(depth_limit=9)
 
     # Scan plays Black
     print(f"Starting Scan engine from: {scan_path}")
@@ -43,7 +43,7 @@ def play_game(scan_path: str, max_moves: int = 100) -> None:
         scan.new_game()
 
         print("\n=== Game Start ===")
-        print(f"White: AlphaBeta (depth=9)")
+        print(f"White: AlphaBeta (depth_limit=9)")
         print(f"Black: {scan.info.name} {scan.info.version}")
         print()
 

readme.md

@@ -150,7 +150,7 @@ Legal moves are: ['31-27', '31-26', '32-28', '32-27', '33-29', '33-28', '34-30',
 
 ```python
 >>> from draughts.engine import AlphaBetaEngine
->>> engine = AlphaBetaEngine(depth=5)
+>>> engine = AlphaBetaEngine(depth_limit=5)
 >>> engine.get_best_move(board, with_evaluation=True)
 Move: 28->37, 3.0
 ```
@@ -172,7 +172,7 @@ via the Hub protocol:
 
 ```python
 >>> from draughts import HubEngine, StandardBoard
->>> with HubEngine("path/to/scan.exe", time_per_move=1.0) as engine:
+>>> with HubEngine("path/to/scan.exe", time_limit=1.0) as engine:
 ...     board = StandardBoard()
 ...     move, score = engine.get_best_move(board, with_evaluation=True)
 ...     print(f"Best move: {move}, Score: {score}")
@@ -182,7 +182,7 @@ Best move: 32-28, Score: 0.15
 The `HubEngine` class:
 - Manages the external engine subprocess lifecycle
 - Auto-detects variant from board type (Standard, Frisian)
-- Supports time-based or depth-based search
+- Supports time-based (`time_limit`) or depth-based (`depth_limit`) search
 - Works as a drop-in replacement for `AlphaBetaEngine`
 
 ## Web UI
@@ -209,8 +209,8 @@ from draughts.server import Server
 board = get_board('standard')
 
 # Create engines with different configurations
-white_engine = AlphaBetaEngine(depth=6)
-black_engine = AlphaBetaEngine(depth=4)
+white_engine = AlphaBetaEngine(depth_limit=6)
+black_engine = AlphaBetaEngine(depth_limit=4)
 
 server = Server(
     board=board,
@@ -239,7 +239,7 @@ board = get_board('standard')
 server = Server(
     board=board,
     white_engine=MyEngine(),
-    black_engine=AlphaBetaEngine(depth=5)
+    black_engine=AlphaBetaEngine(depth_limit=5)
 )
 server.run()
 ```

test/test_engine.py

@@ -12,7 +12,7 @@ class TestAlphaBetaEngine:
     @pytest.fixture(autouse=True)
     def setup(self):
         self.board = get_board("standard")
-        self.engine = AlphaBetaEngine(depth=3)
+        self.engine = AlphaBetaEngine(depth_limit=3)
         yield
         del self.board
         del self.engine
@@ -98,7 +98,7 @@ def _snapshot(board: StandardBoard):
 @pytest.mark.parametrize("seed", list(seeded_range(15)))
 def test_engine_get_best_move_does_not_mutate_board(seed):
     board = standard_board_after_random_play(seed=seed, plies=30)
-    engine = AlphaBetaEngine(depth=2)
+    engine = AlphaBetaEngine(depth_limit=2)
 
     if board.game_over:
         return
@@ -118,7 +118,7 @@ def test_engine_get_best_move_does_not_mutate_board(seed):
 @pytest.mark.parametrize("seed", list(seeded_range(15)))
 def test_engine_hash_is_stable_across_push_pop(seed):
     board = standard_board_after_random_play(seed=seed, plies=25)
-    engine = AlphaBetaEngine(depth=1)
+    engine = AlphaBetaEngine(depth_limit=1)
 
     legal = list(board.legal_moves)
     if not legal:
@@ -134,7 +134,7 @@ def test_engine_hash_is_stable_across_push_pop(seed):
 @pytest.mark.parametrize("seed", list(seeded_range(10)))
 def test_engine_populates_transposition_table_for_root(seed):
     board = standard_board_after_random_play(seed=seed, plies=20)
-    engine = AlphaBetaEngine(depth=2)
+    engine = AlphaBetaEngine(depth_limit=2)
 
     if board.game_over:
         return

test/test_server.py

@@ -3,12 +3,12 @@
 from fastapi.testclient import TestClient
 
 from draughts import get_board
-from draughts.engine import AlphaBetaEngine
+from draughts.engine import AlphaBetaEngine, Engine
 from draughts.server.server import Server
 from draughts.move import Move
 
 
-class _SlowStaleEngine:
+class _SlowStaleEngine(Engine):
     """Engine stub that always returns the same *initial* move after a delay.
 
     This simulates autoplay overlap: a long search returns a move that was legal
@@ -22,8 +22,10 @@ def __init__(self, stale_move, delay_s: float = 0.15):
         self._delay_s = delay_s
         self._time = time
 
-    def get_best_move(self, _board):
+    def get_best_move(self, _board, with_evaluation=False):
         self._time.sleep(self._delay_s)
+        if with_evaluation:
+            return self._stale_move, 0.0
         return self._stale_move
 
 
@@ -122,21 +124,21 @@ def test_set_depth_clamps_and_updates_engine():
     try:
         Server.APP = _new_test_app()
         board = get_board("standard")
-        engine = AlphaBetaEngine(depth=6)
+        engine = AlphaBetaEngine(depth_limit=6)
         server = Server(
-            board=board, get_best_move_method=engine.get_best_move, engine=engine
+            board=board, white_engine=engine, black_engine=engine
         )
         client = TestClient(server.APP)
 
         r = client.get("/set_depth/0")
         assert r.status_code == 200
         assert r.json()["depth"] == 1
-        assert engine.depth == 1
+        assert engine.depth_limit == 1
 
         r = client.get("/set_depth/999")
         assert r.status_code == 200
         assert r.json()["depth"] == 10
-        assert engine.depth == 10
+        assert engine.depth_limit == 10
     finally:
         Server.APP = old_app
 
@@ -158,7 +160,7 @@ def test_overlapping_best_move_requests_do_not_corrupt_board():
         stale_move = list(board.legal_moves)[0]
 
         engine = _SlowStaleEngine(stale_move=stale_move, delay_s=0.15)
-        server = Server(board=board, get_best_move_method=engine.get_best_move, engine=engine)
+        server = Server(board=board, white_engine=engine, black_engine=engine)
         client = TestClient(server.APP)
 
         barrier = threading.Barrier(3)
@@ -200,11 +202,14 @@ def test_best_move_falls_back_if_engine_returns_illegal_move():
         Server.APP = _new_test_app()
         board = get_board("standard")
 
-        def bad_engine(_board):
-            # Definitely illegal: no-op move
-            return Move([0, 0])
+        class BadEngine(Engine):
+            def get_best_move(self, _board, with_evaluation=False):
+                # Definitely illegal: no-op move
+                move = Move([0, 0])
+                return (move, 0.0) if with_evaluation else move
 
-        server = Server(board=board, get_best_move_method=bad_engine)
+        bad_engine = BadEngine()
+        server = Server(board=board, white_engine=bad_engine, black_engine=bad_engine)
         client = TestClient(server.APP)
 
         r = client.get("/best_move")

tools/depth_benchmark.py

@@ -30,7 +30,7 @@
 
 def benchmark_depth(depth: int) -> dict:
     """Benchmark engine at given depth, return stats."""
-    engine = AlphaBetaEngine(depth=depth)
+    engine = AlphaBetaEngine(depth_limit=depth)
 
     total_time = 0.0
     total_moves = 0