Chess Challenge submission by filomeneroquefort

README.md

@@ -0,0 +1,20 @@
+---
+library_name: transformers
+tags:
+- chess
+- llm-course
+- chess-challenge
+license: mit
+---
+# chess_filo_7
+Chess model submitted to the LLM Course Chess Challenge.
+## Submission Info
+- **Submitted by**: [filomeneroquefort](https://huggingface.co/filomeneroquefort)
+- **Parameters**: 885,696
+- **Organization**: LLM-course
+## Model Details
+- **Architecture**: Chess Transformer (GPT-style)
+- **Vocab size**: 90
+- **Embedding dim**: 112
+- **Layers**: 6
+- **Heads**: 8

config.json

@@ -0,0 +1,20 @@
+{
+  "architectures": [
+    "ChessForCausalLM"
+  ],
+  "bos_token_id": 1,
+  "dropout": 0.1,
+  "dtype": "float32",
+  "eos_token_id": 2,
+  "layer_norm_epsilon": 1e-05,
+  "model_type": "chess_transformer",
+  "n_ctx": 1024,
+  "n_embd": 112,
+  "n_head": 8,
+  "n_inner": 336,
+  "n_layer": 6,
+  "pad_token_id": 0,
+  "tie_weights": true,
+  "transformers_version": "4.57.6",
+  "vocab_size": 90
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:77f947eafa7925a4f394a23f72d0b2c74bdac0e3b41516a6ea69afb532cc2d46
+size 3549224

special_tokens_map.json

@@ -0,0 +1,6 @@
+{
+  "bos_token": "[BOS]",
+  "eos_token": "[EOS]",
+  "pad_token": "[PAD]",
+  "unk_token": "[UNK]"
+}

tokenizer.py

@@ -0,0 +1,197 @@
+"""
+Atomic Chess Tokenizer.
+
+Decomposes chess moves into atomic components:
+[Piece] + [Source] + [Destination] + [Suffix]
+
+Example: "WPe2e4(x)" -> ["WP", "e2", "e4", "(x)"]
+
+Benefits:
+- Drastically reduces vocab size (~1200 -> ~90)
+- Saves ~140k parameters in the embedding layer
+- Allows the model to learn spatial relationships (e2 is close to e3)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Dict, List, Optional
+
+from transformers import PreTrainedTokenizer
+
+class ChessTokenizer(PreTrainedTokenizer):
+    
+    model_input_names = ["input_ids", "attention_mask"]
+    
+    # Special tokens
+    PAD_TOKEN = "[PAD]"
+    BOS_TOKEN = "[BOS]"
+    EOS_TOKEN = "[EOS]"
+    UNK_TOKEN = "[UNK]"
+    
+    # Regex to parse the extended UCI format
+    # Groups: 1=Piece, 2=Source, 3=Dest, 4=Suffix
+    MOVE_REGEX = re.compile(r"([WB][PNBRQK])([a-h][1-8])([a-h][1-8])(.*)")
+
+    def __init__(
+        self,
+        vocab_file: Optional[str] = None,
+        vocab: Optional[Dict[str, int]] = None,
+        **kwargs,
+    ):
+        self._pad_token = self.PAD_TOKEN
+        self._bos_token = self.BOS_TOKEN
+        self._eos_token = self.EOS_TOKEN
+        self._unk_token = self.UNK_TOKEN
+        
+        # Clean kwargs
+        kwargs.pop("pad_token", None)
+        kwargs.pop("bos_token", None)
+        kwargs.pop("eos_token", None)
+        kwargs.pop("unk_token", None)
+        
+        if vocab is not None:
+            self._vocab = vocab
+        elif vocab_file is not None and os.path.exists(vocab_file):
+            with open(vocab_file, "r", encoding="utf-8") as f:
+                self._vocab = json.load(f)
+        else:
+            self._vocab = self._create_atomic_vocab()
+            
+        self._ids_to_tokens = {v: k for k, v in self._vocab.items()}
+        
+        super().__init__(
+            pad_token=self._pad_token,
+            bos_token=self._bos_token,
+            eos_token=self._eos_token,
+            unk_token=self._unk_token,
+            **kwargs,
+        )
+
+    def _create_atomic_vocab(self) -> Dict[str, int]:
+        """
+        Manually builds the vocabulary because we know the rules of Chess.
+        We don't need to learn this from the dataset.
+        """
+        vocab = {}
+        idx = 0
+        
+        # 1. Special Tokens
+        for token in [self.PAD_TOKEN, self.BOS_TOKEN, self.EOS_TOKEN, self.UNK_TOKEN]:
+            vocab[token] = idx
+            idx += 1
+            
+        # 2. Pieces (Color + Type)
+        colors = ['W', 'B']
+        pieces = ['P', 'N', 'B', 'R', 'Q', 'K']
+        for c in colors:
+            for p in pieces:
+                vocab[f"{c}{p}"] = idx
+                idx += 1
+                
+        # 3. Squares (a1 to h8)
+        files = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']
+        ranks = ['1', '2', '3', '4', '5', '6', '7', '8']
+        for f in files:
+            for r in ranks:
+                vocab[f"{f}{r}"] = idx
+                idx += 1
+                
+        # 4. Common Suffixes (derived from Lichess notation)
+        # (x)=capture, (+)=check, (#)=mate, (o)=castling
+        suffixes = ["(x)", "(+)", "(+*)", "(o)", "(O)", "=", "=Q", "=R", "=B", "=N"]
+        for s in suffixes:
+            vocab[s] = idx
+            idx += 1
+            
+        return vocab
+
+    @property
+    def vocab_size(self) -> int:
+        return len(self._vocab)
+
+    def get_vocab(self) -> Dict[str, int]:
+        return dict(self._vocab)
+
+    def _tokenize(self, text: str) -> List[str]:
+        """
+        Splits a string of moves into atomic tokens.
+        "WPe2e4" -> ["WP", "e2", "e4"]
+        """
+        raw_moves = text.strip().split()
+        tokens = []
+        
+        for move in raw_moves:
+            match = self.MOVE_REGEX.match(move)
+            if match:
+                # Add piece, source, dest
+                tokens.extend([match.group(1), match.group(2), match.group(3)])
+                # Add suffix if it exists
+                suffix = match.group(4)
+                if suffix:
+                    tokens.append(suffix)
+            else:
+                # Fallback for weird formatting (or UNK)
+                tokens.append(move)
+                
+        return tokens
+
+    def _convert_token_to_id(self, token: str) -> int:
+        return self._vocab.get(token, self._vocab.get(self.UNK_TOKEN))
+
+    def _convert_id_to_token(self, index: int) -> str:
+        return self._ids_to_tokens.get(index, self.UNK_TOKEN)
+
+    def convert_tokens_to_string(self, tokens: List[str]) -> str:
+        """
+        Reconstructs moves from atomic tokens.
+        This is tricky because we need to join them without spaces, 
+        but add spaces between actual moves.
+        """
+        out = []
+        current_move = []
+        
+        special = {self.PAD_TOKEN, self.BOS_TOKEN, self.EOS_TOKEN, self.UNK_TOKEN}
+        
+        for t in tokens:
+            if t in special:
+                continue
+            
+            current_move.append(t)
+            
+            # Logic to decide when a move ends
+            # A move usually ends after a Suffix OR after a Destination square if no suffix follows
+            # This heuristic is simple: if we have a piece, src, and dest, check next token
+            
+            # Simplified reconstruction:
+            # Just join everything and use a heuristic to insert spaces?
+            # Better: The model generates atomic tokens. 
+            # We know a move starts with [WB][PNBRQK].
+            
+        # Robust reconstruction approach:
+        full_str = "".join([t for t in tokens if t not in special])
+        
+        # Insert space before every Piece token (except the first one)
+        # Regex lookbehind isn't strictly necessary, we can just replace
+        formatted = re.sub(r'(?<!^)([WB][PNBRQK])', r' \1', full_str)
+        
+        return formatted
+
+    def save_vocabulary(self, save_directory: str, filename_prefix: Optional[str] = None) -> tuple:
+        if not os.path.isdir(save_directory):
+            os.makedirs(save_directory, exist_ok=True)
+        vocab_file = os.path.join(
+            save_directory, (filename_prefix + "-" if filename_prefix else "") + "vocab.json"
+        )
+        with open(vocab_file, "w", encoding="utf-8") as f:
+            json.dump(self._vocab, f, ensure_ascii=False, indent=2)
+        return (vocab_file,)
+
+    # We don't really need build_vocab_from_dataset anymore as we hardcoded the rules,
+    # but we keep the method signature to satisfy the template.
+    @classmethod
+    def build_vocab_from_dataset(cls, *args, **kwargs):
+        print("Note: Atomic tokenizer uses a static vocabulary rule set.")
+        return cls()

tokenizer_config.json

@@ -0,0 +1,50 @@
+{
+  "added_tokens_decoder": {
+    "0": {
+      "content": "[PAD]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "1": {
+      "content": "[BOS]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "2": {
+      "content": "[EOS]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "3": {
+      "content": "[UNK]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    }
+  },
+  "auto_map": {
+    "AutoTokenizer": [
+      "tokenizer.ChessTokenizer",
+      null
+    ]
+  },
+  "bos_token": "[BOS]",
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "[EOS]",
+  "extra_special_tokens": {},
+  "model_max_length": 1000000000000000019884624838656,
+  "pad_token": "[PAD]",
+  "tokenizer_class": "ChessTokenizer",
+  "unk_token": "[UNK]"
+}

vocab.json

@@ -0,0 +1,92 @@
+{
+  "[PAD]": 0,
+  "[BOS]": 1,
+  "[EOS]": 2,
+  "[UNK]": 3,
+  "WP": 4,
+  "WN": 5,
+  "WB": 6,
+  "WR": 7,
+  "WQ": 8,
+  "WK": 9,
+  "BP": 10,
+  "BN": 11,
+  "BB": 12,
+  "BR": 13,
+  "BQ": 14,
+  "BK": 15,
+  "a1": 16,
+  "a2": 17,
+  "a3": 18,
+  "a4": 19,
+  "a5": 20,
+  "a6": 21,
+  "a7": 22,
+  "a8": 23,
+  "b1": 24,
+  "b2": 25,
+  "b3": 26,
+  "b4": 27,
+  "b5": 28,
+  "b6": 29,
+  "b7": 30,
+  "b8": 31,
+  "c1": 32,
+  "c2": 33,
+  "c3": 34,
+  "c4": 35,
+  "c5": 36,
+  "c6": 37,
+  "c7": 38,
+  "c8": 39,
+  "d1": 40,
+  "d2": 41,
+  "d3": 42,
+  "d4": 43,
+  "d5": 44,
+  "d6": 45,
+  "d7": 46,
+  "d8": 47,
+  "e1": 48,
+  "e2": 49,
+  "e3": 50,
+  "e4": 51,
+  "e5": 52,
+  "e6": 53,
+  "e7": 54,
+  "e8": 55,
+  "f1": 56,
+  "f2": 57,
+  "f3": 58,
+  "f4": 59,
+  "f5": 60,
+  "f6": 61,
+  "f7": 62,
+  "f8": 63,
+  "g1": 64,
+  "g2": 65,
+  "g3": 66,
+  "g4": 67,
+  "g5": 68,
+  "g6": 69,
+  "g7": 70,
+  "g8": 71,
+  "h1": 72,
+  "h2": 73,
+  "h3": 74,
+  "h4": 75,
+  "h5": 76,
+  "h6": 77,
+  "h7": 78,
+  "h8": 79,
+  "(x)": 80,
+  "(+)": 81,
+  "(+*)": 82,
+  "(o)": 83,
+  "(O)": 84,
+  "=": 85,
+  "=Q": 86,
+  "=R": 87,
+  "=B": 88,
+  "=N": 89
+}