53 lines
3.4 KiB
Markdown
53 lines
3.4 KiB
Markdown
# @flybrain/brain
|
|
|
|
A connectome-constrained spiking network, reward-modulated plasticity and a population-rate
|
|
readout, for driving games from a simulated fly brain.
|
|
|
|
Four layers:
|
|
|
|
- **dataset** (`src/dataset/`): the schema-1 artifact format, validation and a seven-part SHA-256
|
|
fingerprint used for checkpoint compatibility. Two loaders, Node and browser, produce identical
|
|
arrays and identical fingerprints.
|
|
- **model** (`src/model/`): a leaky integrate-and-fire kernel stepped in integer 1-ms ticks over
|
|
the connectome, with a deterministic xorshift noise stream, an image-to-column retina
|
|
projection and three-factor plasticity on a bounded set of excitatory Kenyon-cell to MBON edges.
|
|
- **readout** (`src/readout/`): `PopulationDecoder` turns `role -> rate` into active channel names
|
|
through one optional exclusive group and any number of pulse channels. Device specifics live in
|
|
`presets/`; the only one shipped is the Game Boy's eight buttons.
|
|
- **agent** (`src/agent/`): `NeuralAgent` composes network and decoder into one per-frame
|
|
`tick()`, with warm-up, calibration, remainder accumulation, transient reset, checkpoint
|
|
export/import with rollback, and a checksummed envelope for serializing state.
|
|
- **view** (`src/view/`): `ConnectomeView`, the fixed orthographic activity map, plus pure layout
|
|
helpers. `three` is an optional peer dependency for it.
|
|
|
|
The default configuration reproduces the `fly-plays-pokemon` prototype bit for bit, pinned by
|
|
oracle tests against verbatim copies of its modules in `tests/legacy/`. Version strings
|
|
`lif-1ms-f64-v2` and `fly-kc-mbon-rstdp-v2` are kept verbatim so prototype checkpoints stay
|
|
loadable.
|
|
|
|
## Exports
|
|
|
|
| Subpath | Module | Exports |
|
|
| --- | --- | --- |
|
|
| `@flybrain/brain` | `src/index.ts` | `LifNetwork` (alias `FlyBrain`), `DEFAULT_LIF_CONFIG`, `kernelVersion`, `NEURAL_KERNEL_VERSION`, `MAX_RATE_ROLES`, `RewardModulatedStdp` (alias `Plasticity`), `DEFAULT_PLASTICITY_CONFIG`, `plasticityVersion`, `PLASTICITY_VERSION`, `projectFrame`, `DEFAULT_RETINA_CONFIG`, `Xorshift32`, `PopulationDecoder`, `gameboyDecoderConfig`, `GAMEBOY_BUTTONS`, `GAMEBOY_BUTTON_BITS`, `toButtonMask`, `fromButtonMask`, `fingerprintDataset`, `validateDataset`, `NeuralAgent`, `GAMEBOY_MS_PER_FRAME`, `DEFAULT_WARMUP_MS`, `DEFAULT_STIMULATION_MS`, `encodeEnvelope`, `decodeEnvelope`, `agentToChunks`, `agentFromChunks`, `AGENT_CHUNK_NAMES`, `ENVELOPE_SCHEMA_VERSION`, and the accompanying types |
|
|
| `@flybrain/brain/node` | `src/dataset/load-node.ts` | `loadBrainDatasetFromDir(dir)`, using `node:fs`, `node:zlib` and `node:crypto` |
|
|
| `@flybrain/brain/browser` | `src/dataset/load-browser.ts` | `loadBrainDataset(baseUrl)`, using `fetch`, `DecompressionStream` and `crypto.subtle` |
|
|
| `@flybrain/brain/view` | `src/view/connectome.ts` | `ConnectomeView`, `normalizePositions`, `classifyByRoles`; needs a DOM and WebGL |
|
|
|
|
The loaders are separate subpaths so a bundle never pulls in `node:zlib` and a server never
|
|
depends on `DecompressionStream`.
|
|
|
|
## Scripts
|
|
|
|
```sh
|
|
npm test # node --import tsx --test tests/**/*.test.ts
|
|
npm run typecheck
|
|
```
|
|
|
|
## Documentation
|
|
|
|
Full documentation is in [`../../docs`](../../docs): [overview](../../docs/overview.md),
|
|
[dataset format](../../docs/dataset-format.md), [model](../../docs/model.md),
|
|
[plasticity](../../docs/plasticity.md), [readout](../../docs/readout.md),
|
|
[integration](../../docs/integration.md), [limitations](../../docs/limitations.md),
|
|
[verification](../../docs/verification.md).
|