felixmanojh/Qwen3-4B-Lichess-Chess-Puzzle-Tutor

Qwen3-4B-Lichess-Chess-Puzzle-Tutor

LoRA adapter for chess puzzle explanations 📚

A LoRA adapter fine-tuned on Qwen3-4B-Instruct to generate educational explanations for tactical chess puzzles from the Lichess database.

🎯 Model Overview

• —Base Model: Qwen/Qwen3-4B-Instruct-2507 (4-bit quantized)
• —Adapter Type: LoRA (Low-Rank Adaptation)
• —Training Data: 5,020 high-quality Lichess puzzles with Claude-generated explanations
• —Best Checkpoint: Iteration 3900 (validation loss: 0.596)
• —Framework: MLX (Apple Silicon optimized)

📊 Training Configuration

• —LoRA Rank: 32
• —LoRA Alpha: 64
• —Training Iterations: 6,000 (best @ 3900)
• —Batch Size: 4
• —Learning Rate: 3e-5
• —Optimizer: AdamW with warmup
• —Validation Loss: 0.596 (best checkpoint)

🚀 Quick Start

Installation

pip install mlx mlx-lm transformers

Using with MLX

from mlx_lm import load, generate

# Load base model with adapter
model, tokenizer = load(
    "mlx-community/Qwen3-4B-Instruct-2507-4bit",
    adapter_path="felixmanojh/Qwen3-4B-Lichess-Chess-Puzzle-Tutor"
)

# Example puzzle
prompt = """Explain this chess puzzle:

Position (FEN): r1bqkb1r/pppp1ppp/2n2n2/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R w KQkq - 4 4
Solution: Nxe5 Nxe5 d4
Themes: fork pin
Rating: 1500"""

# Generate explanation
messages = [{"role": "user", "content": prompt}]
formatted_prompt = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True
)

response = generate(
    model,
    tokenizer,
    prompt=formatted_prompt,
    max_tokens=512,
    verbose=False
)

print(response)

Using with Transformers + PEFT

from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

# Load base model
base_model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-4B-Instruct-2507",
    torch_dtype=torch.float16,
    device_map="auto"
)

# Load adapter
model = PeftModel.from_pretrained(
    base_model,
    "felixmanojh/Qwen3-4B-Lichess-Chess-Puzzle-Tutor"
)

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-4B-Instruct-2507")

# Generate as usual...

💡 Why Use the Adapter?

✅ Small size — ~150MB vs 8GB for merged model ✅ Training flexibility — Continue fine-tuning or merge with other adapters ✅ MLX optimized — Fast training and inference on Apple Silicon ✅ Version control — Easy to experiment with different checkpoints

📚 Training Data

Data Source

• —Puzzles: Lichess puzzle database (CC0 1.0 Universal)
• —Explanations: Generated using Claude API (Anthropic)
• —Size: 5,020 training + 502 validation puzzles

Data Quality

Puzzles filtered for:

• —Popularity ≥ 90th percentile
• —Rating deviation ≤ 80 (consistent difficulty)
• —Minimum plays ≥ 500
• —Balanced across tactical themes (fork, pin, skewer, discovered attack, mate patterns, sacrifice, deflection, etc.)

Explanations generated using Claude API with consistent prompting for educational quality, focusing on:

• —Clear explanation of the tactical pattern
• —Step-by-step move analysis
• —Why alternatives don't work
• —Key learning points

Coverage

• —Rating Range: 1000-2500
• —Themes: 20+ tactical patterns
• —Format: FEN position + UCI solution + themes + rating → educational explanation

📈 Performance Metrics

• —Best Validation Loss: 0.596 (iteration 3900)
• —Average Explanation Length: 659 characters (107 words)
• —Completeness: 96% (48/50 test puzzles)
• —Zero truncations or hallucinations

🎓 Intended Use

✅ Recommended

• —Educational chess puzzle explanations
• —Learning tactical patterns
• —Automated puzzle commentary
• —Chess training applications
• —Interactive chess tutoring systems
• —Fine-tuning base for further specialization

❌ Not Recommended

• —Full game analysis (puzzle-focused only)
• —Opening theory (not in training data)
• —Endgame tablebase analysis
• —Chess engine evaluation (explanation model, not engine)

🔄 Model Variants

🔧 GGUF Conversion

Step 1: Merge the LoRA Adapter

pip install mlx mlx-lm

mlx_lm.fuse \
  --model mlx-community/Qwen3-4B-Instruct-2507-4bit \
  --adapter-path felixmanojh/Qwen3-4B-Lichess-Chess-Puzzle-Tutor \
  --save-path ./merged-chess-tutor \
  --dequantize

Step 2: Convert to GGUF

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
pip install -r requirements.txt

python convert_hf_to_gguf.py ../merged-chess-tutor \
  --outtype f16 \
  --outfile chess-tutor-f16.gguf

# Optional: Quantize further
./llama-quantize chess-tutor-f16.gguf chess-tutor-q4_k_m.gguf Q4_K_M

🌐 Live Demo

Try it live: Chess Puzzle Tutor Space

📝 Citation

@software{qwen3_chess_tutor_2025,
  author = {Felix Manojh},
  title = {Qwen3-4B-Lichess-Chess-Puzzle-Tutor},
  year = {2025},
  url = {https://huggingface.co/felixmanojh/Qwen3-4B-Lichess-Chess-Puzzle-Tutor},
  note = {LoRA adapter fine-tuned on Lichess puzzle database with Claude-generated explanations}
}

📄 License

• —Model: Apache 2.0
• —Puzzle Data: Lichess puzzle database (CC0 1.0 Universal)
• —Explanations: Generated using Claude API for training purposes

🙏 Acknowledgments

• —Lichess for the comprehensive puzzle database
• —Anthropic for Claude API used to generate training explanations
• —Qwen Team for the excellent Qwen3-4B base model
• —Apple MLX Team for the MLX framework

Built by Felix Manojh | Interactive Demo