Chess Challenge submission by Oceane28

README.md

@@ -14,13 +14,18 @@ Chess model submitted to the LLM Course Chess Challenge.
 ## Submission Info
 
 - **Submitted by**: [Oceane28](https://huggingface.co/Oceane28)
-- **Parameters**: 997,488
+- **Parameters**: 973,544
 - **Organization**: LLM-course
 
-## Model Details
+## Usage
 
-- **Architecture**: Chess Transformer (GPT-style)
-- **Vocab size**: 72
-- **Embedding dim**: 128
-- **Layers**: 6
-- **Heads**: 8
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model = AutoModelForCausalLM.from_pretrained("LLM-course/chess-6-Oceane28", trust_remote_code=True)
+tokenizer = AutoTokenizer.from_pretrained("LLM-course/chess-6-Oceane28", trust_remote_code=True)
+```
+
+## Evaluation
+
+This model is evaluated at the [Chess Challenge Arena](https://huggingface.co/spaces/LLM-course/Chess1MChallenge).

config.json

@@ -9,12 +9,16 @@
   "layer_norm_epsilon": 1e-05,
   "model_type": "chess_transformer",
   "n_ctx": 256,
-  "n_embd": 128,
-  "n_head": 8,
-  "n_inner": 360,
-  "n_layer": 6,
+  "n_embd": 92,
+  "n_head": 4,
+  "n_inner": 276,
+  "n_layer": 11,
   "pad_token_id": 0,
   "tie_weights": true,
-  "transformers_version": "4.57.5",
-  "vocab_size": 72
-}
+  "transformers_version": "4.57.6",
+  "vocab_size": 72,
+  "auto_map": {
+    "AutoConfig": "model.ChessConfig",
+    "AutoModelForCausalLM": "model.ChessForCausalLM"
+  }
+}

model.py

@@ -0,0 +1,396 @@
+"""
+Modèle Transformer pour le Chess Challenge (1M paramètres).
+
+Ce module fournit une architecture transformer de style GPT conçue
+pour respecter la contrainte stricte de moins de 1 million de paramètres.
+
+Composants clés :
+- ChessConfig : Configuration des hyperparamètres.
+- ChessForCausalLM : Le modèle principal pour la prédiction du prochain coup.
+"""
+from __future__ import annotations
+import math
+from dataclasses import dataclass
+from typing import Optional, Tuple, Union
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from transformers import PretrainedConfig, PreTrainedModel, AutoConfig, AutoModelForCausalLM
+from transformers.modeling_outputs import CausalLMOutputWithPast
+
+# -----------------------------------------------------------------------------
+# Configuration
+# -----------------------------------------------------------------------------
+
+class ChessConfig(PretrainedConfig):
+    """
+    Classe de configuration pour le modèle Chess Transformer.
+    
+    Conçue pour un budget de paramètres très serré (< 1M).
+    
+    Répartition du budget (avec les valeurs par défaut de ton ami) :
+    - Vocabulaire (Embeddings) : 72 * 92 = ~6,6k
+    - Embeddings de position : 256 * 92 = ~23,5k
+    - Couches Transformer : 11 couches * (~85k par couche) = ~935k
+    - Tête LM (liée aux embeddings) : 0 paramètre supplémentaire
+    - Total : ~970k paramètres (juste en dessous de 1M).
+    """
+    
+    model_type = "chess_transformer"
+    
+    def __init__(
+        self,
+        vocab_size: int = 1200,
+        n_embd: int = 128,
+        n_layer: int = 6,
+        n_head: int = 4,
+        n_ctx: int = 256,
+        n_inner: Optional[int] = None,
+        dropout: float = 0.1,
+        layer_norm_epsilon: float = 1e-5,
+        tie_weights: bool = True,
+        pad_token_id: int = 0,
+        bos_token_id: int = 1,
+        eos_token_id: int = 2,
+        **kwargs,
+    ):
+        super().__init__(
+            pad_token_id=pad_token_id,
+            bos_token_id=bos_token_id,
+            eos_token_id=eos_token_id,
+            **kwargs,
+        )
+        
+        self.vocab_size = vocab_size
+        self.n_embd = n_embd
+        self.n_layer = n_layer
+        self.n_head = n_head
+        self.n_ctx = n_ctx
+        self.n_inner = n_inner if n_inner is not None else 3 * n_embd
+        self.dropout = dropout
+        self.layer_norm_epsilon = layer_norm_epsilon
+        self.tie_weights = tie_weights
+        self.tie_word_embeddings = bool(tie_weights)
+
+
+# -----------------------------------------------------------------------------
+# Modules du Transformer
+# -----------------------------------------------------------------------------
+
+class MultiHeadAttention(nn.Module):
+    """
+    Module d'attention multi-têtes standard.
+    Inclut le masquage causal pour empêcher le modèle de "voir le futur".
+    """
+    
+    def __init__(self, config: ChessConfig):
+        super().__init__()
+        
+        assert config.n_embd % config.n_head == 0, \
+            f"n_embd ({config.n_embd}) doit être divisible par n_head ({config.n_head})"
+        
+        self.n_head = config.n_head
+        self.n_embd = config.n_embd
+        self.head_dim = config.n_embd // config.n_head
+        
+        # Projection combinée Q, K, V pour l'efficacité
+        self.c_attn = nn.Linear(config.n_embd, 3 * config.n_embd)
+        self.c_proj = nn.Linear(config.n_embd, config.n_embd)
+        
+        self.dropout = nn.Dropout(config.dropout)
+        
+        # Masque causal (registre persistent=False pour ne pas le sauvegarder dans le checkpoint)
+        self.register_buffer(
+            "bias",
+            torch.tril(torch.ones(config.n_ctx, config.n_ctx)).view(
+                1, 1, config.n_ctx, config.n_ctx
+            ),
+            persistent=False,
+        )
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        attention_mask: Optional[torch.Tensor] = None,
+    ) -> torch.Tensor:
+        batch_size, seq_len, _ = x.size()
+        
+        # Calcul de Q, K, V
+        qkv = self.c_attn(x)
+        q, k, v = qkv.split(self.n_embd, dim=2)
+        
+        # Remodelage pour l'attention multi-têtes
+        # (batch, seq_len, n_head, head_dim) -> (batch, n_head, seq_len, head_dim)
+        q = q.view(batch_size, seq_len, self.n_head, self.head_dim).transpose(1, 2)
+        k = k.view(batch_size, seq_len, self.n_head, self.head_dim).transpose(1, 2)
+        v = v.view(batch_size, seq_len, self.n_head, self.head_dim).transpose(1, 2)
+        
+        # Attention produit scalaire (Scaled Dot-Product Attention)
+        attn_weights = torch.matmul(q, k.transpose(-2, -1)) / math.sqrt(self.head_dim)
+        
+        # Application du masque causal (le futur est masqué avec -inf)
+        causal_mask = self.bias[:, :, :seq_len, :seq_len]
+        attn_weights = attn_weights.masked_fill(causal_mask == 0, float("-inf"))
+        
+        # Application du masque d'attention (pour le padding)
+        if attention_mask is not None:
+            # attention_mask shape: (batch_size, seq_len) -> (batch_size, 1, 1, seq_len)
+            attention_mask = attention_mask.unsqueeze(1).unsqueeze(2)
+            attn_weights = attn_weights.masked_fill(attention_mask == 0, float("-inf"))
+        
+        attn_weights = F.softmax(attn_weights, dim=-1)
+        attn_weights = self.dropout(attn_weights)
+        
+        # Application de l'attention aux valeurs
+        attn_output = torch.matmul(attn_weights, v)
+        
+        # Remise en forme
+        attn_output = attn_output.transpose(1, 2).contiguous().view(
+            batch_size, seq_len, self.n_embd
+        )
+        
+        # Projection de sortie
+        attn_output = self.c_proj(attn_output)
+        
+        return attn_output
+
+
+class FeedForward(nn.Module):
+    """
+    Réseau de neurones Feed-Forward (MLP).
+    Deux couches linéaires avec une activation GELU entre les deux.
+    """
+    
+    def __init__(self, config: ChessConfig):
+        super().__init__()
+        self.c_fc = nn.Linear(config.n_embd, config.n_inner)
+        self.c_proj = nn.Linear(config.n_inner, config.n_embd)
+        self.dropout = nn.Dropout(config.dropout)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        x = self.c_fc(x)
+        x = F.gelu(x)
+        x = self.c_proj(x)
+        x = self.dropout(x)
+        return x
+
+
+class TransformerBlock(nn.Module):
+    """
+    Un bloc transformer unique contenant Attention et Feed-Forward.
+    Utilise la "Pre-normalization" (LayerNorm avant l'attention/FFN) pour la stabilité.
+    """
+    
+    def __init__(self, config: ChessConfig):
+        super().__init__()
+        self.ln_1 = nn.LayerNorm(config.n_embd, eps=config.layer_norm_epsilon)
+        self.attn = MultiHeadAttention(config)
+        self.ln_2 = nn.LayerNorm(config.n_embd, eps=config.layer_norm_epsilon)
+        self.mlp = FeedForward(config)
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        attention_mask: Optional[torch.Tensor] = None,
+    ) -> torch.Tensor:
+        # Connexion résiduelle + Pre-norm Attention
+        x = x + self.attn(self.ln_1(x), attention_mask=attention_mask)
+        # Connexion résiduelle + Pre-norm FFN
+        x = x + self.mlp(self.ln_2(x))
+        return x
+
+
+# -----------------------------------------------------------------------------
+# Modèle Principal
+# -----------------------------------------------------------------------------
+
+class ChessForCausalLM(PreTrainedModel):
+    """
+    Modèle final pour la prédiction de coups (Causal Language Modeling).
+    
+    Architecture :
+    1. Embeddings (Tokens + Position)
+    2. Empilement de blocs Transformer
+    3. Tête linéaire finale (Projection vers le vocabulaire)
+    """
+    
+    config_class = ChessConfig
+    base_model_prefix = "transformer"
+    supports_gradient_checkpointing = True
+    
+    # Ignore l'avertissement de clé manquante car lm_head partage les poids avec wte
+    keys_to_ignore_on_load_missing = ["lm_head.weight"]
+    
+    def __init__(self, config: ChessConfig):
+        super().__init__(config)
+        
+        # Embeddings
+        self.wte = nn.Embedding(config.vocab_size, config.n_embd)
+        self.wpe = nn.Embedding(config.n_ctx, config.n_embd)
+        
+        self.drop = nn.Dropout(config.dropout)
+        
+        # Blocs Transformer
+        self.h = nn.ModuleList([
+            TransformerBlock(config) for _ in range(config.n_layer)
+        ])
+        
+        # LayerNorm final
+        self.ln_f = nn.LayerNorm(config.n_embd, eps=config.layer_norm_epsilon)
+        
+        # Tête de sortie (sans biais pour économiser des paramètres)
+        self.lm_head = nn.Linear(config.n_embd, config.vocab_size, bias=False)
+        
+        # Gestion du partage de poids (Weight Tying)
+        if config.tie_weights:
+            self._tied_weights_keys = ["lm_head.weight"]
+        
+        # Initialisation des poids
+        self.post_init()
+        
+        # Forcer le lien des poids si configuré
+        if config.tie_weights:
+            self.tie_weights()
+
+    def get_input_embeddings(self) -> nn.Module:
+        return self.wte
+
+    def set_input_embeddings(self, new_embeddings: nn.Module):
+        self.wte = new_embeddings
+        if getattr(self.config, "tie_weights", False):
+            self.tie_weights()
+
+    def get_output_embeddings(self) -> nn.Module:
+        return self.lm_head
+
+    def set_output_embeddings(self, new_embeddings: nn.Module):
+        self.lm_head = new_embeddings
+
+    def tie_weights(self):
+        """Lie les poids de l'embedding d'entrée et de la tête de sortie."""
+        if getattr(self.config, "tie_weights", False) or getattr(self.config, "tie_word_embeddings", False):
+            self._tie_or_clone_weights(self.lm_head, self.wte)
+
+    def _init_weights(self, module: nn.Module):
+        """Initialisation des poids style GPT-2."""
+        if isinstance(module, nn.Linear):
+            torch.nn.init.normal_(module.weight, mean=0.0, std=0.02)
+            if module.bias is not None:
+                torch.nn.init.zeros_(module.bias)
+        elif isinstance(module, nn.Embedding):
+            torch.nn.init.normal_(module.weight, mean=0.0, std=0.02)
+        elif isinstance(module, nn.LayerNorm):
+            torch.nn.init.ones_(module.weight)
+            torch.nn.init.zeros_(module.bias)
+
+    def forward(
+        self,
+        input_ids: torch.LongTensor,
+        attention_mask: Optional[torch.Tensor] = None,
+        position_ids: Optional[torch.LongTensor] = None,
+        labels: Optional[torch.LongTensor] = None,
+        return_dict: Optional[bool] = None,
+        **kwargs,
+    ) -> Union[Tuple, CausalLMOutputWithPast]:
+        """
+        Passe avant (Forward pass).
+        Calcule les logits et, si des étiquettes (labels) sont fournies, la perte (loss).
+        """
+        return_dict = return_dict if return_dict is not None else self.config.use_return_dict
+        
+        batch_size, seq_len = input_ids.size()
+        device = input_ids.device
+        
+        # Création des IDs de position s'ils ne sont pas fournis
+        if position_ids is None:
+            position_ids = torch.arange(seq_len, device=device).unsqueeze(0).expand(batch_size, -1)
+        
+        # Calcul des embeddings (Token + Position)
+        token_embeds = self.wte(input_ids)
+        position_embeds = self.wpe(position_ids)
+        hidden_states = self.drop(token_embeds + position_embeds)
+        
+        # Passage dans les blocs Transformer
+        for block in self.h:
+            hidden_states = block(hidden_states, attention_mask=attention_mask)
+        
+        # Normalisation finale
+        hidden_states = self.ln_f(hidden_states)
+        
+        # Calcul des logits (prédiction du prochain token)
+        logits = self.lm_head(hidden_states)
+        
+        # Calcul de la perte (Training Loss)
+        loss = None
+        if labels is not None:
+            # On décale les logits et les labels d'un cran
+            # (le modèle doit prédire le token t+1 à partir du token t)
+            shift_logits = logits[..., :-1, :].contiguous()
+            shift_labels = labels[..., 1:].contiguous()
+            
+            # Perte CrossEntropy standard
+            loss_fct = nn.CrossEntropyLoss(ignore_index=-100)
+            loss = loss_fct(
+                shift_logits.view(-1, shift_logits.size(-1)),
+                shift_labels.view(-1),
+            )
+        
+        if not return_dict:
+            output = (logits,)
+            return ((loss,) + output) if loss is not None else output
+        
+        return CausalLMOutputWithPast(
+            loss=loss,
+            logits=logits,
+            past_key_values=None,
+            hidden_states=None,
+            attentions=None,
+        )
+
+    @torch.no_grad()
+    def generate_move(
+        self,
+        input_ids: torch.LongTensor,
+        temperature: float = 1.0,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+    ) -> int:
+        """
+        Génère le prochain coup pour une séquence donnée.
+        Utilisé pour l'inférence en jeu réel.
+        """
+        self.eval()
+        
+        # Récupère les logits pour la dernière position uniquement
+        outputs = self(input_ids)
+        logits = outputs.logits[:, -1, :] / temperature
+        
+        # Filtrage Top-K
+        if top_k is not None:
+            indices_to_remove = logits < torch.topk(logits, top_k)[0][..., -1, None]
+            logits[indices_to_remove] = float("-inf")
+        
+        # Filtrage Top-P (Nucleus Sampling)
+        if top_p is not None:
+            sorted_logits, sorted_indices = torch.sort(logits, descending=True)
+            cumulative_probs = torch.cumsum(F.softmax(sorted_logits, dim=-1), dim=-1)
+            
+            # On retire les tokens qui sont au-dessus du seuil cumulatif
+            sorted_indices_to_remove = cumulative_probs > top_p
+            sorted_indices_to_remove[..., 1:] = sorted_indices_to_remove[..., :-1].clone()
+            sorted_indices_to_remove[..., 0] = 0
+            
+            indices_to_remove = sorted_indices_to_remove.scatter(
+                dim=-1, index=sorted_indices, src=sorted_indices_to_remove
+            )
+            logits[indices_to_remove] = float("-inf")
+        
+        # Échantillonnage final
+        probs = F.softmax(logits, dim=-1)
+        next_token = torch.multinomial(probs, num_samples=1)
+        
+        return next_token.item()
+
+# Enregistrement pour chargement automatique via AutoModel
+AutoConfig.register("chess_transformer", ChessConfig)
+AutoModelForCausalLM.register(ChessConfig, ChessForCausalLM)

model.safetensors

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:96e89751fab2b60548bd62e6d1b132137e69909a1ad95b159be791149a048c76
-size 3996400
+oid sha256:9d7fc7fc4cdca06483427cd9d6066888ad27c1d2d21337b6c81ef6d76941f02a
+size 3905600

tokenizer.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+import json
+import os
+import re
+from typing import Dict, List, Optional
+from transformers import PreTrainedTokenizer
+
+class ChessTokenizer(PreTrainedTokenizer):
+    """
+    Tokenizer personnalisé pour le défi 'Chess 1M'.
+    Ce tokenizer découpe les coups d'échecs en cases individuelles (ex: 'e2e4' -> 'e2', 'e4').
+    Cela permet de réduire la taille du vocabulaire à ~72 tokens (cases + promotions).
+    """
+    
+    model_input_names = ["input_ids", "attention_mask"]
+    
+    # Définition des tokens spéciaux
+    PAD_TOKEN = "[PAD]"
+    BOS_TOKEN = "[BOS]"
+    EOS_TOKEN = "[EOS]"
+    UNK_TOKEN = "[UNK]"
+
+    def __init__(
+        self,
+        vocab_file: Optional[str] = None,
+        vocab: Optional[Dict[str, int]] = None,
+        **kwargs,
+    ):
+        # Initialisation des attributs de tokens spéciaux
+        self._pad_token = self.PAD_TOKEN
+        self._bos_token = self.BOS_TOKEN
+        self._eos_token = self.EOS_TOKEN
+        self._unk_token = self.UNK_TOKEN
+
+        # Nettoyage des arguments pour éviter les doublons avec la classe mère
+        for token in ("pad_token", "bos_token", "eos_token", "unk_token"):
+            kwargs.pop(token, None)
+
+        # Regex cruciale : Elle capture soit une case (a1..h8), soit une pièce de promotion (q,r,b,n)
+        self.token_pattern = re.compile(r"[a-h][1-8]|[qrbn]")
+
+        # Chargement du vocabulaire
+        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:
+            # Création par défaut si aucun fichier n'est fourni
+            self._vocab = self._create_default_vocab()
+
+        # Création du dictionnaire inverse (ID -> Token) pour le décodage
+        self._ids_to_tokens = {idx: tok for tok, idx 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_default_vocab(self) -> Dict[str, int]:
+        """
+        Génère le vocabulaire par défaut si 'vocab.json' est absent.
+        Ordre : Tokens spéciaux -> Cases (a1..h8) -> Promotions (q,r,b,n).
+        """
+        special_tokens = [
+            self.PAD_TOKEN,
+            self.BOS_TOKEN,
+            self.EOS_TOKEN,
+            self.UNK_TOKEN,
+        ]
+        vocab = {token: idx for idx, token in enumerate(special_tokens)}
+        idx = len(vocab)
+
+        # Ajout des 64 cases de l'échiquier
+        for file in "abcdefgh":
+            for rank in "12345678":
+                vocab[f"{file}{rank}"] = idx
+                idx += 1
+
+        # Ajout des pièces de promotion (minuscules)
+        for piece in ("q", "r", "b", "n"):
+            vocab[piece] = idx
+            idx += 1
+
+        return vocab
+
+    def _tokenize(self, text: str) -> List[str]:
+        """
+        Découpe une chaîne de coups (PGN brut) en liste de tokens.
+        Exemple : "e2e4 c7c5" -> ["e2", "e4", "c7", "c5"]
+        """
+        text = text.replace("(Q)", "q").replace("(R)", "r").replace("(B)", "b").replace("(N)", "n")
+        return self.token_pattern.findall(text)
+
+    def _convert_token_to_id(self, token: str) -> int:
+        """Transforme un token (str) en son ID (int)."""
+        return self._vocab.get(token, self._vocab[self.UNK_TOKEN])
+
+    def _convert_id_to_token(self, index: int) -> str:
+        """Transforme un ID (int) en son token (str)."""
+        return self._ids_to_tokens.get(index, self.UNK_TOKEN)
+
+    def convert_tokens_to_string(self, tokens: List[str]) -> str:
+        """
+        Reconstruit une chaîne lisible à partir d'une liste de tokens.
+        C'est l'opération inverse de la tokenization.
+        Fusionne ["e2", "e4"] en "e2e4".
+        """
+        special_tokens = {
+            self.PAD_TOKEN,
+            self.BOS_TOKEN,
+            self.EOS_TOKEN,
+            self.UNK_TOKEN,
+        }
+        # On filtre les tokens spéciaux pour ne garder que les coups
+        filtered_tokens = [t for t in tokens if t not in special_tokens]
+        
+        output: List[str] = []
+        for token in filtered_tokens:
+            # Cas 1 : C'est une promotion (ex: 'q'), on l'attache au coup précédent
+            if token in {"q", "r", "b", "n"} and output:
+                output[-1] += token
+            
+            # Cas 2 : C'est une case de destination. 
+            # Si le dernier élément ajouté est une case seule (len==2), on fusionne.
+            # Ex: output=['e2'], token='e4' -> output=['e2e4']
+            elif output and len(output[-1]) == 2 and output[-1][0] in "abcdefgh":
+                output[-1] += token
+            
+            # Cas 3 : C'est une nouvelle case de départ
+            else:
+                output.append(token)
+                
+        return " ".join(output)
+
+    def save_vocabulary(
+        self,
+        save_directory: str,
+        filename_prefix: Optional[str] = None,
+    ) -> tuple:
+        """Sauvegarde le vocabulaire au format JSON."""
+        os.makedirs(save_directory, exist_ok=True)
+        vocab_file = os.path.join(
+            save_directory,
+            f"{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,)
+
+    # Méthodes requises par Hugging Face mais non utilisées ici
+    @classmethod
+    def build_vocab_from_iterator(cls, iterator, min_frequency: int = 1):
+        return cls()
+
+    @classmethod
+    def build_vocab_from_dataset(cls, **kwargs):
+        return cls()
+
+    @property
+    def vocab_size(self) -> int:
+        return len(self._vocab)
+
+    def get_vocab(self) -> Dict[str, int]:
+        return dict(self._vocab)

tokenizer_config.json

@@ -40,5 +40,11 @@
   "model_max_length": 1000000000000000019884624838656,
   "pad_token": "[PAD]",
   "tokenizer_class": "ChessTokenizer",
-  "unk_token": "[UNK]"
-}
+  "unk_token": "[UNK]",
+  "auto_map": {
+    "AutoTokenizer": [
+      "tokenizer.ChessTokenizer",
+      null
+    ]
+  }
+}

training_args.bin

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