InterwebAlchemy/pgn-lichess-puzzle-dataset

---
license: cc0-1.0
language:
- en
tags:
- chess
- pgn
- puzzles
- tactics
pretty_name: Chess Puzzles with PGN Context
size_categories:
- 1K<n<10K
---

# Chess Puzzles with PGN Context

Tactical chess puzzles drawn from the [Lichess Open Puzzle Database](https://database.lichess.org/#puzzles),
augmented with full PGN game context reconstructed from the source Lichess games.

Each record presents a middlegame position as a PGN move sequence — the same format used
to train PGN language models like [kn1ght](https://github.com/InterwebAlchemy/kn1ght) — together
with the engine-validated best move as the label.

## Dataset Summary

- **5,000 puzzles** with reconstructed PGN context
- Rating range: 1200–1900 (mean: 1540)
- Themes: `middlegame`, `short`, `advantage`, `crushing`, `long`, `mate`, `fork`, `kingsideAttack` (middlegame only; opening/endgame excluded)
- Splits: 80% train / 10% validation / 10% test

## Schema

| Column | Type | Description |
|---|---|---|
| `puzzle_id` | string | Lichess puzzle ID |
| `game_id` | string | Lichess game ID (source of PGN context) |
| `rating` | int32 | Puzzle difficulty (Lichess Glicko-2 rating) |
| `themes` | list[string] | Tactical theme tags (e.g. `fork`, `pin`, `skewer`) |
| `pgn_context` | string | PGN move text up to (not including) the puzzle move |
| `fen` | string | Board position at start of puzzle in FEN notation |
| `best_move_uci` | string | Correct first move in UCI notation |
| `best_move_san` | string | Correct first move in SAN notation |

## Usage

```python
from datasets import load_dataset

ds = load_dataset("InterwebAlchemy/chess-puzzles-pgn")

# Each example:
# {'pgn_context': '1.e4 e5 2.Nf3 Nc6 ... 18.Rxd4',
# 'best_move_san': 'Nf6+',
# 'rating': 1487,
# 'themes': ['fork', 'middlegame']}
```

## How PGN context is reconstructed

For each Lichess puzzle:
1. The source game PGN is fetched from `lichess.org/api/game/<id>`
2. The game is replayed move by move until the board FEN matches the puzzle FEN
3. The move-text up to that point is stored as `pgn_context`
4. The first solution move (UCI → SAN) is stored as `best_move_san`

Puzzles where the FEN could not be located in the source game are discarded.

## Intended use

Evaluating and fine-tuning PGN language models on tactical positions. The `pgn_context`
field can be fed directly to any model that generates chess moves as PGN continuations.

## Licensing

This dataset is derived from the [Lichess Open Database](https://database.lichess.org/),
which is released under [CC0 1.0 (Public Domain)](https://creativecommons.org/publicdomain/zero/1.0/).
This derived dataset is also released under CC0 1.0.

---
许可证：CC0 1.0
语言：
- 英语
标签：
- 国际象棋
- PGN（可移植对局格式，Portable Game Notation）
- 谜题
- 战术
友好展示名称：带PGN上下文的国际象棋谜题
样本量区间：
- 1000 < 样本数 < 10000
---

# 带PGN上下文的国际象棋谜题

本数据集的战术国际象棋谜题源自[Lichess公开谜题数据库](https://database.lichess.org/#puzzles)，并补充了从原始Lichess对局中重构的完整PGN上下文。每条数据以PGN走棋序列的形式呈现一个中局局面，该格式与训练[kn1ght](https://github.com/InterwebAlchemy/kn1ght)等PGN大语言模型所用的格式一致，并附带经引擎验证的最优走法作为标签。

## 数据集概览
- **共5000道谜题**，附带重构的PGN上下文
- 难度评级区间：1200–1900（平均分为1540）
- 战术主题：`中局（middlegame）`、`短对局（short）`、`优势局面（advantage）`、`碾压式优势（crushing）`、`长对局（long）`、`将死（mate）`、`捉双（fork）`、`王翼进攻（kingsideAttack）`（仅包含中局主题，排除开局与残局）
- 数据集划分：80%训练集、10%验证集、10%测试集

## 数据结构
| 列名 | 数据类型 | 描述 |
|---|---|---|
| `puzzle_id` | 字符串 | Lichess谜题ID |
| `game_id` | 字符串 | 原始对局的Lichess对局ID（用于生成PGN上下文） |
| `rating` | int32 | 谜题难度（采用Lichess Glicko-2评级体系） |
| `themes` | 字符串列表 | 战术主题标签（例如`捉双（fork）`、`牵制（pin）`、`闪击（skewer）`等） |
| `pgn_context` | 字符串 | 谜题走法之前的所有PGN走棋文本（不包含谜题走法本身） |
| `fen` | 字符串 | 谜题开始时的棋盘局面，采用FEN（Forsyth-Edwards Notation）记法 |
| `best_move_uci` | 字符串 | 正确的首步走法，采用UCI（通用象棋接口，Universal Chess Interface）记法 |
| `best_move_san` | 字符串 | 正确的首步走法，采用SAN（标准代数记法，Standard Algebraic Notation）记法 |

## 使用示例
python
from datasets import load_dataset

ds = load_dataset("InterwebAlchemy/chess-puzzles-pgn")

# 每条数据示例：
# {'pgn_context': '1.e4 e5 2.Nf3 Nc6 ... 18.Rxd4',
# 'best_move_san': 'Nf6+',
# 'rating': 1487,
# 'themes': ['捉双（fork）', '中局（middlegame）']}

## PGN上下文重构流程
针对每一道Lichess谜题：
1. 从`lichess.org/api/game/<id>`接口获取原始对局的PGN数据
2. 逐手复盘对局，直到棋盘FEN记法与谜题的FEN记法匹配
3. 将截至该位置的走棋文本存储为`pgn_context`字段
4. 将首步解法（从UCI记法转换为SAN记法）存储为`best_move_san`字段

无法在原始对局中匹配到对应FEN记法的谜题将被剔除。

## 预期用途
用于在战术局面下评估与微调PGN大语言模型。`pgn_context`字段可直接输入至任何以PGN续招作为输出的模型。

## 许可证
本数据集源自[Lichess公开数据库](https://database.lichess.org/)，该数据库采用[CC0 1.0（公共领域）](https://creativecommons.org/publicdomain/zero/1.0/)许可证发布。本衍生数据集同样采用CC0 1.0许可证发布。