README.md

---
license: mit
library_name: onnxruntime
tags:
  - chess
  - onnx
  - gan
  - computer-vision
---

# King's Vision — models

ONNX artifacts for [King's Vision](https://github.com/RyanMatthew04/kings-vision):
mate-in-one puzzle generators steered by a Cross-Entropy Method search, and a
board square classifier that reads a chessboard image into a FEN.

Every model runs on `onnxruntime` alone — no TensorFlow, no PyTorch.

```python
from huggingface_hub import hf_hub_download
import onnxruntime as ort

path = hf_hub_download("FlappingChance/kings-vision-models", "queen_mate_generator.onnx")
session = ort.InferenceSession(path)
```

The application fetches these automatically; see `src/kings_vision/artifacts.py`.

---

## mate-type generators and CEM agents

Five DCGAN generators that synthesise chess checkmate positions, each paired with
a multi-modal Cross-Entropy Method agent that steers its latent input.

| | |
|---|---|
| **Version** | 1.0 (weights migrated from the original Keras training run; not retrained) |
| **Format** | ONNX opset 18, float32, single self-contained file |
| **Size** | 20.8 MB per generator · 8.8 KB per CEM agent |
| **Parameters** | 5,193,997 per generator |
| **Licence** | MIT (this repository) |
| **Contact** | https://github.com/RyanMatthew04/kings-vision/issues |

## Intended use

Generating mate-in-one training puzzles for the King's Vision trainer. The
generator produces a *finished* checkmate; `kings_vision.puzzles.backtrack`
reconstructs the position one move earlier and verifies by replaying forward.

**Out of scope.** These models do not play chess, do not evaluate positions, and
have no notion of a game. They sample from a distribution over checkmate-shaped
board states. They are not a substitute for a curated puzzle set such as the
Lichess database, which carries human difficulty ratings these do not.

## Architecture

Generator: 100-d latent → `Dense(32768)` → `Reshape(8, 8, 512)` → four
`Conv2DTranspose` blocks (256 → 128 → 64 → 32, stride 1, `same` padding, kernels
3/3/5/5), each with `LeakyReLU(0.2)` and batch normalisation → `Conv2D(13, k=7)`
→ softmax over the channel axis.

Output is an 8×8×13 tensor: channel 0 is an empty square, 1–6 are white
pawn…king, 7–12 are black. `argmax` per square decodes it to a board. That
encoding is shared with the board classifier — see `kings_vision.core.encoding`.

## Training data

**The training data no longer exists.** The original run derived checkmate
positions from Lichess PGN archives, split them by mating piece into five
datasets, and trained one generator per mate type. Neither the intermediate CSV
nor the extraction script survived into either predecessor repository or its
history.

This is a real limitation and the main reason these weights were migrated rather
than retrained: they are not reproducible from anything in this repository. The
pipeline in `ml/data/` reconstructs the *method*, not the exact dataset.

## Training procedure

Recovered from telemetry embedded in the original notebook
(`docs/data/gan_training_log.csv`):

- 10,000 epochs, batch size 128, Adam
- ≈67 minutes wall clock on CPU
- Discriminator settles at 46–50% accuracy — near chance, the healthy adversarial
  equilibrium — after an unstable first ~800 epochs

The inherited README claimed 200–300 epochs at batch 32 over 2–4 hours. None of
those figures matched the logs.

## The CEM agents

Each agent is five Gaussians over the generator's 100-dimensional input, trained
by Cross-Entropy Method against a binary reward (is this a legal checkmate?) with
a penalty for repeating a position. **The generator's weights are frozen.** Only
the input distribution is optimised, which is why the learned artifact is 8.8 KB
rather than another 20.8 MB.

One shipped agent (queen) has a mode whose weight decayed to 2×10⁻¹⁴ — an
effectively collapsed mode. `MultiModalCEM.collapsed_modes` reports this.

## Evaluation

`python -m ml.eval.eval_gan --n 1000 --seed 0`, Wilson intervals on validity and
bootstrap intervals on uniqueness:

| Mate type | Valid, raw | Valid, + CEM | Δ | Unique, raw | Unique, + CEM | Δ | Puzzle yield |
|---|--:|--:|--:|--:|--:|--:|--:|
| Queen | 47.4% | 88.2% | +40.8 | 100.0% | 50.8% | −49.2 | 83.6% |
| Rook | 62.1% | 77.6% | +15.5 | 100.0% | 73.7% | −26.3 | 73.6% |
| Bishop | 40.8% | 73.6% | +32.8 | 99.3% | 62.6% | −36.6 | 72.5% |
| Knight | 53.4% | 93.9% | +40.5 | 100.0% | 73.1% | −26.9 | 93.7% |
| Pawn | 46.9% | 82.7% | +35.8 | 99.8% | 74.8% | −24.9 | 27.5% |
| **Mean** | **50.1%** | **83.2%** | **+33.1** | **99.8%** | **67.0%** | **−32.8** | **70.2%** |

"Valid" is the fraction of samples that are legal positions in which the side to
move is genuinely checkmated. "Unique" is the distinct fraction among valid
samples. "Puzzle yield" is the fraction of all samples that convert to a
mate-in-one with exactly one solution.

## Limitations and honest caveats

**Diversity is traded for validity, roughly one for one.** Concentrating
probability mass on elite samples is simultaneously what raises the hit rate and
what narrows the output distribution. The diversity-aware reward limits this but
does not remove it. Anyone wanting maximum variety should sample unsteered and
filter, accepting a ~50% rejection rate.

**Validity overstates usefulness for pawn mates.** 82.7% valid but only 27.5%
convert to a unique-solution puzzle, because a pawn has few squares it could have
come from. Judge by puzzle yield, not validity.

**Puzzles are non-capturing mates.** The backtracking construction moves a piece
backwards to an empty square, so mates delivered by a capture are unreachable.
Discovered and promotion mates are reachable.

**No difficulty rating.** These puzzles are not calibrated to human skill. Every
one is mate-in-one, but "mate in one" spans a wide difficulty range and nothing
here estimates where a given puzzle sits.

**Positions are synthetic.** They are legal and reachable-looking, but not drawn
from real games, and some carry the slightly artificial texture of GAN output.

**Numerical fidelity.** The ONNX artifacts agree with the original Keras models
to 100% argmax agreement across fixed-seed reference batches — identical puzzles,
verified by `ml/export/build_onnx_generator.py`. Probability residuals of ~1e−5
are float32 accumulation differences across frameworks.

## Ethical considerations

Low risk. The models generate chess positions. They carry no personal data, and
the training corpus was public game archives. The most plausible harm is a user
being served an artificial-feeling puzzle, which the limitations above cover.


---

## board square classifier

A 13-class CNN that reads one square of a chessboard image. Sixty-four
invocations produce a position.

| | |
|---|---|
| **Version** | 1.0 |
| **Format** | ONNX opset 18, float32, single self-contained file |
| **Size** | ~0.4 MB |
| **Parameters** | 95,373 |
| **Input** | `(N, 3, 32, 32)` uint8-valued float, **0–255** |
| **Output** | `(N, 13)` logits |
| **Licence** | MIT |

Scaling to `[0, 1]` happens *inside* the graph. The serving code passes raw
pixel values and there is no preprocessing contract to get subtly wrong, which
is a common and silent source of train/serve skew.

## Intended use

Turning a screenshot of a chessboard into a FEN, so a position can be analysed
without retyping it. Output is a *placement* only — a picture cannot show whose
move it is, and the API returns the placement field rather than inventing the
rest.

**Out of scope.** Photographs of physical boards (this is trained on rendered
2D boards), boards at an angle, 3D piece sets, and any board that is not
axis-aligned and square in the crop.

## Classes

Channel order is shared with the mate generators — the same 8×8×13 encoding they
emit into. `0` empty, `1–6` white pawn…king, `7–12` black.

## Training data

**Fully synthetic, and that is the interesting part.** No corpus of screenshotted
boards with per-square labels exists, and none is needed: rendering a known
position makes every label exact and free.

`ml/data/render_boards.py` draws positions sampled from random legal playouts —
real piece densities and structures, including near-empty endgames — then
degrades them the way a screenshot is degraded between a website and a file:
rendered at 3× and downsampled so pieces land on fractional pixels, JPEG ringing,
last-move highlights, coordinate labels bleeding into edge squares, blur, and
brightness/contrast drift.

- 4,000 boards / 256,000 squares for training across 6 themes
- 600 boards / 38,400 squares for validation across 2 unseen themes
- 600 boards / 38,400 squares for test across 2 further unseen themes

**Splits are by theme, three ways.** A validation set drawn from the training
themes reports 100% and measures memorisation. One drawn from the test themes
lets epoch selection peek at the reported number. Six themes train, two select,
two are looked at once.

## Training procedure

8 epochs, AdamW with one-cycle scheduling, batch 512, label smoothing 0.02,
~22 minutes on CPU. Best epoch selected on validation board-exact match.

**Colour augmentation is the whole ballgame.** Per-channel gain, channel
permutation, random greyscale, brightness/contrast, and noise — all applied at
batch time. Every one is label-preserving because piece identity in these sprites
is carried by *luminance* (white pieces are light with a dark outline, black the
reverse), never by hue. So hue can be attacked freely, and must be.

## Evaluation

Board-level exact match is the metric that matters. A FEN wrong in one square is
wrong, and per-square accuracy hides that.

| Themes | Per-square | **Board exact** |
|---|--:|--:|
| Seen (training) | 100.0000% | 100.00% |
| Unseen (validation) | 100.0000% | 100.00% |
| **Unseen (test)** | **99.8724%** | **94.50%** |

### The augmentation ablation

`--no-augment` reproduces the failure the augmentation was written to fix:

| | Per-square (test) | **Board exact (test)** |
|---|--:|--:|
| Without augmentation | 96.1745% | **58.83%** |
| With augmentation | 99.8724% | **94.50%** |
| Δ | +3.70 pts | **+35.67 pts** |

Without it the model reached 100.0000% per-square accuracy on the six themes it
trained on and collapsed on an unfamiliar palette. It had learned colour schemes,
not chess pieces.

## Limitations

**94.5%, not 99%.** One board in eighteen is still wrong somewhere on an
unfamiliar theme. The legality repair search recovers some of those, but it can
only fix boards whose errors make the position *illegal* — a bishop misread as a
queen usually leaves a perfectly legal board and passes through silently.

**Evaluated on synthetic themes, not real screenshots.** Unseen renders are a
proxy for transfer, not a measurement of it. A hand-labelled set of real captures
from Lichess and Chess.com would be the honest test and does not exist here.

**Two held-out splits disagreed sharply.** In the ablation the validation themes
scored 99.17% board exact and the test themes 58.83% — same model, same run.
Transfer depends heavily on *which* unfamiliar theme, so 94.50% should be read as
one sample from a wide distribution rather than a guarantee.

**Assumes a square, axis-aligned, tightly-cropped board.** `autocrop` handles
uniform page background and deliberately gives up rather than guess. A skewed or
partially occluded board is out of scope and will fail without saying so.

**Piece sets.** Trained on one sprite set (the Wikipedia pieces) with geometric
and colour augmentation. A visually distinct set — Lichess's `cburnett`,
Chess.com's `neo` — is untested.

## Ethical considerations

Low risk. The model reads chessboards. It processes user-supplied images, which
are held in memory for the duration of a request and not stored; uploads are
capped at 8 MB.


---