# mncrftfrcnm/making-fly-play-chess architecture

> Architecture diagram of the GitHub repository mncrftfrcnm/making-fly-play-chess, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mncrftfrcnm/making-fly-play-chess
- Repository: https://github.com/mncrftfrcnm/making-fly-play-chess

## Overview

This repository is an experimental chess agent that evaluates positions with a fixed fruit-fly connectome and learns a readout through self-play. The main user workflow is to start a game, encode each chess position, score legal moves, and show the game and neural activity in a Gradio interface. A separate trainer builds and updates the model; an optional FlyGym interface maps activity to rendered fly movement. README documents a connectome-versus-classical comparison notebook, but its implementation was not sampled, so its internal links are omitted.

Main entry points: [`scripts/fly_chess_inference.py`](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py) (Position readout), [`scripts/fly_chess_inference_flygym.py`](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference_flygym.py) (FlyGym game interface), [`scripts/gif_gen_flygym.py`](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/gif_gen_flygym.py) (Fly chess GIF), [`fly_chess_model.joblib`](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/fly_chess_model.joblib) (Trained model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Chess inference"]
  node_game_ui["Game interface"]
  node_game_flow["Game orchestration"]
  node_move_eval["Move selection"]
end

subgraph group_brain["Connectome model"]
  node_board_encode["Board encoding"]
  node_reservoir["Connectome propagation"]
  node_readout["Position readout"]
  node_model_file[("Trained model")]
end

subgraph group_learn["Model training"]
  node_trainer["Self-play trainer"]
  node_connectome_source["Fly connectivity data"]
end

subgraph group_extensions["Visualization and research"]
  node_flygym_ui["FlyGym game interface"]
  node_fly_renderer["Neural motion renderer"]
  node_gif_renderer["Fly chess GIF<br/>[gif_gen_flygym.py]"]
  node_gif_frames["Chess GIF frames<br/>[gif_gen.py]"]
  node_architecture_study["Architecture comparison"]
end

node_player(("Player"))

node_player -->|"plays through"| node_game_ui
node_game_ui -->|"dispatches actions"| node_game_flow
node_game_flow -->|"requests move"| node_move_eval
node_move_eval -->|"scores positions"| node_board_encode
node_board_encode -->|"feeds features"| node_reservoir
node_reservoir -->|"produces activity"| node_readout
node_readout -->|"returns score"| node_move_eval
node_model_file -->|"provides weights"| node_readout
node_connectome_source -->|"supplies connectivity"| node_trainer
node_trainer -->|"saves trained model"| node_model_file
node_player -.->|"plays with rendering"| node_flygym_ui
node_flygym_ui -->|"delegates game actions"| node_game_flow
node_flygym_ui -->|"requests fly output"| node_fly_renderer
node_fly_renderer -->|"uses neuron activity"| node_readout
node_gif_renderer -->|"renders fly frames"| node_fly_renderer
node_gif_renderer -->|"uses board rendering"| node_gif_frames
node_architecture_study -.->|"compares architectures"| node_reservoir

click node_game_ui "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py"
click node_game_flow "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py"
click node_move_eval "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py"
click node_board_encode "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py"
click node_reservoir "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py"
click node_readout "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py"
click node_model_file "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/fly_chess_model.joblib"
click node_trainer "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_trainer.py"
click node_connectome_source "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_trainer.py"
click node_flygym_ui "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference_flygym.py"
click node_fly_renderer "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference_flygym.py"
click node_gif_renderer "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/gif_gen_flygym.py"
click node_gif_frames "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/gif_gen.py"
click node_architecture_study "https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/notebooks/connectome_vs_classical_architectures.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_game_ui,node_game_flow,node_move_eval toneBlue
class node_board_encode,node_reservoir,node_readout,node_model_file toneAmber
class node_trainer,node_connectome_source toneMint
class node_flygym_ui,node_fly_renderer,node_gif_renderer,node_gif_frames,node_architecture_study toneRose
class node_player toneIndigo
```

## Components

### Chess inference

- [Game interface](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py): `scripts/fly_chess_inference.py`
- [Game orchestration](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py): `scripts/fly_chess_inference.py`
- [Move selection](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py): `scripts/fly_chess_inference.py`

### Connectome model

- [Board encoding](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py): `scripts/fly_chess_inference.py`
- [Connectome propagation](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py): `scripts/fly_chess_inference.py`
- [Position readout](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference.py): `scripts/fly_chess_inference.py`
- [Trained model](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/fly_chess_model.joblib): `fly_chess_model.joblib`

### Model training

- [Self-play trainer](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_trainer.py): `scripts/fly_chess_trainer.py`
- [Fly connectivity data](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_trainer.py): `scripts/fly_chess_trainer.py`

### Visualization and research

- [FlyGym game interface](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference_flygym.py): `scripts/fly_chess_inference_flygym.py`
- [Neural motion renderer](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/fly_chess_inference_flygym.py): `scripts/fly_chess_inference_flygym.py`
- [Fly chess GIF](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/gif_gen_flygym.py): `scripts/gif_gen_flygym.py`
- [Chess GIF frames](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/scripts/gif_gen.py): `scripts/gif_gen.py`
- [Architecture comparison](https://github.com/mncrftfrcnm/making-fly-play-chess/blob/main/notebooks/connectome_vs_classical_architectures.ipynb): `notebooks/connectome_vs_classical_architectures.ipynb`

### Other components

- **Player**

## Connections

- Player → Game interface: plays through (evidence: `README.md`)
- Game interface → Game orchestration: dispatches actions (evidence: `scripts/fly_chess_inference.py`)
- Game orchestration → Move selection: requests move (evidence: `scripts/fly_chess_inference.py`)
- Move selection → Board encoding: scores positions (evidence: `README.md`)
- Board encoding → Connectome propagation: feeds features (evidence: `README.md`)
- Connectome propagation → Position readout: produces activity (evidence: `README.md`)
- Position readout → Move selection: returns score (evidence: `scripts/fly_chess_inference.py`)
- Trained model → Position readout: provides weights (evidence: `README.md`)
- Fly connectivity data → Self-play trainer: supplies connectivity (evidence: `README.md`)
- Self-play trainer → Trained model: saves trained model (evidence: `README.md`)
- Player → FlyGym game interface: plays with rendering (evidence: `README.md`)
- FlyGym game interface → Game orchestration: delegates game actions (evidence: `scripts/fly_chess_inference_flygym.py`)
- FlyGym game interface → Neural motion renderer: requests fly output (evidence: `scripts/fly_chess_inference_flygym.py`)
- Neural motion renderer → Position readout: uses neuron activity (evidence: `scripts/fly_chess_inference_flygym.py`)
- Fly chess GIF → Neural motion renderer: renders fly frames (evidence: `scripts/gif_gen_flygym.py`)
- Fly chess GIF → Chess GIF frames: uses board rendering (evidence: `scripts/gif_gen_flygym.py`)
- Architecture comparison → Connectome propagation: compares architectures (evidence: `README.md`)
