Meiring47817909/Tsoro_Yematatu

This project implements the traditional African board game Tsoro Yematatu and explores reinforcement learning approaches (tabular Q‑learning and Deep Q‑Networks) to train agents that can play the game. It also includes a Tkinter GUI for interactive play. # Tsoro Yematatu Reinforcement Learning Project This project implements the traditional African board game **Tsoro Yematatu** and trains a Tabular Q-Learning agent to master it. The game features a completely mathematically symmetric zero-sum reward function (Option C) and a hard 50-turn cap to enforce hyper-efficient, realistic gameplay. It also includes a Tkinter GUI for interactive human-vs-AI play. --- ## 📂 Project Structure ```text tsoro_yematatu/ │ ├── game/ │ ├── game_interface.py # Abstract interface for games │ ├── tsoro_yematatu.py # Tsoro Yematatu game rules & logic │ ├── board_gui.py # Tkinter GUI for human play │ ├── agents/ │ ├── gui_agent.py # GUI wrapper for human vs computer │ ├── qlearning_agent.py # Core Q-learning agent with Option C reward │ ├── training/ │ ├── train_qlearning.py # Train the Q-learning agent │ ├── evaluate_master.py # Tournament: 1000-episode agent vs historical checkpoints │ ├── profile_training_intervals.py # Track average game lengths in 100-episode buckets │ ├── main.py # Entry point for GUI play ``` ## 🚀 How to Use ### 1. Train the Agent Train a fresh Q-learning agent. We recommend 1,000 to 5,000 episodes for optimal intelligence. This will generate a file called `qlearning_table.pkl` in the root directory. ```bash python training/train_qlearning.py --episodes 5000 ``` ### 2. Play the Game (GUI) Play interactively against the computer using the Tkinter GUI. By default, you play as 'X' (going first). ```bash python main.py --mode qlearning --player O ``` **Options:** - `--mode random` → computer plays completely random moves - `--mode qlearning` → computer uses trained Q‑learning agent - `--player X|O` → choose which side the computer plays (O goes second) - `--model filename.pkl` → load a specific Q-table file (defaults to `qlearning_table.pkl`) *Example:* To play as 'O' (meaning the A …