🏆 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: 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:

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. model.safetensors: The model weights. Standard pickled files (.pth, .bin) are explicitly not allowed for security and rule enforcement.
2. config.json: To verify architecture settings and parameter counts.
3. 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:

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 the Discord server? Or would you like to join the tournament?