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

Model	Format	Size	Use Case
This model	LoRA adapter	~150MB	Training, fine-tuning, MLX
Qwen3-4B-Lichess-Chess-Puzzle-Tutor-Merged	HuggingFace merged	~8GB	Deployment, Spaces, GPU
Qwen3-4B-Chess-Puzzle-Tutor-Fused-MLX	MLX merged	~4GB	Apple Silicon, local inference

🔧 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