# ethanramli/fly-chess-research architecture

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

- Interactive diagram: https://gitdiagram.com/ethanramli/fly-chess-research
- Repository: https://github.com/ethanramli/fly-chess-research

## Overview

FlyChess is a research project for testing whether a fruit-fly-connectome-based model can learn chess by choosing moves and receiving feedback. The documented workflow separates move choice, independently checked consequences, learning feedback, and tests of transfer or combined lessons. The supplied tree is dominated by archived experiments and exposes only three Python action modules from the current runner; the README-described active simulator and demo source is absent, so those implementation links cannot be mapped reliably. The archived puzzle-review and training code represents earlier research, not necessarily the current runtime.

Main entry points: [`python actions/curriculum.py`](https://github.com/ethanramli/fly-chess-research/blob/main/python%20actions/curriculum.py) (Curriculum runner), [`python actions/verify_pause_controls.py`](https://github.com/ethanramli/fly-chess-research/blob/main/python%20actions/verify_pause_controls.py) (Pause verification), [`archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/trace-consequence-review.mjs`](https://github.com/ethanramli/fly-chess-research/blob/main/archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/trace-consequence-review.mjs) (Trace review), [`python actions/fly_controls.py`](https://github.com/ethanramli/fly-chess-research/blob/main/python%20actions/fly_controls.py) (Pause controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runner["Research runner"]
  node_curriculum["Curriculum runner<br/>[curriculum.py]"]
  node_controls["Pause controls<br/>[fly_controls.py]"]
  node_pausecheck["Pause verification"]
end

subgraph group_archive["Archived puzzle research"]
  node_puzzletrainer["Puzzle trainer"]
  node_trace["Trace review"]
  node_puzzlesearch["Puzzle search"]
  node_experience["Experience feedback"]
end

subgraph group_training["Archived training"]
  node_latencyprofile["Training profile"]
end

node_operator(("Research operator"))

node_operator -->|"runs commands"| node_curriculum
node_curriculum -->|"imports"| node_controls
node_pausecheck -->|"imports"| node_curriculum
node_pausecheck -->|"imports"| node_controls
node_trace -->|"replays traces"| node_puzzlesearch
node_trace -->|"reviews experience"| node_experience

click node_curriculum "https://github.com/ethanramli/fly-chess-research/blob/main/python%20actions/curriculum.py"
click node_controls "https://github.com/ethanramli/fly-chess-research/blob/main/python%20actions/fly_controls.py"
click node_pausecheck "https://github.com/ethanramli/fly-chess-research/blob/main/python%20actions/verify_pause_controls.py"
click node_puzzletrainer "https://github.com/ethanramli/fly-chess-research/blob/main/archive/early-development/research/reports/puzzle-pipeline-v1-2026-10-06/source/train-puzzle-pipeline.mjs"
click node_trace "https://github.com/ethanramli/fly-chess-research/blob/main/archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/trace-consequence-review.mjs"
click node_puzzlesearch "https://github.com/ethanramli/fly-chess-research/blob/main/archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/experimental-puzzle-search.mjs"
click node_experience "https://github.com/ethanramli/fly-chess-research/blob/main/archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/experience-feedback.mjs"
click node_latencyprofile "https://github.com/ethanramli/fly-chess-research/blob/main/archive/early-development/research/data/training-latency-v2/sources/profile-g0-training-pipeline.mjs"

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_curriculum,node_controls,node_pausecheck toneBlue
class node_puzzletrainer,node_trace,node_puzzlesearch,node_experience toneAmber
class node_latencyprofile toneMint
class node_operator toneIndigo
```

## Components

### Research runner

- [Curriculum runner](https://github.com/ethanramli/fly-chess-research/blob/main/python%20actions/curriculum.py): `python actions/curriculum.py`
- [Pause controls](https://github.com/ethanramli/fly-chess-research/blob/main/python%20actions/fly_controls.py): `python actions/fly_controls.py`
- [Pause verification](https://github.com/ethanramli/fly-chess-research/blob/main/python%20actions/verify_pause_controls.py): `python actions/verify_pause_controls.py`

### Archived puzzle research

- [Puzzle trainer](https://github.com/ethanramli/fly-chess-research/blob/main/archive/early-development/research/reports/puzzle-pipeline-v1-2026-10-06/source/train-puzzle-pipeline.mjs): `archive/early-development/research/reports/puzzle-pipeline-v1-2026-10-06/source/train-puzzle-pipeline.mjs`
- [Trace review](https://github.com/ethanramli/fly-chess-research/blob/main/archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/trace-consequence-review.mjs): `archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/trace-consequence-review.mjs`
- [Puzzle search](https://github.com/ethanramli/fly-chess-research/blob/main/archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/experimental-puzzle-search.mjs): `archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/experimental-puzzle-search.mjs`
- [Experience feedback](https://github.com/ethanramli/fly-chess-research/blob/main/archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/experience-feedback.mjs): `archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/experience-feedback.mjs`

### Archived training

- [Training profile](https://github.com/ethanramli/fly-chess-research/blob/main/archive/early-development/research/data/training-latency-v2/sources/profile-g0-training-pipeline.mjs): `archive/early-development/research/data/training-latency-v2/sources/profile-g0-training-pipeline.mjs`

### Other components

- **Research operator**

## Connections

- Research operator → Curriculum runner: runs commands
- Curriculum runner → Pause controls: imports (evidence: `python actions/curriculum.py`)
- Pause verification → Curriculum runner: imports (evidence: `python actions/verify_pause_controls.py`)
- Pause verification → Pause controls: imports (evidence: `python actions/verify_pause_controls.py`)
- Trace review → Puzzle search: replays traces (evidence: `archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/trace-consequence-review.mjs`)
- Trace review → Experience feedback: reviews experience (evidence: `archive/early-development/research/reports/monte-carlo-review-software-2026-10-06/source/trace-consequence-review.mjs`)
