# flybrain-sdk

> Open-source Python connectome simulation SDK. No CUDA required.

Working: NumPy CPU backend, synthetic 12-neuron toy, sensory/motor APIs,
schema-2 JSON checkpoints, direct current injection, annotation selection,
custom output channels, selected observations, reversible silencing, and a
3.8 MB opt-in real MaleCNS subgraph with assumed LIF dynamics. SDK 0.5.0a1.
Also working: JavaScript CPU runtime, interactive browser circuit lab, standalone
HTML demo export and Python replay of browser stimulus/intervention recordings.
Also working: Python Session with replaceable current encoders, rate readouts and
JSON environments; deterministic dodge and tone demo kits, full feedback replay,
standalone recorded viewers and WAV sonification with checkpoint continuation.
The gallery is recorded playback; the circuit lab and game sandbox are live simulations.
The game supports obstacle edits, mapping gains, silencing, JS checkpoints and
verified full-feedback replay. Its 20 ms reference adapter is tested against Python.
Also working: `flybrain doctor`, `flybrain demos list/run`, and `flybrain init`
for editable Python projects with recipe.json, attribution and pinned model identity.
Also working: Godot 4 CPU scene and reusable ExternalController offer/ack boundary,
20 ms fixed neural periods, paired world/brain checkpoints and failure-stop behavior.
Start examples/godot/bridge.py, then open examples/godot/project.godot in Godot.
Raw MaleCNS/FlyWire downloads also remain available.
Not yet implemented: calibrated biological models, full-brain real-time guarantees,
WASM, biological learning or plasticity. No PyPI or NPM publication yet.

Version 0.5 alpha adds optional CuPy CUDA support (older v0.4.0a4 is CPU-only). It passed
12/12 actual NVIDIA A16-2Q hardware tests. Small circuits are slower on CUDA.
Full FlyWire v783 test on A16-8Q: all 139,255 proofread neurons and all 16,847,997
source neuron-pair/neuropil rows (54,492,922 contacts), no extra pruning.
200 active CPU/CUDA ticks compared across all neurons every 25 ticks; checkpoint
replay and 10,000 additional CUDA ticks passed. 171 tests passed, none skipped.
Median wall time per simulated second: CPU 110.955 s, CUDA 11.552 s (not real time).
This is an experimental script with assumed LIF dynamics and artificial currents,
not a catalog-ready whole-brain behavior model.

Reflex School trains only a three-weight external readout on fixed 313-cell
MaleCNS dynamics: 50% to 100% on 80 balanced held-out two-choice trials.
It is a limited resetting task, not biological plasticity or general game skill.

- [Complete FlyWire CUDA benchmark and evidence](https://freeman-1984-coder.github.io/flybrain-sdk/fullbrain.html)
- [Reflex School recorded learning experiment](https://freeman-1984-coder.github.io/flybrain-sdk/reflex.html)
- [Godot CPU adapter](https://freeman-1984-coder.github.io/flybrain-sdk/demos.html#godot)
- [Godot integration reference](https://github.com/freeman-1984-coder/flybrain-sdk/blob/main/examples/godot/README.md)
- [Live game sandbox](https://freeman-1984-coder.github.io/flybrain-sdk/live.html)
- [Live adapter and replay guide](https://github.com/freeman-1984-coder/flybrain-sdk/blob/main/docs/live-sandbox.md)
- [Game/audio demo kits](https://freeman-1984-coder.github.io/flybrain-sdk/demos.html)
- [Session integration guide](https://github.com/freeman-1984-coder/flybrain-sdk/blob/main/docs/demo-kits.md)
- [Interactive circuit lab](https://freeman-1984-coder.github.io/flybrain-sdk/lab.html)
- [Browser/demo/replay guide](https://github.com/freeman-1984-coder/flybrain-sdk/blob/main/docs/browser-lab.md)
- [Quickstart](https://freeman-1984-coder.github.io/flybrain-sdk/api.html)
- [Model catalog](https://freeman-1984-coder.github.io/flybrain-sdk/models.html)
- [Runnable real model](https://freeman-1984-coder.github.io/flybrain-sdk/male-cns-escape.html)
- [Model catalog JSON](https://freeman-1984-coder.github.io/flybrain-sdk/model-catalog.json)
- [Contributing](https://freeman-1984-coder.github.io/flybrain-sdk/contribute.html)
- [Source](https://github.com/freeman-1984-coder/flybrain-sdk)
- [Python API](https://github.com/freeman-1984-coder/flybrain-sdk/blob/main/docs/api.md)
- [Real-data plan](https://github.com/freeman-1984-coder/flybrain-sdk/blob/main/docs/real-data.md)

Package name: flybrain-sdk. Python import: from flybrain import FlyBrain.
Do not describe raw source datasets as already runnable biological brains.

Full-brain sensory update (2026-09-13): The A16-8Q five-condition ORN_DM1 probe ran all 139,255 neurons, but produced no ALPN or descending spikes. The benchmark incoming abs-weight sum 2.5 imposes a subthreshold bound of 0.9179135 for neurons without external current under its refractory rule. Do not describe that benchmark preset as supporting sensory-to-motor behavior or banana seeking. [Evidence and interpretation](https://freeman-1984-coder.github.io/flybrain-sdk/fullbrain.html#olfaction).

New synaptic-engine result (2026-09-13): The independently checked mV LIF engine passed five actual A16 GPU cases, 200 active full-graph CPU/GPU ticks and exact 20-tick checkpoint replay. Full FlyWire sensory-only input produced ALPN, MBON and descending spikes; no-odor and input-silenced controls stayed silent. DNa02 remained left-biased for both stimulus sides, so odor-directed navigation is not established. This result uses different dynamics/weights from the historical normalized benchmark. [Raw evidence and limitations](https://freeman-1984-coder.github.io/flybrain-sdk/fullbrain.html#synaptic).

[Full-brain GPU voxel recording](https://freeman-1984-coder.github.io/flybrain-sdk/foraging.html): all 139,255 neurons run on actual A16 GPU; two 2-second closed-loop runs, 100 frames each. A fixed, untrained DNa02-to-speed/turn readout produces movement but curves away from food (distance 2.778 to 4.380 game units); silencing input ORNs leaves the body stationary. Neither run reaches food. 207 hardware-host software tests passed, plus exact joint brain/world/RNG next-frame replay. Recorded browser playback, not live inference, flight, biological locomotion or learned navigation.

[Full-brain odor gain pilot](https://freeman-1984-coder.github.io/flybrain-sdk/odor-calibration.html): eight actual A16 runs compare four mV/contact strengths and both stimulus orders with all FlyWire neurons and source edges retained. At 0.05 downstream output is absent; larger strengths produce persistent downstream spikes during recovery. The 0.275 right-first run has an early ipsilateral DNa02 response but later contralateral bias. One seed, no fitted decoder, no automatic parameter selection and no navigation claim. 217 hardware-host tests passed with zero skips. The page presents all conditions, original counts and smoothed traces. [Sensory mapping explained](https://freeman-1984-coder.github.io/flybrain-sdk/foraging.html#odor-input).