README.md

---
license: mit
library_name: pytorch
tags:
- chess
- chess-engine
- stockfish
- imitation-learning
- policy-distillation
- value-network
- uci
- lichess-bot
---

# ChessResNet-30M

**ChessResNet-30M** is a lightweight neural chess engine distilled from Stockfish-labeled positions.

It is designed to be simple to run, easy to plug into `lichess-bot`, and useful as a compact baseline for **search-free neural chess play**.

```text
Model:        30M-parameter policy/value CNN
Training:     Stockfish imitation learning
Dataset:      10M positions
Labels:       depth-10 Stockfish, MultiPV=5
Inference:    no search, no opening book, no tablebase
Interface:    UCI-compatible
```

---

## Links

- **Model:** https://huggingface.co/Joeyfully/chess-stockfish-il-10m-d10-mpv5
- **Dataset:** https://huggingface.co/datasets/Joeyfully/chess-stockfish-il-10m-d10-mpv5
- **Lichess bot:** https://lichess.org/@/Joey_ChessEngine

---

## Model Tags

```text
neural chess engine
Stockfish distillation
imitation learning
policy/value network
search-free chess engine
UCI engine
lichess-bot compatible
PyTorch
```

---

## Performance

ChessResNet is evaluated as a **pure neural engine**:

```text
No alpha-beta search
No MCTS
No opening book
No endgame tablebase
One neural forward pass per move
```

### Offline test set

| Metric | Value |
|---|---:|
| Test positions | 500,000 |
| Stockfish top-1 accuracy | 47.12% |
| Stockfish top-3 accuracy | 77.59% |
| Stockfish top-5 accuracy | 87.78% |
| Value correlation | 0.9401 |
| Test loss | 2.0580 |

### Engine match diagnostics

These are preliminary diagnostics, not official Elo ratings.

| Opponent | Time Control | Games | Score |
|---|---:|---:|---:|
| Stockfish UCI_Elo=1500 | 60+0.6 | 20 | 60.0% |
| Stockfish UCI_Elo=1500 | 10+0.1 | 100 | 70.0% |
| Stockfish UCI_Elo=1800 | 10+0.1 | 100 | 34.0% |

Observed behavior:

```text
Stronger at short time controls
Strong in direct attacks and mating patterns
Weaker in long forcing lines and endgame conversion
```

---

## Quick Start

Install dependencies:

```bash
pip install torch numpy python-chess
```

Run the UCI engine:

```bash
python uci_engine.py --ckpt best_engine.pt --device cpu
```

Manual UCI test:

```text
uci
isready
position startpos
go movetime 1000
quit
```
---

## Use with lichess-bot

ChessResNet can be used directly as a custom UCI engine in `lichess-bot`.

Example layout:

```text
lichess-bot/
  engines/
    ChessResNet/
      joey_engine.sh
      uci_engine.py
      model.py
      common_chess.py
      best_engine.pt
```

Example `joey_engine.sh`:

```bash
#!/usr/bin/env bash
cd "$(dirname "$0")"
export OMP_NUM_THREADS=1
export MKL_NUM_THREADS=1
export OPENBLAS_NUM_THREADS=1
export NUMEXPR_NUM_THREADS=1
export NUMEXPR_MAX_THREADS=1
exec /path/to/python -u uci_engine.py --ckpt best_engine.pt --device cpu
```

Example `config.yml` engine block:

```yaml
engine:
  dir: "./engines/ChessResNet"
  name: "joey_engine.sh"
  debug: false
  working_dir: "./engines/ChessResNet"
  protocol: "uci"
  ponder: false
  uci_options: {}
  silence_stderr: false
```

For pure ChessResNet evaluation, disable external move sources:

```yaml
online_moves:
  chessdb_book:
    enabled: false
  lichess_cloud_analysis:
    enabled: false
  lichess_opening_explorer:
    enabled: false
  online_egtb:
    enabled: false

lichess_bot_tbs:
  syzygy:
    enabled: false
  gaviota:
    enabled: false
```

---

## Citation

```bibtex
@misc{ChessResNet30m2026,
  title        = {ChessResNet-30M: Stockfish Policy/Value Distillation for Search-Free Neural Chess Play},
  author       = {Joey},
  year         = {2026},
  howpublished = {https://huggingface.co/Joeyfully/chess-stockfish-il-10m-d10-mpv5}
}
```