README.md

---
license: apache-2.0
base_model: Qwen/Qwen3-4B-Instruct-2507
library_name: transformers
pipeline_tag: text-generation
language:
- en
tags:
- chess
- reasoning
- chess-puzzles
- qwen3
- reinforcement-learning
- dapo
---

# C1: Grounded Chess Reasoning in Language Models via Master Distillation

[![Code](https://img.shields.io/badge/Code-GitHub-181717?logo=github)](https://github.com/CSSLab/C1) [![arXiv](https://img.shields.io/badge/arXiv-2603.20510-b31b1b?logo=arxiv)](https://arxiv.org/abs/2603.20510) [![Hugging Face](https://img.shields.io/badge/HuggingFace-Dataset-yellow?link=https://huggingface.co/datasets/UofTCSSLab/C1-data)](https://huggingface.co/datasets/UofTCSSLab/C1-data)

The **final (SFT + RL)** model of **C1**. Given a chess position,
the model reasons step by step in natural language and ends with a single best
move in UCI notation.

This is the **final (SFT + RL) model**. The SFT-stage checkpoint is
[`UofTCSSLab/C1-SFT-4B`](https://huggingface.co/UofTCSSLab/C1-SFT-4B).

## Results

900-puzzle test set, greedy pass@1, `FINAL_ANSWER` exact-match UCI:

| stage | accuracy |
|---|---|
| SFT (base for RL) | 42.3% |
| **RL (this model)** | **48.3%** |

Average response length ~169 tokens.

## Usage

The prompt gives the FEN, piece positions, and legal moves, then asks for a
step-by-step analysis ending in `FINAL_ANSWER: <uci_move>`. **Greedy decoding
(temperature 0) is recommended**.

```python
# pip install chess
import chess

def build_prompt(fen: str) -> str:
    board = chess.Board(fen)
    names = {1: "Pawn", 2: "Knight", 3: "Bishop", 4: "Rook", 5: "Queen", 6: "King"}
    pieces = {}
    for sq in chess.SQUARES:
        p = board.piece_at(sq)
        if p:
            key = f"{'White' if p.color else 'Black'} {names[p.piece_type]}"
            pieces.setdefault(key, []).append(chess.square_name(sq))
    order = [f"{c} {t}" for c in ("White", "Black")
             for t in ("King", "Queen", "Rook", "Bishop", "Knight", "Pawn")]
    arrangement = ", ".join(f"{k}: {sorted(pieces[k])}" for k in order if k in pieces)
    legal = ", ".join(m.uci() for m in board.legal_moves)
    return (
        f"You are given a chess position in FEN: {fen}.\n"
        f"Piece positions: {arrangement}\n"
        f"Legal moves: {legal}\n"
        "Find the best move for the side to play.\n"
        "Analyze step by step and explain your reasoning.\n"
        "Finish with a single line formatted EXACTLY as:\n"
        "FINAL_ANSWER: <answer>\n"
        "Use UCI notation (e.g., e2e4, c2b1q) for the final answer."
    )

MODEL_ID = "UofTCSSLab/C1-4B"
FEN = "2kr3r/ppp2Npp/2nbp3/6N1/2PP2n1/4B2q/PP2BP2/R2Q1RK1 b - - 2 15"
messages = [{"role": "user", "content": build_prompt(FEN)}]
```

### Transformers

```python
# pip install transformers torch
from transformers import AutoModelForCausalLM, AutoTokenizer

tok = AutoTokenizer.from_pretrained(MODEL_ID)
model = AutoModelForCausalLM.from_pretrained(MODEL_ID, torch_dtype="bfloat16", device_map="auto")

ids = tok.apply_chat_template(messages, add_generation_prompt=True, return_tensors="pt").to(model.device)
out = model.generate(ids, max_new_tokens=1024, do_sample=False)  # greedy
print(tok.decode(out[0, ids.shape[-1]:], skip_special_tokens=True))
# ... step-by-step reasoning ...
# FINAL_ANSWER: h3h2
```

### vLLM

```python
# pip install vllm
from vllm import LLM, SamplingParams

llm = LLM(model=MODEL_ID, dtype="bfloat16")
sampling = SamplingParams(temperature=0.0, max_tokens=1024)  # greedy
out = llm.chat(messages, sampling_params=sampling)
print(out[0].outputs[0].text)
# ... step-by-step reasoning ...
# FINAL_ANSWER: h3h2
```

## Citation

```bibtex
@article{tang2026grounded,
  title={Grounded Chess Reasoning in Language Models via Master Distillation},
  author={Tang, Zhenwei and Wen, Qianfeng and Grief-Albert, Seth and Elgabra, Yahya and Yang, Blair and Dong, Honghua and Anderson, Ashton},
  journal={arXiv preprint arXiv:2603.20510},
  year={2026}
}
```