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

A merged chess puzzle explanation model — ready to use without adapters!

This is a fully merged version of Qwen3-4B-Lichess-Chess-Puzzle-Tutor, with the LoRA adapter weights fused directly into the base model. No need for PEFT or adapter loading — just load and go!

🎯 Model Overview

• Base Model: Qwen/Qwen3-4B-Instruct-2507
• Fine-tuning: LoRA adapter trained on 5,020 Lichess puzzles
• Format: Merged (base + adapter fused)
• Best Checkpoint: Iteration 3900 (validation loss: 0.596)
• Framework: Compatible with transformers, MLX, llama.cpp

📊 Training Details

• Training Data: 5,020 high-quality Lichess chess puzzles with Claude-generated explanations
• LoRA Config: rank=32, alpha=64
• Training Iterations: 6,000 (best @ 3900)
• Batch Size: 4
• Learning Rate: 3e-5
• Quality Metrics: 96% completeness, avg 659 chars/explanation

🚀 Quick Start

Using Transformers

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "felixmanojh/Qwen3-4B-Lichess-Chess-Puzzle-Tutor-Merged"

# Load model and tokenizer
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.float16,
    device_map="auto",
    trust_remote_code=True
)

# Example puzzle
puzzle = """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": puzzle}]
text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True
)

inputs = tokenizer(text, return_tensors="pt").to(model.device)
outputs = model.generate(
    **inputs,
    max_new_tokens=512,
    temperature=0.7,
    top_p=0.9,
    do_sample=True
)

response = tokenizer.decode(outputs[0][inputs['input_ids'].shape[1]:], skip_special_tokens=True)
print(response)

Using MLX (Apple Silicon)

from mlx_lm import load, generate

# Note: This merged model is in HuggingFace format
# For MLX, use the MLX-format version or the original adapter

model, tokenizer = load("felixmanojh/Qwen3-4B-Lichess-Chess-Puzzle-Tutor-Merged")

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"""

response = generate(model, tokenizer, prompt=prompt, max_tokens=512)
print(response)

💡 Why Use the Merged Version?

✅ Simpler deployment — No adapter loading, no PEFT dependencies
✅ Faster startup — Single model file, no merging at runtime
✅ Gradio/Spaces friendly — Works with standard transformers
✅ GGUF conversion — Easier conversion for llama.cpp

📚 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

🎓 Intended Use

✅ Recommended

• Educational chess puzzle explanations
• Learning tactical patterns
• Automated puzzle commentary
• Interactive chess tutoring systems

❌ Not Recommended

• Full game analysis (puzzle-focused only)
• Opening theory (not in training data)
• Endgame tablebase analysis

🔄 Differences from Base Adapter Model

Feature	Adapter Version	Merged Version (this)
Format	LoRA adapter only	Full model (base + adapter)
Size	~150MB	~8GB
Loading	Requires base + PEFT	Direct transformers load
Use Case	MLX, custom training	Deployment, Spaces, inference

🌐 Live Demo

Try it live: Chess Puzzle Tutor Space

📝 Citation

@software{qwen3_chess_tutor_merged_2025,
  author = {Felix Manojh},
  title = {Qwen3-4B-Lichess-Chess-Puzzle-Tutor-Merged},
  year = {2025},
  url = {https://huggingface.co/felixmanojh/Qwen3-4B-Lichess-Chess-Puzzle-Tutor-Merged},
  note = {Merged model 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

---

Related Models:

• Qwen3-4B-Lichess-Chess-Puzzle-Tutor - LoRA adapter version
• Qwen3-4B-Chess-Puzzle-Tutor-Fused-MLX - MLX format