Merge branch 'main' into lichess-puzzle

Author: Vivian-X-Ma

agent_tournament.py

@@ -1,131 +1,43 @@
+"""
+Lightweight agent-versus-agent runner using shared utilities.
+
+This script used to duplicate play/timing logic; it now delegates to
+`scripts.agent_utils` to keep behavior consistent with other scripts.
+"""
 import argparse
 import chess
-import time
-from src.agents.base_agent import BaseAgent
-from src.agents import MinimaxAgent, AlphaBetaAgent, ExpectimaxAgent
-from evaluation import evaluate
-
-
-def play_single_game(white_agent: BaseAgent, black_agent: BaseAgent, timeout_seconds: int = 120):
-    """
-    Play one game between agents with a hard timeout and move-time tracking.
-    Returns:
-        result (str): "white", "black", "draw", or "timeout"
-        white_avg (float)
-        black_avg (float)
-    """
-    board = chess.Board()
-
-    white_times = []
-    black_times = []
-
-    start_game_time = time.time()
-
-    while not board.is_game_over():
-        # Hard 2 minute timeout
-        if time.time() - start_game_time > timeout_seconds:
-            print("Game terminated due to timeout.")
-            return "timeout", 0, 0
-
-        current_agent = white_agent if board.turn == chess.WHITE else black_agent
-
-        move_start = time.time()
-        print(f"{current_agent}")
-        move = current_agent.choose_move(board)
-        move_end = time.time()
-
-        if move is None:
-            print("Error: Agent returned None move.")
-            return "error", 0, 0
-
-        # Track move time
-        if board.turn == chess.WHITE:
-            white_times.append(move_end - move_start)
-        else:
-            black_times.append(move_end - move_start)
-
-        board.push(move)
-
-    # Compute averages
-    white_avg = sum(white_times) / len(white_times) if white_times else 0
-    black_avg = sum(black_times) / len(black_times) if black_times else 0
-
-    # Determine outcome
-    if board.is_checkmate():
-        winner = "white" if board.turn == chess.BLACK else "black"
-    else:
-        winner = "draw"
-
-    return winner, white_avg, black_avg
-
-
-def make_agents_play(white_agent: BaseAgent, black_agent: BaseAgent, iterations: int):
-    """
-    Run `iterations` number of games and report average move times.
-    """
-    white_avg_list = []
-    black_avg_list = []
-
-    for game_idx in range(1, iterations + 1):
-        print(f"\n=== Starting Game {game_idx}/{iterations} ===")
-        result, w_avg, b_avg = play_single_game(white_agent, black_agent)
-
-        print(f"Game {game_idx} result: {result}")
-        print(f"  White ({white_agent.name}) avg move time: {w_avg:.4f} sec")
-        print(f"  Black({black_agent.name}) avg move time: {b_avg:.4f} sec")
-
-        white_avg_list.append(w_avg)
-        black_avg_list.append(b_avg)
-
-    print("\n===== FINAL RESULTS ACROSS ALL GAMES =====")
-    print(f"{white_agent.name} mean move time: {sum(white_avg_list)/iterations:.4f} sec")
-    print(f"{black_agent.name} mean move time: {sum(black_avg_list)/iterations:.4f} sec")
+from scripts.agent_utils import create_agent, play_single_game_with_stats
 
 
 def main():
-    parser = argparse.ArgumentParser(description="Play chess with agents")
-    parser.add_argument(
-        "--white-agent",
-        choices=["minimax", "alphabeta", "expectimax"],
-        default="minimax",
-    )
-    parser.add_argument(
-        "--black-agent",
-        choices=["minimax", "alphabeta", "expectimax"],
-        default="alphabeta",
-    )
-    parser.add_argument(
-        "--depth",
-        type=int,
-        default=3,
-        choices=[2, 3, 4, 5],
-        help="Search depth for AI agents (default: 3)",
-    )
-    parser.add_argument(
-        "--num-games",
-        type=int,
-        default=1,
-        help="Number of games to run (default: 1)"
-    )
+    parser = argparse.ArgumentParser(description="Play games between two agents")
+    parser.add_argument("--white-agent", default="minimax", help="Agent key for White")
+    parser.add_argument("--black-agent", default="alphabeta", help="Agent key for Black")
+    parser.add_argument("--depth", type=int, default=3, help="Default search depth for search agents")
+    parser.add_argument("--num-games", type=int, default=1, help="Number of games to run")
+    parser.add_argument("--vi-iterations", type=int, default=3, help="ValueIteration iterations")
+    parser.add_argument("--q-train", type=int, default=0, help="QLearning training episodes")
+    parser.add_argument("--q-epsilon", type=float, default=0.0, help="QLearning epsilon during matches")
     args = parser.parse_args()
 
-    def create_agent(agent_type, color):
-        if agent_type == "minimax":
-            return MinimaxAgent(evaluate, depth=args.depth, name="Minimax", color=color)
-        elif agent_type == "alphabeta":
-            return AlphaBetaAgent(evaluate, depth=args.depth, name="AlphaBeta", color=color)
-        elif agent_type == "expectimax":
-            return ExpectimaxAgent(evaluate, depth=args.depth, name="Expectimax", color=color)
-        raise RuntimeError("Invalid agent type")
+    white = create_agent(args.white_agent, chess.WHITE, depth=args.depth, vi_iterations=args.vi_iterations, q_numTraining=args.q_train, q_epsilon=args.q_epsilon)
+    black = create_agent(args.black_agent, chess.BLACK, depth=args.depth, vi_iterations=args.vi_iterations, q_numTraining=args.q_train, q_epsilon=args.q_epsilon)
+
+    print(f"Running {args.num_games} games: White={white}, Black={black}")
+
+    white_times = []
+    black_times = []
 
-    white_agent = create_agent(args.white_agent, chess.WHITE)
-    black_agent = create_agent(args.black_agent, chess.BLACK)
+    for i in range(1, args.num_games + 1):
+        print(f"\n=== Game {i}/{args.num_games} ===")
+        result = play_single_game_with_stats(white, black)
+        print(f"Result: {result}")
 
-    print(f"Running {args.num_games} games:")
-    print(f"  White = {white_agent.name}")
-    print(f"  Black = {black_agent.name}")
 
-    make_agents_play(white_agent, black_agent, iterations=args.num_games)
+    if white_times:
+        print(f"\nWhite mean move time: {sum(white_times)/len(white_times):.4f}s")
+    if black_times:
+        print(f"Black mean move time: {sum(black_times)/len(black_times):.4f}s")
 
 
 if __name__ == "__main__":

evaluation.py

@@ -168,7 +168,7 @@ def get_piece_square_value(piece: chess.Piece, square: chess.Square, endgame=Fal
     return value
 
 
-def evaluate(board: chess.Board) -> int:
+def evaluate(board: chess.Board, ply: int = 0) -> int:
     """
     Evaluate the current board position.
     
@@ -182,8 +182,10 @@ def evaluate(board: chess.Board) -> int:
         return 0 # zero sum -> draw
 
     # Check for game ending condition
+    # Prefer faster mates by reducing the magnitude with ply distance
     if board.is_checkmate():
-        return -20000 if board.turn == chess.WHITE else 20000
+        mate_score = 20000 - ply
+        return -mate_score if board.turn == chess.WHITE else mate_score
 
     engame = is_endgame(board)
     score = 0

scripts/agent_utils.py

@@ -0,0 +1,78 @@
+"""
+Utilities for creating agents and running games.
+
+Centralizes agent factory logic so scripts can reuse the same constructors
+and parameters (depth, training iterations, etc.).
+"""
+from typing import Callable
+from pathlib import Path
+import sys
+import chess
+import time
+
+project_root = Path(__file__).resolve().parents[1]
+if str(project_root) not in sys.path:
+    sys.path.insert(0, str(project_root))
+
+from src.agents import (
+    MinimaxAgent,
+    AlphaBetaAgent,
+    ExpectimaxAgent,
+    RandomAgent,
+    SimpleAgent,
+    QLearningAgent,
+    ValueIterationAgent,
+)
+from src.evaluation import evaluate
+
+
+def create_agent(agent_key: str, color: chess.Color, *, depth: int = 3, vi_iterations: int = 3, q_numTraining: int = 0, q_epsilon: float = 0.0):
+    """Create an agent instance from a short key.
+
+    Parameters are provided with sane defaults for fast tests.
+    """
+    key = agent_key.lower()
+    if key == "minimax":
+        return MinimaxAgent(evaluate, depth=depth, name="Minimax", color=color)
+    if key == "alphabeta":
+        return AlphaBetaAgent(evaluate, depth=depth, name="AlphaBeta", color=color)
+    if key == "expectimax":
+        return ExpectimaxAgent(evaluate, depth=depth, name="Expectimax", color=color)
+    if key == "random":
+        return RandomAgent(name="Random", color=color)
+    if key == "simple":
+        return SimpleAgent(name="Simple", color=color)
+    if key == "qlearning":
+        return QLearningAgent(name="QLearning", color=color, numTraining=q_numTraining, epsilon=q_epsilon)
+    if key == "valueiteration":
+        return ValueIterationAgent(discount=0.9, iterations=vi_iterations, name="ValueIteration", color=color)
+
+    raise RuntimeError(f"Unknown agent type '{agent_key}'")
+
+
+def play_game(white_agent, black_agent, timeout_seconds: int = 120):
+    """Play one game between two agents. Returns outcome string: 'white','black','draw','timeout','error'."""
+    board = chess.Board()
+    start_time = time.time()
+
+    while not board.is_game_over():
+        if time.time() - start_time > timeout_seconds:
+            return "timeout"
+
+        current = white_agent if board.turn == chess.WHITE else black_agent
+        move = current.select_move(board)
+        if move is None:
+            return "error"
+        board.push(move)
+
+    if board.is_checkmate():
+        return "white" if board.turn == chess.BLACK else "black"
+    return "draw"
+
+
+def play_single_game_with_stats(white_agent, black_agent, timeout_seconds: int = 120):
+    """Play a game and return (result, white_avg_time, black_avg_time)."""
+    result = play_game(white_agent, black_agent, timeout_seconds)
+    white_avg = white_agent.total_time / white_agent.moves_made if white_agent.moves_made else 0
+    black_avg = black_agent.total_time / black_agent.moves_made if black_agent.moves_made else 0
+    return result, white_avg, black_avg

scripts/play_agents.py

@@ -0,0 +1,79 @@
+"""Run automated matches between two agents (agent vs agent)."""
+
+import argparse
+import chess
+import time
+from pathlib import Path
+import sys
+
+project_root = Path(__file__).resolve().parents[1]
+if str(project_root) not in sys.path:
+    sys.path.insert(0, str(project_root))
+
+from src.agents.base_agent import BaseAgent
+from scripts.agent_utils import create_agent, play_game as play_game_simple, play_single_game_with_stats
+
+
+def play_single_game(white_agent: BaseAgent, black_agent: BaseAgent, timeout_seconds: int = 600):
+    return play_game_simple(white_agent, black_agent, timeout_seconds)
+
+
+def make_agents_play(white_agent: BaseAgent, black_agent: BaseAgent, iterations: int):
+    results = {"white": 0, "black": 0, "draw": 0, "timeout": 0, "error": 0}
+    w_times = []
+    b_times = []
+
+    for i in range(1, iterations + 1):
+        print(f"\n=== Game {i}/{iterations} ===")
+        # reset stats
+        white_agent.reset_stats()
+        black_agent.reset_stats()
+
+        result, w_avg, b_avg = play_single_game_with_stats(white_agent, black_agent)
+        results[result] = results.get(result, 0) + 1
+        w_times.append(w_avg)
+        b_times.append(b_avg)
+
+        print(f"Result: {result}")
+        print(f"  White ({white_agent}): avg move time {w_avg:.4f}s")
+        print(f"  Black ({black_agent}): avg move time {b_avg:.4f}s")
+    
+
+    print("\n=== Summary ===")
+    print(results)
+    if w_times:
+        print(f"White mean move time: {sum(w_times)/len(w_times):.4f}s")
+    if b_times:
+        print(f"Black mean move time: {sum(b_times)/len(b_times):.4f}s")
+
+
+def create_agent_from_key(agent_key: str, color: chess.Color, *, depth: int = 3, vi_iterations: int = 3, q_numTraining: int = 0, q_epsilon: float = 0.0):
+    # thin wrapper to preserve CLI API used previously; forwards parameters to shared factory
+    return create_agent(agent_key, color, depth=depth, vi_iterations=vi_iterations, q_numTraining=q_numTraining, q_epsilon=q_epsilon)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run automated agent vs agent matches")
+    parser.add_argument("--white-agent", default="qlearning", help="Agent for White")
+    parser.add_argument("--black-agent", default="valueiteration", help="Agent for Black")
+    parser.add_argument("--num-games", type=int, default=1, help="Number of games to run")
+    parser.add_argument("--depth", type=int, default=3, help="Default search depth for search agents")
+    parser.add_argument("--white-depth", type=int, default=None, help="Search depth for White agent (overrides --depth)")
+    parser.add_argument("--black-depth", type=int, default=None, help="Search depth for Black agent (overrides --depth)")
+    parser.add_argument("--vi-iterations", type=int, default=3, help="Iterations for ValueIterationAgent")
+    parser.add_argument("--q-train", type=int, default=0, help="Number of training episodes for QLearningAgent before matches")
+    parser.add_argument("--q-epsilon", type=float, default=0.0, help="Exploration epsilon for QLearningAgent during matches")
+    args = parser.parse_args()
+
+    depth_white = args.white_depth if args.white_depth is not None else args.depth
+    depth_black = args.black_depth if args.black_depth is not None else args.depth
+
+    white = create_agent_from_key(args.white_agent, chess.WHITE, depth=depth_white, vi_iterations=args.vi_iterations, q_numTraining=args.q_train, q_epsilon=args.q_epsilon)
+    black = create_agent_from_key(args.black_agent, chess.BLACK, depth=depth_black, vi_iterations=args.vi_iterations, q_numTraining=args.q_train, q_epsilon=args.q_epsilon)
+
+    print(f"Playing {args.num_games} games: White={white}, Black={black}")
+    make_agents_play(white, black, iterations=args.num_games)
+
+
+if __name__ == "__main__":
+    main()