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

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

🌐 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