first commit

.gitattributes

@@ -0,0 +1,10 @@
+# Image files
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.svg filter=lfs diff=lfs merge=lfs -text
+
+# Specifically track assets directory with LFS
+frontend/assets/** filter=lfs diff=lfs merge=lfs -text
+frontend/streamlit/assets/** filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.pytest_cache
+.env
+.kiro
+.vscode
+# Local configuration files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+.env.staging.local
+.env.*.local
+
+

Dockerfile

@@ -0,0 +1,55 @@
+# Stage 1: Build the React frontend (can remain Alpine, it's a separate build environment)
+FROM node:18-alpine AS frontend-builder
+
+WORKDIR /app/frontend/web
+
+COPY frontend/web/package*.json ./
+RUN npm install
+COPY frontend/web/ ./
+
+# Stage 2: Build the Python backend (switching to Debian-based image)
+FROM python:3.11-slim AS backend-builder
+
+WORKDIR /app
+
+# Install build tools using apt-get
+RUN apt-get update && apt-get install -y --no-install-recommends gcc && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.api.txt .
+RUN pip install --no-cache-dir -r requirements.api.txt
+
+COPY chess_engine/ ./chess_engine
+COPY main.py .
+COPY app.py .
+
+# Stage 3: Final image (switching to Debian-based image)
+FROM python:3.11-slim
+
+# Install Node.js, npm, Stockfish, and dos2unix using apt-get
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends curl dos2unix && \
+    curl -fsSL https://deb.nodesource.com/setup_18.x | bash - && \
+    apt-get install -y --no-install-recommends nodejs stockfish && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy the frontend code and dependencies
+COPY --from=frontend-builder /app/frontend/web/ ./frontend/web/
+
+# Copy the installed Python dependencies
+COPY --from=backend-builder /usr/local/lib/python3.11/site-packages/ /usr/local/lib/python3.11/site-packages/
+COPY --from=backend-builder /app/chess_engine ./chess_engine
+COPY --from=backend-builder /app/main.py .
+COPY --from=backend-builder /app/app.py .
+
+# Copy the entrypoint script and ensure it's executable
+COPY docker-entrypoint.sh .
+RUN dos2unix docker-entrypoint.sh && \
+    chmod +x docker-entrypoint.sh
+
+# Expose the ports
+EXPOSE 8000
+EXPOSE 5173
+
+ENTRYPOINT ["./docker-entrypoint.sh"]

LICENSE-ASSETS.md

@@ -0,0 +1,29 @@
+# Asset Licensing Information
+
+## Chess Pieces and Board Squares
+The chess piece images and board square assets in this project were sourced from [OpenGameArt.org](https://opengameart.org/) under the [Creative Commons Attribution-ShareAlike (CC-BY-SA) license](https://creativecommons.org/licenses/by-sa/4.0/).
+
+### Attribution
+- Source: "Chess Pieces and Board squares" from OpenGameArt.org
+- Original Author: As specified on OpenGameArt.org
+- License: Creative Commons Attribution-ShareAlike (CC-BY-SA)
+- Link: https://opengameart.org/
+
+### License Compliance
+These assets are used in compliance with the CC-BY-SA license, which requires:
+1. **Attribution**: We have provided appropriate credit to the original creator.
+2. **ShareAlike**: Any derivative works incorporating these assets must be distributed under the same license terms.
+
+## License Compatibility Notice
+
+This project uses the MIT License for code, while some assets are under the CC-BY-SA license. Please note:
+
+1. The MIT License applies to all software code in this repository.
+2. The CC-BY-SA license applies to the chess piece images and board square assets in the `frontend/assets` and `frontend/streamlit/assets` directories.
+
+### Important:
+If you redistribute this project or create derivative works:
+- You may use the code under the terms of the MIT License.
+- You must comply with the CC-BY-SA license for the chess piece assets, which includes providing attribution and sharing any modifications to these assets under the same CC-BY-SA license.
+
+This dual licensing approach is common in projects that combine code with creative assets from different sources.

README.md

@@ -0,0 +1,90 @@
+# Chess Engine with Stockfish Integration
+
+---
+title: Image Captioning with BLIP
+emoji: ♟️🏁♟️
+colorFrom: green
+colorTo: orange
+sdk: docker
+app_port: 5173
+---
+
+
+
+A Python chess engine with Stockfish integration, providing both a command-line interface and a REST API for playing chess against an AI opponent.
+
+## Features
+
+- **AI Integration**: Play against Stockfish, one of the strongest chess engines available
+- **Multiple Interfaces**:
+  - Command-line interface for quick games
+  - REST API for integration with web or desktop applications
+  - Streamlit web interface for graphical gameplay
+- **Adjustable Difficulty**: Six difficulty levels from beginner to master
+- **Position Analysis**: Get detailed evaluation of board positions
+- **Move Hints**: Receive suggestions and explanations for optimal moves
+- **Notation Support**: Works with both UCI (e2e4) and SAN (e4) chess notations
+- **Game Management**: Start, play, analyze, and save games
+- **Comprehensive Evaluation**: Material balance, piece positioning, king safety, mobility, and pawn structure
+
+## Requirements
+
+- Python 3.8+
+- Stockfish chess engine (optional, but recommended for AI play)
+- Dependencies listed in requirements.txt
+
+
+## API Documentation
+
+For information please refer Dockerfile
+
+### Example API Usage
+
+Start a new game:
+```bash
+curl -X POST "http://localhost:8000/game/new" \
+  -H "Content-Type: application/json" \
+  -d '{"player_color": "white", "difficulty": "medium"}'
+```
+
+Make a move:
+```bash
+curl -X POST "http://localhost:8000/game/move" \
+  -H "Content-Type: application/json" \
+  -d '{"move": "e2e4"}'
+```
+
+Get current game state:
+```bash
+curl -X GET "http://localhost:8000/game/state"
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+python test/run_tests.py
+```
+
+For more detailed output:
+
+```bash
+python test/run_tests.py -v
+```
+
+The test suite includes:
+- Board representation and move validation tests
+- Position evaluation tests
+- Game controller tests
+- REST API endpoint tests
+
+## License
+
+### Code
+The code in this repository is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+### Assets
+The chess piece images and board square assets are licensed under the Creative Commons Attribution-ShareAlike (CC-BY-SA) license. See the [LICENSE-ASSETS.md](LICENSE-ASSETS.md) file for details on attribution and compliance requirements.
+
+**Note:** If you redistribute this project or create derivative works, you must comply with both licenses - MIT for the code and CC-BY-SA for the assets.

app.py

@@ -0,0 +1,9 @@
+"""
+Chess Engine API Server
+This file provides the FastAPI app for the chess engine.
+"""
+
+from chess_engine.api.rest_api import app
+
+# This file is used by Uvicorn to run the API server
+# The app variable is imported from chess_engine.api.rest_api

chess_engine/__init__.py

@@ -0,0 +1,13 @@
+# chess_engine/__init__.py
+
+"""
+Chess Engine with Stockfish Integration
+
+A Python chess engine with Stockfish integration, providing both a 
+command-line interface and a REST API.
+"""
+
+__version__ = "0.1.0"
+
+from chess_engine.board import ChessBoard
+from chess_engine.pieces import ChessPiece, PieceManager

chess_engine/ai/__init__.py

@@ -0,0 +1,4 @@
+# chess_engine/ai/__init__.py
+
+from chess_engine.ai.evaluation import ChessEvaluator, PositionEvaluation
+from chess_engine.ai.stockfish_wrapper import StockfishWrapper, DifficultyLevel

chess_engine/ai/evaluation.py

@@ -0,0 +1,535 @@
+# chess_engine/ai/evaluation.py
+
+import chess
+from typing import Dict, List, Tuple, Optional
+from dataclasses import dataclass
+import math
+
+@dataclass
+class PositionEvaluation:
+    """Complete position evaluation data"""
+    total_score: float
+    material_score: float
+    positional_score: float
+    safety_score: float
+    mobility_score: float
+    pawn_structure_score: float
+    endgame_score: float
+    white_advantage: float
+    evaluation_breakdown: Dict[str, float]
+
+class ChessEvaluator:
+    """
+    Chess position evaluator with various strategic factors
+    """
+    
+    # Piece values in centipawns
+    PIECE_VALUES = {
+        chess.PAWN: 100,
+        chess.KNIGHT: 320,
+        chess.BISHOP: 330,
+        chess.ROOK: 500,
+        chess.QUEEN: 900,
+        chess.KING: 20000
+    }
+    
+    # Piece-square tables for positional evaluation
+    PAWN_TABLE = [
+        [0,  0,  0,  0,  0,  0,  0,  0],
+        [50, 50, 50, 50, 50, 50, 50, 50],
+        [10, 10, 20, 30, 30, 20, 10, 10],
+        [5,  5, 10, 25, 25, 10,  5,  5],
+        [0,  0,  0, 20, 20,  0,  0,  0],
+        [5, -5,-10,  0,  0,-10, -5,  5],
+        [5, 10, 10,-20,-20, 10, 10,  5],
+        [0,  0,  0,  0,  0,  0,  0,  0]
+    ]
+    
+    KNIGHT_TABLE = [
+        [-50,-40,-30,-30,-30,-30,-40,-50],
+        [-40,-20,  0,  0,  0,  0,-20,-40],
+        [-30,  0, 10, 15, 15, 10,  0,-30],
+        [-30,  5, 15, 20, 20, 15,  5,-30],
+        [-30,  0, 15, 20, 20, 15,  0,-30],
+        [-30,  5, 10, 15, 15, 10,  5,-30],
+        [-40,-20,  0,  5,  5,  0,-20,-40],
+        [-50,-40,-30,-30,-30,-30,-40,-50]
+    ]
+    
+    BISHOP_TABLE = [
+        [-20,-10,-10,-10,-10,-10,-10,-20],
+        [-10,  0,  0,  0,  0,  0,  0,-10],
+        [-10,  0,  5, 10, 10,  5,  0,-10],
+        [-10,  5,  5, 10, 10,  5,  5,-10],
+        [-10,  0, 10, 10, 10, 10,  0,-10],
+        [-10, 10, 10, 10, 10, 10, 10,-10],
+        [-10,  5,  0,  0,  0,  0,  5,-10],
+        [-20,-10,-10,-10,-10,-10,-10,-20]
+    ]
+    
+    ROOK_TABLE = [
+        [0,  0,  0,  0,  0,  0,  0,  0],
+        [5, 10, 10, 10, 10, 10, 10,  5],
+        [-5,  0,  0,  0,  0,  0,  0, -5],
+        [-5,  0,  0,  0,  0,  0,  0, -5],
+        [-5,  0,  0,  0,  0,  0,  0, -5],
+        [-5,  0,  0,  0,  0,  0,  0, -5],
+        [-5,  0,  0,  0,  0,  0,  0, -5],
+        [0,  0,  0,  5,  5,  0,  0,  0]
+    ]
+    
+    QUEEN_TABLE = [
+        [-20,-10,-10, -5, -5,-10,-10,-20],
+        [-10,  0,  0,  0,  0,  0,  0,-10],
+        [-10,  0,  5,  5,  5,  5,  0,-10],
+        [-5,  0,  5,  5,  5,  5,  0, -5],
+        [0,  0,  5,  5,  5,  5,  0, -5],
+        [-10,  5,  5,  5,  5,  5,  0,-10],
+        [-10,  0,  5,  0,  0,  0,  0,-10],
+        [-20,-10,-10, -5, -5,-10,-10,-20]
+    ]
+    
+    KING_TABLE_MIDDLEGAME = [
+        [-30,-40,-40,-50,-50,-40,-40,-30],
+        [-30,-40,-40,-50,-50,-40,-40,-30],
+        [-30,-40,-40,-50,-50,-40,-40,-30],
+        [-30,-40,-40,-50,-50,-40,-40,-30],
+        [-20,-30,-30,-40,-40,-30,-30,-20],
+        [-10,-20,-20,-20,-20,-20,-20,-10],
+        [20, 20,  0,  0,  0,  0, 20, 20],
+        [20, 30, 10,  0,  0, 10, 30, 20]
+    ]
+    
+    KING_TABLE_ENDGAME = [
+        [-50,-40,-30,-20,-20,-30,-40,-50],
+        [-30,-20,-10,  0,  0,-10,-20,-30],
+        [-30,-10, 20, 30, 30, 20,-10,-30],
+        [-30,-10, 30, 40, 40, 30,-10,-30],
+        [-30,-10, 30, 40, 40, 30,-10,-30],
+        [-30,-10, 20, 30, 30, 20,-10,-30],
+        [-30,-30,  0,  0,  0,  0,-30,-30],
+        [-50,-30,-30,-30,-30,-30,-30,-50]
+    ]
+    
+    def __init__(self):
+        """Initialize the evaluator"""
+        self.piece_square_tables = {
+            chess.PAWN: self.PAWN_TABLE,
+            chess.KNIGHT: self.KNIGHT_TABLE,
+            chess.BISHOP: self.BISHOP_TABLE,
+            chess.ROOK: self.ROOK_TABLE,
+            chess.QUEEN: self.QUEEN_TABLE,
+            chess.KING: self.KING_TABLE_MIDDLEGAME
+        }
+    
+    def evaluate_position(self, board: chess.Board) -> PositionEvaluation:
+        """
+        Comprehensive position evaluation
+        
+        Args:
+            board: Chess board to evaluate
+            
+        Returns:
+            PositionEvaluation object with detailed analysis
+        """
+        if board.is_checkmate():
+            score = -20000 if board.turn == chess.WHITE else 20000
+            return PositionEvaluation(
+                total_score=score,
+                material_score=score,
+                positional_score=0,
+                safety_score=0,
+                mobility_score=0,
+                pawn_structure_score=0,
+                endgame_score=0,
+                white_advantage=score,
+                evaluation_breakdown={"checkmate": score}
+            )
+        
+        if board.is_stalemate() or board.is_insufficient_material():
+            return PositionEvaluation(
+                total_score=0,
+                material_score=0,
+                positional_score=0,
+                safety_score=0,
+                mobility_score=0,
+                pawn_structure_score=0,
+                endgame_score=0,
+                white_advantage=0,
+                evaluation_breakdown={"draw": 0}
+            )
+        
+        # Calculate individual evaluation components
+        material_score = self._evaluate_material(board)
+        positional_score = self._evaluate_position_tables(board)
+        safety_score = self._evaluate_king_safety(board)
+        mobility_score = self._evaluate_mobility(board)
+        pawn_structure_score = self._evaluate_pawn_structure(board)
+        endgame_score = self._evaluate_endgame_factors(board)
+        
+        # Combine scores
+        total_score = (
+            material_score + 
+            positional_score + 
+            safety_score + 
+            mobility_score + 
+            pawn_structure_score + 
+            endgame_score
+        )
+        
+        # Create breakdown
+        breakdown = {
+            "material": material_score,
+            "positional": positional_score,
+            "safety": safety_score,
+            "mobility": mobility_score,
+            "pawn_structure": pawn_structure_score,
+            "endgame": endgame_score
+        }
+        
+        return PositionEvaluation(
+            total_score=total_score,
+            material_score=material_score,
+            positional_score=positional_score,
+            safety_score=safety_score,
+            mobility_score=mobility_score,
+            pawn_structure_score=pawn_structure_score,
+            endgame_score=endgame_score,
+            white_advantage=total_score,
+            evaluation_breakdown=breakdown
+        )
+    
+    def _evaluate_material(self, board: chess.Board) -> float:
+        """Evaluate material balance"""
+        score = 0
+        
+        for square in chess.SQUARES:
+            piece = board.piece_at(square)
+            if piece:
+                value = self.PIECE_VALUES[piece.piece_type]
+                score += value if piece.color == chess.WHITE else -value
+        
+        return score
+    
+    def _evaluate_position_tables(self, board: chess.Board) -> float:
+        """Evaluate piece positions using piece-square tables"""
+        score = 0
+        is_endgame = self._is_endgame(board)
+        
+        for square in chess.SQUARES:
+            piece = board.piece_at(square)
+            if piece:
+                rank = chess.square_rank(square)
+                file = chess.square_file(square)
+                
+                # Choose appropriate table for king
+                if piece.piece_type == chess.KING:
+                    table = self.KING_TABLE_ENDGAME if is_endgame else self.KING_TABLE_MIDDLEGAME
+                else:
+                    table = self.piece_square_tables[piece.piece_type]
+                
+                # Flip table for black pieces
+                if piece.color == chess.WHITE:
+                    value = table[rank][file]
+                else:
+                    value = -table[7-rank][file]
+                
+                score += value
+        
+        return score
+    
+    def _evaluate_king_safety(self, board: chess.Board) -> float:
+        """Evaluate king safety"""
+        score = 0
+        
+        # Check for king exposure
+        for color in [chess.WHITE, chess.BLACK]:
+            king_square = board.king(color)
+            if king_square is None:
+                continue
+            
+            # Count attackers around king
+            attackers = 0
+            defenders = 0
+            
+            for square in chess.SQUARES:
+                if chess.square_distance(king_square, square) <= 2:
+                    if board.is_attacked_by(not color, square):
+                        attackers += 1
+                    if board.is_attacked_by(color, square):
+                        defenders += 1
+            
+            safety = (defenders - attackers) * 10
+            score += safety if color == chess.WHITE else -safety
+        
+        return score
+    
+    def _evaluate_mobility(self, board: chess.Board) -> float:
+        """Evaluate piece mobility"""
+        white_mobility = len(list(board.legal_moves)) if board.turn == chess.WHITE else 0
+        
+        # Switch turn to count black mobility
+        board.turn = not board.turn
+        black_mobility = len(list(board.legal_moves)) if board.turn == chess.BLACK else 0
+        board.turn = not board.turn  # Switch back
+        
+        return (white_mobility - black_mobility) * 1.5
+    
+    def _evaluate_pawn_structure(self, board: chess.Board) -> float:
+        """Evaluate pawn structure"""
+        score = 0
+        
+        # Get pawn positions
+        white_pawns = [sq for sq in chess.SQUARES if board.piece_at(sq) and 
+                      board.piece_at(sq).piece_type == chess.PAWN and 
+                      board.piece_at(sq).color == chess.WHITE]
+        
+        black_pawns = [sq for sq in chess.SQUARES if board.piece_at(sq) and 
+                      board.piece_at(sq).piece_type == chess.PAWN and 
+                      board.piece_at(sq).color == chess.BLACK]
+        
+        # Evaluate doubled pawns
+        score += self._evaluate_doubled_pawns(white_pawns, chess.WHITE)
+        score += self._evaluate_doubled_pawns(black_pawns, chess.BLACK)
+        
+        # Evaluate isolated pawns
+        score += self._evaluate_isolated_pawns(white_pawns, chess.WHITE)
+        score += self._evaluate_isolated_pawns(black_pawns, chess.BLACK)
+        
+        # Evaluate passed pawns
+        score += self._evaluate_passed_pawns(board, white_pawns, chess.WHITE)
+        score += self._evaluate_passed_pawns(board, black_pawns, chess.BLACK)
+        
+        return score
+    
+    def _evaluate_doubled_pawns(self, pawns: List[int], color: chess.Color) -> float:
+        """Evaluate doubled pawns penalty"""
+        files = {}
+        for pawn in pawns:
+            file = chess.square_file(pawn)
+            files[file] = files.get(file, 0) + 1
+        
+        doubled_count = sum(max(0, count - 1) for count in files.values())
+        penalty = doubled_count * -20
+        
+        return penalty if color == chess.WHITE else -penalty
+    
+    def _evaluate_isolated_pawns(self, pawns: List[int], color: chess.Color) -> float:
+        """Evaluate isolated pawns penalty"""
+        files = set(chess.square_file(pawn) for pawn in pawns)
+        isolated_count = 0
+        
+        for file in files:
+            if (file - 1 not in files) and (file + 1 not in files):
+                isolated_count += 1
+        
+        penalty = isolated_count * -15
+        return penalty if color == chess.WHITE else -penalty
+    
+    def _evaluate_passed_pawns(self, board: chess.Board, pawns: List[int], color: chess.Color) -> float:
+        """Evaluate passed pawns bonus"""
+        bonus = 0
+        opponent_color = not color
+        
+        for pawn in pawns:
+            file = chess.square_file(pawn)
+            rank = chess.square_rank(pawn)
+            
+            # Check if pawn is passed
+            is_passed = True
+            direction = 1 if color == chess.WHITE else -1
+            
+            # Check files that could block this pawn
+            for check_file in [file - 1, file, file + 1]:
+                if 0 <= check_file <= 7:
+                    for check_rank in range(rank + direction, 8 if color == chess.WHITE else -1, direction):
+                        if 0 <= check_rank <= 7:
+                            square = chess.square(check_file, check_rank)
+                            piece = board.piece_at(square)
+                            if piece and piece.piece_type == chess.PAWN and piece.color == opponent_color:
+                                is_passed = False
+                                break
+                    if not is_passed:
+                        break
+            
+            if is_passed:
+                # Bonus increases with advancement
+                advancement = rank if color == chess.WHITE else 7 - rank
+                bonus += advancement * 10
+        
+        return bonus if color == chess.WHITE else -bonus
+    
+    def _is_endgame(self, board: chess.Board) -> bool:
+        """
+        Determine if the position is in the endgame
+        
+        Args:
+            board: Chess board to evaluate
+            
+        Returns:
+            True if position is in endgame, False otherwise
+        """
+        # Count major pieces (queens and rooks)
+        queens = 0
+        rooks = 0
+        total_material = 0
+        
+        for square in chess.SQUARES:
+            piece = board.piece_at(square)
+            if piece:
+                if piece.piece_type == chess.QUEEN:
+                    queens += 1
+                elif piece.piece_type == chess.ROOK:
+                    rooks += 1
+                total_material += self.PIECE_VALUES[piece.piece_type]
+        
+        # Endgame conditions:
+        # 1. No queens
+        # 2. Only one queen total and no other major pieces
+        # 3. Less than 25% of starting material
+        return (queens == 0) or (queens == 1 and rooks <= 1) or (total_material < 3200)
+    
+    def _evaluate_endgame_factors(self, board: chess.Board) -> float:
+        """Evaluate endgame-specific factors"""
+        if not self._is_endgame(board):
+            return 0
+        
+        score = 0
+        
+        # King centralization in endgame
+        score += self._evaluate_king_centralization(board)
+        
+        # Passed pawns become more valuable in endgame
+        score += self._evaluate_endgame_passed_pawns(board)
+        
+        # Rook on open files
+        score += self._evaluate_rooks_on_open_files(board)
+        
+        return score
+    
+    def _evaluate_king_centralization(self, board: chess.Board) -> float:
+        """
+        Evaluate king centralization in endgame
+        Kings should move to the center in endgames
+        """
+        score = 0
+        
+        for color in [chess.WHITE, chess.BLACK]:
+            king_square = board.king(color)
+            if king_square is None:
+                continue
+            
+            # Calculate distance from center (d4, d5, e4, e5)
+            file = chess.square_file(king_square)
+            rank = chess.square_rank(king_square)
+            
+            # Distance from center files (0-3.5)
+            file_distance = abs(3.5 - file)
+            
+            # Distance from center ranks (0-3.5)
+            rank_distance = abs(3.5 - rank)
+            
+            # Manhattan distance from center
+            center_distance = file_distance + rank_distance
+            
+            # Bonus for being close to center (max 15 points)
+            centralization_bonus = (7 - center_distance) * 3
+            
+            if color == chess.WHITE:
+                score += centralization_bonus
+            else:
+                score -= centralization_bonus
+        
+        return score
+    
+    def _evaluate_endgame_passed_pawns(self, board: chess.Board) -> float:
+        """
+        Evaluate passed pawns in endgame - they're more valuable
+        """
+        score = 0
+        
+        # Get pawn positions
+        white_pawns = [sq for sq in chess.SQUARES if board.piece_at(sq) and 
+                      board.piece_at(sq).piece_type == chess.PAWN and 
+                      board.piece_at(sq).color == chess.WHITE]
+        
+        black_pawns = [sq for sq in chess.SQUARES if board.piece_at(sq) and 
+                      board.piece_at(sq).piece_type == chess.PAWN and 
+                      board.piece_at(sq).color == chess.BLACK]
+        
+        # Check for passed pawns
+        for pawn in white_pawns:
+            if self._is_passed_pawn(board, pawn, chess.WHITE):
+                rank = chess.square_rank(pawn)
+                # Bonus increases dramatically with advancement
+                bonus = (rank * rank) * 5
+                score += bonus
+        
+        for pawn in black_pawns:
+            if self._is_passed_pawn(board, pawn, chess.BLACK):
+                rank = 7 - chess.square_rank(pawn)  # Flip for black
+                # Bonus increases dramatically with advancement
+                bonus = (rank * rank) * 5
+                score -= bonus
+        
+        return score
+    
+    def _is_passed_pawn(self, board: chess.Board, square: int, color: chess.Color) -> bool:
+        """Check if a pawn is passed"""
+        file = chess.square_file(square)
+        rank = chess.square_rank(square)
+        
+        # Direction of pawn movement
+        direction = 1 if color == chess.WHITE else -1
+        
+        # Check files that could block this pawn
+        for check_file in [file - 1, file, file + 1]:
+            if 0 <= check_file <= 7:
+                for check_rank in range(rank + direction, 8 if color == chess.WHITE else -1, direction):
+                    if 0 <= check_rank <= 7:
+                        check_square = chess.square(check_file, check_rank)
+                        piece = board.piece_at(check_square)
+                        if piece and piece.piece_type == chess.PAWN and piece.color != color:
+                            return False
+        
+        return True
+    
+    def _evaluate_rooks_on_open_files(self, board: chess.Board) -> float:
+        """Evaluate rooks on open or semi-open files"""
+        score = 0
+        
+        # Get all files with pawns
+        files_with_white_pawns = set()
+        files_with_black_pawns = set()
+        
+        for square in chess.SQUARES:
+            piece = board.piece_at(square)
+            if piece and piece.piece_type == chess.PAWN:
+                file = chess.square_file(square)
+                if piece.color == chess.WHITE:
+                    files_with_white_pawns.add(file)
+                else:
+                    files_with_black_pawns.add(file)
+        
+        # Check rooks
+        for square in chess.SQUARES:
+            piece = board.piece_at(square)
+            if piece and piece.piece_type == chess.ROOK:
+                file = chess.square_file(square)
+                
+                # Open file (no pawns)
+                if file not in files_with_white_pawns and file not in files_with_black_pawns:
+                    bonus = 25
+                # Semi-open file (no friendly pawns)
+                elif (piece.color == chess.WHITE and file not in files_with_white_pawns) or \
+                     (piece.color == chess.BLACK and file not in files_with_black_pawns):
+                    bonus = 15
+                else:
+                    bonus = 0
+                
+                if piece.color == chess.WHITE:
+                    score += bonus
+                else:
+                    score -= bonus
+        
+        return score

chess_engine/ai/stockfish_wrapper.py

@@ -0,0 +1,422 @@
+# chess_engine/ai/stockfish_wrapper.py
+
+import chess
+import chess.engine
+from stockfish import Stockfish
+from typing import Optional, Dict, List, Tuple, Any
+from enum import Enum
+import asyncio
+import logging
+from dataclasses import dataclass
+
+class DifficultyLevel(Enum):
+    BEGINNER = 1
+    EASY = 3
+    MEDIUM = 5
+    HARD = 8
+    EXPERT = 12
+    MASTER = 15
+
+@dataclass
+class EngineConfig:
+    """Configuration for Stockfish engine"""
+    depth: int = 10
+    time_limit: float = 1.0  # seconds
+    threads: int = 1
+    hash_size: int = 16  # MB
+    skill_level: int = 20  # 0-20 (20 is strongest)
+    contempt: int = 0
+    ponder: bool = False
+
+@dataclass
+class MoveAnalysis:
+    """Analysis result for a move"""
+    best_move: str
+    evaluation: float
+    depth: int
+    principal_variation: List[str]
+    time_taken: float
+    nodes_searched: int
+
+class StockfishWrapper:
+    """
+    Wrapper for Stockfish chess engine with both python-chess and stockfish library support
+    """
+    
+    def __init__(self, stockfish_path: Optional[str] = None, config: Optional[EngineConfig] = None):
+        """
+        Initialize Stockfish wrapper
+        
+        Args:
+            stockfish_path: Path to Stockfish executable
+            config: Engine configuration
+        """
+        self.config = config or EngineConfig()
+        self.stockfish_path = stockfish_path
+        self.engine = None
+        self.stockfish = None
+        self.is_initialized = False
+        
+        # Setup logging
+        self.logger = logging.getLogger(__name__)
+        
+    def initialize(self) -> bool:
+        """
+        Initialize the Stockfish engine
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            # Try to initialize with stockfish library first
+            if self.stockfish_path:
+                self.stockfish = Stockfish(
+                    path=self.stockfish_path,
+                    depth=self.config.depth,
+                    parameters={
+                        "Threads": self.config.threads,
+                        "Hash": self.config.hash_size,
+                        "Skill Level": self.config.skill_level,
+                        "Contempt": self.config.contempt,
+                        "Ponder": self.config.ponder
+                    }
+                )
+            else:
+                # Use default system Stockfish
+                self.stockfish = Stockfish(
+                    depth=self.config.depth,
+                    parameters={
+                        "Threads": self.config.threads,
+                        "Hash": self.config.hash_size,
+                        "Skill Level": self.config.skill_level,
+                        "Contempt": self.config.contempt,
+                        "Ponder": self.config.ponder
+                    }
+                )
+            
+            # Test if engine is working
+            if self.stockfish.is_fen_valid("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"):
+                self.is_initialized = True
+                self.logger.info("Stockfish engine initialized successfully")
+                return True
+            else:
+                self.logger.error("Stockfish engine test failed")
+                return False
+                
+        except Exception as e:
+            self.logger.error(f"Failed to initialize Stockfish: {e}")
+            return False
+    
+    async def initialize_async(self) -> bool:
+        """
+        Initialize the chess.engine for async operations
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            if self.stockfish_path:
+                self.engine = await chess.engine.SimpleEngine.popen_uci(self.stockfish_path)
+            else:
+                # Try common Stockfish paths
+                paths = [
+                    "/usr/bin/stockfish",
+                    "/usr/local/bin/stockfish",
+                    "stockfish",
+                    "stockfish.exe"
+                ]
+                
+                for path in paths:
+                    try:
+                        self.engine = await chess.engine.SimpleEngine.popen_uci(path)
+                        break
+                    except FileNotFoundError:
+                        continue
+                
+                if not self.engine:
+                    raise FileNotFoundError("Stockfish executable not found")
+            
+            # Configure engine
+            await self.engine.configure({
+                "Threads": self.config.threads,
+                "Hash": self.config.hash_size,
+                "Skill Level": self.config.skill_level,
+                "Contempt": self.config.contempt,
+                "Ponder": self.config.ponder
+            })
+            
+            self.is_initialized = True
+            self.logger.info("Async Stockfish engine initialized successfully")
+            return True
+            
+        except Exception as e:
+            self.logger.error(f"Failed to initialize async Stockfish: {e}")
+            return False
+    
+    def get_best_move(self, board: chess.Board, time_limit: Optional[float] = None) -> Optional[str]:
+        """
+        Get the best move for current position
+        
+        Args:
+            board: Current chess board position
+            time_limit: Time limit in seconds (overrides config)
+            
+        Returns:
+            Best move in UCI notation or None if error
+        """
+        if not self.is_initialized or not self.stockfish:
+            return None
+        
+        try:
+            # Set position
+            self.stockfish.set_fen_position(board.fen())
+            
+            # Get best move
+            best_move = self.stockfish.get_best_move_time(
+                time_limit or self.config.time_limit * 1000  # Convert to milliseconds
+            )
+            
+            return best_move
+            
+        except Exception as e:
+            self.logger.error(f"Error getting best move: {e}")
+            return None
+    
+    async def get_best_move_async(self, board: chess.Board, time_limit: Optional[float] = None) -> Optional[MoveAnalysis]:
+        """
+        Get the best move asynchronously with detailed analysis
+        
+        Args:
+            board: Current chess board position
+            time_limit: Time limit in seconds
+            
+        Returns:
+            MoveAnalysis object or None if error
+        """
+        if not self.is_initialized or not self.engine:
+            return None
+        
+        try:
+            # Set up analysis parameters
+            limit = chess.engine.Limit(
+                time=time_limit or self.config.time_limit,
+                depth=self.config.depth
+            )
+            
+            # Analyze position
+            info = await self.engine.analyse(board, limit)
+            
+            # Get best move
+            result = await self.engine.play(board, limit)
+            
+            # Extract information
+            evaluation = info.get("score", chess.engine.Cp(0))
+            pv = info.get("pv", [])
+            
+            # Convert evaluation to numerical value
+            if evaluation.is_mate():
+                eval_value = 1000.0 if evaluation.mate() > 0 else -1000.0
+            else:
+                eval_value = evaluation.score() / 100.0  # Convert centipawns to pawns
+            
+            return MoveAnalysis(
+                best_move=result.move.uci() if result.move else "",
+                evaluation=eval_value,
+                depth=info.get("depth", 0),
+                principal_variation=[move.uci() for move in pv],
+                time_taken=info.get("time", 0.0),
+                nodes_searched=info.get("nodes", 0)
+            )
+            
+        except Exception as e:
+            self.logger.error(f"Error in async move analysis: {e}")
+            return None
+    
+    def evaluate_position(self, board: chess.Board) -> Optional[float]:
+        """
+        Evaluate current position
+        
+        Args:
+            board: Current chess board position
+            
+        Returns:
+            Evaluation in pawns (positive for white advantage)
+        """
+        if not self.is_initialized or not self.stockfish:
+            return None
+        
+        try:
+            self.stockfish.set_fen_position(board.fen())
+            evaluation = self.stockfish.get_evaluation()
+            
+            if evaluation is None:
+                return 0.0
+            
+            if evaluation["type"] == "cp":
+                return evaluation["value"] / 100.0  # Convert centipawns to pawns
+            elif evaluation["type"] == "mate":
+                return 1000.0 if evaluation["value"] > 0 else -1000.0
+            
+            return 0.0
+            
+        except Exception as e:
+            self.logger.error(f"Error evaluating position: {e}")
+            return None
+    
+    def get_legal_moves_with_evaluation(self, board: chess.Board) -> List[Tuple[str, float]]:
+        """
+        Get all legal moves with their evaluations
+        
+        Args:
+            board: Current chess board position
+            
+        Returns:
+            List of (move, evaluation) tuples
+        """
+        if not self.is_initialized or not self.stockfish:
+            return []
+        
+        moves_with_eval = []
+        
+        try:
+            for move in board.legal_moves:
+                # Make move temporarily
+                board.push(move)
+                
+                # Evaluate position
+                evaluation = self.evaluate_position(board)
+                
+                # Undo move
+                board.pop()
+                
+                if evaluation is not None:
+                    moves_with_eval.append((move.uci(), -evaluation))  # Negate for opponent's perspective
+            
+            # Sort by evaluation (best first)
+            moves_with_eval.sort(key=lambda x: x[1], reverse=True)
+            
+            return moves_with_eval
+            
+        except Exception as e:
+            self.logger.error(f"Error getting moves with evaluation: {e}")
+            return []
+    
+    def set_difficulty_level(self, level: DifficultyLevel):
+        """
+        Set AI difficulty level
+        
+        Args:
+            level: Difficulty level enum
+        """
+        skill_levels = {
+            DifficultyLevel.BEGINNER: 1,
+            DifficultyLevel.EASY: 3,
+            DifficultyLevel.MEDIUM: 8,
+            DifficultyLevel.HARD: 12,
+            DifficultyLevel.EXPERT: 17,
+            DifficultyLevel.MASTER: 20
+        }
+        
+        depths = {
+            DifficultyLevel.BEGINNER: 3,
+            DifficultyLevel.EASY: 5,
+            DifficultyLevel.MEDIUM: 8,
+            DifficultyLevel.HARD: 12,
+            DifficultyLevel.EXPERT: 15,
+            DifficultyLevel.MASTER: 20
+        }
+        
+        self.config.skill_level = skill_levels[level]
+        self.config.depth = depths[level]
+        
+        # Update engine parameters if initialized
+        if self.is_initialized and self.stockfish:
+            self.stockfish.set_depth(self.config.depth)
+            self.stockfish.set_skill_level(self.config.skill_level)
+    
+    def get_engine_info(self) -> Dict[str, Any]:
+        """
+        Get engine information and statistics
+        
+        Returns:
+            Dictionary with engine info
+        """
+        if not self.is_initialized:
+            return {"status": "not_initialized"}
+        
+        return {
+            "status": "initialized",
+            "config": {
+                "depth": self.config.depth,
+                "skill_level": self.config.skill_level,
+                "time_limit": self.config.time_limit,
+                "threads": self.config.threads,
+                "hash_size": self.config.hash_size
+            },
+            "stockfish_available": self.stockfish is not None,
+            "async_engine_available": self.engine is not None
+        }
+    
+    def is_move_blunder(self, board: chess.Board, move: str, threshold: float = 2.0) -> bool:
+        """
+        Check if a move is a blunder
+        
+        Args:
+            board: Current chess board position
+            move: Move to check in UCI notation
+            threshold: Evaluation drop threshold for blunder detection
+            
+        Returns:
+            True if move is a blunder
+        """
+        if not self.is_initialized:
+            return False
+        
+        try:
+            # Get current position evaluation
+            current_eval = self.evaluate_position(board)
+            if current_eval is None:
+                return False
+            
+            # Make the move
+            move_obj = chess.Move.from_uci(move)
+            if move_obj not in board.legal_moves:
+                return True  # Illegal move is definitely a blunder
+            
+            board.push(move_obj)
+            
+            # Get evaluation after move
+            new_eval = self.evaluate_position(board)
+            
+            # Undo move
+            board.pop()
+            
+            if new_eval is None:
+                return False
+            
+            # Check if evaluation dropped significantly
+            # Note: negate new_eval because it's opponent's turn
+            eval_drop = current_eval - (-new_eval)
+            
+            return eval_drop > threshold
+            
+        except Exception as e:
+            self.logger.error(f"Error checking blunder: {e}")
+            return False
+    
+    def close(self):
+        """Close the engine connection"""
+        if self.engine:
+            asyncio.create_task(self.engine.quit())
+        
+        self.is_initialized = False
+        self.logger.info("Stockfish engine closed")
+    
+    def __enter__(self):
+        """Context manager entry"""
+        self.initialize()
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit"""
+        self.close()

chess_engine/api/__init__.py

@@ -0,0 +1,3 @@
+# chess_engine/api/__init__.py
+
+from chess_engine.api.game_controller import GameController, GameOptions

chess_engine/api/cli.py

@@ -0,0 +1,223 @@
+# chess_engine/api/cli.py
+
+import chess
+import argparse
+import sys
+import os
+from typing import Optional, Dict, Any
+import time
+
+from chess_engine.api.game_controller import GameController, GameOptions
+from chess_engine.ai.stockfish_wrapper import DifficultyLevel
+
+class ChessCLI:
+    """Command-line interface for chess engine"""
+    
+    def __init__(self):
+        self.controller = None
+        self.options = None
+        
+    def setup_game(self, args):
+        """Setup game with command line arguments"""
+        # Parse color
+        player_color = chess.WHITE
+        if args.color and args.color.lower() == 'black':
+            player_color = chess.BLACK
+        
+        # Parse difficulty
+        difficulty_map = {
+            'beginner': DifficultyLevel.BEGINNER,
+            'easy': DifficultyLevel.EASY,
+            'medium': DifficultyLevel.MEDIUM,
+            'hard': DifficultyLevel.HARD,
+            'expert': DifficultyLevel.EXPERT,
+            'master': DifficultyLevel.MASTER
+        }
+        
+        difficulty = difficulty_map.get(args.difficulty.lower(), DifficultyLevel.MEDIUM)
+        
+        # Create options
+        self.options = GameOptions(
+            player_color=player_color,
+            difficulty=difficulty,
+            time_limit=args.time,
+            use_opening_book=not args.no_book,
+            enable_analysis=not args.no_analysis,
+            stockfish_path=args.stockfish_path
+        )
+        
+        # Create controller
+        self.controller = GameController(self.options)
+        
+    def print_board(self, unicode: bool = True):
+        """Print chess board to console"""
+        board = self.controller.board.board
+        
+        # Get board as string
+        if unicode:
+            board_str = str(board)
+        else:
+            board_str = board.unicode()
+            
+        print("\n" + board_str + "\n")
+        
+        # Print whose turn it is
+        turn = "White" if board.turn == chess.WHITE else "Black"
+        print(f"{turn} to move")
+        
+        # Print check status
+        if board.is_check():
+            print("CHECK!")
+        
+    def print_analysis(self, analysis: Dict[str, Any]):
+        """Print position analysis"""
+        if not analysis:
+            return
+            
+        eval_data = analysis.get("evaluation", {})
+        best_moves = analysis.get("best_moves", [])
+        
+        print("\nPosition Analysis:")
+        print(f"Evaluation: {eval_data.get('total', 0):.2f} pawns")
+        print(f"Stockfish: {eval_data.get('stockfish', 0):.2f} pawns")
+        
+        if best_moves:
+            print("\nBest moves:")
+            for i, (move, eval_score) in enumerate(best_moves[:3], 1):
+                print(f"{i}. {move} ({eval_score:.2f})")
+    
+    def run(self):
+        """Run the CLI game loop"""
+        # Start new game
+        result = self.controller.start_new_game()
+        
+        if result["status"] == "error":
+            print(f"Error: {result['message']}")
+            return
+            
+        print("Chess game started!")
+        print("Enter moves in UCI notation (e.g., 'e2e4') or SAN (e.g., 'e4')")
+        print("Commands: 'quit', 'help', 'hint', 'undo', 'board', 'resign'")
+        
+        self.print_board()
+        
+        # Game loop
+        while True:
+            # Get user input
+            try:
+                user_input = input("\nYour move: ").strip()
+            except (KeyboardInterrupt, EOFError):
+                print("\nGame terminated.")
+                break
+                
+            # Process commands
+            if user_input.lower() in ('quit', 'exit', 'q'):
+                print("Game terminated.")
+                break
+                
+            elif user_input.lower() == 'help':
+                print("\nCommands:")
+                print("  <move> - Make a move (e.g., 'e2e4' or 'e4')")
+                print("  board  - Display the board")
+                print("  hint   - Get a move suggestion")
+                print("  undo   - Undo last move")
+                print("  resign - Resign the game")
+                print("  quit   - Exit the game")
+                continue
+                
+            elif user_input.lower() == 'board':
+                self.print_board()
+                continue
+                
+            elif user_input.lower() == 'hint':
+                hint_result = self.controller.get_hint()
+                if hint_result["status"] == "success":
+                    print(f"\nHint: {hint_result['hint']}")
+                    print(f"Explanation: {hint_result['explanation']}")
+                else:
+                    print(f"Error: {hint_result['message']}")
+                continue
+                
+            elif user_input.lower() == 'undo':
+                undo_result = self.controller.undo_move()
+                if undo_result["status"] in ("success", "partial"):
+                    print("Move undone.")
+                    self.print_board()
+                else:
+                    print(f"Error: {undo_result['message']}")
+                continue
+                
+            elif user_input.lower() == 'resign':
+                resign_result = self.controller.resign()
+                print("You resigned. Game over.")
+                break
+                
+            # Process move
+            move_result = self.controller.make_player_move(user_input)
+            
+            if move_result["status"] == "error":
+                print(f"Error: {move_result['message']}")
+                continue
+                
+            # Print board after move
+            self.print_board()
+            
+            # Print AI's move
+            if "ai_move" in move_result and move_result["ai_move"]:
+                print(f"AI plays: {move_result['ai_move']}")
+                
+            # Print analysis if available
+            if "analysis" in move_result and move_result["analysis"]:
+                self.print_analysis(move_result["analysis"])
+                
+            # Check if game is over
+            if move_result["status"] == "game_over":
+                result = move_result["result"]
+                reason = move_result["reason"]
+                
+                print("\nGame over!")
+                
+                if result == "draw":
+                    print(f"Result: Draw ({reason})")
+                else:
+                    winner = move_result["winner"].capitalize()
+                    print(f"Result: {winner} wins by {reason}")
+                    
+                break
+        
+        # Clean up
+        if self.controller:
+            self.controller.close()
+
+def main(args=None):
+    """
+    Main entry point for CLI
+    
+    Args:
+        args: Command-line arguments (optional, parsed from sys.argv if None)
+    """
+    if args is None:
+        # Parse arguments only if not provided
+        parser = argparse.ArgumentParser(description="Chess Engine CLI")
+        parser.add_argument("--color", "-c", choices=["white", "black"], default="white",
+                            help="Player's color (default: white)")
+        parser.add_argument("--difficulty", "-d", 
+                            choices=["beginner", "easy", "medium", "hard", "expert", "master"],
+                            default="medium", help="AI difficulty level (default: medium)")
+        parser.add_argument("--time", "-t", type=float, default=1.0,
+                            help="Time limit for AI moves in seconds (default: 1.0)")
+        parser.add_argument("--stockfish-path", "-s", type=str, default=None,
+                            help="Path to Stockfish executable")
+        parser.add_argument("--no-book", action="store_true",
+                            help="Disable opening book")
+        parser.add_argument("--no-analysis", action="store_true",
+                            help="Disable position analysis")
+        
+        args = parser.parse_args()
+    
+    cli = ChessCLI()
+    cli.setup_game(args)
+    cli.run()
+
+if __name__ == "__main__":
+    main()

chess_engine/api/game_controller.py

@@ -0,0 +1,402 @@
+# chess_engine/api/game_controller.py
+
+import chess
+from typing import Dict, List, Optional, Tuple, Any
+from enum import Enum
+from dataclasses import dataclass
+
+from chess_engine.board import ChessBoard, MoveResult, GameState
+from chess_engine.ai.stockfish_wrapper import StockfishWrapper, DifficultyLevel
+from chess_engine.ai.evaluation import ChessEvaluator
+from chess_engine.promotion import PromotionMoveHandler
+
+@dataclass
+class GameOptions:
+    """Game configuration options"""
+    player_color: chess.Color = chess.WHITE
+    difficulty: DifficultyLevel = DifficultyLevel.MEDIUM
+    time_limit: float = 1.0  # seconds for AI to think
+    use_opening_book: bool = True
+    enable_analysis: bool = True
+    stockfish_path: Optional[str] = None
+
+class GameController:
+    """
+    Main game controller that handles game flow, user moves, and AI responses
+    """
+    
+    def __init__(self, options: Optional[GameOptions] = None):
+        """
+        Initialize game controller
+        
+        Args:
+            options: Game configuration options
+        """
+        self.options = options or GameOptions()
+        self.board = ChessBoard()
+        self.engine = StockfishWrapper(stockfish_path=self.options.stockfish_path)
+        self.evaluator = ChessEvaluator()
+        self.game_active = False
+        self.last_analysis = None
+        
+    def start_new_game(self, options: Optional[GameOptions] = None) -> Dict[str, Any]:
+        """
+        Start a new game
+        
+        Args:
+            options: Game options (optional, uses current options if None)
+            
+        Returns:
+            Game state information
+        """
+        if options:
+            self.options = options
+            
+        # Reset board
+        self.board.reset_board()
+        
+        # Initialize engine
+        if not self.engine.is_initialized:
+            engine_initialized = self.engine.initialize()
+            if not engine_initialized:
+                return {
+                    "status": "error",
+                    "message": "Failed to initialize chess engine",
+                    "board_state": self.board.get_board_state()
+                }
+        
+        # Set difficulty
+        self.engine.set_difficulty_level(self.options.difficulty)
+        
+        self.game_active = True
+        
+        # If AI plays white, make first move
+        if self.options.player_color == chess.BLACK:
+            ai_move = self._get_ai_move()
+            if ai_move:
+                self.board.make_move(ai_move)
+        
+        return {
+            "status": "success",
+            "message": "New game started",
+            "board_state": self.board.get_board_state(),
+            "player_color": "white" if self.options.player_color == chess.WHITE else "black"
+        }
+    
+    def make_player_move(self, move_str: str) -> Dict[str, Any]:
+        """
+        Process a player's move
+        
+        Args:
+            move_str: Move in UCI notation (e.g., 'e2e4', 'e7e8q') or SAN (e.g., 'e4', 'e8=Q')
+            
+        Returns:
+            Response with move result and updated game state
+        """
+        if not self.game_active:
+            return {
+                "status": "error",
+                "message": "No active game",
+                "board_state": self.board.get_board_state()
+            }
+        
+        # Check if it's player's turn
+        if self.board.board.turn != self.options.player_color:
+            return {
+                "status": "error",
+                "message": "Not your turn",
+                "board_state": self.board.get_board_state()
+            }
+        
+        # Make the move
+        result, move_info = self.board.make_move(move_str)
+        
+        # Handle promotion requirement
+        if result == MoveResult.INVALID and move_info and move_info.promotion_required:
+            return {
+                "status": "promotion_required",
+                "message": "Pawn promotion requires piece selection",
+                "promotion_details": {
+                    "from": move_info.uci[:2],
+                    "to": move_info.uci[2:4],
+                    "available_pieces": ["queen", "rook", "bishop", "knight"]
+                },
+                "board_state": self.board.get_board_state()
+            }
+        
+        if result != MoveResult.VALID:
+            return {
+                "status": "error",
+                "message": f"Invalid move: {move_str}",
+                "board_state": self.board.get_board_state()
+            }
+        
+        # Check if game is over after player's move
+        game_state = self._check_game_state()
+        if game_state:
+            return game_state
+        
+        # Make AI move
+        ai_move = self._get_ai_move()
+        if ai_move:
+            self.board.make_move(ai_move)
+            
+        # Check if game is over after AI's move
+        game_state = self._check_game_state()
+        if game_state:
+            return game_state
+        
+        # Analyze position if enabled
+        analysis = None
+        if self.options.enable_analysis:
+            analysis = self._analyze_position()
+            self.last_analysis = analysis
+        
+        return {
+            "status": "success",
+            "player_move": move_str,
+            "ai_move": ai_move,
+            "board_state": self.board.get_board_state(),
+            "analysis": analysis
+        }
+    
+    def _get_ai_move(self) -> Optional[str]:
+        """
+        Get AI's move using Stockfish
+        
+        Returns:
+            Move in UCI notation or None if error
+        """
+        return self.engine.get_best_move(
+            self.board.board, 
+            time_limit=self.options.time_limit
+        )
+    
+    def _check_game_state(self) -> Optional[Dict[str, Any]]:
+        """
+        Check if game is over
+        
+        Returns:
+            Game result dict if game is over, None otherwise
+        """
+        board_state = self.board.get_board_state()
+        game_state = board_state["game_state"]
+        
+        if game_state in [GameState.CHECKMATE, GameState.STALEMATE, GameState.DRAW]:
+            self.game_active = False
+            
+            result = "draw"
+            winner = None
+            
+            if game_state == GameState.CHECKMATE:
+                # Winner is the opposite of who's turn it is
+                winner = "black" if self.board.board.turn == chess.WHITE else "white"
+                result = f"{winner}_win"
+            
+            return {
+                "status": "game_over",
+                "result": result,
+                "winner": winner,
+                "reason": game_state.value,
+                "board_state": board_state
+            }
+        
+        return None
+    
+    def _analyze_position(self) -> Dict[str, Any]:
+        """
+        Analyze current position
+        
+        Returns:
+            Analysis data
+        """
+        # Get evaluation from our evaluator
+        evaluation = self.evaluator.evaluate_position(self.board.board)
+        
+        # Get Stockfish evaluation
+        stockfish_eval = self.engine.evaluate_position(self.board.board)
+        
+        # Get best moves with evaluation
+        best_moves = self.engine.get_legal_moves_with_evaluation(self.board.board)[:3]
+        
+        return {
+            "evaluation": {
+                "total": evaluation.total_score / 100,  # Convert to pawns
+                "material": evaluation.material_score / 100,
+                "positional": evaluation.positional_score / 100,
+                "safety": evaluation.safety_score / 100,
+                "mobility": evaluation.mobility_score / 100,
+                "pawn_structure": evaluation.pawn_structure_score / 100,
+                "endgame": evaluation.endgame_score / 100,
+                "white_advantage": evaluation.white_advantage / 100,
+                "stockfish": stockfish_eval
+            },
+            "best_moves": best_moves
+        }
+    
+    def get_hint(self) -> Dict[str, Any]:
+        """
+        Get a hint for the current position
+        
+        Returns:
+            Hint information
+        """
+        if not self.game_active:
+            return {
+                "status": "error",
+                "message": "No active game"
+            }
+        
+        # Get best move from engine
+        best_move = self._get_ai_move()
+        
+        if not best_move:
+            return {
+                "status": "error",
+                "message": "Could not generate hint"
+            }
+        
+        # Get move explanation
+        explanation = self._get_move_explanation(best_move)
+        
+        return {
+            "status": "success",
+            "hint": best_move,
+            "explanation": explanation,
+            "board_state": self.board.get_board_state()
+        }
+    
+    def _get_move_explanation(self, move_str: str) -> str:
+        """
+        Generate a simple explanation for a move
+        
+        Args:
+            move_str: Move in UCI notation
+            
+        Returns:
+            Human-readable explanation
+        """
+        try:
+            move = chess.Move.from_uci(move_str)
+            board = self.board.board
+            
+            from_square = chess.square_name(move.from_square)
+            to_square = chess.square_name(move.to_square)
+            
+            piece = board.piece_at(move.from_square)
+            if not piece:
+                return "Unknown move"
+                
+            piece_name = chess.piece_name(piece.piece_type).capitalize()
+            
+            # Check if move is a capture
+            capture = ""
+            if board.is_capture(move):
+                captured_piece = board.piece_at(move.to_square)
+                if captured_piece:
+                    captured_name = chess.piece_name(captured_piece.piece_type).capitalize()
+                    capture = f", capturing {captured_name}"
+                else:
+                    # En passant
+                    capture = ", capturing Pawn en passant"
+            
+            # Check if move gives check
+            check = ""
+            if board.gives_check(move):
+                check = ", giving check"
+            
+            # Check if castling
+            if board.is_castling(move):
+                if chess.square_file(move.to_square) > chess.square_file(move.from_square):
+                    return "Kingside castling"
+                else:
+                    return "Queenside castling"
+            
+            # Check if promotion
+            promotion = ""
+            if move.promotion:
+                promoted_piece = chess.piece_name(move.promotion).capitalize()
+                promotion = f", promoting to {promoted_piece}"
+            elif piece.piece_type == chess.PAWN and self.board.is_promotion_move(from_square, to_square):
+                # This is a promotion move but piece not specified
+                promotion = ", promotion required"
+            
+            return f"{piece_name} from {from_square} to {to_square}{capture}{promotion}{check}"
+            
+        except Exception:
+            return "Move analysis not available"
+    
+    def undo_move(self, count: int = 2) -> Dict[str, Any]:
+        """
+        Undo moves (both player and AI)
+        
+        Args:
+            count: Number of half-moves to undo (default 2 for one full move)
+            
+        Returns:
+            Updated game state
+        """
+        if not self.game_active:
+            return {
+                "status": "error",
+                "message": "No active game",
+                "board_state": self.board.get_board_state()
+            }
+        
+        success = True
+        for _ in range(count):
+            if not self.board.undo_move():
+                success = False
+                break
+        
+        return {
+            "status": "success" if success else "partial",
+            "message": f"Undid {count} moves" if success else "Could not undo all requested moves",
+            "board_state": self.board.get_board_state()
+        }
+    
+    def resign(self) -> Dict[str, Any]:
+        """
+        Resign the current game
+        
+        Returns:
+            Game result
+        """
+        if not self.game_active:
+            return {
+                "status": "error",
+                "message": "No active game"
+            }
+        
+        self.game_active = False
+        winner = "black" if self.options.player_color == chess.WHITE else "white"
+        
+        return {
+            "status": "game_over",
+            "result": f"{winner}_win",
+            "winner": winner,
+            "reason": "resignation",
+            "board_state": self.board.get_board_state()
+        }
+    
+    def get_game_state(self) -> Dict[str, Any]:
+        """
+        Get current game state
+        
+        Returns:
+            Game state information
+        """
+        board_state = self.board.get_board_state()
+        
+        return {
+            "status": "active" if self.game_active else "inactive",
+            "player_color": "white" if self.options.player_color == chess.WHITE else "black",
+            "board_state": board_state,
+            "difficulty": self.options.difficulty.name,
+            "last_analysis": self.last_analysis
+        }
+    
+    def close(self):
+        """Clean up resources"""
+        if self.engine:
+            self.engine.close()

chess_engine/api/rest_api.py

@@ -0,0 +1,271 @@
+# chess_engine/api/rest_api.py
+
+from fastapi import FastAPI, HTTPException, Depends
+from pydantic import BaseModel, Field
+from typing import Dict, List, Optional, Any
+import chess
+from enum import Enum
+
+from chess_engine.api.game_controller import GameController, GameOptions
+from chess_engine.ai.stockfish_wrapper import DifficultyLevel
+
+# Define API models
+class ColorEnum(str, Enum):
+    WHITE = "white"
+    BLACK = "black"
+
+class DifficultyEnum(str, Enum):
+    BEGINNER = "beginner"
+    EASY = "easy"
+    MEDIUM = "medium"
+    HARD = "hard"
+    EXPERT = "expert"
+    MASTER = "master"
+
+class NewGameRequest(BaseModel):
+    player_color: ColorEnum = ColorEnum.WHITE
+    difficulty: DifficultyEnum = DifficultyEnum.MEDIUM
+    time_limit: float = Field(default=1.0, ge=0.1, le=10.0)
+    use_opening_book: bool = True
+    enable_analysis: bool = True
+    stockfish_path: Optional[str] = None
+
+class MoveRequest(BaseModel):
+    move: str = Field(..., description="Move in UCI notation (e.g., 'e2e4', 'e7e8q') or SAN (e.g., 'e4', 'e8=Q')")
+
+class PromotionDetails(BaseModel):
+    """Details about a required promotion move"""
+    from_square: str = Field(..., description="Starting square of the promotion move (e.g., 'e7')")
+    to_square: str = Field(..., description="Destination square of the promotion move (e.g., 'e8')")
+    available_pieces: List[str] = Field(..., description="Available pieces for promotion: ['queen', 'rook', 'bishop', 'knight']")
+
+class GameResponse(BaseModel):
+    """Enhanced game response that can include promotion requirements"""
+    status: str = Field(..., description="Response status: 'success', 'error', 'promotion_required', 'game_over'")
+    message: Optional[str] = Field(None, description="Response message")
+    player_move: Optional[str] = Field(None, description="Player's move in UCI notation")
+    ai_move: Optional[str] = Field(None, description="AI's move in UCI notation")
+    board_state: Optional[Dict[str, Any]] = Field(None, description="Current board state")
+    analysis: Optional[Dict[str, Any]] = Field(None, description="Position analysis")
+    promotion_details: Optional[PromotionDetails] = Field(None, description="Promotion requirements when status is 'promotion_required'")
+    result: Optional[str] = Field(None, description="Game result when status is 'game_over'")
+    winner: Optional[str] = Field(None, description="Winner when game is over")
+    reason: Optional[str] = Field(None, description="Reason for game end")
+
+class UndoRequest(BaseModel):
+    count: int = Field(default=2, ge=1, le=10, description="Number of half-moves to undo")
+
+class PromotionRequest(BaseModel):
+    """Request for completing a promotion move"""
+    from_square: str = Field(..., description="Starting square of the promotion move (e.g., 'e7')")
+    to_square: str = Field(..., description="Destination square of the promotion move (e.g., 'e8')")
+    promotion_piece: str = Field(..., description="Piece to promote to: 'queen', 'rook', 'bishop', 'knight', or 'q', 'r', 'b', 'n'")
+
+# Create FastAPI app
+app = FastAPI(
+    title="Chess Engine API",
+    description="REST API for chess engine with Stockfish integration",
+    version="1.0.0"
+)
+
+# Game controller instance
+game_controller = GameController()
+
+# Helper function to get game controller
+def get_game_controller():
+    return game_controller
+
+@app.post("/game/new", response_model=Dict[str, Any], tags=["Game Control"])
+async def new_game(request: NewGameRequest, controller: GameController = Depends(get_game_controller)):
+    """Start a new game with specified options"""
+    # Convert enum values to appropriate types
+    options = GameOptions(
+        player_color=chess.WHITE if request.player_color == ColorEnum.WHITE else chess.BLACK,
+        difficulty=DifficultyLevel[request.difficulty.upper()],
+        time_limit=request.time_limit,
+        use_opening_book=request.use_opening_book,
+        enable_analysis=request.enable_analysis,
+        stockfish_path=request.stockfish_path
+    )
+    
+    result = controller.start_new_game(options)
+    
+    if result["status"] == "error":
+        raise HTTPException(status_code=500, detail=result["message"])
+    
+    return result
+
+@app.post("/game/move", response_model=GameResponse, tags=["Game Play"])
+async def make_move(request: MoveRequest, controller: GameController = Depends(get_game_controller)):
+    """
+    Make a move on the board.
+    
+    This endpoint handles regular moves and promotion moves. When a pawn reaches the back rank
+    without specifying a promotion piece, it returns a 'promotion_required' status with details
+    about the required promotion.
+    
+    **Move Formats:**
+    - Regular moves: 'e2e4', 'Nf3', 'O-O'
+    - Promotion moves: 'e7e8q' (UCI) or 'e8=Q' (SAN)
+    
+    **Promotion Pieces:**
+    - 'q' or 'queen' for Queen
+    - 'r' or 'rook' for Rook  
+    - 'b' or 'bishop' for Bishop
+    - 'n' or 'knight' for Knight
+    
+    **Response Status Values:**
+    - 'success': Move completed successfully
+    - 'promotion_required': Pawn promotion requires piece selection
+    - 'error': Invalid move or game state error
+    - 'game_over': Game ended after this move
+    """
+    result = controller.make_player_move(request.move)
+    
+    # Handle different response statuses
+    if result["status"] == "error":
+        raise HTTPException(status_code=400, detail=result["message"])
+    elif result["status"] == "promotion_required":
+        # Return 200 with promotion_required status - this is not an error
+        return GameResponse(
+            status="promotion_required",
+            message=result["message"],
+            board_state=result["board_state"],
+            promotion_details=PromotionDetails(
+                from_square=result["promotion_details"]["from"],
+                to_square=result["promotion_details"]["to"],
+                available_pieces=result["promotion_details"]["available_pieces"]
+            )
+        )
+    elif result["status"] == "game_over":
+        return GameResponse(
+            status="game_over",
+            message=result.get("message"),
+            board_state=result["board_state"],
+            result=result["result"],
+            winner=result.get("winner"),
+            reason=result["reason"]
+        )
+    else:
+        # Success case
+        return GameResponse(
+            status="success",
+            player_move=result.get("player_move"),
+            ai_move=result.get("ai_move"),
+            board_state=result["board_state"],
+            analysis=result.get("analysis")
+        )
+
+@app.get("/game/state", response_model=Dict[str, Any], tags=["Game Info"])
+async def get_game_state(controller: GameController = Depends(get_game_controller)):
+    """Get current game state"""
+    return controller.get_game_state()
+
+@app.post("/game/hint", response_model=Dict[str, Any], tags=["Game Help"])
+async def get_hint(controller: GameController = Depends(get_game_controller)):
+    """Get a hint for the current position"""
+    result = controller.get_hint()
+    
+    if result["status"] == "error":
+        raise HTTPException(status_code=400, detail=result["message"])
+    
+    return result
+
+@app.post("/game/undo", response_model=Dict[str, Any], tags=["Game Control"])
+async def undo_move(request: UndoRequest, controller: GameController = Depends(get_game_controller)):
+    """Undo moves"""
+    result = controller.undo_move(request.count)
+    
+    if result["status"] == "error":
+        raise HTTPException(status_code=400, detail=result["message"])
+    
+    return result
+
+@app.post("/game/promotion", response_model=GameResponse, tags=["Game Play"])
+async def complete_promotion(request: PromotionRequest, controller: GameController = Depends(get_game_controller)):
+    """
+    Complete a pawn promotion by specifying the promotion piece.
+    
+    This endpoint is used when a previous move request returned 'promotion_required' status.
+    It completes the promotion move with the specified piece.
+    
+    **Promotion Pieces:**
+    - 'queen' or 'q' for Queen (most common choice)
+    - 'rook' or 'r' for Rook
+    - 'bishop' or 'b' for Bishop  
+    - 'knight' or 'n' for Knight
+    
+    **Example Usage:**
+    1. Make move 'e7e8' -> returns promotion_required
+    2. Call this endpoint with promotion_piece='queen' to complete the move
+    """
+    from chess_engine.promotion import PromotionMoveHandler
+    
+    # Create the full promotion move in UCI notation
+    promotion_move = PromotionMoveHandler.create_promotion_move(
+        request.from_square, 
+        request.to_square, 
+        request.promotion_piece
+    )
+    
+    # Make the promotion move
+    result = controller.make_player_move(promotion_move)
+    
+    # Handle different response statuses
+    if result["status"] == "error":
+        raise HTTPException(status_code=400, detail=result["message"])
+    elif result["status"] == "promotion_required":
+        # This shouldn't happen with a properly formed promotion move
+        raise HTTPException(status_code=400, detail="Invalid promotion move format")
+    elif result["status"] == "game_over":
+        return GameResponse(
+            status="game_over",
+            message=result.get("message"),
+            board_state=result["board_state"],
+            result=result["result"],
+            winner=result.get("winner"),
+            reason=result["reason"]
+        )
+    else:
+        # Success case
+        return GameResponse(
+            status="success",
+            player_move=result.get("player_move"),
+            ai_move=result.get("ai_move"),
+            board_state=result["board_state"],
+            analysis=result.get("analysis")
+        )
+
+@app.post("/game/resign", response_model=Dict[str, Any], tags=["Game Control"])
+async def resign_game(controller: GameController = Depends(get_game_controller)):
+    """Resign the current game"""
+    result = controller.resign()
+    
+    if result["status"] == "error":
+        raise HTTPException(status_code=400, detail=result["message"])
+    
+    return result
+
+@app.get("/game/promotion/pieces", response_model=Dict[str, Any], tags=["Game Info"])
+async def get_promotion_pieces():
+    """
+    Get available promotion pieces with their details.
+    
+    Returns information about all pieces that a pawn can be promoted to,
+    including their names, symbols, UCI notation, and relative values.
+    """
+    from chess_engine.promotion import PromotionMoveHandler
+    
+    return {
+        "status": "success",
+        "promotion_pieces": PromotionMoveHandler.get_available_promotions()
+    }
+
+@app.get("/health", response_model=Dict[str, str], tags=["System"])
+async def health_check():
+    """Health check endpoint for container monitoring"""
+    return {
+        "status": "healthy",
+        "service": "chess-engine-api",
+        "version": "1.0.0"
+    }

chess_engine/board.py

@@ -0,0 +1,341 @@
+# chess_engine/board.py
+
+import chess
+import chess.engine
+from typing import Optional, List, Tuple, Dict, Any
+from enum import Enum
+from dataclasses import dataclass
+from .promotion import PromotionMoveHandler
+
+class GameState(Enum):
+    PLAYING = "playing"
+    CHECK = "check"
+    CHECKMATE = "checkmate"
+    STALEMATE = "stalemate"
+    DRAW = "draw"
+
+class MoveResult(Enum):
+    VALID = "valid"
+    INVALID = "invalid"
+    ILLEGAL = "illegal"
+
+@dataclass
+class MoveInfo:
+    move: chess.Move
+    san: str  # Standard Algebraic Notation
+    uci: str  # Universal Chess Interface notation
+    is_capture: bool
+    is_check: bool
+    is_checkmate: bool
+    is_castling: bool
+    promoted_piece: Optional[chess.PieceType] = None
+    is_promotion: bool = False
+    promotion_required: bool = False
+    available_promotions: Optional[List[str]] = None
+
+class ChessBoard:
+    """
+    Enhanced chess board class that wraps python-chess with additional functionality
+    """
+    
+    def __init__(self, fen: Optional[str] = None):
+        """
+        Initialize chess board
+        
+        Args:
+            fen: FEN string to initialize position, defaults to starting position
+        """
+        self.board = chess.Board(fen) if fen else chess.Board()
+        self.move_history: List[MoveInfo] = []
+        self.position_history: List[str] = [self.board.fen()]
+        
+    def get_board_state(self) -> Dict[str, Any]:
+        """Get current board state as dictionary"""
+        return {
+            'fen': self.board.fen(),
+            'turn': 'white' if self.board.turn == chess.WHITE else 'black',
+            'game_state': self._get_game_state(),
+            'castling_rights': {
+                'white_kingside': self.board.has_kingside_castling_rights(chess.WHITE),
+                'white_queenside': self.board.has_queenside_castling_rights(chess.WHITE),
+                'black_kingside': self.board.has_kingside_castling_rights(chess.BLACK),
+                'black_queenside': self.board.has_queenside_castling_rights(chess.BLACK),
+            },
+            'en_passant': self.board.ep_square,
+            'halfmove_clock': self.board.halfmove_clock,
+            'fullmove_number': self.board.fullmove_number,
+            'legal_moves': [move.uci() for move in self.board.legal_moves],
+            'in_check': self.board.is_check(),
+            'move_count': len(self.move_history)
+        }
+    
+    def get_piece_at(self, square: str) -> Optional[Dict[str, Any]]:
+        """
+        Get piece information at given square
+        
+        Args:
+            square: Square in algebraic notation (e.g., 'e4')
+            
+        Returns:
+            Dictionary with piece info or None if empty square
+        """
+        try:
+            square_index = chess.parse_square(square)
+            piece = self.board.piece_at(square_index)
+            
+            if piece is None:
+                return None
+                
+            return {
+                'type': piece.piece_type,
+                'color': 'white' if piece.color == chess.WHITE else 'black',
+                'symbol': piece.symbol(),
+                'unicode': piece.unicode_symbol(),
+                'square': square
+            }
+        except ValueError:
+            return None
+    
+    def get_all_pieces(self) -> Dict[str, Dict[str, Any]]:
+        """Get all pieces on the board"""
+        pieces = {}
+        for square in chess.SQUARES:
+            square_name = chess.square_name(square)
+            piece_info = self.get_piece_at(square_name)
+            if piece_info:
+                pieces[square_name] = piece_info
+        return pieces
+    
+    def make_move(self, move_str: str) -> Tuple[MoveResult, Optional[MoveInfo]]:
+        """
+        Make a move on the board
+        
+        Args:
+            move_str: Move in UCI notation (e.g., 'e2e4', 'e7e8q') or SAN (e.g., 'e4', 'e8=Q')
+            
+        Returns:
+            Tuple of (MoveResult, MoveInfo if successful)
+        """
+        try:
+            # Try to parse as UCI first, then SAN
+            try:
+                move = chess.Move.from_uci(move_str)
+            except ValueError:
+                move = self.board.parse_san(move_str)
+            
+            # Check if this is a promotion move that requires piece specification
+            from_square = chess.square_name(move.from_square)
+            to_square = chess.square_name(move.to_square)
+            
+            # If this is a promotion move but no promotion piece is specified, return promotion required
+            if self.is_promotion_move(from_square, to_square) and move.promotion is None:
+                # Get available promotion moves for this pawn
+                available_promotions = self.get_promotion_moves(from_square)
+                
+                move_info = MoveInfo(
+                    move=move,
+                    san="",  # Will be empty since move is incomplete
+                    uci=move.uci(),
+                    is_capture=self.board.is_capture(move),
+                    is_check=False,  # Cannot determine without promotion piece
+                    is_checkmate=False,
+                    is_castling=False,
+                    promoted_piece=None,
+                    is_promotion=True,
+                    promotion_required=True,
+                    available_promotions=available_promotions
+                )
+                
+                return MoveResult.INVALID, move_info
+            
+            # Check if move is legal
+            if move not in self.board.legal_moves:
+                return MoveResult.ILLEGAL, None
+            
+            # Store move information before making the move
+            is_promotion = move.promotion is not None
+            move_info = MoveInfo(
+                move=move,
+                san=self.board.san(move),
+                uci=move.uci(),
+                is_capture=self.board.is_capture(move),
+                is_check=self.board.gives_check(move),
+                is_checkmate=False,  # Will be updated after move
+                is_castling=self.board.is_castling(move),
+                promoted_piece=move.promotion,
+                is_promotion=is_promotion,
+                promotion_required=False,
+                available_promotions=None
+            )
+            
+            # Make the move
+            self.board.push(move)
+            
+            # Update move info with post-move state
+            move_info.is_checkmate = self.board.is_checkmate()
+            
+            # Store in history
+            self.move_history.append(move_info)
+            self.position_history.append(self.board.fen())
+            
+            return MoveResult.VALID, move_info
+            
+        except ValueError:
+            return MoveResult.INVALID, None
+    
+    def undo_move(self) -> bool:
+        """
+        Undo the last move
+        
+        Returns:
+            True if successful, False if no moves to undo
+        """
+        if not self.move_history:
+            return False
+            
+        self.board.pop()
+        self.move_history.pop()
+        self.position_history.pop()
+        return True
+    
+    def get_legal_moves(self, square: Optional[str] = None) -> List[str]:
+        """
+        Get legal moves, optionally filtered by starting square
+        
+        Args:
+            square: Starting square to filter moves (e.g., 'e2')
+            
+        Returns:
+            List of legal moves in UCI notation
+        """
+        legal_moves = []
+        
+        for move in self.board.legal_moves:
+            if square is None:
+                legal_moves.append(move.uci())
+            else:
+                try:
+                    square_index = chess.parse_square(square)
+                    if move.from_square == square_index:
+                        legal_moves.append(move.uci())
+                except ValueError:
+                    continue
+                    
+        return legal_moves
+    
+    def get_move_history(self) -> List[Dict[str, Any]]:
+        """Get move history as list of dictionaries"""
+        return [
+            {
+                'move_number': i + 1,
+                'san': move.san,
+                'uci': move.uci,
+                'is_capture': move.is_capture,
+                'is_check': move.is_check,
+                'is_checkmate': move.is_checkmate,
+                'is_castling': move.is_castling,
+                'promoted_piece': move.promoted_piece,
+                'is_promotion': move.is_promotion,
+                'promotion_required': move.promotion_required,
+                'available_promotions': move.available_promotions
+            }
+            for i, move in enumerate(self.move_history)
+        ]
+    
+    def reset_board(self):
+        """Reset board to starting position"""
+        self.board = chess.Board()
+        self.move_history.clear()
+        self.position_history = [self.board.fen()]
+    
+    def load_position(self, fen: str) -> bool:
+        """
+        Load position from FEN string
+        
+        Args:
+            fen: FEN string
+            
+        Returns:
+            True if successful, False if invalid FEN
+        """
+        try:
+            self.board = chess.Board(fen)
+            self.move_history.clear()
+            self.position_history = [fen]
+            return True
+        except ValueError:
+            return False
+    
+    def _get_game_state(self) -> GameState:
+        """Determine current game state"""
+        if self.board.is_checkmate():
+            return GameState.CHECKMATE
+        elif self.board.is_stalemate():
+            return GameState.STALEMATE
+        elif self.board.is_insufficient_material() or \
+             self.board.is_seventyfive_moves() or \
+             self.board.is_fivefold_repetition():
+            return GameState.DRAW
+        elif self.board.is_check():
+            return GameState.CHECK
+        else:
+            return GameState.PLAYING
+    
+    def get_board_array(self) -> List[List[Optional[str]]]:
+        """
+        Get board as 2D array for easier frontend rendering
+        
+        Returns:
+            8x8 array where each cell contains piece symbol or None
+        """
+        board_array = []
+        for rank in range(8):
+            row = []
+            for file in range(8):
+                square = chess.square(file, 7-rank)  # Flip rank for display
+                piece = self.board.piece_at(square)
+                row.append(piece.symbol() if piece else None)
+            board_array.append(row)
+        return board_array
+    
+    def get_attacked_squares(self, color: chess.Color) -> List[str]:
+        """Get squares attacked by given color"""
+        attacked = []
+        for square in chess.SQUARES:
+            if self.board.is_attacked_by(color, square):
+                attacked.append(chess.square_name(square))
+        return attacked
+    
+    def is_square_attacked(self, square: str, by_color: str) -> bool:
+        """Check if square is attacked by given color"""
+        try:
+            square_index = chess.parse_square(square)
+            color = chess.WHITE if by_color.lower() == 'white' else chess.BLACK
+            return self.board.is_attacked_by(color, square_index)
+        except ValueError:
+            return False
+    
+    def is_promotion_move(self, from_square: str, to_square: str) -> bool:
+        """
+        Detect if a move from one square to another would result in pawn promotion.
+        
+        Args:
+            from_square: Starting square in algebraic notation (e.g., 'e7')
+            to_square: Destination square in algebraic notation (e.g., 'e8')
+            
+        Returns:
+            True if the move is a pawn promotion, False otherwise
+        """
+        return PromotionMoveHandler.is_promotion_move(self.board, from_square, to_square)
+    
+    def get_promotion_moves(self, square: str) -> List[str]:
+        """
+        Get all possible promotion moves for a pawn at the given square.
+        
+        Args:
+            square: Square in algebraic notation (e.g., 'e7')
+            
+        Returns:
+            List of promotion moves in UCI notation (e.g., ['e7e8q', 'e7e8r', 'e7e8b', 'e7e8n'])
+        """
+        return PromotionMoveHandler.get_promotion_moves(self.board, square)

chess_engine/pieces.py

@@ -0,0 +1,316 @@
+# chess_engine/pieces.py
+
+import chess
+from typing import Dict, List, Optional, Tuple
+from enum import Enum
+
+class PieceType(Enum):
+    PAWN = chess.PAWN
+    KNIGHT = chess.KNIGHT
+    BISHOP = chess.BISHOP
+    ROOK = chess.ROOK
+    QUEEN = chess.QUEEN
+    KING = chess.KING
+
+class PieceColor(Enum):
+    WHITE = chess.WHITE
+    BLACK = chess.BLACK
+
+class ChessPiece:
+    """Represents a chess piece with its properties and behaviors"""
+    
+    # Unicode symbols for pieces
+    UNICODE_PIECES = {
+        chess.WHITE: {
+            chess.PAWN: "♙", chess.KNIGHT: "♘", chess.BISHOP: "♗",
+            chess.ROOK: "♖", chess.QUEEN: "♕", chess.KING: "♔"
+        },
+        chess.BLACK: {
+            chess.PAWN: "♟", chess.KNIGHT: "♞", chess.BISHOP: "♝",
+            chess.ROOK: "♜", chess.QUEEN: "♛", chess.KING: "♚"
+        }
+    }
+    
+    # Piece values for evaluation
+    PIECE_VALUES = {
+        chess.PAWN: 1,
+        chess.KNIGHT: 3,
+        chess.BISHOP: 3,
+        chess.ROOK: 5,
+        chess.QUEEN: 9,
+        chess.KING: 0  # King is invaluable
+    }
+    
+    def __init__(self, piece_type: chess.PieceType, color: chess.Color):
+        self.piece_type = piece_type
+        self.color = color
+        self.piece = chess.Piece(piece_type, color)
+    
+    @property
+    def symbol(self) -> str:
+        """Get the piece symbol (uppercase for white, lowercase for black)"""
+        return self.piece.symbol()
+    
+    @property
+    def unicode_symbol(self) -> str:
+        """Get the Unicode symbol for the piece"""
+        return self.UNICODE_PIECES[self.color][self.piece_type]
+    
+    @property
+    def value(self) -> int:
+        """Get the piece value"""
+        return self.PIECE_VALUES[self.piece_type]
+    
+    @property
+    def name(self) -> str:
+        """Get the piece name"""
+        piece_names = {
+            chess.PAWN: "Pawn",
+            chess.KNIGHT: "Knight",
+            chess.BISHOP: "Bishop",
+            chess.ROOK: "Rook",
+            chess.QUEEN: "Queen",
+            chess.KING: "King"
+        }
+        return piece_names[self.piece_type]
+    
+    @property
+    def color_name(self) -> str:
+        """Get the color name"""
+        return "White" if self.color == chess.WHITE else "Black"
+    
+    def __str__(self) -> str:
+        return f"{self.color_name} {self.name}"
+    
+    def __repr__(self) -> str:
+        return f"ChessPiece({self.piece_type}, {self.color})"
+
+class PieceManager:
+    """Manages piece-related operations and utilities"""
+    
+    @staticmethod
+    def create_piece(piece_type: str, color: str) -> Optional[ChessPiece]:
+        """
+        Create a piece from string representations
+        
+        Args:
+            piece_type: 'pawn', 'knight', 'bishop', 'rook', 'queen', 'king'
+            color: 'white' or 'black'
+            
+        Returns:
+            ChessPiece instance or None if invalid input
+        """
+        piece_type_map = {
+            'pawn': chess.PAWN,
+            'knight': chess.KNIGHT,
+            'bishop': chess.BISHOP,
+            'rook': chess.ROOK,
+            'queen': chess.QUEEN,
+            'king': chess.KING
+        }
+        
+        color_map = {
+            'white': chess.WHITE,
+            'black': chess.BLACK
+        }
+        
+        if piece_type.lower() not in piece_type_map or color.lower() not in color_map:
+            return None
+            
+        return ChessPiece(
+            piece_type_map[piece_type.lower()],
+            color_map[color.lower()]
+        )
+    
+    @staticmethod
+    def get_piece_moves(board: chess.Board, square: str) -> List[str]:
+        """
+        Get all possible moves for a piece at given square
+        
+        Args:
+            board: Chess board instance
+            square: Square in algebraic notation
+            
+        Returns:
+            List of destination squares in algebraic notation
+        """
+        try:
+            square_index = chess.parse_square(square)
+            piece = board.piece_at(square_index)
+            
+            if piece is None:
+                return []
+            
+            moves = []
+            for move in board.legal_moves:
+                if move.from_square == square_index:
+                    moves.append(chess.square_name(move.to_square))
+            
+            return moves
+            
+        except ValueError:
+            return []
+    
+    @staticmethod
+    def get_piece_attacks(board: chess.Board, square: str) -> List[str]:
+        """
+        Get all squares attacked by piece at given square
+        
+        Args:
+            board: Chess board instance
+            square: Square in algebraic notation
+            
+        Returns:
+            List of attacked squares in algebraic notation
+        """
+        try:
+            square_index = chess.parse_square(square)
+            piece = board.piece_at(square_index)
+            
+            if piece is None:
+                return []
+            
+            attacks = []
+            for target_square in chess.SQUARES:
+                if board.is_attacked_by(piece.color, target_square):
+                    # Check if this specific piece is doing the attacking
+                    # This is a simplified check - in a real game you might need more sophisticated logic
+                    attacks.append(chess.square_name(target_square))
+            
+            return attacks
+            
+        except ValueError:
+            return []
+    
+    @staticmethod
+    def get_material_count(board: chess.Board) -> Dict[str, Dict[str, int]]:
+        """
+        Get material count for both sides
+        
+        Args:
+            board: Chess board instance
+            
+        Returns:
+            Dictionary with material counts for white and black
+        """
+        white_pieces = {'pawn': 0, 'knight': 0, 'bishop': 0, 'rook': 0, 'queen': 0, 'king': 0}
+        black_pieces = {'pawn': 0, 'knight': 0, 'bishop': 0, 'rook': 0, 'queen': 0, 'king': 0}
+        
+        piece_names = {
+            chess.PAWN: 'pawn',
+            chess.KNIGHT: 'knight',
+            chess.BISHOP: 'bishop',
+            chess.ROOK: 'rook',
+            chess.QUEEN: 'queen',
+            chess.KING: 'king'
+        }
+        
+        for square in chess.SQUARES:
+            piece = board.piece_at(square)
+            if piece:
+                piece_name = piece_names[piece.piece_type]
+                if piece.color == chess.WHITE:
+                    white_pieces[piece_name] += 1
+                else:
+                    black_pieces[piece_name] += 1
+        
+        return {
+            'white': white_pieces,
+            'black': black_pieces
+        }
+    
+    @staticmethod
+    def get_material_value(board: chess.Board) -> Dict[str, int]:
+        """
+        Get total material value for both sides
+        
+        Args:
+            board: Chess board instance
+            
+        Returns:
+            Dictionary with material values for white and black
+        """
+        white_value = 0
+        black_value = 0
+        
+        for square in chess.SQUARES:
+            piece = board.piece_at(square)
+            if piece:
+                value = ChessPiece.PIECE_VALUES[piece.piece_type]
+                if piece.color == chess.WHITE:
+                    white_value += value
+                else:
+                    black_value += value
+        
+        return {
+            'white': white_value,
+            'black': black_value,
+            'advantage': white_value - black_value
+        }
+    
+    @staticmethod
+    def get_piece_list(board: chess.Board) -> Dict[str, List[Dict[str, str]]]:
+        """
+        Get list of all pieces on the board
+        
+        Args:
+            board: Chess board instance
+            
+        Returns:
+            Dictionary with lists of white and black pieces
+        """
+        white_pieces = []
+        black_pieces = []
+        
+        for square in chess.SQUARES:
+            piece = board.piece_at(square)
+            if piece:
+                piece_info = {
+                    'type': chess.piece_name(piece.piece_type),
+                    'square': chess.square_name(square),
+                    'symbol': piece.symbol(),
+                    'unicode': ChessPiece.UNICODE_PIECES[piece.color][piece.piece_type]
+                }
+                
+                if piece.color == chess.WHITE:
+                    white_pieces.append(piece_info)
+                else:
+                    black_pieces.append(piece_info)
+        
+        return {
+            'white': white_pieces,
+            'black': black_pieces
+        }
+    
+    @staticmethod
+    def is_promotion_move(board: chess.Board, move_str: str) -> bool:
+        """
+        Check if a move is a pawn promotion
+        
+        Args:
+            board: Chess board instance
+            move_str: Move in UCI notation
+            
+        Returns:
+            True if the move is a promotion
+        """
+        try:
+            move = chess.Move.from_uci(move_str)
+            return move.promotion is not None
+        except ValueError:
+            return False
+    
+    @staticmethod
+    def get_promotion_pieces() -> List[Dict[str, str]]:
+        """
+        Get available promotion pieces
+        
+        Returns:
+            List of promotion piece options
+        """
+        return [
+            {'type': 'queen', 'symbol': 'Q', 'name': 'Queen'},
+            {'type': 'rook', 'symbol': 'R', 'name': 'Rook'},
+            {'type': 'bishop', 'symbol': 'B', 'name': 'Bishop'},
+            {'type': 'knight', 'symbol': 'N', 'name': 'Knight'}
+        ]

chess_engine/promotion.py

@@ -0,0 +1,306 @@
+# chess_engine/promotion.py
+
+import chess
+from typing import List, Optional, Tuple, Dict, Any
+from enum import Enum
+
+class PromotionPiece(Enum):
+    """Available pieces for pawn promotion"""
+    QUEEN = chess.QUEEN
+    ROOK = chess.ROOK
+    BISHOP = chess.BISHOP
+    KNIGHT = chess.KNIGHT
+
+class PromotionMoveHandler:
+    """
+    Handles pawn promotion move detection, validation, and generation.
+    
+    This class provides functionality to:
+    - Detect when a pawn move would result in promotion
+    - Validate promotion moves
+    - Generate all possible promotion moves for a given pawn
+    - Create UCI notation moves with promotion suffixes
+    """
+    
+    # Mapping from piece names to chess.PieceType
+    PIECE_NAME_MAP = {
+        'queen': chess.QUEEN,
+        'rook': chess.ROOK,
+        'bishop': chess.BISHOP,
+        'knight': chess.KNIGHT,
+        'q': chess.QUEEN,
+        'r': chess.ROOK,
+        'b': chess.BISHOP,
+        'n': chess.KNIGHT
+    }
+    
+    # Mapping from chess.PieceType to UCI notation
+    UCI_PIECE_MAP = {
+        chess.QUEEN: 'q',
+        chess.ROOK: 'r',
+        chess.BISHOP: 'b',
+        chess.KNIGHT: 'n'
+    }
+    
+    @staticmethod
+    def is_promotion_move(board: chess.Board, from_square: str, to_square: str) -> bool:
+        """
+        Detect if a move from one square to another would result in pawn promotion.
+        
+        Args:
+            board: Current chess board state
+            from_square: Starting square in algebraic notation (e.g., 'e7')
+            to_square: Destination square in algebraic notation (e.g., 'e8')
+            
+        Returns:
+            True if the move is a pawn promotion, False otherwise
+        """
+        try:
+            from_idx = chess.parse_square(from_square)
+            to_idx = chess.parse_square(to_square)
+            
+            # Get the piece at the from square
+            piece = board.piece_at(from_idx)
+            
+            # Must be a pawn
+            if piece is None or piece.piece_type != chess.PAWN:
+                return False
+            
+            # Check if pawn is moving to the back rank
+            to_rank = chess.square_rank(to_idx)
+            
+            # White pawns promote on 8th rank (rank 7 in 0-indexed), black on 1st rank (rank 0)
+            if piece.color == chess.WHITE and to_rank == 7:
+                return True
+            elif piece.color == chess.BLACK and to_rank == 0:
+                return True
+                
+            return False
+            
+        except ValueError:
+            return False
+    
+    @staticmethod
+    def can_pawn_promote(board: chess.Board, square: str) -> bool:
+        """
+        Check if a pawn at the given square can potentially promote.
+        
+        Args:
+            board: Current chess board state
+            square: Square in algebraic notation (e.g., 'e7')
+            
+        Returns:
+            True if the pawn can promote in the next move, False otherwise
+        """
+        try:
+            square_idx = chess.parse_square(square)
+            piece = board.piece_at(square_idx)
+            
+            # Must be a pawn
+            if piece is None or piece.piece_type != chess.PAWN:
+                return False
+            
+            rank = chess.square_rank(square_idx)
+            
+            # White pawns on 7th rank (rank 6 in 0-indexed) can promote
+            # Black pawns on 2nd rank (rank 1 in 0-indexed) can promote
+            if piece.color == chess.WHITE and rank == 6:
+                return True
+            elif piece.color == chess.BLACK and rank == 1:
+                return True
+                
+            return False
+            
+        except ValueError:
+            return False
+    
+    @staticmethod
+    def get_promotion_moves(board: chess.Board, square: str) -> List[str]:
+        """
+        Get all possible promotion moves for a pawn at the given square.
+        
+        Args:
+            board: Current chess board state
+            square: Square in algebraic notation (e.g., 'e7')
+            
+        Returns:
+            List of promotion moves in UCI notation (e.g., ['e7e8q', 'e7e8r', 'e7e8b', 'e7e8n'])
+        """
+        try:
+            from_idx = chess.parse_square(square)
+            piece = board.piece_at(from_idx)
+            
+            # Must be a pawn that can promote
+            if not PromotionMoveHandler.can_pawn_promote(board, square):
+                return []
+            
+            promotion_moves = []
+            
+            # Check all legal moves from this square that are promotions
+            for move in board.legal_moves:
+                if move.from_square == from_idx and move.promotion is not None:
+                    promotion_moves.append(move.uci())
+            
+            return promotion_moves
+            
+        except ValueError:
+            return []
+    
+    @staticmethod
+    def validate_promotion_move(board: chess.Board, move_str: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a promotion move in UCI notation.
+        
+        Args:
+            board: Current chess board state
+            move_str: Move in UCI notation (e.g., 'e7e8q')
+            
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        try:
+            # Parse the move
+            if len(move_str) < 5:
+                return False, "Promotion move must include promotion piece (e.g., 'e7e8q')"
+            
+            from_square = move_str[:2]
+            to_square = move_str[2:4]
+            promotion_piece = move_str[4:].lower()
+            
+            # Validate squares
+            try:
+                from_idx = chess.parse_square(from_square)
+                to_idx = chess.parse_square(to_square)
+            except ValueError:
+                return False, "Invalid square notation"
+            
+            # Validate promotion piece
+            if promotion_piece not in PromotionMoveHandler.UCI_PIECE_MAP.values():
+                return False, f"Invalid promotion piece '{promotion_piece}'. Must be one of: q, r, b, n"
+            
+            # Check if this is actually a promotion move
+            if not PromotionMoveHandler.is_promotion_move(board, from_square, to_square):
+                return False, "Move is not a valid promotion move"
+            
+            # Check if the move is legal
+            try:
+                move = chess.Move.from_uci(move_str)
+                if move not in board.legal_moves:
+                    return False, "Move is not legal in current position"
+            except ValueError:
+                return False, "Invalid UCI move format"
+            
+            return True, None
+            
+        except Exception as e:
+            return False, f"Error validating promotion move: {str(e)}"
+    
+    @staticmethod
+    def create_promotion_move(from_square: str, to_square: str, promotion_piece: str) -> str:
+        """
+        Create a UCI promotion move string.
+        
+        Args:
+            from_square: Starting square (e.g., 'e7')
+            to_square: Destination square (e.g., 'e8')
+            promotion_piece: Piece to promote to ('queen', 'rook', 'bishop', 'knight', or 'q', 'r', 'b', 'n')
+            
+        Returns:
+            UCI move string (e.g., 'e7e8q')
+        """
+        # Normalize promotion piece to UCI format
+        piece_lower = promotion_piece.lower()
+        if piece_lower in PromotionMoveHandler.PIECE_NAME_MAP:
+            piece_type = PromotionMoveHandler.PIECE_NAME_MAP[piece_lower]
+            uci_piece = PromotionMoveHandler.UCI_PIECE_MAP[piece_type]
+        else:
+            # Assume it's already in UCI format
+            uci_piece = piece_lower
+        
+        return f"{from_square}{to_square}{uci_piece}"
+    
+    @staticmethod
+    def get_available_promotions() -> List[Dict[str, Any]]:
+        """
+        Get list of available promotion pieces with their details.
+        
+        Returns:
+            List of dictionaries containing promotion piece information
+        """
+        return [
+            {
+                'type': 'queen',
+                'symbol': 'Q',
+                'uci': 'q',
+                'name': 'Queen',
+                'value': 9
+            },
+            {
+                'type': 'rook',
+                'symbol': 'R',
+                'uci': 'r',
+                'name': 'Rook',
+                'value': 5
+            },
+            {
+                'type': 'bishop',
+                'symbol': 'B',
+                'uci': 'b',
+                'name': 'Bishop',
+                'value': 3
+            },
+            {
+                'type': 'knight',
+                'symbol': 'N',
+                'uci': 'n',
+                'name': 'Knight',
+                'value': 3
+            }
+        ]
+    
+    @staticmethod
+    def parse_promotion_move(move_str: str) -> Optional[Dict[str, str]]:
+        """
+        Parse a promotion move string and extract components.
+        
+        Args:
+            move_str: Move in UCI notation (e.g., 'e7e8q')
+            
+        Returns:
+            Dictionary with move components or None if invalid
+        """
+        try:
+            if len(move_str) < 5:
+                return None
+            
+            from_square = move_str[:2]
+            to_square = move_str[2:4]
+            promotion_piece = move_str[4:].lower()
+            
+            # Validate components
+            chess.parse_square(from_square)  # Will raise ValueError if invalid
+            chess.parse_square(to_square)   # Will raise ValueError if invalid
+            
+            if promotion_piece not in PromotionMoveHandler.UCI_PIECE_MAP.values():
+                return None
+            
+            # Convert UCI piece to full name
+            piece_name_map = {v: k for k, v in PromotionMoveHandler.UCI_PIECE_MAP.items()}
+            piece_type = piece_name_map[promotion_piece]
+            piece_names = {
+                chess.QUEEN: 'queen',
+                chess.ROOK: 'rook',
+                chess.BISHOP: 'bishop',
+                chess.KNIGHT: 'knight'
+            }
+            
+            return {
+                'from_square': from_square,
+                'to_square': to_square,
+                'promotion_piece_uci': promotion_piece,
+                'promotion_piece_name': piece_names[piece_type],
+                'full_move': move_str
+            }
+            
+        except ValueError:
+            return None

docker-entrypoint.sh

@@ -0,0 +1,19 @@
+#!/bin/sh
+
+# Add /usr/games to PATH so stockfish can be found
+export PATH=$PATH:/usr/games
+
+# Start the backend server in the background
+python -m uvicorn app:app --host 0.0.0.0 --port 8000 &
+BACKEND_PID=$!
+
+# Start the frontend server in the foreground
+cd frontend/web
+npm run dev -- --host 0.0.0.0 --port 5173
+FRONTEND_PID=$!
+
+# Wait for either process to exit
+wait -n $BACKEND_PID $FRONTEND_PID
+
+# Exit with the status of the process that exited
+exit $?

main.py

@@ -0,0 +1,62 @@
+import argparse
+import sys
+from chess_engine.api.cli import main as cli_main
+
+# Try to import uvicorn, but don't fail if it's not available
+try:
+    import uvicorn
+    UVICORN_AVAILABLE = True
+except ImportError:
+    UVICORN_AVAILABLE = False
+
+def main():
+    """Main entry point for the application"""
+    parser = argparse.ArgumentParser(description="Chess Engine with Stockfish")
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+    
+    # CLI command
+    cli_parser = subparsers.add_parser("cli", help="Run command-line interface")
+    cli_parser.add_argument("--color", "-c", choices=["white", "black"], default="white",
+                        help="Player's color (default: white)")
+    cli_parser.add_argument("--difficulty", "-d", 
+                        choices=["beginner", "easy", "medium", "hard", "expert", "master"],
+                        default="medium", help="AI difficulty level (default: medium)")
+    cli_parser.add_argument("--time", "-t", type=float, default=1.0,
+                        help="Time limit for AI moves in seconds (default: 1.0)")
+    cli_parser.add_argument("--stockfish-path", "-s", type=str, default=None,
+                        help="Path to Stockfish executable")
+    cli_parser.add_argument("--no-book", action="store_true",
+                        help="Disable opening book")
+    cli_parser.add_argument("--no-analysis", action="store_true",
+                        help="Disable position analysis")
+    
+    # API command
+    api_parser = subparsers.add_parser("api", help="Run REST API server")
+    api_parser.add_argument("--host", default="127.0.0.1", help="Host to bind (default: 127.0.0.1)")
+    api_parser.add_argument("--port", "-p", type=int, default=8000, help="Port to bind (default: 8000)")
+    api_parser.add_argument("--reload", action="store_true", help="Enable auto-reload")
+    
+    args = parser.parse_args()
+    
+    if args.command == "cli":
+        cli_main(args)
+    elif args.command == "api":
+        if not UVICORN_AVAILABLE:
+            print("Error: uvicorn package is not installed. Please install it with:")
+            print("pip install uvicorn")
+            sys.exit(1)
+        
+        try:
+            from chess_engine.api.rest_api import app
+            uvicorn.run(app, host=args.host, port=args.port, reload=args.reload)
+        except ImportError as e:
+            print(f"Error: {e}")
+            print("Make sure all required packages are installed:")
+            print("pip install fastapi uvicorn")
+            sys.exit(1)
+    else:
+        # Default to CLI if no command specified
+        cli_main()
+
+if __name__ == "__main__":
+    main()

requirements.api.txt

@@ -0,0 +1,14 @@
+chess==1.10.0
+stockfish==3.28.0
+fastapi==0.104.1
+uvicorn==0.24.0
+websockets==11.0.2
+pydantic==2.5.0
+python-multipart==0.0.6
+sqlalchemy==2.0.23
+alembic==1.12.1
+asyncpg==0.29.0
+aiosqlite==0.19.0
+python-dotenv==1.0.0
+click==8.1.7
+colorama==0.4.6

web/.npmrc

@@ -0,0 +1,2 @@
+registry=https://registry.npmjs.org/
+legacy-peer-deps=true

web/IMPLEMENTATION_DETAILS.md

@@ -0,0 +1,82 @@
+# Chess UI Implementation Details
+
+## Overview
+
+This implementation provides a modern, interactive web UI for the chess engine using React with TypeScript and Tailwind CSS. The UI is designed to be fluid, responsive, and user-friendly, addressing the limitations of the previous Streamlit interface.
+
+## Key Features
+
+1. **Interactive Chess Board**:
+   - Pieces can be moved by clicking on the source and destination squares
+   - Valid moves are highlighted with green dots
+   - Hint moves are highlighted with a light color
+   - Last move is animated for better visibility
+
+2. **Visual Feedback**:
+   - Selected pieces are highlighted
+   - Legal moves are shown with green dots
+   - Hints highlight both source and destination squares
+   - Move animations provide visual feedback
+
+3. **Game Controls**:
+   - New Game with configurable options (difficulty, color, time limit)
+   - Undo Move functionality
+   - Resign option
+   - Board theme selection (brown or grey)
+
+4. **Game Information**:
+   - Current game status display
+   - Move history tracking
+   - Position analysis with evaluation bar
+   - Material and positional advantage indicators
+
+## Technical Implementation
+
+### Components Structure
+
+1. **App.tsx**: Main application component that organizes the layout
+2. **ChessBoard.tsx**: Handles the chess board rendering and interaction logic
+3. **GameControls.tsx**: Provides game control buttons and options
+4. **GameInfo.tsx**: Displays game status, move history, and analysis
+
+### API Integration
+
+The UI communicates with the backend REST API using Axios. The main endpoints used are:
+
+- `/game/new`: Start a new game with specified options
+- `/game/move`: Make a move on the board
+- `/game/state`: Get current game state
+- `/game/hint`: Get a hint for the current position
+- `/game/undo`: Undo moves
+- `/game/resign`: Resign the current game
+
+### Chess Logic
+
+- FEN parsing to render the board state
+- Legal move validation through the API
+- Piece movement handling
+- Game state tracking
+
+### Styling
+
+- Tailwind CSS for responsive design
+- Custom CSS for chess-specific styling
+- Animations for piece movement
+- Theme support for different board styles
+
+## Asset Usage
+
+The implementation uses the provided chess assets:
+
+- Board squares from both brown and grey themes
+- Chess piece images for both black and white pieces
+
+## Future Enhancements
+
+1. **Drag and Drop**: Implement drag-and-drop functionality for piece movement
+2. **Sound Effects**: Add sound effects for moves, captures, and game events
+3. **Move Notation**: Display algebraic notation for moves in the history panel
+4. **Time Control**: Add chess clock functionality
+5. **Opening Explorer**: Integrate an opening book explorer
+6. **Game Analysis**: Enhanced post-game analysis features
+7. **Local Storage**: Save game state to browser storage for resuming games

web/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,88 @@
+# Chess UI Implementation Summary
+
+## Overview
+
+This modern web UI for the chess engine is built using React with TypeScript and Tailwind CSS. It provides a fluid, interactive experience for users, addressing the limitations of the previous Streamlit interface.
+
+## Key Features
+
+### Interactive Chess Board
+- Pieces can be moved by clicking on source and destination squares
+- Valid moves are highlighted with green dots
+- Hint system with highlighted source and destination squares
+- Visual feedback for moves and selections
+- Support for both mouse and touch interactions
+
+### Game Controls
+- New game with configurable options (difficulty, color, time limit)
+- Undo move functionality
+- Resign option
+- Board theme selection (brown and grey)
+- Sound toggle
+
+### Game Information
+- Game status display
+- Move history in algebraic notation
+- Position analysis with evaluation bar
+- Captured pieces display with material advantage
+- Chess timer for both players
+
+### Visual and Audio Feedback
+- Animations for piece movement
+- Highlighting of last move
+- Sound effects for different move types (regular move, capture, check, etc.)
+- High-resolution images for Retina displays
+
+## Technical Implementation
+
+### Component Structure
+- **App.tsx**: Main application component that organizes the layout
+- **ChessBoard.tsx**: Handles the chess board rendering and interaction logic
+- **GameControls.tsx**: Provides game control buttons and options
+- **GameInfo.tsx**: Displays game status, move history, and analysis
+- **CapturedPieces.tsx**: Shows captured pieces and material advantage
+- **ChessTimer.tsx**: Displays and manages the chess clock
+
+### State Management
+- React hooks for local component state
+- Polling mechanism to keep UI in sync with backend state
+- FEN parsing to render the board state
+
+### API Integration
+- Communication with the backend REST API using Axios
+- Endpoints for game state, moves, hints, and game control
+
+### Styling
+- Tailwind CSS for responsive design
+- Custom CSS for chess-specific styling
+- Animations for piece movement and square highlighting
+
+### Asset Management
+- Support for both 1x and 2x resolution images
+- Sound effects for different move types
+- Multiple board themes
+
+## User Experience Improvements
+
+1. **Intuitive Interaction**: Users can simply click on a piece and then click on a valid destination square to make a move, with visual feedback at each step.
+
+2. **Visual Cues**: Valid moves are clearly marked with green dots, and the hint feature highlights both source and destination squares.
+
+3. **Responsive Design**: The UI adapts to different screen sizes, making it usable on both desktop and mobile devices.
+
+4. **Game Information**: Users can see the game status, move history, captured pieces, and position analysis all in one view.
+
+5. **Customization**: Users can choose between different board themes and toggle sound effects.
+
+## Future Enhancements
+
+1. **Drag and Drop**: Implement drag-and-drop functionality for piece movement
+2. **Opening Explorer**: Add an opening book explorer
+3. **Game Analysis**: Enhance post-game analysis features
+4. **Local Storage**: Save game state to browser storage for resuming games
+5. **Multiplayer**: Add support for playing against other users
+6. **Accessibility**: Improve keyboard navigation and screen reader support
+
+## Conclusion
+
+This implementation provides a modern, interactive web UI for the chess engine that is both visually appealing and user-friendly. It addresses all the requirements specified in the initial request and adds several additional features to enhance the user experience.

web/OVERVIEW.md

@@ -0,0 +1,91 @@
+# Chess UI Implementation Overview
+
+## Architecture
+
+The Chess UI is built using React with TypeScript and Tailwind CSS, providing a modern, fluid, and interactive user experience. The application communicates with the backend chess engine via a REST API.
+
+## Key Components
+
+### 1. ChessBoard
+- Interactive chess board with piece movement
+- Visual indicators for legal moves (green dots)
+- Hint system with highlighted squares
+- Last move highlighting
+- Support for high-resolution (2x) assets
+- Sound effects for moves, captures, and other game events
+
+### 2. GameControls
+- New game button with configurable options
+- Undo move functionality
+- Resign option
+- Board theme selection (brown or grey)
+
+### 3. GameInfo
+- Game status display
+- Move history in a tabular format
+- Position analysis with evaluation bar
+- Material advantage indicator
+- Captured pieces display
+
+### 4. Additional Components
+- **ChessTimer**: Chess clock for time control
+- **CapturedPieces**: Visual display of captured pieces
+- **PromotionDialog**: Dialog for pawn promotion
+
+## Features
+
+### Interactive Gameplay
+- Click-to-move interface
+- Valid moves are highlighted with green dots
+- Pieces animate when moved
+- Last move is highlighted
+
+### Visual Feedback
+- Highlighted squares for selected pieces
+- Visual indicators for check
+- Animation for piece movement
+- Hint highlighting
+
+### Game Analysis
+- Position evaluation display
+- Material advantage calculation
+- Move history tracking
+
+### User Experience
+- Responsive design for various screen sizes
+- Multiple board themes
+- Sound effects for game events
+- Time control with chess clock
+
+## Technical Implementation
+
+### State Management
+- React hooks for component state
+- Polling mechanism for game state updates
+- FEN parsing for board representation
+
+### API Integration
+- Axios for API communication
+- Endpoints for game control, moves, and analysis
+- Error handling for failed requests
+
+### Styling
+- Tailwind CSS for responsive design
+- Custom CSS for chess-specific styling
+- Animations for enhanced user experience
+
+### Asset Handling
+- Support for both 1x and 2x resolution assets
+- Dynamic loading based on device resolution
+- Preloading of assets for smoother experience
+
+## Future Enhancements
+
+1. **Drag and Drop**: Implement drag-and-drop functionality for piece movement
+2. **Opening Explorer**: Add an opening book explorer
+3. **Game Analysis**: Enhanced post-game analysis features
+4. **Offline Support**: Add local storage for game state persistence
+5. **Multiplayer**: Add support for playing against other users
+6. **Accessibility**: Enhance keyboard navigation and screen reader support
+7. **Themes**: Add more board and piece themes
+8. **Annotations**: Allow users to annotate moves and positions

web/README.md

@@ -0,0 +1,125 @@
+# Chess Engine Web UI
+
+A modern, interactive web interface for the chess engine using React and Tailwind CSS.
+
+## Features
+
+- Interactive chess board with piece movement
+- Visual indicators for legal moves (green dots)
+- Hint system with highlighted squares
+- Game controls (new game, undo, resign)
+- Position analysis display
+- Move history tracking
+- Responsive design for various screen sizes
+- Multiple board themes (brown and grey)
+
+## Setup
+
+### WSL Setup (Recommended)
+
+If you're using Windows Subsystem for Linux (WSL):
+
+1. Run the setup script to install all dependencies:
+```bash
+chmod +x setup.sh
+./setup.sh
+```
+
+2. Copy the chess assets to the public folder:
+```bash
+chmod +x copy-assets.sh
+./copy-assets.sh
+```
+
+3. Start the development server:
+```bash
+npm run dev
+```
+
+For detailed WSL-specific instructions, see [WSL_SETUP.md](./WSL_SETUP.md).
+
+### Windows Setup
+
+1. Run the setup script to install all dependencies:
+```
+setup.bat
+```
+
+2. Copy the chess assets to the public folder (see Asset Setup section below)
+
+3. Start the development server:
+```
+npm run dev
+```
+
+### Manual Setup
+
+1. Install dependencies:
+```
+npm install --save react react-dom axios
+npm install --save-dev typescript @types/react @types/react-dom @vitejs/plugin-react vite tailwindcss postcss autoprefixer
+```
+
+2. Start the development server:
+```
+npm run dev
+```
+
+3. Build for production:
+```
+npm run build
+```
+
+## Troubleshooting TypeScript Errors
+
+If you encounter TypeScript errors related to React, try these steps:
+
+1. Make sure all dependencies are installed:
+```
+npm install
+```
+
+2. If you see "Cannot find module 'react'" errors, try:
+```bash
+# WSL/Linux
+./fix-dependencies.sh
+
+# Windows
+fix-dependencies.bat
+```
+
+3. Restart your IDE or TypeScript server
+
+4. For detailed instructions, see [TYPESCRIPT_FIXES.md](./TYPESCRIPT_FIXES.md)
+
+## Asset Setup
+
+Before running the application, you need to copy the chess assets to the public folder:
+
+1. Copy all files from `frontend/assets/pieces` to `frontend/web/public/assets/pieces`
+2. Copy all files from `frontend/assets/boards/brown` to `frontend/web/public/assets/boards/brown`
+3. Copy all files from `frontend/assets/boards/grey` to `frontend/web/public/assets/boards/grey`
+
+Or use the provided script:
+```bash
+# WSL/Linux
+./copy-assets.sh
+```
+
+### High-Resolution Assets
+
+For high-resolution displays:
+1. Copy your 2x assets to the same folders, keeping the same naming convention but with "2x" instead of "1x"
+2. Example: `b_bishop_1x.png` and `b_bishop_2x.png` should both be in the pieces folder
+
+## Backend Integration
+
+The web UI communicates with the chess engine's REST API. Make sure the backend API is running on port 8000 or update the proxy configuration in `vite.config.ts` to match your backend URL.
+
+## Technologies Used
+
+- React 18
+- TypeScript
+- Tailwind CSS
+- Vite
+- Axios for API communication

web/SETUP_GUIDE.md

@@ -0,0 +1,123 @@
+# Chess UI Setup Guide
+
+This guide will help you set up and run the Chess UI web application.
+
+## Prerequisites
+
+- Node.js (v14 or later)
+- npm (v6 or later)
+- Python with the chess engine backend running
+
+## Setup Steps
+
+### 1. Install Dependencies
+
+Navigate to the web UI directory and install the required dependencies:
+
+```bash
+cd frontend/web
+npm install
+```
+
+### 2. Copy Chess Assets
+
+The UI requires chess piece and board images. Copy them from the assets directory:
+
+```bash
+# Create the necessary directories if they don't exist
+mkdir -p public/assets/pieces
+mkdir -p public/assets/boards/brown
+mkdir -p public/assets/boards/grey
+mkdir -p public/assets/sounds
+
+# Copy the assets
+cp ../../frontend/assets/pieces/*.png public/assets/pieces/
+cp ../../frontend/assets/boards/brown/*.png public/assets/boards/brown/
+cp ../../frontend/assets/boards/grey/*.png public/assets/boards/grey/
+```
+
+### 3. Add Sound Files (Optional)
+
+For a better experience, add sound effects to the `public/assets/sounds` directory:
+- move.mp3 - Sound for regular piece movement
+- capture.mp3 - Sound for capturing a piece
+- check.mp3 - Sound for when a king is in check
+- castle.mp3 - Sound for castling
+- promote.mp3 - Sound for pawn promotion
+- game-start.mp3 - Sound for starting a new game
+- game-end.mp3 - Sound for game ending
+
+### 4. Configure Backend URL
+
+The UI is configured to connect to the backend at `http://localhost:8000`. If your backend is running on a different URL, update the `vite.config.ts` file:
+
+```typescript
+server: {
+  proxy: {
+    '/api': {
+      target: 'http://your-backend-url:port',
+      changeOrigin: true,
+      rewrite: (path) => path.replace(/^\/api/, '')
+    }
+  }
+}
+```
+
+### 5. Start the Development Server
+
+Run the development server:
+
+```bash
+npm run dev
+```
+
+The UI will be available at `http://localhost:5173` (or another port if 5173 is in use).
+
+### 6. Build for Production
+
+To create a production build:
+
+```bash
+npm run build
+```
+
+The build output will be in the `dist` directory, which you can serve using any static file server.
+
+## Troubleshooting
+
+### TypeScript Errors
+
+If you encounter TypeScript errors related to React:
+
+1. Run the fix-dependencies script:
+```bash
+./fix-dependencies.bat
+```
+
+2. Or manually reinstall React dependencies:
+```bash
+npm uninstall react react-dom @types/react @types/react-dom
+npm install --save react react-dom
+npm install --save-dev @types/react @types/react-dom
+```
+
+### Backend Connection Issues
+
+If the UI can't connect to the backend:
+
+1. Make sure the backend server is running
+2. Check that the proxy configuration in `vite.config.ts` points to the correct URL
+3. Look for CORS errors in the browser console and update the backend to allow requests from the UI's origin
+
+## Features
+
+- Interactive chess board with piece movement
+- Visual indicators for legal moves (green dots)
+- Hint system with highlighted squares
+- Game controls (new game, undo, resign)
+- Position analysis display
+- Move history tracking
+- Captured pieces display
+- Chess timer
+- Sound effects for moves and captures
+- Multiple board themes (brown and grey)

web/SETUP_INSTRUCTIONS.md

@@ -0,0 +1,108 @@
+# Chess UI Setup Instructions
+
+This document provides detailed instructions for setting up and running the Chess UI.
+
+## Prerequisites
+
+- Node.js (v14 or later)
+- npm (v6 or later)
+- Python backend with FastAPI (for the chess engine)
+
+## Setup Steps
+
+### 1. Install Dependencies
+
+Navigate to the web UI directory and install the required dependencies:
+
+```bash
+cd frontend/web
+npm install
+```
+
+### 2. Copy Assets
+
+Copy the chess assets to the public directory:
+
+```bash
+# Create directories if they don't exist
+mkdir -p public/assets/pieces
+mkdir -p public/assets/boards/brown
+mkdir -p public/assets/boards/grey
+mkdir -p public/assets/sounds
+
+# Copy assets
+cp ../../assets/pieces/*.png public/assets/pieces/
+cp ../../assets/boards/brown/*.png public/assets/boards/brown/
+cp ../../assets/boards/grey/*.png public/assets/boards/grey/
+```
+
+### 3. Add Sound Effects (Optional)
+
+For a better user experience, add sound effects to the `public/assets/sounds` directory:
+
+- `move.mp3` - Sound when a piece moves
+- `capture.mp3` - Sound when a piece is captured
+- `check.mp3` - Sound when a king is in check
+- `castle.mp3` - Sound when castling
+- `promote.mp3` - Sound when a pawn is promoted
+- `game-end.mp3` - Sound when the game ends
+- `illegal.mp3` - Sound when an illegal move is attempted
+
+### 4. Start the Backend
+
+Make sure your chess engine backend is running:
+
+```bash
+cd ../..  # Return to project root
+python -m uvicorn chess_engine.api.rest_api:app --reload
+```
+
+### 5. Start the Web UI
+
+In a separate terminal, start the web UI development server:
+
+```bash
+cd frontend/web
+npm run dev
+```
+
+The UI will be available at http://localhost:5173
+
+## Building for Production
+
+To create a production build:
+
+```bash
+npm run build
+```
+
+The built files will be in the `dist` directory, which can be served by any static file server.
+
+## Troubleshooting
+
+### TypeScript Errors
+
+If you encounter TypeScript errors related to React:
+
+1. Run the fix-dependencies script:
+   ```bash
+   ./fix-dependencies.bat
+   ```
+
+2. Restart your IDE or TypeScript server
+
+### API Connection Issues
+
+If the UI can't connect to the backend:
+
+1. Check that the backend is running on port 8000
+2. Verify the proxy settings in `vite.config.ts`
+3. Check browser console for CORS or network errors
+
+### Missing Assets
+
+If chess pieces or board squares don't appear:
+
+1. Verify that all assets are correctly copied to the public directory
+2. Check browser console for 404 errors
+3. Ensure the file paths in the code match your asset directory structure

web/TYPESCRIPT_FIXES.md

@@ -0,0 +1,69 @@
+# Fixing TypeScript Errors in the Chess UI
+
+If you're encountering TypeScript errors related to React modules not being found, follow these steps to resolve them:
+
+## Step 1: Reinstall Dependencies
+
+Run the provided script to reinstall React and its type definitions:
+
+```
+fix-dependencies.bat
+```
+
+Or manually run these commands:
+
+```
+npm uninstall react react-dom @types/react @types/react-dom
+npm install --save react react-dom
+npm install --save-dev @types/react @types/react-dom
+```
+
+## Step 2: Update Import Syntax
+
+Make sure all React imports use the following syntax:
+
+```typescript
+import * as React from 'react';
+import { useState, useEffect } from 'react';
+```
+
+Instead of:
+
+```typescript
+import React, { useState, useEffect } from 'react';
+```
+
+## Step 3: Restart TypeScript Server
+
+If you're using VS Code or another IDE, restart the TypeScript server:
+
+- VS Code: Press Ctrl+Shift+P (or Cmd+Shift+P on Mac), type "TypeScript: Restart TS Server" and press Enter
+
+## Step 4: Check tsconfig.json
+
+Make sure your tsconfig.json has the correct configuration:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "jsx": "react-jsx",
+    "allowSyntheticDefaultImports": true,
+    "types": ["vite/client", "node"]
+  }
+}
+```
+
+## Additional Tips
+
+1. If you're still having issues, try creating a new Vite project with React and TypeScript template and compare the configurations:
+
+```
+npm create vite@latest my-react-app -- --template react-ts
+```
+
+2. Make sure your node_modules folder is properly installed and not corrupted.
+
+3. Check for any conflicting TypeScript configurations in your project.
+
+4. If all else fails, you can use JavaScript (.jsx/.js) files temporarily instead of TypeScript until the issue is resolved.

web/WSL_SETUP.md

@@ -0,0 +1,100 @@
+# Setting Up the Chess UI in WSL
+
+This guide provides instructions for setting up and running the Chess UI in a Windows Subsystem for Linux (WSL) environment.
+
+## Prerequisites
+
+1. WSL installed with a Linux distribution (Ubuntu recommended)
+2. Node.js and npm installed in your WSL environment
+
+## Installation Steps
+
+### 1. Install Node.js and npm (if not already installed)
+
+```bash
+# Update package lists
+sudo apt update
+
+# Install Node.js and npm
+sudo apt install nodejs npm
+
+# Check installation
+node --version
+npm --version
+```
+
+Alternatively, use nvm for better Node.js version management:
+
+```bash
+# Install nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
+
+# Reload shell configuration
+source ~/.bashrc
+
+# Install latest LTS version of Node.js
+nvm install --lts
+
+# Use the installed version
+nvm use --lts
+```
+
+### 2. Set Up the Project
+
+Navigate to the project directory and run the setup script:
+
+```bash
+cd frontend/web
+chmod +x setup.sh
+./setup.sh
+```
+
+### 3. Copy Assets
+
+Run the asset copy script to copy chess pieces and board images to the public directory:
+
+```bash
+chmod +x copy-assets.sh
+./copy-assets.sh
+```
+
+### 4. Fix TypeScript Issues (if needed)
+
+If you encounter TypeScript errors related to React:
+
+```bash
+chmod +x fix-dependencies.sh
+./fix-dependencies.sh
+```
+
+### 5. Start the Development Server
+
+```bash
+npm run dev
+```
+
+## Troubleshooting
+
+### TypeScript Errors
+
+If you see "Cannot find module 'react'" errors:
+
+1. Make sure all dependencies are installed correctly
+2. Check that you're using the correct import syntax in your components:
+   ```typescript
+   import * as React from 'react';
+   import { useState, useEffect } from 'react';
+   ```
+3. Restart the TypeScript server in your IDE
+
+### Path Issues
+
+WSL uses Linux-style paths. Make sure you're using forward slashes (/) instead of backslashes (\\) in your code.
+
+### Performance Issues
+
+If you experience slow performance when running the development server in WSL:
+
+1. Store your project files in the Linux filesystem (e.g., /home/username/projects) rather than the Windows filesystem (/mnt/c/...)
+2. Use WSL 2 instead of WSL 1 for better performance
+3. Consider using Visual Studio Code with the Remote - WSL extension for a better development experience

web/copy-assets-fixed.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+echo "Copying chess assets to public directory with correct filenames..."
+
+# Create directories if they don't exist
+mkdir -p frontend/web/public/assets/pieces
+mkdir -p frontend/web/public/assets/boards/brown
+mkdir -p frontend/web/public/assets/boards/grey
+mkdir -p frontend/web/public/assets/sounds
+
+# Copy pieces
+echo "Copying chess pieces..."
+cp -v frontend/assets/pieces/*.png frontend/web/public/assets/pieces/
+
+# Copy brown board
+echo "Copying brown board..."
+cp -v frontend/assets/boards/brown/*.png frontend/web/public/assets/boards/brown/
+
+# Copy grey board (with correct filenames)
+echo "Copying grey board..."
+cp -v frontend/assets/boards/grey/*.png frontend/web/public/assets/boards/grey/
+
+# Create placeholder sound files if they don't exist
+echo "Creating placeholder sound files..."
+touch frontend/web/public/assets/sounds/move.mp3
+touch frontend/web/public/assets/sounds/capture.mp3
+touch frontend/web/public/assets/sounds/check.mp3
+touch frontend/web/public/assets/sounds/castle.mp3
+touch frontend/web/public/assets/sounds/game-end.mp3
+
+echo "Assets copied successfully!"
+echo "Please restart the development server to see the changes."

web/copy-assets.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+echo "Copying chess assets to public directory..."
+
+# Create directories if they don't exist
+mkdir -p public/assets/pieces
+mkdir -p public/assets/boards/brown
+mkdir -p public/assets/boards/grey
+
+# Copy pieces
+cp -v ../assets/pieces/*.png public/assets/pieces/
+
+# Copy board images
+cp -v ../assets/boards/brown/*.png public/assets/boards/brown/
+cp -v ../assets/boards/grey/*.png public/assets/boards/grey/
+
+echo "Assets copied successfully!"

web/fix-dependencies.bat

@@ -0,0 +1,8 @@
+@echo off
+echo Fixing React dependencies for Chess UI...
+npm uninstall react react-dom @types/react @types/react-dom
+npm install --save react react-dom
+npm install --save-dev @types/react @types/react-dom
+echo Dependencies reinstalled successfully!
+echo.
+echo You can now run "npm run dev" to start the development server.

web/fix-dependencies.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+echo "Fixing React dependencies for Chess UI..."
+npm uninstall react react-dom @types/react @types/react-dom
+npm install --save react react-dom
+npm install --save-dev @types/react @types/react-dom
+echo "Dependencies reinstalled successfully!"
+echo ""
+echo "You can now run 'npm run dev' to start the development server."

web/fix-react-typescript.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+echo "Fixing React TypeScript issues..."
+
+# Create a temporary package.json backup
+cp package.json package.json.bak
+
+# Remove React and its types
+npm uninstall react react-dom @types/react @types/react-dom
+
+# Clean npm cache
+npm cache clean --force
+
+# Install React and its types with specific versions known to work well together
+npm install --save [email protected] [email protected]
+npm install --save-dev @types/[email protected] @types/[email protected]
+
+# Create a proper tsconfig.json if it doesn't exist
+cat > tsconfig.json << EOL
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    },
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src", "**/*.ts", "**/*.tsx", "src/types/*.d.ts"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}
+EOL
+
+# Create a proper tsconfig.node.json if it doesn't exist
+cat > tsconfig.node.json << EOL
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["vite.config.ts"]
+}
+EOL
+
+echo "React TypeScript issues fixed! Please restart your IDE or TypeScript server."
+echo "You can now run 'npm run dev' to start the development server."

web/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Chess Engine UI</title>
+  </head>
+  <body class="bg-gray-100">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

web/node_modules/.bin/acorn

@@ -0,0 +1 @@
+../acorn/bin/acorn

web/node_modules/.bin/autoprefixer

@@ -0,0 +1 @@
+../autoprefixer/bin/autoprefixer

web/node_modules/.bin/browserslist

@@ -0,0 +1 @@
+../browserslist/cli.js

web/node_modules/.bin/cssesc

@@ -0,0 +1 @@
+../cssesc/bin/cssesc

web/node_modules/.bin/esbuild

@@ -0,0 +1 @@
+../esbuild/bin/esbuild

web/node_modules/.bin/glob

@@ -0,0 +1 @@
+../glob/dist/esm/bin.mjs

web/node_modules/.bin/jiti

@@ -0,0 +1 @@
+../jiti/bin/jiti.js

web/node_modules/.bin/jsesc

@@ -0,0 +1 @@
+../jsesc/bin/jsesc

web/node_modules/.bin/json5

@@ -0,0 +1 @@
+../json5/lib/cli.js

web/node_modules/.bin/loose-envify

@@ -0,0 +1 @@
+../loose-envify/cli.js

web/node_modules/.bin/nanoid

@@ -0,0 +1 @@
+../nanoid/bin/nanoid.cjs

web/node_modules/.bin/node-which

@@ -0,0 +1 @@
+../which/bin/node-which

web/node_modules/.bin/parser

@@ -0,0 +1 @@
+../@babel/parser/bin/babel-parser.js

web/node_modules/.bin/resolve

@@ -0,0 +1 @@
+../resolve/bin/resolve

web/node_modules/.bin/rollup

@@ -0,0 +1 @@
+../rollup/dist/bin/rollup