README.md

---
license: cc-by-nc-4.0
language:
  - en
tags:
  - chess
  - connectome
  - drosophila
  - flywire
  - neuroscience
  - recurrent-neural-network
  - reinforcement-learning
  - pytorch
library_name: flychess
pipeline_tag: reinforcement-learning
---

# fly-chess brains

Chess-playing neural networks whose wiring **is** the FlyWire adult *Drosophila melanogaster* connectome:
134,209 neurons, 2,700,513 neuron-to-neuron connections (34.2 M synapses), every synapse's sign fixed by the
presynaptic neuron's neurotransmitter (acetylcholine excitatory; GABA and glutamate inhibitory). Training
learns only synaptic strength magnitudes, per-neuron biases / leaks / gains, and the board-input and
move-readout projections — no connection is added, removed or re-signed.

Code, training pipeline and the website that runs these brains in the browser:
**https://github.com/cesp99/fly-chess** (MIT).

## Model description

The network is a recurrent rate model on the connectome: `h_t+1 = (1-a) h_t + a · f(W h_t + bias + input)`,
`W` sparse with the connectome's pattern and signs, unrolled 8 or 16 timesteps per position. The board
(20 planes × 64 squares, always from the side to move) enters through learned projections into sensory
neurons; the move policy (4,168 logits) and value are linear/MLP read-outs of the descending and motor
neurons. `fly3` additionally lets the fly **see** the board: 5,543 real photoreceptors (R1–6, R7, R8,
placed on their ommatidial columns; left eye files a–d, right eye e–h) each receive one square, and the
signal travels through the real lamina → medulla → lobula → central brain wiring. Details:
`docs/SPEC.md` and `docs/RETINA.md` in the code repository.

## Files

| file | step | stage | size | notes |
|---|---|---|---|---|
| `checkpoints/fly1-imitation.pt` | 110,767 | imitation | 69 MB | random +191, material +70 |
| `checkpoints/fly2-imitation.pt` | 280,000 | imitation | 69 MB | random +338, material +70 |
| `checkpoints/fly3-imitation.pt` | 260,000 | imitation | 114 MB | random +338, material +241 |
| `checkpoints/fly3-selfplay.pt` | 264,000 | selfplay | 114 MB | random +636, material +241, previous-best +61 |
| `graph/full.npz` | — | — | 37 MB | the BrainGraph (CSR connectome, signs, retina mapping) every checkpoint needs |
| `web/brain.json`, `web/brain.flyb`, `web/brain.flyb.gz` | — | — | 60 / 50 MB | browser blob of `fly3-selfplay` (SPEC §8 format; the website loads it from here) |

Each `checkpoints/<name>.json` holds the exact training configuration and evaluation numbers of that
checkpoint; `manifest.json` lists sizes and sha256 for every file.

## Generations

| run | recipe | held-out top-1 / top-3 (same 5,120 human positions) |
|---|---|---|
| `fly1-imitation` | 8 timesteps, ReLU, board via 2,048 sensory/ascending neurons, Lichess 2014 | 34.1% / 58.4% |
| `fly2-imitation` | 16 timesteps, saturating rates, Lichess 2014+2015, fp32 | 33.1% / 57.2% |
| `fly3-imitation` | fly2 + retina input, homeostatic gains, multi-timestep readout, neuromodulatory gating, central-brain readout, + 30 M Stockfish-evaluated positions | 36.9% / 62.3% |
| **`fly3-selfplay`** | fly3-imitation + gated self-play (5 of 9 iterations promoted) | **37.6% / 63.4%** |

Head-to-head with 100-simulation MCTS over 100 games on 50 paired openings: `fly3-selfplay` vs `fly1`
**+50 =50 −0**, vs `fly2` **+100 =0 −0**; vs its own imitation checkpoint (200 sims, 20 games) 20–0; vs a
1-ply material-greedy bot +38 =2 −0 with search and +16 =4 −0 without. It is a beatable club-level-ish
opponent without search and a real fight with it; it is not an engine.

## Use

```bash
pip install git+https://github.com/cesp99/fly-chess
hf download cesp99/fly-chess --local-dir fly-chess-models
```

```python
import torch, chess
from flychess.connectome.graph import BrainGraph
from flychess.model.config import BrainConfig
from flychess.model.flybrain import FlyBrain
from flychess.play.engine import FlyEngine

ck = torch.load("fly-chess-models/checkpoints/fly3-selfplay.pt", map_location="cpu", weights_only=False)
graph = BrainGraph.load("fly-chess-models/graph/full.npz")
model = FlyBrain.from_checkpoint(ck["model"], BrainConfig.from_dict(ck["brain_config"]), graph).eval()
engine = FlyEngine(model, graph, device="cpu")          # "cuda" if available
move, info = engine.choose_move(chess.Board(), difficulty="fly")   # larva | fly | superfly (MCTS)
print(move, info["policy_top"], info["value"])
```

Or with the CLI from the code repository: `fly play --ckpt fly-chess-models/checkpoints/fly3-selfplay.pt --gui`.

## Training data

* Lichess monthly databases 2014-01 … 2015-12 (CC0): rated standard games, both players ≥ 1800 Elo, not
  bullet; 229 M positions (policy target = the human move, value target = the game result).
* Lichess evaluation database: 30 M positions with Stockfish evaluations (policy target = engine best move,
  value target = win probability from the centipawn score); used for `fly3`.
* Self-play games of the network itself (gated, with human/engine positions rehearsed in every batch).

## Limitations

A fixed random-for-chess topology with sign constraints is a poor chess architecture: the brains play
plausible openings and positional chess and still miss tactics; value estimates are weak without search.
The rate model is a caricature of real neural dynamics (no spikes, gap junctions, dendrites or real
neuromodulation). Input/output neuron choices are modelling decisions, not biology.

## Licence and attribution

The FlyWire Codex data release the weights derive from is **CC BY-NC 4.0**, so the weights are published
under **CC BY-NC 4.0** (`LICENSE`): non-commercial use only, with attribution. See `ATTRIBUTION.md` for the
full list of sources and citations. Training code: MIT.

## Citation

```bibtex
@misc{flychess2026,
  title  = {fly-chess: a chess engine wired like the FlyWire fruit-fly connectome},
  author = {Esposito, Carlo},
  year   = {2026},
  url    = {https://github.com/cesp99/fly-chess}
}
```
Please also cite the connectome papers listed in `ATTRIBUTION.md`.