flyreview 0.1.0__tar.gz

flyreview-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Brekkylab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

flyreview-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+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.

flyreview-0.1.0/README.md

@@ -0,0 +1,90 @@
+# 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.

flyreview-0.1.0/flybrain/__init__.py

@@ -0,0 +1,6 @@
+"""flybrain: the complete MaleCNS v1.0 fruit fly nervous system as a spiking
+network, with a screen in front of its eyes."""
+from .brain import Brain, DT
+from .paths import HOME, GRAPH, CELLS, ready
+
+__all__ = ['Brain', 'DT', 'HOME', 'GRAPH', 'CELLS', 'ready']

flyreview-0.1.0/flybrain/brain.py

@@ -0,0 +1,120 @@
+"""The simulated brain: load the graph, drive the photoreceptors with an
+image, integrate every neuron, hand back spike counts.
+
+Sensory model (deliberately simple, stated so it can be argued with):
+* R1-R6 receive linear luminance at their screen position, low-passed with a
+  10 ms time constant, through a saturating current 30 * I / (0.02 + I) mV.
+* R8y receive the green channel and R8p the blue channel the same way.
+* Lamina cells L1/L2/L3/L5 get a constant 12 mV: photoreceptor input to the
+  lamina is inhibitory in the fly, so light has to be able to turn them down.
+* Everything else is the connectome.
+"""
+from __future__ import annotations
+import ctypes as C
+import json
+import math
+import subprocess
+import sys
+from pathlib import Path
+import numpy as np
+
+from .paths import GRAPH, CELLS, LIB, HOME
+
+DT = 0.1
+SOURCE = Path(__file__).with_name('lif.cpp')
+
+
+def build_library(log=print) -> Path:
+    """Compile the kernel once per machine; rebuild if the source changed."""
+    stamp = LIB.with_suffix(LIB.suffix + '.json')
+    src = SOURCE.read_bytes()
+    import hashlib
+    digest = hashlib.sha256(src).hexdigest()
+    if LIB.exists() and stamp.exists() and json.loads(stamp.read_text()).get('source') == digest:
+        return LIB
+    HOME.mkdir(parents=True, exist_ok=True)
+    compiler = 'clang++' if sys.platform == 'darwin' else 'g++'
+    log(f'compiling {SOURCE.name} with {compiler}')
+    subprocess.run([compiler, '-O3', '-std=c++17', '-shared', '-fPIC', str(SOURCE), '-o', str(LIB)], check=True)
+    stamp.write_text(json.dumps({'source': digest}))
+    return LIB
+
+
+def srgb_to_linear(x: np.ndarray) -> np.ndarray:
+    x = x.astype(np.float32) / 255
+    return np.where(x <= 0.04045, x / 12.92, ((x + 0.055) / 1.055) ** 2.4).astype(np.float32)
+
+
+def sample_bilinear(channel: np.ndarray, uv: np.ndarray) -> np.ndarray:
+    h, w = channel.shape
+    x = uv[:, 0] * (w - 1); y = uv[:, 1] * (h - 1)
+    x0 = x.astype(int); y0 = y.astype(int); x1 = np.minimum(x0 + 1, w - 1); y1 = np.minimum(y0 + 1, h - 1)
+    dx = x - x0; dy = y - y0
+    return ((1 - dx) * (1 - dy) * channel[y0, x0] + dx * (1 - dy) * channel[y0, x1]
+            + (1 - dx) * dy * channel[y1, x0] + dx * dy * channel[y1, x1]).astype(np.float32)
+
+
+class Brain:
+    def __init__(self, graph: Path = GRAPH, cells: Path = CELLS):
+        g = np.load(graph)
+        self.ptr = g['ptr'].astype(np.int64); self.post = g['post'].astype(np.int32); self.weight = g['weight'].astype(np.float32)
+        self.ids = g['ids']; self.retina = g['retina'].astype(np.int32); self.uv = g['uv'].astype(np.float32)
+        self.r8 = g['r8'].astype(np.int32); self.r8_uv = g['r8_uv'].astype(np.float32); self.r8_channel = g['r8_channel'].astype(np.int32)
+        self.lamina = g['lamina'].astype(np.int32)
+        c = np.load(cells)
+        self.type = c['type']; self.superclass = c['superclass']; self.side = c['side']; self.soma = c['soma']
+        self.n = len(self.ids)
+        self.receptors = np.r_[self.retina, self.r8]
+        self.r8y = self.r8[self.r8_channel == 1]; self.r8p = self.r8[self.r8_channel == 2]
+        self.kc = np.flatnonzero(np.char.startswith(self.type, 'KC')).astype(np.int32)
+        self.readout = {name: np.flatnonzero((self.type == t) & (self.side == s)).astype(np.int32)
+                        for name, (t, s) in {'DNp20 L': ('DNp20', 'L'), 'DNp20 R': ('DNp20', 'R'), 'DNpe017 L': ('DNpe017', 'L'), 'DNpe017 R': ('DNpe017', 'R')}.items()}
+        # State
+        self.v = np.full(self.n, -52, np.float32); self.g = np.zeros(self.n, np.float32)
+        self.refractory = np.zeros(self.n, np.int16); self.drive = np.zeros(self.n, np.float32); self.drive_seen = np.zeros(self.n, np.float32)
+        slots = int(round(1.8 / DT)) + 1
+        self.queue = np.zeros((slots, self.n), np.int32); self.queue_count = np.zeros(slots, np.int32)
+        self.counts = np.zeros(self.n, np.int32)
+        self.active = np.zeros(self.n, np.int32); self.is_active = np.zeros(self.n, np.uint8)
+        seed = np.unique(np.r_[self.retina, self.r8, self.lamina])
+        self.active[:len(seed)] = seed; self.is_active[seed] = 1; self.n_active = np.array([len(seed)], np.int32)
+        self.touched = np.full(self.n, -1, np.int64); self.clock = np.zeros(1, np.int64)
+        self.lum = np.zeros(len(self.retina), np.float32); self.r8_light = np.zeros(len(self.r8), np.float32)
+        self.sim_ms = 0.0
+        lib = C.CDLL(str(build_library()))
+        self._advance = lib.flybrain_advance
+        self._advance.argtypes = [C.c_int] + [C.c_void_p] * 11 + [C.c_int, C.c_float] + [C.c_void_p] * 5
+        self._advance.restype = None
+
+    def step(self, frame: np.ndarray, ms: float, lamina_mv: float = 12.0, extra: list | None = None, colour: bool = True) -> np.ndarray:
+        """Show `frame` (H x W x 3 uint8) for `ms` milliseconds; return spikes per neuron."""
+        if frame.ndim != 3 or frame.shape[2] != 3 or frame.dtype != np.uint8:
+            raise ValueError('frame must be H x W x 3 uint8')
+        steps = int(round(ms / DT))
+        if steps < 1:
+            raise ValueError('ms too short')
+        lin = srgb_to_linear(frame)
+        luminance = lin @ np.array([0.2126, 0.7152, 0.0722], np.float32)
+        alpha = 1 - math.exp(-ms / 10)
+        self.lum += alpha * (np.clip(sample_bilinear(luminance, self.uv), 0, 1) - self.lum)
+        h, w = frame.shape[:2]
+        xi = np.minimum((self.r8_uv[:, 0] * (w - 1)).astype(int), w - 1); yi = np.minimum((self.r8_uv[:, 1] * (h - 1)).astype(int), h - 1)
+        channel_light = lin[yi, xi, self.r8_channel]
+        self.r8_light += alpha * (channel_light - self.r8_light)
+        self.drive.fill(0)
+        self.drive[self.lamina] = lamina_mv
+        self.drive[self.retina] = 30 * self.lum / (0.02 + self.lum)
+        if colour:
+            self.drive[self.r8] += 30 * self.r8_light / (0.02 + self.r8_light)
+        for idx, mv in (extra or []):
+            self.drive[idx] += mv
+        self.counts.fill(0)
+        arrays = [self.ptr, self.post, self.weight, self.v, self.g, self.refractory, self.drive, self.drive_seen,
+                  self.queue, self.queue_count, self.clock]
+        self._advance(self.n, *[a.ctypes.data for a in arrays], steps, DT,
+                      *[a.ctypes.data for a in (self.counts, self.active, self.is_active, self.n_active, self.touched)])
+        self.sim_ms += steps * DT
+        return self.counts.copy()
+
+    def rate(self, counts: np.ndarray, idx: np.ndarray, ms: float) -> float:
+        return float(counts[idx].sum() * 1000 / ms)

flyreview-0.1.0/flybrain/graph.py

@@ -0,0 +1,143 @@
+"""Build the simulation graph from the MaleCNS v1.0 tables.
+
+Nodes: every body with an assigned neuronal superclass that is not glia.
+Edges: every released connection between retained nodes, weight = synapse
+count x 0.275 mV x transmitter sign (acetylcholine +; GABA, glutamate,
+histamine -; anything else +). Nothing is thresholded away.
+
+Retina: R1-R6 photoreceptors have no soma in the volume, so each is placed at
+the optic-lobe column of the lamina cells (L1, L2, L3) it contacts most, and
+the hexagonal column grid is unrolled onto the screen: left eye on the left
+60 percent, right eye mirrored on the right 60 percent. R8 (colour) cells
+get their column from the column-annotated cells they project to.
+
+Outputs graph.npz (ptr, post, weight, ids, retina, uv, r8, r8_uv, r8_channel,
+lamina) and cells.npz (type, superclass, side per node).
+"""
+from __future__ import annotations
+import json
+import numpy as np
+import pyarrow as pa
+import pyarrow.feather as feather
+import pyarrow.ipc as ipc
+
+from .paths import SOURCE, GRAPH, CELLS, HOME
+
+CONTACT_MV = 0.275
+INHIBITORY = {'gaba', 'glutamate', 'histamine'}
+
+
+def transmitter_sign(label) -> int:
+    tokens = set(str(label).lower().split(','))
+    excitatory = 'acetylcholine' in tokens
+    inhibitory = bool(tokens & INHIBITORY)
+    if excitatory == inhibitory:      # both, neither, modulator-only: leave the edge active and positive
+        return 1
+    return 1 if excitatory else -1
+
+
+def hex_to_plane(h1, h2):
+    return np.column_stack([h1 - 0.5 * h2, np.sqrt(3) / 2 * h2])
+
+
+def viewport(xy, side):
+    """Axial hex coordinates -> screen uv in [0,1]. Left eye covers x 0..0.6, right eye 0.4..1.0 mirrored."""
+    lo, span = xy.min(axis=0), np.ptp(xy, axis=0)
+    z = (xy - lo) / span
+    u = 0.6 * z[:, 0] if side == 'L' else 0.4 + 0.6 * (1 - z[:, 0])
+    return np.column_stack([u, 1 - z[:, 1]])
+
+
+def build(log=print):
+    a = feather.read_table(SOURCE / 'annotations.feather').to_pandas()
+    nt = feather.read_table(SOURCE / 'neurotransmitters.feather').to_pandas().set_index('body')
+    keep = a.superclass.notna() & a.superclass.astype(str).ne('') & ~a.status.eq('Glia')
+    nodes = a.loc[keep].copy()
+    nodes['nt'] = nodes.bodyId.map(nt.consensus_nt)
+    nodes = nodes.sort_values('bodyId', ignore_index=True)
+    ids = nodes.bodyId.to_numpy(np.int64)
+    n = len(ids)
+    log(f'{n} neurons retained')
+
+    signs = np.array([transmitter_sign(x) for x in nodes.nt], np.int8)
+    reader = ipc.open_file(pa.memory_map(str(SOURCE / 'edges.feather'), 'r'))
+    pre_all, post_all, cnt_all = [], [], []
+    for b in range(reader.num_record_batches):
+        batch = reader.get_batch(b)
+        pre = batch.column('body_pre').to_numpy(zero_copy_only=False).astype(np.int64)
+        post = batch.column('body_post').to_numpy(zero_copy_only=False).astype(np.int64)
+        cnt = batch.column('weight').to_numpy(zero_copy_only=False)
+        i = np.searchsorted(ids, pre); j = np.searchsorted(ids, post)
+        ok = (i < n) & (j < n)
+        ok &= ids[np.minimum(i, n - 1)] == pre
+        ok &= ids[np.minimum(j, n - 1)] == post
+        pre_all.append(i[ok]); post_all.append(j[ok]); cnt_all.append(cnt[ok].astype(np.int64))
+    pre = np.concatenate(pre_all); post = np.concatenate(post_all); cnt = np.concatenate(cnt_all)
+    order = np.argsort(pre, kind='stable')
+    ptr = np.r_[0, np.cumsum(np.bincount(pre, minlength=n))].astype(np.int64)
+    post = post[order].astype(np.int32)
+    weight = (cnt[order].astype(np.float32) * signs[pre[order]] * CONTACT_MV).astype(np.float32)
+    log(f'{len(post)} edges, {int(cnt.sum())} synaptic contacts')
+
+    ann = a.set_index('bodyId').loc[ids]
+    types = ann.type.fillna('').astype(str).to_numpy()
+    side = ann.rootSide.fillna(ann.somaSide).fillna('').astype(str).to_numpy()
+    hex1 = ann.assignedOlHex1.to_numpy(float); hex2 = ann.assignedOlHex2.to_numpy(float)
+
+    # R1-R6: modal lamina column by contact count.
+    receptor = types == 'R1-R6'
+    anchor = np.isin(types, ['L1', 'L2', 'L3']) & ~np.isnan(hex1)
+    votes: dict[int, dict[tuple, int]] = {}
+    src = pre[order]
+    sel = receptor[src] & anchor[post]
+    for i, j, w in zip(src[sel], post[sel], cnt[order][sel]):
+        votes.setdefault(int(i), {})
+        key = (hex1[j], hex2[j]); votes[int(i)][key] = votes[int(i)].get(key, 0) + int(w)
+    retina = np.array(sorted(votes), np.int32)
+    hexes = np.array([max(votes[i], key=votes[i].get) for i in retina])
+    uv = np.empty((len(retina), 2), np.float32)
+    xy = hex_to_plane(hexes[:, 0], hexes[:, 1])
+    for s in 'LR':
+        m = side[retina] == s
+        uv[m] = viewport(xy[m], s)
+    log(f'{len(retina)} of {receptor.sum()} R1-R6 cells placed on the screen')
+
+    # R8: modal column over all column-annotated targets, weighted by |weight|; same viewport fit as R1-R6.
+    r8_all = np.flatnonzero(np.isin(types, ['R8p', 'R8y']))
+    r8, r8_hex = [], []
+    for i in r8_all:
+        e = np.arange(ptr[i], ptr[i + 1]); tg = post[e]
+        ok = ~np.isnan(hex1[tg]) & ~np.isnan(hex2[tg])
+        if not ok.any():
+            continue
+        v: dict[tuple, float] = {}
+        for ee, j in zip(e[ok], tg[ok]):
+            k = (hex1[j], hex2[j]); v[k] = v.get(k, 0.0) + abs(float(weight[ee]))
+        r8.append(i); r8_hex.append(max(v, key=v.get))
+    r8 = np.array(r8, np.int32); r8_hex = np.array(r8_hex)
+    r8_xy = hex_to_plane(r8_hex[:, 0], r8_hex[:, 1])
+    r8_uv = np.empty((len(r8), 2), np.float32)
+    for s in 'LR':
+        base = side[retina] == s; m = side[r8] == s
+        lo, span = xy[base].min(axis=0), np.ptp(xy[base], axis=0)
+        z = (r8_xy[m] - lo) / span
+        u = 0.6 * z[:, 0] if s == 'L' else 0.4 + 0.6 * (1 - z[:, 0])
+        r8_uv[m] = np.column_stack([u, 1 - z[:, 1]])
+    r8_uv = np.clip(r8_uv, 0, 1)
+    r8_channel = np.where(types[r8] == 'R8p', 2, 1).astype(np.int32)   # 2 = blue-sensitive, 1 = green/yellow-sensitive
+    log(f'{len(r8)} R8 cells placed ({int((r8_channel == 1).sum())} R8y, {int((r8_channel == 2).sum())} R8p)')
+
+    lamina = np.flatnonzero(np.isin(types, ['L1', 'L2', 'L3', 'L5'])).astype(np.int32)
+    HOME.mkdir(parents=True, exist_ok=True)
+    np.savez(GRAPH, ptr=ptr, post=post, weight=weight, ids=ids, retina=retina, uv=uv, r8=r8, r8_uv=r8_uv,
+             r8_channel=r8_channel, lamina=lamina, retina_hex=hexes.astype(np.float32), r8_hex=r8_hex.astype(np.float32))
+    np.savez(CELLS, type=types.astype('U48'), superclass=nodes.superclass.fillna('unassigned').astype(str).to_numpy().astype('U48'),
+             side=side.astype('U4'), hex=np.column_stack([hex1, hex2]).astype(np.float32), soma=np.array([list(s) if s is not None and len(s) == 3 else [np.nan] * 3 for s in ann.somaLocation], np.float32))
+    manifest = {'dataset': 'MaleCNS v1.0', 'neurons': int(n), 'edges': int(len(post)), 'contacts': int(cnt.sum()),
+                'retina': int(len(retina)), 'r8': int(len(r8)), 'lamina': int(len(lamina))}
+    (HOME / 'manifest.json').write_text(json.dumps(manifest, indent=1))
+    return manifest
+
+
+if __name__ == '__main__':
+    print(build())

flyreview-0.1.0/flybrain/lif.cpp

@@ -0,0 +1,89 @@
+// flybrain: event-driven leaky integrate-and-fire over a CSR graph.
+//
+// Model (Shiu et al. 2024 constants): membrane tau 20 ms, synaptic tau 5 ms,
+// rest -52 mV, threshold -45 mV, refractory 2.2 ms, axonal delay 1.8 ms,
+// one synaptic contact = 0.275 mV (already folded into the edge weights).
+// Between events a neuron's state has a closed form, so a cell is only
+// touched when something arrives or when it could possibly cross threshold.
+// Every edge in the graph is delivered; nothing is pruned.
+#include <cmath>
+#include <cstdint>
+
+namespace {
+constexpr float REST = -52.f, THRESH = -45.f, TAU_M = 20.f, TAU_G = 5.f;
+constexpr float DELAY_MS = 1.8f, REFRACTORY_MS = 2.2f;
+constexpr int TABLE = 1024;
+
+struct Decay { float m[TABLE], g[TABLE]; float dt; };
+
+inline void fill(Decay& d, float dt) {
+  d.dt = dt;
+  for (int k = 0; k < TABLE; k++) { d.m[k] = std::exp(-dt * k / TAU_M); d.g[k] = std::exp(-dt * k / TAU_G); }
+}
+}  // namespace
+
+extern "C" void flybrain_advance(
+    int n, const int64_t* ptr, const int32_t* post, const float* weight,
+    float* v, float* g, int16_t* refractory, const float* drive, float* drive_seen,
+    int32_t* queue, int32_t* queue_count, int64_t* clock, int steps, float dt,
+    int32_t* counts, int32_t* active, uint8_t* is_active, int32_t* n_active, int64_t* touched) {
+  Decay decay; fill(decay, dt);
+  const int delay = std::lround(DELAY_MS / dt), refractory_steps = std::lround(REFRACTORY_MS / dt);
+  const int slots = delay + 1;
+
+  // Bring cell i up to time `now` under constant input `current`, honouring any refractory period.
+  auto settle = [&](int i, int64_t now, float current) {
+    int64_t elapsed = now - touched[i];
+    if (elapsed <= 0) return;
+    const int frozen = refractory[i] > 0 ? refractory[i] - 1 : 0;
+    const int skipped = static_cast<int>(elapsed < frozen ? elapsed : frozen);
+    refractory[i] = elapsed >= refractory[i] ? 0 : static_cast<int16_t>(refractory[i] - elapsed);
+    elapsed -= skipped;
+    if (elapsed > 0) {
+      const float a = elapsed < TABLE ? decay.m[elapsed] : std::exp(-dt * elapsed / TAU_M);
+      const float b = elapsed < TABLE ? decay.g[elapsed] : std::exp(-dt * elapsed / TAU_G);
+      v[i] = REST + (v[i] - REST) * a + current * (1.f - a) + g[i] * (a - b) / 3.f;
+      g[i] *= b;
+    }
+    touched[i] = now;
+  };
+  auto wake = [&](int i) { if (!is_active[i]) { is_active[i] = 1; active[(*n_active)++] = i; } };
+
+  // A changed input current ends the old closed-form segment first.
+  for (int i = 0; i < n; i++) {
+    if (drive[i] != drive_seen[i]) { settle(i, *clock - 1, drive_seen[i]); drive_seen[i] = drive[i]; wake(i); }
+  }
+
+  for (int t = 0; t < steps; t++, (*clock)++) {
+    const int slot = *clock % slots, arrival = (*clock + delay) % slots;
+    int kept = 0;
+    const int before = *n_active;
+    for (int k = 0; k < before; k++) {
+      const int i = active[k];
+      settle(i, *clock, drive[i]);
+      if (refractory[i] == 0 && v[i] > THRESH) { queue[arrival * n + queue_count[arrival]++] = i; counts[i]++; }
+      // The membrane relaxes toward drive + g. If neither can reach threshold and the
+      // cell is below it now, nothing can fire until a new event arrives.
+      const bool reachable = v[i] > THRESH || drive[i] > 7.f || drive[i] + g[i] > 7.f;
+      if (reachable) active[kept++] = i; else is_active[i] = 0;
+    }
+    *n_active = kept;
+    // Spikes emitted `delay` steps ago land now.
+    for (int q = 0; q < queue_count[slot]; q++) {
+      const int i = queue[slot * n + q];
+      for (int64_t e = ptr[i]; e < ptr[i + 1]; e++) {
+        const int j = post[e];
+        settle(j, *clock, drive[j]);
+        if (refractory[j] == 0) { g[j] += weight[e]; wake(j); }
+      }
+    }
+    queue_count[slot] = 0;
+    // Cells that just fired reset and go refractory.
+    for (int q = 0; q < queue_count[arrival]; q++) {
+      const int i = queue[arrival * n + q];
+      v[i] = REST; g[i] = 0.f; refractory[i] = static_cast<int16_t>(refractory_steps);
+    }
+  }
+  // Leave every cell materialised at the end of the interval.
+  for (int i = 0; i < n; i++) settle(i, *clock - 1, drive[i]);
+}

flyreview-0.1.0/flybrain/paths.py

@@ -0,0 +1,71 @@
+"""Where flyreview keeps the connectome: FLYREVIEW_HOME, else ~/.cache/flyreview."""
+from __future__ import annotations
+import hashlib
+import json
+import os
+import sys
+import urllib.request
+from pathlib import Path
+
+HOME = Path(os.environ.get('FLYREVIEW_HOME', Path.home() / '.cache' / 'flyreview'))
+SOURCE = HOME / 'malecns_v1'
+GRAPH = HOME / 'graph.npz'
+CELLS = HOME / 'cells.npz'
+LIB = HOME / ('libflybrain.dylib' if sys.platform == 'darwin' else 'libflybrain.so')
+
+# MaleCNS v1.0 flat connectome, HHMI Janelia FlyEM, CC BY 4.0. Digests pinned on 2026-09-11.
+FILES = {
+    'annotations.feather': ('https://storage.googleapis.com/flyem-male-cns/v1.0/connectome-data/flat-connectome/body-annotations-male-cns-v1.0-minconf-0.5.feather',
+                            '2177e246113e4cfbf1e7772ec37c6da1955ff22e8063d0b1f833101f99a9a3b2'),
+    'neurotransmitters.feather': ('https://storage.googleapis.com/flyem-male-cns/v1.0/connectome-data/flat-connectome/body-neurotransmitters-male-cns-v1.0.feather',
+                                  '95c9289220663abeb3409f3ad9e5a7f8a53f8093f5139d15502cd08da8879621'),
+    'edges.feather': ('https://storage.googleapis.com/flyem-male-cns/v1.0/connectome-data/flat-connectome/connectome-weights-male-cns-v1.0-minconf-0.5.feather',
+                      'e35da783d1c686b2b58b3b87cd6a403ae43bfcfba8bff28e08ef752c1a56afc1'),
+}
+BUNDLE_URL = os.environ.get('FLYREVIEW_BUNDLE_URL', 'https://github.com/brekkylab/flyreview/releases/download/graph-v2/flyreview-graph.tar')
+
+
+def sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open('rb') as f:
+        for block in iter(lambda: f.read(1 << 24), b''):
+            h.update(block)
+    return h.hexdigest()
+
+
+def download_sources(log=print):
+    """Fetch the three Janelia tables (about 1.1 GB) and verify them."""
+    SOURCE.mkdir(parents=True, exist_ok=True)
+    for name, (url, digest) in FILES.items():
+        target = SOURCE / name
+        if not target.exists():
+            log(f'downloading {name}')
+            part = target.with_suffix('.part')
+            urllib.request.urlretrieve(url, part)
+            part.replace(target)
+        got = sha256(target)
+        if got != digest:
+            raise SystemExit(f'{name}: checksum {got} does not match the pinned {digest}')
+        log(f'{name} ok')
+    (SOURCE / 'digests.json').write_text(json.dumps({k: v[1] for k, v in FILES.items()}, indent=1))
+
+
+def fetch_bundle(log=print) -> bool:
+    """Prepared graph from the release. Returns False if it is not reachable."""
+    import tarfile
+    HOME.mkdir(parents=True, exist_ok=True)
+    tar = HOME / 'bundle.tar'
+    try:
+        log(f'fetching {BUNDLE_URL}')
+        urllib.request.urlretrieve(BUNDLE_URL, tar)
+    except Exception as e:  # noqa: BLE001
+        log(f'bundle not available ({e}); building from the Janelia tables instead')
+        return False
+    with tarfile.open(tar) as t:
+        t.extractall(HOME)
+    tar.unlink()
+    return GRAPH.exists() and CELLS.exists()
+
+
+def ready() -> bool:
+    return GRAPH.exists() and CELLS.exists()

flyreview-0.1.0/flyreview/__init__.py

@@ -0,0 +1 @@
+"""A simulated fruit fly brain (MaleCNS v1.0) reviews pull requests."""

flyreview-0.1.0/flyreview/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+main()