chess-tournament-model

♟️ Chess Tournament - AI Game Playing

Hệ thống thi đấu cờ vua với các AI agents sử dụng Minimax và Machine Learning.

Bài tập lớn môn Trí tuệ Nhân tạo (AI) - HCMUT

---

📋 Mục tiêu dự án

• Hiện thực game playing agent cho trò chơi cờ vua (đối kháng)
• Sử dụng giải thuật Minimax với Alpha-Beta Pruning
• Sử dụng Machine Learning (Neural Network) học từ Lichess database
• Đáp ứng yêu cầu:
  • ✅ Minimax thắng Random ≥ 90%
  • ✅ ML Agent thắng Random ≥ 60%

---

🎮 Tính năng

AI Agents

Giao diện

• 🎯 Chọn agents và số trận đấu
• 📊 Hiển thị thống kê real-time
• 🔄 Replay các ván đã đấu
• ⌨️ Hỗ trợ phím tắt

---

🗂️ Cấu trúc dự án

chess-tournament/
├── main.py                 # Ứng dụng chính (GUI)
├── agents.py               # Định nghĩa các AI agents
├── tournament.py           # Quản lý giải đấu
├── ui_components.py        # Các component giao diện
├── setup_assets.py         # Setup hình ảnh quân cờ
├── requirements.txt        # Dependencies
│
├── ml/                     # 🤖 Machine Learning Module
│   ├── __init__.py
│   ├── data_processor.py   # Xử lý dữ liệu PGN từ Lichess
│   ├── model.py            # Neural Network models
│   ├── train.py            # Script training
│   └── models/             # Trained models
│       ├── chess_model.pth     # PyTorch model (90% accuracy)
│       └── simple_model.npz    # Backup model
│
├── data/                   # 📦 Dữ liệu
│   ├── pgn/                # File PGN từ Lichess
│   └── processed/          # Dataset đã xử lý
│
├── assets/                 # 🎨 Hình ảnh
│   └── img/chess_pieces/   # Hình các quân cờ
│
└── tournaments/            # 📁 Kết quả các giải đấu

---

🚀 Cài đặt và Chạy

1. Cài đặt dependencies

pip install -r requirements.txt

2. Setup hình ảnh (lần đầu)

python setup_assets.py

3. Chạy ứng dụng

python main.py

---

🤖 Training ML Agent

Bước 1: Chuẩn bị dữ liệu

Cách 1: Tải từ Lichess Database (khuyến nghị)

# Tải file từ https://database.lichess.org/
# Đặt file .pgn.zst vào data/pgn/

# Giải nén bằng Python
python -c "from ml.data_processor import decompress_zst_file; decompress_zst_file('data/pgn/FILE.pgn.zst', 'data/pgn/lichess_games.pgn')"

Cách 2: Tải từ Lichess API (nhanh hơn, ít data hơn)

python ml/train.py --use-api --max-games 3000

Bước 2: Training

# Training với file PGN local
python ml/train.py --pgn data/pgn/lichess_games.pgn --max-games 15000 --min-elo 1800 --epochs 50
hoặc
python ml/train.py --pgn "data/pgn/lichess_games.pgn" --max-games 30000 --min-elo 2000 --epochs 80 --batch-size 512 --model pytorch

# Các options khác
python ml/train.py --help

Kết quả Training

---

📊 Kết quả đánh giá

Minimax vs Random (100 trận)

ML vs Random (100 trận)

---

🧠 Chi tiết thuật toán

1. Minimax Agent

Thuật toán: Minimax với Alpha-Beta Pruning
Độ sâu: 3 ply
Hàm đánh giá: Material-based
  - Tốt: 100, Mã: 320, Tượng: 330
  - Xe: 500, Hậu: 900, Vua: 20000

2. ML Agent

Model: Fully Connected Neural Network
Architecture: 773 → 1024 → 512 → 256 → 128 → 1
Input: Board state (773 features)
  - 768: Piece positions (12 types × 64 squares)
  - 1: Turn
  - 4: Castling rights
Output: Win probability [0, 1]
Training data: 563,284 positions từ Lichess (Elo ≥ 1800)
Framework: PyTorch

---

📁 Dữ liệu Lichess

Dữ liệu được lấy từ Lichess Database:

• File sử dụng: lichess_db_standard_rated_2015-07.pgn.zst
• Kích thước: ~460MB (nén) → 2.5GB (giải nén)
• Số games xử lý: 15,000 (filtered Elo ≥ 1800)
• Số positions: 563,284

---

🎮 Hướng dẫn sử dụng

Tạo giải đấu mới

1. Click "New Tournament"
2. Chọn Agent 1 và Agent 2
3. Nhập số trận đấu
4. Click "Start"

Xem lại ván đấu

1. Click "Replay Tournament"
2. Chọn giải đấu từ danh sách
3. Chọn ván đấu cụ thể
4. Sử dụng controls để xem từng nước

Phím tắt (Replay)

---

📝 Requirements

pygame>=2.6.0
python-chess>=1.9.0
numpy>=1.24.0
torch>=2.0.0
requests>=2.28.0
zstandard>=0.21.0

---

👥 Thành viên nhóm

---

📚 Tài liệu tham khảo

1. Russell, S., & Norvig, P. - Artificial Intelligence: A Modern Approach
2. Lichess Database
3. python-chess Documentation
4. PyTorch Documentation

---

📄 License

Dự án này được thực hiện cho mục đích học tập tại HCMUT.