| --- |
| title: README |
| emoji: 🏃 |
| colorFrom: yellow |
| colorTo: indigo |
| sdk: static |
| pinned: false |
| --- |
| |
| # 🏆 Open Machine Learning Chess Tournament (OMLCheT) |
|
|
| Welcome to **OMLCheT**, the community-driven, lightweight AI chess championship hosted entirely on Hugging Face! |
|
|
| Unlike traditional tournaments dominated by massive compute-heavy engines, OMLCheT is designed to showcase open-source creativity, architectural innovation, and training efficiency. We pit lightweight **Language Models (LMs)** and **Reinforcement Learning (RL) agents** against each other in a battle of pure strategy. |
|
|
| > [!NOTE]⚠️ **Note:** This tournament is held completely **for fun and bragging rights**! There are no cash prizes or material rewards—just a cool space for the community to experiment, test small architectures, and see whose lightweight model reigns supreme. |
|
|
| --- |
|
|
| ## Tournament Brackets & Constraints |
|
|
| To keep the playing field level and ensure models can be easily evaluated on open hardware (Kaggle/Colab), all submissions must adhere to the following division rules: |
|
|
| | Constraint | 🧠 Language Model (LM) Bracket | 🤖 Reinforcement Learning (RL) Bracket | |
| | :--- | :--- | :--- | |
| | **Max Size** | **1.5B parameters** *(allows 1.2B/1.3B variants)* | **100M parameters** *(to save training time)* | |
| | **Required Format** | Weights as `*.safetensors` + Python script | Weights as `*.safetensors` + Python script | |
| | **Input Type** | SAN (Standard Algebraic Notation) | SAN, FEN, or Bitboards (handled via wrapper) | |
| | **Architectures** | Transformers, Mamba, RWKV, LSTM, RNN, Hybrids | Deep Q-Networks, Actor-Critic, Policy Gradients, etc. | |
| | **Precision** | Any (FP32, FP16, INT8, INT4, Trinary/Binary, etc.) | Any | |
|
|
| ### Key Technical Allowances |
| * **Training Style:** You are fully allowed to fine-tune existing base architectures (e.g., GPT-2) or pre-train your custom model entirely from scratch solely on chess data. |
| * **Quantization:** If you want to train a custom 10M parameter model using an exotic trinary/binary precision setup, go for it! As long as inference runs in Python, it is legal. |
|
|
| --- |
|
|
| ## Submission Requirements |
|
|
| To enter the tournament, you must host your model on Hugging Face and submit your repository link. To guarantee security and compatibility with our automated tournament runner, your repository **must** contain these three components: |
| 1. **`README.md`**: A comprehensive model card detailing your agent. To ensure transparency, your README must include the following sections: |
| * Model Overview: The architecture type (e.g., Transformer, Mamba, LSTM) and intended playstyle. |
| * Architecture Details: Parameter count, number of layers, embedding dimensions, and attention heads. |
| * Training Data: Sources used (e.g., Lichess database, FICS) and the volume of data. |
| * Training Methodology: The training process, key hyperparameters (learning rate, batch size, etc.), and whether it was supervised learning or Reinforcement Learning. |
| * Known limitations / failure modes: does the model blunder in endgames? struggle with promotions? useful for the community. |
| * Inference speed: since games run on Kaggle/Colab, knowing roughly how fast a model generates moves could matter. |
| * License: Any license as long it doesn't break the "open-source" vibe, like costume license's. |
| * Performance Metrics (Optional): Any self-evaluations, such as win rates against known engines or estimated Elo. |
| 2. **`model.safetensors`**: The model weights. Standard pickled files (`.pth`, `.bin`) are explicitly **not allowed** for security and rule enforcement. |
| 3. **`config.json`**: To verify architecture settings and parameter counts. |
| 4. **`chess_agent.py`**: Your inference logic. It must implement the standard template below. |
| |
| --- |
| |
| ### Model Packaging & Architecture Rules |
| |
| Depending on what kind of model you are submitting, please ensure your repository is packaged according to these rules so the evaluation engine can run it smoothly: |
| |
| * 🧩 **Standard HF Model Types (Fine-tunes & Pre-trains):** If your model uses an existing architecture natively supported by the Hugging Face `transformers` library (e.g., `gpt2`, `llama`, `qwen`, `opt`), **you do not need to upload any custom model architecture code**. Simply uploading your configuration files and `*.safetensors` weights is enough; our evaluator will hook into them automatically. |
| * 🛠️ **Custom Architectures:** If you build a completely custom neural network from scratch or modify an architecture to the point that it has a unique `model_type` in your `config.json`, you **must** supply the underlying architecture definitions (`modeling_*.py`) inside your repository and properly hook them up using the `auto_map` property in your config so it can be safely initialized via `trust_remote_code=True`. |
| * 🤖 **Reinforcement Learning Agents:** Because RL agents do not follow a unified, standard Hugging Face model architecture out of the box, **all RL submissions must bring their own standalone inference and network code**. Make sure your custom PyTorch/JAX definitions are fully included in your repo or embedded cleanly within your `chess_agent.py` script so the weights can be loaded. |
|
|
| --- |
|
|
| ### Standard Inference Template (`chess_agent.py`) |
| Your repository must include this exact class structure so our evaluation script can play games automatically: |
| |
| ```python |
| import chess |
| |
| class ChessAgent: |
| def __init__(self, model_dir="./"): |
| """ |
| Initialize your model, tokenizer, or custom neural network here. |
| model_dir points to the root of your Hugging Face repository download. |
| """ |
| # Pass and load your safetensors weights here |
| pass |
| |
| def select_move(self, board_history_san: str, legal_moves_san: list[str]) -> str: |
| """ |
| Inputs: |
| - board_history_san: Space-separated string of the game so far |
| (e.g., "e4 e5 Nf3 Nc6") |
| - legal_moves_san: A list of completely legal SAN moves available |
| (e.g., ["d4", "Bc4", "Nxe5"]) |
| |
| Output: |
| - A string containing exactly one chosen move from legal_moves_san. |
| """ |
| # Your inference logic here |
| # Tip: Use legal_moves_san to filter or mask your model outputs! |
| |
| chosen_move = legal_moves_san[0] # Default fallback example |
| return chosen_move |
| |
|
|
| ``` |
| |
| --- |
| |
| ## Tournament Execution & Rules |
| |
| * **The Arena:** The tournament will be run asynchronously using Kaggle/Colab environments using the `python-chess` framework. |
| * **The Illegal Move Fallback:** We know LMs can hallucinate and RL models can sometimes guess out-of-bounds moves. If your agent returns a move that is illegal or unparseable, **the tournament engine will automatically pick a random legal move as a fallback** so the game can continue. However, relying on the fallback too much will likely hurt your model's strategy, so try to mask or filter your outputs! |
| * **The Grand Finale:** The tournament will progress via a Swiss-system group stage leading into a single-elimination knockout. The champion of the LM bracket will face off against the champion of the RL bracket in a final showdown. Full PGN match histories and bracket summaries will be fully published once the tournament simulation concludes. |
| |
| > Would you like to [join](https://discord.gg/VgZffqPjzk) the Discord server? |
| > Or would you like to [join](https://huggingface.co/organizations/OMLCheT/share/euQvZOczfZjZlqjWQKsofBuuheDLEUHhpf) the tournament? |
