The Fly That Does QA

A connectome-driven image QA scanner: the real MaleCNS v1.0 fly-brain connectome (~165K neurons, ~25.6M synapses, used unmodified) sits between a task-specific sensory encoder and a fixed descending-neuron decoder. This is a research/art exercise, not a production QA tool. See docs/model.md for what it actually does and its validation results.

Install

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Copy .env.example to .env and set NEUPRINT_API_TOKEN -- the connectome is the actual classifier here, so this is required.

Then fetch the connectome (one-time):

python scripts/fetch_connectome.py --output-dir ~/.cache/fly_qa/connectome_export

Calibrate & validate

To calibrate against your own labeled QA dataset (masi-qa QA.csv format), holding out a study to test on:

# Calibrate on every study except the one you hold out.
python scripts/calibrate_on_real_labels.py <dataset-dir>/ \
    --exclude-study "study #1" \
    --connectome-export ~/.cache/fly_qa/connectome_export

# Validate on exactly the study you excluded.
python scripts/validate_on_real_labels.py "<dataset-dir>/study #1" \
    --connectome-export ~/.cache/fly_qa/connectome_export

This writes thresholds to src/fly_qa/data/decoder_thresholds.json (--output-thresholds to save elsewhere; pass the matching --thresholds to validate_on_real_labels.py and to fly-qa to use it).

See docs/model.md for full numbers, both protocols, and what a passing/failing calibration actually means here.

Run inference

fly-qa /path/to/pngs

Accepts a single PNG or a directory (scanned recursively). Verdicts are pass / fail / flag only -- never auto-delete, auto-publish, or auto-block; flag means route to a human reviewer. Results are written to --output (default fly_qa_results.csv) in masi-qa-compatible format (filename, QA_status, reason, user, date, duration, with pass/fail/flag mapped to yes/no/maybe), plus extra fly_qa-specific columns (verdict, defect_score, confidence_signal, precheck_passed, precheck_findings, fed_to_connectome, calibrated).

A local web dashboard auto-launches showing the current image, real sampled connectome activity, and a live pass/flag/fail tally (--no-dashboard to disable, --port to pin the port).

Development

pytest -q

AI Disclosure

We used generative/agentic AI to create code segments based on task descriptions, as well as debug, edit, and autocomplete code. We take accountability for the review of all content generated by AI in this work.