flybrain-sdk

flybrain-sdk is an alpha-stage (0.4) Python SDK for running small connectome simulations and wiring them into games, audio demos and experiments. It is deliberately CPU-first: the reference backend is a NumPy leaky integrate-and-fire (LIF) runtime over float64 edge lists, so no GPU or CUDA setup is involved. Python 3.9+ and NumPy are the only runtime requirements, and importing the package or loading the bundled toy model works offline. Core API. A session starts with FlyBrain.load("toy", backend="cpu"), which accepts the bundled data, a local model JSON path, or a Connectome object. From there, stimulate(name, strength, duration_ms) schedules a finite current pulse for the next tick, step(n) advances n fixed simulation ticks and returns an immutable final state, and action() reads independent motor intensities without advancing time. save()/restore() write and reload a checkpoint containing model, config, dynamics and pending stimuli; advance(duration_ms=...) offers a duration-based variant. The toy sensory channels are food, looming_left, looming_right and touch; motor channels are walk, turn_left, turn_right and jump, each between 0 and 1 and described as heuristic control values rather than probabilities or measured velocities. Game movement and rendering are left to the host application. Backends. Only cpu is implemented. The names wasm and cuda exist as reserved interfaces that raise BackendUnavailableError; the project states CUDA and WASM are not implemented runtimes. Models. The bundled offline demo is a hand-authored 12-neuron circuit. A separate approximately 3.8 MB MaleCNS model (male-cns-escape-v1) runs 313 real source neurons and 20,607 anatomical edges with explicitly assumed LIF parameters, documented in a model card with a reproducible recipe. An offline catalog can be inspected via list_models() and model_info(); fetch_model() performs an explicit network request, caches assets locally and returns file paths. CLI equivalents include "python -m flybrain models list|info|download". Biological models require an explicit download=True flag. The wheel ships no large model, and raw Feather/NPY assets cannot yet be passed directly to FlyBrain.load(). Readouts and interventions. Users can select neuron populations (for example by cell_type), observe fields such as rates_hz, bind custom readout names to groups, drive selected cells with current of specified amplitude, duration and units, and silence groups through an intervention layer that can be released. The open_circuit example and the MaleCNS reproduction guide show the workflow. Demo kits and browser tools. A Session loop supports replaceable feature encoders, rate readouts and environments, plus checkpoints and verified feedback replay. "python examples/demo_session.py dodge" and "... tones" generate recordings, checkpoints and standalone playback HTML, with the tones template also exporting WAV. A browser circuit lab runs live, letting visitors stimulate toy or real cells, silence outputs, inspect rates and download an editable HTML demo; gallery viewers replay recorded Python runs. A TypeScript CPU runtime package is present in the repository. Installation and build. The package is not published on PyPI, so installation is from GitHub (pip install "flybrain-sdk @ git+https://github.com/freeman-1984-coder/flybrain-sdk.git") or from a clone using pip install -e ., optionally with the dev extra for pytest. Distribution artifacts are produced with python -m build and checked with twine check. Scope and honesty notes. The authors describe the SDK as plumbing for experiments, not a validated emulation of a fly: wiring alone does not determine physiological parameters, receptor effects, sensory encoding, motor decoding, a body or learning, and the demo has no plasticity, morphology, realistic vision or inferred biological behaviour. Full-brain real-time CPU performance has not been established. Code and original toy data are MIT-licensed; third-party datasets keep their own licences and citation requirements. The project states it is independent and unaffiliated with Janelia, FlyWire, Google or the dataset authors. Contribution areas listed include versioned model sources with licence and integrity metadata, FlyWire importers, Godot/Unity adapters and a WASM port of the reference dynamics.