Metadata-Version: 2.4
Name: flyreview
Version: 0.1.0
Summary: A simulated fruit fly brain (MaleCNS v1.0) reviews pull requests.
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pillow>=10
Requires-Dist: pyarrow>=14
Requires-Dist: pandas>=2.0
Dynamic: license-file

# flyreview

A simulated fruit fly brain reviews your pull request.

![the fly reads a SWE-bench diff and presses one of three buttons; its brain lights up on the right](docs/img/fly-review.gif)

The brain is the complete male *Drosophila* central nervous system, MaleCNS v1.0 (HHMI Janelia and Google Research, September 2026): 166,700 neurons and 25,582,938 connections, simulated as is. The diff is put on a dark screen in front of its eyes. It presses one of three buttons. It cannot read.

```sh
pip install flyreview
flyreview pr owner/repo 123          # prints the review
flyreview pr owner/repo 123 --post   # submits it under your gh login
```

The first run fetches the prepared connectome (about 300 MB) into `~/.cache/flyreview`. A review takes a second or two on a laptop.

## What it does

1. The unified diff becomes 640x480 screens in GitHub dark mode: light text on dark, added rows green, removed rows red, 29 rows per screen.
2. Each screen drives 4,146 photoreceptors: 3,335 R1-R6 cells with luminance and 811 R8 cells with colour (R8y green, R8p blue), placed on the screen through the optic-lobe column each one wires into.
3. Every neuron is integrated at 0.1 ms with the leaky integrate-and-fire constants of Shiu et al. 2024. Every connection is delivered. Nothing is cropped, added or learned.
4. Two readouts, both fixed and published:
   - **Verdict.** R8y (green) spikes per second while the diff is up, minus the same on a blank dark screen. Above 17,692 Hz by more than 15 percent: request changes. Below by more than 15 percent: approve. In between: comment.
   - **Inline comments.** DNpe017, a descending neuron: one comment per 2 Hz, one to four, on the rows that lit the eye most, which on a dark screen are the rows with the most code.

![the same django patch in light and dark mode, with the photoreceptors that fired drawn on top](docs/img/retina-dark.png)

Dark mode is not decoration. On a white page the brightest rows are the empty ones, so the photoreceptors fire on whitespace and ignore the code (row-by-row correlation with characters: -0.59). On a dark page light is text (+0.56), and the green rows are exactly the added lines.

Green is added code, and in SWE-bench Verified the model patches that add more lines fail more often (median 10 added lines for passing patches, 22 for failing). The fly likes short pull requests. That is the entire mechanism.

## How well

Same 200 model-written SWE-bench Verified patches, 100 that passed the hidden tests and 100 that failed. The threshold was set on a random half and scored on the other half, 300 splits.

| | |
| --- | --- |
| decides | 74% of patches (the rest get a comment) |
| right when it decides | **65%** |
| right if forced to decide all | 62% |
| approves human-written gold patches | 83% of 500 |

![R8y spikes per second for 200 patches, passed above and failed below, with the threshold and the comment band](docs/img/r8y-distribution.png)

Tables by repository and the method in [`docs/swebench.md`](docs/swebench.md). A picture-by-picture explanation in [`docs/how-it-works.html`](docs/how-it-works.html).

## Run it on a diff, or in CI

```sh
flyreview review change.patch
git diff main | flyreview review -
```

```yaml
# .github/workflows/fly.yml
on: pull_request
permissions:
  pull-requests: write
jobs:
  fly:
    runs-on: ubuntu-latest
    steps:
      - uses: brekkylab/flyreview@main
```

A workflow token cannot approve a pull request unless the repository (and organization) allows it; the fly then files its approval as a comment and says so.

## Build it yourself

```sh
git clone https://github.com/brekkylab/flyreview && cd flyreview
python -m venv .venv && . .venv/bin/activate && pip install -e .
flyreview setup        # release bundle, or the 1.1 GB Janelia tables if the bundle is unreachable
python -m pytest
```

`flyreview setup` with `FLYREVIEW_BUNDLE_URL=` unset and no release falls back to downloading the three Janelia tables, checking their SHA-256, and building the graph with `flybrain/graph.py`. Needs a C++ compiler for the kernel, ninety lines of C++.

## What is real and what is a model

Real: which neuron connects to which, with how many synapses; each cell's predicted transmitter; cell types and optic-lobe column coordinates. A model: identical LIF dynamics for every cell, photoreceptors as spiking cells, the screen-to-receptor projection, the 12 mV standing current on lamina cells, and every mapping from spike count to button. None of the readouts are what those cells do in a living fly.

## Provenance

- MaleCNS v1.0, HHMI Janelia FlyEM with Cambridge, MRC LMB and Google Research. CC BY 4.0. Source URLs and digests in `flybrain/paths.py`.
- LIF constants from Shiu et al., "A Drosophila computational brain model reveals sensorimotor processing", Nature 2024.
- The choice of DNp20 and DNpe017 as visually responsive descending neurons and the idea of placing photoreceptors by their lamina column follow DOOMFLY (Alex Wormuth). The simulator, importer and retina in `flybrain/` are ours, and reproduce that kernel spike for spike on identical input.
- Patches and labels: SWE-bench Verified; AlexCuadron/SWE-Bench-Verified-O1-reasoning-high-results.

MIT.
