Add README and initial implementation for Chess Reasoner app

README.md

@@ -1,6 +1,6 @@
 ---
 title: Chess
-emoji: 🦀
+emoji: ♟️
 colorFrom: purple
 colorTo: gray
 sdk: gradio
@@ -9,6 +9,47 @@ app_file: app.py
 pinned: false
 license: mit
 short_description: Play against chess-playing reasoning LLM
+models:
+  - nuriyev/chess-reasoner
+datasets:
+  - nuriyev/chess-reasoning
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ♔ Chess Reasoner
+
+Play chess against a reasoning LLM! This demo showcases **[nuriyev/chess-reasoner](https://huggingface.co/nuriyev/chess-reasoner)**, a Qwen3-4B model fine-tuned to output structured reasoning before selecting moves.
+
+## 🎮 How to Play
+
+1. **You play as White** - click on pieces to move them
+2. **AI plays as Black** - the model will respond with its move
+3. **View AI Reasoning** - expand the "🧠 AI Reasoning" accordion to see the model's thought process
+4. **AI First** - click this button if you want the AI to play White instead
+
+## 🧠 Model Details
+
+| Attribute | Value |
+|-----------|-------|
+| Base Model | [Qwen/Qwen3-4B-Instruct-2507](https://huggingface.co/Qwen/Qwen3-4B-Instruct-2507) |
+| Training | SFT with LoRA (r=32) on reasoning traces |
+| Dataset | [nuriyev/chess-reasoning](https://huggingface.co/datasets/nuriyev/chess-reasoning) |
+| Output Format | `<think>reasoning</think><uci_move>move</uci_move>` |
+
+## 📋 Output Format
+
+The model outputs structured reasoning:
+```
+<think>The opponent left their queen undefended. Taking it wins material.</think>
+<uci_move>d4d8</uci_move>
+```
+
+## ⚠️ Limitations
+
+This is an **SFT checkpoint** focused on format alignment. The model outputs valid reasoning but hasn't been optimized for chess strength via reinforcement learning yet. A GRPO stage using Stockfish rewards is planned.
+
+## 🔗 Links
+
+- [Model Card](https://huggingface.co/nuriyev/chess-reasoner)
+- [LoRA Adapter](https://huggingface.co/nuriyev/chess-reasoner-lora)
+- [Training Dataset](https://huggingface.co/datasets/nuriyev/chess-reasoning)
+- [Training Code](https://colab.research.google.com/drive/1koRx4Aa8AzA1HGwvEFYll9dWmw0hyVzo)

app.py

@@ -0,0 +1,481 @@
+import re
+import chess
+import gradio as gr
+from jinja2 import Template
+from gradio_chessboard import Chessboard
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+# ============================================================================
+# Model Loading
+# ============================================================================
+
+MODEL_ID = "nuriyev/chess-reasoner"
+
+print("Loading model...")
+tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
+model = AutoModelForCausalLM.from_pretrained(
+    MODEL_ID,
+    torch_dtype=torch.float16,
+    device_map="auto",
+    trust_remote_code=True,
+)
+model.eval()
+print("Model loaded!")
+
+# Custom chat template (matching training)
+CHAT_TEMPLATE = """{%- if messages[0].role == 'system' %}
+    {{- '<|im_start|>system\n' + messages[0].content + '<|im_end|>\n' }}
+{%- endif %}
+{%- for message in messages %}
+    {%- if message.role == 'user' or (message.role == 'system' and not loop.first) %}
+        {{- '<|im_start|>' + message.role + '\n' + message.content + '<|im_end|>\n' }}
+    {%- elif message.role == 'assistant' %}
+        {{- '<|im_start|>assistant\n' + message.content + '<|im_end|>\n' }}
+    {%- endif %}
+{%- endfor %}
+{%- if add_generation_prompt %}
+    {{- '<|im_start|>assistant\n<think>\n' }}
+{%- endif %}"""
+
+tokenizer.chat_template = CHAT_TEMPLATE
+
+# ============================================================================
+# Chess Rendering (matching training exactly)
+# ============================================================================
+
+UNICODE_PIECES = {
+    'P': '♙', 'R': '♖', 'N': '♘', 'B': '♗', 'Q': '♕', 'K': '♔',
+    'p': '♟', 'r': '♜', 'n': '♞', 'b': '♝', 'q': '♛', 'k': '♚',
+}
+
+
+def render_board_unicode(board: chess.Board) -> str:
+    """Render the chess board using Unicode pieces (matching training format)."""
+    lines = []
+    files = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']
+    ranks = ['8', '7', '6', '5', '4', '3', '2', '1']
+
+    coord_parts = [f" {file} " for file in files]
+    coord_line = "   " + "".join(coord_parts) + "  "
+    lines.append(coord_line)
+
+    border_width = len(files) * 3
+    lines.append("   +" + "-" * border_width + "+")
+
+    for rank_idx, rank in enumerate(ranks):
+        line_parts = [f"{rank} |"]
+        for file_idx, file in enumerate(files):
+            square = chess.parse_square(file + rank)
+            piece = board.piece_at(square)
+            piece_char = "·" if piece is None else UNICODE_PIECES[piece.symbol(
+            )]
+            line_parts.append(f" {piece_char} ")
+        line_parts.append(f"| {rank}")
+        lines.append("".join(line_parts))
+
+    lines.append("   +" + "-" * border_width + "+")
+    lines.append(coord_line)
+    return "\n".join(lines)
+
+
+# ============================================================================
+# Prompts (matching training exactly)
+# ============================================================================
+
+SYSTEM_PROMPT = """You are an expert chess player.
+
+Given a current game state, you must select the best next move. Think in 1-2 sentences, then output your chosen move.
+
+Output format:
+<think>brief thinking (2 sentences max)</think>
+<uci_move>your_move</uci_move>"""
+
+USER_PROMPT = Template("""Here is the current game state
+Board (Fen): {{ fen }}
+Turn: It is your turn ({{ turn }})
+Board (Unicode):
+{{ board_utf }}""")
+
+
+# ============================================================================
+# Model Inference
+# ============================================================================
+
+def get_model_move(fen: str) -> tuple[str, str, str]:
+    """Get model's move for the given position. Returns (uci_move, reasoning, raw_output)."""
+    board = chess.Board(fen)
+    turn = "white" if board.turn else "black"
+
+    messages = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": USER_PROMPT.render(
+            fen=fen,
+            board_utf=render_board_unicode(board),
+            turn=turn,
+        )},
+    ]
+
+    text = tokenizer.apply_chat_template(
+        messages,
+        tokenize=False,
+        add_generation_prompt=True,
+    )
+
+    inputs = tokenizer(text, return_tensors="pt").to(model.device)
+
+    with torch.no_grad():
+        outputs = model.generate(
+            **inputs,
+            max_new_tokens=256,
+            temperature=0.7,
+            top_p=0.8,
+            top_k=20,
+            do_sample=True,
+            pad_token_id=tokenizer.pad_token_id,
+        )
+
+    generated = tokenizer.decode(
+        outputs[0][inputs['input_ids'].shape[1]:], skip_special_tokens=False)
+
+    # Parse the output
+    think_match = re.search(r'<think>(.*?)</think>', generated, re.DOTALL)
+    move_match = re.search(r'<uci_move>(.*?)</uci_move>', generated)
+
+    reasoning = think_match.group(1).strip(
+    ) if think_match else "No reasoning provided"
+    uci_move = move_match.group(1).strip() if move_match else None
+
+    # Clean up raw output for display
+    raw_output = generated.split('<|im_end|>')[0].strip()
+
+    return uci_move, reasoning, raw_output
+
+
+# ============================================================================
+# Game State
+# ============================================================================
+
+def create_initial_state():
+    return {
+        "board": chess.Board(),
+        "history": [],
+        "last_reasoning": "",
+        "last_raw_output": "",
+        "game_over": False,
+        "result": "",
+    }
+
+
+# ============================================================================
+# Game Logic
+# ============================================================================
+
+def make_player_move(fen: str, state: dict) -> tuple[str, dict, str, str, str]:
+    """Handle player's move from the chessboard."""
+    if state["game_over"]:
+        return state["board"].fen(), state, get_status(state), state["last_reasoning"], state["last_raw_output"]
+
+    board = chess.Board(fen)
+    state["board"] = board
+    state["history"].append(fen)
+
+    # Check if game is over after player move
+    if board.is_game_over():
+        state["game_over"] = True
+        state["result"] = get_game_result(board)
+        return board.fen(), state, get_status(state), state["last_reasoning"], state["last_raw_output"]
+
+    # AI's turn (Black)
+    if not board.turn:  # Black's turn
+        uci_move, reasoning, raw_output = get_model_move(board.fen())
+        state["last_reasoning"] = reasoning
+        state["last_raw_output"] = raw_output
+
+        if uci_move:
+            try:
+                move = chess.Move.from_uci(uci_move)
+                if move in board.legal_moves:
+                    board.push(move)
+                    state["board"] = board
+                    state["history"].append(board.fen())
+                else:
+                    # Try to find a legal move that starts with the same piece
+                    state["last_reasoning"] = f"Model suggested illegal move: {uci_move}. " + reasoning
+            except:
+                state["last_reasoning"] = f"Model output invalid move format: {uci_move}. " + reasoning
+
+        # Check if game is over after AI move
+        if board.is_game_over():
+            state["game_over"] = True
+            state["result"] = get_game_result(board)
+
+    return board.fen(), state, get_status(state), state["last_reasoning"], state["last_raw_output"]
+
+
+def get_game_result(board: chess.Board) -> str:
+    """Get the game result string."""
+    if board.is_checkmate():
+        winner = "Black" if board.turn else "White"
+        return f"Checkmate! {winner} wins!"
+    elif board.is_stalemate():
+        return "Stalemate! It's a draw."
+    elif board.is_insufficient_material():
+        return "Draw by insufficient material."
+    elif board.is_fifty_moves():
+        return "Draw by fifty-move rule."
+    elif board.is_repetition():
+        return "Draw by repetition."
+    return "Game Over"
+
+
+def get_status(state: dict) -> str:
+    """Get current game status."""
+    if state["game_over"]:
+        return f"🏁 {state['result']}"
+
+    board = state["board"]
+    turn = "White (You)" if board.turn else "Black (AI)"
+
+    status = f"**Turn:** {turn}"
+    if board.is_check():
+        status += " ⚠️ **CHECK!**"
+
+    move_count = len(state["history"])
+    status += f"\n**Move:** {move_count // 2 + 1}"
+
+    return status
+
+
+def new_game() -> tuple[str, dict, str, str, str]:
+    """Start a new game."""
+    state = create_initial_state()
+    return state["board"].fen(), state, get_status(state), "", ""
+
+
+def ai_first_move(state: dict) -> tuple[str, dict, str, str, str]:
+    """Let AI make the first move (play as Black)."""
+    board = state["board"]
+
+    if len(state["history"]) > 0:
+        return board.fen(), state, get_status(state) + "\n⚠️ Game already started!", state["last_reasoning"], state["last_raw_output"]
+
+    uci_move, reasoning, raw_output = get_model_move(board.fen())
+    state["last_reasoning"] = reasoning
+    state["last_raw_output"] = raw_output
+
+    if uci_move:
+        try:
+            move = chess.Move.from_uci(uci_move)
+            if move in board.legal_moves:
+                board.push(move)
+                state["board"] = board
+                state["history"].append(board.fen())
+        except:
+            pass
+
+    return board.fen(), state, get_status(state), reasoning, raw_output
+
+
+# ============================================================================
+# Custom CSS for chess.com-like appearance
+# ============================================================================
+
+CUSTOM_CSS = """
+/* Main container */
+.gradio-container {
+    max-width: 1200px !important;
+    margin: auto !important;
+    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif !important;
+}
+
+/* Header styling */
+.header-title {
+    text-align: center;
+    color: #769656;
+    font-size: 2.5em;
+    font-weight: bold;
+    margin-bottom: 0.2em;
+    text-shadow: 2px 2px 4px rgba(0,0,0,0.1);
+}
+
+.header-subtitle {
+    text-align: center;
+    color: #666;
+    font-size: 1.1em;
+    margin-bottom: 1em;
+}
+
+/* Game panel */
+.game-panel {
+    background: linear-gradient(145deg, #312e2b, #272522);
+    border-radius: 12px;
+    padding: 20px;
+    box-shadow: 0 8px 32px rgba(0,0,0,0.3);
+}
+
+/* Status box */
+.status-box {
+    background: #1a1916;
+    border-radius: 8px;
+    padding: 15px;
+    color: #fff;
+    font-size: 1.1em;
+    border-left: 4px solid #769656;
+}
+
+/* Reasoning box */
+.reasoning-box {
+    background: #262421;
+    border-radius: 8px;
+    padding: 15px;
+    color: #bababa;
+    font-family: 'Courier New', monospace;
+    font-size: 0.95em;
+    max-height: 200px;
+    overflow-y: auto;
+}
+
+/* Buttons */
+.game-button {
+    background: #769656 !important;
+    color: white !important;
+    border: none !important;
+    border-radius: 6px !important;
+    padding: 10px 20px !important;
+    font-weight: bold !important;
+    transition: all 0.2s ease !important;
+}
+
+.game-button:hover {
+    background: #8bac6a !important;
+    transform: translateY(-1px) !important;
+}
+
+.secondary-button {
+    background: #4a4745 !important;
+    color: #bababa !important;
+}
+
+.secondary-button:hover {
+    background: #5a5755 !important;
+}
+
+/* Accordion */
+.reasoning-accordion {
+    background: #1a1916 !important;
+    border: 1px solid #333 !important;
+    border-radius: 8px !important;
+}
+
+/* Footer */
+.footer-text {
+    text-align: center;
+    color: #666;
+    font-size: 0.9em;
+    margin-top: 1em;
+}
+"""
+
+# ============================================================================
+# Gradio Interface
+# ============================================================================
+
+with gr.Blocks(css=CUSTOM_CSS, title="Chess Reasoner", theme=gr.themes.Soft(
+    primary_hue="green",
+    secondary_hue="gray",
+    neutral_hue="gray",
+)) as demo:
+
+    # State
+    game_state = gr.State(create_initial_state)
+
+    # Header
+    gr.HTML("""
+        <div class="header-title">♟️ Chess Reasoner</div>
+        <div class="header-subtitle">Play chess against a reasoning AI • You play as White</div>
+    """)
+
+    with gr.Row():
+        # Left: Chessboard
+        with gr.Column(scale=3):
+            chessboard = Chessboard(
+                value=chess.STARTING_FEN,
+                label="",
+                interactive=True,
+                game_mode=True,
+            )
+
+        # Right: Game controls and info
+        with gr.Column(scale=2):
+            with gr.Group(elem_classes="game-panel"):
+                # Status
+                gr.Markdown("### 📊 Game Status")
+                status_display = gr.Markdown(
+                    value="**Turn:** White (You)\n**Move:** 1",
+                    elem_classes="status-box"
+                )
+
+                gr.Markdown("---")
+
+                # Controls
+                with gr.Row():
+                    new_game_btn = gr.Button(
+                        "🔄 New Game", elem_classes="game-button", size="lg")
+                    ai_first_btn = gr.Button(
+                        "🤖 AI First", elem_classes="secondary-button", size="lg")
+
+                gr.Markdown("---")
+
+                # AI Reasoning (collapsible)
+                with gr.Accordion("🧠 AI Reasoning", open=True, elem_classes="reasoning-accordion"):
+                    reasoning_display = gr.Textbox(
+                        value="",
+                        label="Thinking",
+                        lines=3,
+                        interactive=False,
+                        elem_classes="reasoning-box"
+                    )
+
+                    with gr.Accordion("📝 Raw Output", open=False):
+                        raw_output_display = gr.Textbox(
+                            value="",
+                            label="Model Output",
+                            lines=5,
+                            interactive=False,
+                            elem_classes="reasoning-box"
+                        )
+
+    # Footer
+    gr.HTML("""
+        <div class="footer-text">
+            Model: <a href="https://huggingface.co/nuriyev/chess-reasoner" target="_blank">nuriyev/chess-reasoner</a> 
+            • Fine-tuned from Qwen3-4B-Instruct • SFT Phase 1
+        </div>
+    """)
+
+    # Event handlers
+    chessboard.change(
+        fn=make_player_move,
+        inputs=[chessboard, game_state],
+        outputs=[chessboard, game_state, status_display,
+                 reasoning_display, raw_output_display],
+    )
+
+    new_game_btn.click(
+        fn=new_game,
+        inputs=[],
+        outputs=[chessboard, game_state, status_display,
+                 reasoning_display, raw_output_display],
+    )
+
+    ai_first_btn.click(
+        fn=ai_first_move,
+        inputs=[game_state],
+        outputs=[chessboard, game_state, status_display,
+                 reasoning_display, raw_output_display],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,7 @@
+gradio>=4.0.0
+transformers>=4.56.2
+torch>=2.9.0
+accelerate>=1.12.0
+chess>=1.11.2
+jinja2>=3.1.6
+gradio_chessboard==0.0.10