# Fly vs Fly

Two agents based on a fruit-fly brain connectome play a complete game of freestyle
Gomoku on a 15×15 board. Each player uses the fixed **138,639-neuron FlyWire v783
spiking model**, with a separately trained output interface. Training combines
supervised coaching with **reinforcement learning using PPO**.

The recorded match ends in a legitimate **37-move victory by Fly B**. Both
anatomical brain views display neural activity recorded during the actual move
calculations. The browser replays this authenticated recording; Python reproduces
inference, training, evaluation, and new recorded games.

![Two anatomical flies and the actual neural activity behind their Gomoku moves](docs/images/demo.png)

[40-second match video](https://github.com/grishahq/fly-vs-fly/releases/download/v1.0.0/fly-vs-fly-short.mp4)
· [Full match video](https://github.com/grishahq/fly-vs-fly/releases/download/v1.0.0/fly-vs-fly-full.mp4)
· [Downloads](https://github.com/grishahq/fly-vs-fly/releases/tag/v1.0.0)

## Run the recorded demo

Requires **Node.js 22.13+ and Python 3.10+**. Python is used only to download and
verify the release assets for browser playback; model execution uses Python 3.12.

```sh
git clone https://github.com/grishahq/fly-vs-fly.git
cd fly-vs-fly
python3 tools/download_demo_assets.py
./launch_demo.sh
```

Open the local URL printed by the server. The viewer provides play/pause,
restart, timeline, playback speed, camera selection, and a move list. No API key,
Codex installation, or hosted service is required.

The versioned asset archive contains anatomical meshes and coordinates,
procedural motion tracks, and all eight games in the declared recorded batch.
The downloader checks the archive and every file against `release-assets.json`.
Videos are separate release downloads. Large research inputs are fetched from
pinned upstream sources when reproducing the Python experiments.

## What the connectome does

```mermaid
flowchart LR
    A[Board occupancy] --> B[Fixed input encoder]
    B --> C[Full fixed spiking connectome]
    C --> D[Measured neural activity]
    D --> E[Trained output interface]
    E --> F[Legal move scores]
    F --> G[Selected move and recorded replay]
```

- The engineered encoder converts occupied points into pulses in 450 fixed
  anatomical input neurons. The full neural model runs for 12 ms per decision.
- A trained decoder and policy/value heads consume measured downstream neural
  state and spike counts. The occupied-cell mask prevents illegal placements.
- Internal anatomical connectivity remains fixed. Supervised learning and PPO
  train the output interfaces; gradients do not pass through the brain model.
- Training teachers and evaluation opponents do not select or repair the
  displayed agents' moves. The delivered agents select their learned argmax.
- Walking and tapping are **procedural animation**, separate from move selection.
  The rendered body is not controlled by a biological motor policy.

The input translator and spatial output architecture are engineered interfaces.
This is an experiment using a connectome model, rather than evidence that a
living fly understands Gomoku or that biological wiring is superior to a random
network. The dataset is the earlier **female FlyWire brain**, not MaleCNS.

## Measured gameplay

| Held-out test | Fly A | Fly B |
| --- | ---: | ---: |
| Immediate winning moves | 200/200 | 199/200 |
| Single-threat defenses | 199/200 | 199/200 |
| Short tactical positions | 97/100 | 97/100 |
| Games against a random opponent | 100/100 wins | 100/100 wins |
| Games against the frozen heuristic | 100/100 wins | 75/100 wins |
| Illegal actions | 0 | 0 |

Each game suite contains 50 games per color. The random suites contain 100
distinct games per player, while the fixed heuristic suites contain only six
distinct trajectories per player. These results certify the specified demo
criteria, with limited opening diversity; they do not establish expert play.

Supervised coaching supplied most tactical competence. In the same-seed
within-protocol comparison, PPO improved Fly A's heuristic result from 76/100
to 100/100 wins; Fly B's aggregate result remained 80/100. See
[model card](docs/MODEL_CARD.md), [evaluation protocol](docs/EVALUATION_PROTOCOL.md),
and `reports/policy_final_summary.json` for evidence and limitations.

## Reproduce Python inference and evaluation

Requires Python 3.12 and `uv`. The full graph is stored sparsely. CPU/MPS
placement was selected from measurements on an M3 Pro with 18 GB of memory:
CPU for neural simulation and single-move inference, MPS for batched head training.
Other hardware may have different performance.

```sh
uv venv --python 3.12 .venv
uv pip sync --python .venv/bin/python requirements.lock
.venv/bin/python tools/fetch_connectome.py
.venv/bin/python -m pytest -q

.venv/bin/python tools/evaluate_policy.py checkpoints/fly_a_final.pt \
  --other-checkpoint checkpoints/fly_b_final.pt --split final_sealed \
  --games 100 --seed 41111001 --name public_fly_a_reproduction
.venv/bin/python tools/evaluate_policy.py checkpoints/fly_b_final.pt \
  --other-checkpoint checkpoints/fly_a_final.pt --split final_sealed \
  --games 100 --seed 41112001 --name public_fly_b_reproduction
.venv/bin/python tools/record_match.py \
  --verify artifacts/matches/final_batch_01/game_001
```

Both final checkpoints, their ancestry, resumable training states, the exact
encoder, and training/held-out position sets are included. The download restores
the encoding probe used in training. Feature caches are generated from actual
neural executions. Exact training commands, resume cautions, and historical
checkpoint hashes are in `reports/policy_reproducible_commands.json`.

The final held-out labels are public for reproduction. Do not tune new policies
on those labels and present the result as a fresh held-out evaluation.

## Rebuild anatomy and render videos

The release already includes the viewer assets. To rebuild them from the pinned
research sources, install the Python environment above, then run:

```sh
.venv/bin/python tools/prepare_anatomy.py --download
.venv/bin/python tools/prepare_gait.py
.venv/bin/python tools/merge_choreography.py
.venv/bin/python tools/sync_demo_assets.py
```

For deterministic offline rendering, start the viewer, then:

```sh
cd demo
npx playwright install chromium
node scripts/render.mjs --url=http://localhost:3000/ \
  --output=../artifacts/fly-vs-fly-full.mp4 --fps=60 --width=1920 --height=1080
```

Use the actual port printed by the server. `ffmpeg` must be on PATH.
[Playback protocol](docs/PLAYBACK_PROTOCOL.md) explains neural and cinematic time;
[social exports](docs/SOCIAL_EXPORTS.md) covers square and vertical compositions.

## Repository and release scope

- `flygomoku/`: rules, full neural simulator, engineered interfaces, policies,
  training teachers, reference opponents, and recording verification.
- `tools/` and `tests/`: training, benchmarks, evaluation, asset preparation,
  rendering audits, acceptance checks, and regressions.
- `demo/`: local viewer and video renderer, using Three.js, React, and Vinext.
- `checkpoints/`, `data/tactics/`, and `reports/`: trained interfaces, position
  sets, and original experiment evidence.
- `demo-assets.zip` in the release: large viewer assets, recorded neural games,
  encoding probe, PPO update features, training cache labels/manifests, and large
  motion audit samples.

The public viewer bootstrap removes the original Codex/Sites hosting integration.
Neural simulation, policy inference, game rules, and recorded activity retain their
original content. A path resolver relocates historical checkpoint and manifest
paths without rewriting authenticated logs.
Historical reports describe the original accepted run; some retain local host
paths and source hashes. Browser package-lock changes in this release do not
retroactively rewrite video provenance. The original local README is retained
in `docs/ORIGINAL_LOCAL_README.md`.

Public-release validation and the inherited lint limitations are documented in
[release notes](docs/PUBLIC_RELEASE.md).

## Credits and licenses

Built by **Grisha Gvadzabia** using research released by the **FlyWire Consortium**,
**Philip Shiu and collaborators**, **Google DeepMind**, **HHMI Janelia Research
Campus**, and the **flybody** authors. Full provenance is in
[SOURCES.md](SOURCES.md), [ASSET_NOTES.md](ASSET_NOTES.md), and
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

Original project code uses the MIT license. FlyWire data and applicable derived
assets retain **CC BY-NC 4.0** terms; flybody retains **Apache-2.0**. The code
license does not grant commercial rights to the research data.