| --- |
| license: mit |
| library_name: pytorch |
| tags: |
| - gomoku |
| - alphazero |
| - mcts |
| - board-game-ai |
| - pytorch |
| pipeline_tag: reinforcement-learning |
| --- |
| |
| # GomokuZeroAI |
|
|
| GomokuZeroAI is an AlphaZero-style Gomoku checkpoint trained with self-play, a PyTorch policy-value network, and Monte Carlo Tree Search. |
|
|
| This repository hosts the model weights used by the companion project: |
|
|
| ```text |
| https://github.com/maojh15/GomokuZeroAI |
| ``` |
|
|
| The current checkpoint is: |
|
|
| ```text |
| iter_0150_15x15.pt |
| ``` |
|
|
| It is intended for local human-vs-AI play through the project's web UI. |
|
|
| ## Quick Start |
|
|
| Clone the code repository: |
|
|
| ```bash |
| git clone https://github.com/maojh15/GomokuZeroAI.git |
| cd GomokuZeroAI |
| ``` |
|
|
| Install dependencies: |
|
|
| ```bash |
| pip install numpy torch pyyaml huggingface_hub |
| ``` |
|
|
| Download the checkpoint: |
|
|
| ```bash |
| hf download maojh15/GomokuZeroAI iter_0150_15x15.pt --local-dir result_15x15/checkpoints |
| ``` |
|
|
| Start the local human-vs-AI server: |
|
|
| ```bash |
| python play_human.py --host 127.0.0.1 --port 8765 |
| ``` |
|
|
| Open the web UI: |
|
|
| ```text |
| http://127.0.0.1:8765 |
| ``` |
|
|
| Select `iter_0150_15x15.pt` in the checkpoint dropdown and click the new-game button to start playing. |
|
|
| ## Model Details |
|
|
| - Game: Gomoku / Five in a Row |
| - Board size: 15x15 |
| - Checkpoint: `iter_0150_15x15.pt` |
| - Training iteration: 150 |
| - Framework: PyTorch |
| - Architecture: convolutional policy-value network |
| - Input channels: 2 |
| - Network width: 128 channels |
| - Player encodings: `1` and `-1` |
| - MCTS backend used during training: C++ Torch Extension |
| - MCTS playouts during training: 2000 |
| - Opening self-play temperature: 1.0 for the first 12 moves |
| - Evaluation temperature: 0.001 after the opening |
|
|
| The network predicts: |
|
|
| - a policy distribution over legal board moves |
| - a value estimate in `[0, 1]` from the current player's perspective |
|
|
| The local web UI can display both the raw network value and the MCTS root value. |
|
|
| ## Intended Use |
|
|
| This checkpoint is meant for: |
|
|
| - playing Gomoku against the AI locally |
| - inspecting policy and visit overlays in the web UI |
| - comparing future GomokuZeroAI checkpoints |
| - experimenting with AlphaZero-style self-play training code |
|
|
| This is not a Transformers model and is not intended for use through the Hugging Face `pipeline()` API. |
|
|
| ## Limitations |
|
|
| - The model was trained for 15x15 Gomoku only. |
| - It requires the GomokuZeroAI codebase to load and run correctly. |
| - Playing strength depends heavily on the MCTS playout setting used at inference time. |
| - Higher playouts usually improve move quality but increase latency. |
| - The checkpoint is an experimental game AI model, not a benchmarked tournament engine. |
|
|
| ## Recommended Inference Settings |
|
|
| For interactive human-vs-AI play, start with: |
|
|
| - `MCTS playouts`: 2000 |
| - `c_puct`: 5.0 |
| - `candidate distance`: empty / all legal moves |
| - `mcts_tactical_shortcuts`: enabled for faster tactical responses in the web UI |
|
|
| If moves are too slow on your machine, reduce `MCTS playouts` to 400-1000. |
|
|
| ## Files |
|
|
| ```text |
| iter_0150_15x15.pt |
| ``` |
|
|
| This file contains the model weights and training configuration payload used by the GomokuZeroAI checkpoint loader. |
|
|
| ## Citation |
|
|
| If you use this checkpoint or codebase in your own experiments, please reference the project repository: |
|
|
| ```text |
| https://github.com/maojh15/GomokuZeroAI |
| ``` |
|
|
