Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,133 @@
+---
+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
+```