flybrainer 0.1.0__tar.gz

flybrainer-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# ─── Python ──────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+*.egg
+
+# ─── Virtual envs ────────────────────────────────────────────────────────
+.venv/
+venv/
+env/
+
+# ─── IDE / OS ────────────────────────────────────────────────────────────
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# ─── Tooling caches ──────────────────────────────────────────────────────
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# ─── Foliko runtime ──────────────────────────────────────────────────────
+.foliko/
+
+# ─── Flybrain local data (~/.flybrain/) ──────────────────────────────────
+# Compiled graphs and downloaded datasets are user-specific and big.
+# Users get these via `flybrain.connectome.compile.compile_graph()`.
+*.npz.lock
+*.npz.tmp

flybrainer-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 OpenFly contributors
+
+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.
+
+NOTE — The MaleCNS connectome data set (downloaded via the [download] extra)
+is licensed under CC-BY 4.0 by the FlyEM / MaleCNS team. See
+https://www.malecns.org for terms.

flybrainer-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.5
+Name: flybrainer
+Version: 0.1.0
+Summary: A reusable, Numba-JIT accelerated fruit-fly connectome (MaleCNS v1.0) extracted from OpenFly
+Project-URL: Homepage, https://github.com/chnak/flybrain
+Project-URL: Source, https://github.com/chnak/flybrain
+Project-URL: Issues, https://github.com/chnak/flybrain/issues
+Project-URL: Changelog, https://github.com/chnak/flybrain/blob/main/docs/USAGE.zh.md
+Author: OpenFly contributors
+License: MIT License
+        
+        Copyright (c) 2026 OpenFly contributors
+        
+        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.
+        
+        NOTE — The MaleCNS connectome data set (downloaded via the [download] extra)
+        is licensed under CC-BY 4.0 by the FlyEM / MaleCNS team. See
+        https://www.malecns.org for terms.
+License-File: LICENSE
+Keywords: connectomics,fruit-fly,neural-simulation,neuroscience,numba
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Life
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: <3.14,>=3.12
+Requires-Dist: numba>=0.61
+Requires-Dist: numpy<2.5,>=2.2
+Requires-Dist: pillow>=10
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: download
+Requires-Dist: requests>=2.32; extra == 'download'
+Provides-Extra: feather
+Requires-Dist: pandas>=2.2; extra == 'feather'
+Requires-Dist: pyarrow>=17; extra == 'feather'
+Provides-Extra: readout
+Requires-Dist: joblib>=1.4; extra == 'readout'
+Requires-Dist: scikit-learn>=1.5; extra == 'readout'
+Requires-Dist: scipy>=1.14; extra == 'readout'
+Description-Content-Type: text/markdown
+
+# flybrainer
+
+A reusable, Numba-JIT accelerated **fruit-fly connectome** simulator —
+extracted from [OpenFly](https://github.com/marketcalls/openfly).
+
+* **Zero heavy deps** by default: `numpy` + `numba` + `pillow` only.
+* **MaleCNS v1.0 connectome** loadable via `[feather,download]` extras.
+* **3 encoders** + **2 readouts** + **optional plasticity**.
+* **Closable LIF** kernel (Numba `@njit`), 18M+ spikes/sec.
+
+## Why?
+
+OpenFly is a trading system. The brain model inside it is excellent but
+inseparable from the broker / market / front-end code. This package
+isolates the brain so it can be reused for **any** sensor → readout task:
+trading, robotics, audio classification, RL environments, etc.
+
+## Install
+
+```bash
+# Minimum (no MaleCNS, no sklearn):
+pip install flybrainer
+
+# With everything:
+pip install flybrainer[feather,readout,download]
+```
+
+## 30-second example
+
+```python
+import numpy as np
+from flybrainer import Brain, Stimulus
+
+# Build a tiny synthetic graph (no MaleCNS required)
+n = 100
+g = dict(
+    ptr=np.array([0, n], dtype=np.int64),
+    post=np.random.randint(0, n, size=n).astype(np.int32),
+    weight=np.where(np.random.rand(n) > 0.5, 0.275, -0.275),
+    modulatory=np.zeros(n, dtype=bool),
+    type=np.array(["L1"]*90 + ["KC"]*4 + ["MBON07"]*3 + ["MBON11"]*3),
+    superclass=np.array(["cb_int"]*n),
+    r16_uv=np.zeros((20, 2), dtype=np.float32),
+    r8_uv=np.zeros((20, 2), dtype=np.float32),
+    r16_eye=np.zeros(20, dtype=np.int8),
+    r8_eye=np.zeros(20, dtype=np.int8),
+    r8_channel=np.ones(20, dtype=np.int8),
+    r16=np.arange(20, dtype=np.int32),
+    r8=np.arange(20, dtype=np.int32),
+)
+brain = Brain(graph_path="<test>", graph=g)
+stim = Stimulus(r16=np.random.rand(20), r8=np.random.rand(20))
+result = brain.observe(stim, neural_ms=500.0)
+print("total spikes:", result.counts.sum())
+```
+
+See `examples/` for more.
+
+## Architecture
+
+```
+src/flybrainer/
+├── interfaces.py    # zero-dep contracts (Stimulus, BrainProtocol, SensorFrame)
+├── eyemap.py        # EyeMap dataclass + resolver
+├── encoders.py      # ChartEncoder, BarsEncoder, FeatureEncoder + make_encoder()
+├── kernel.py        # Numba @njit LIF kernel + KernelState
+├── plasticity.py    # KC→MBON plasticity (Ormond-style Oja)
+├── brain.py          # Brain class (the orchestrator)
+├── readout/
+│   ├── fixed.py     # FixedDecoder (no training)
+│   └── reservoir.py # ReservoirReadout (ridge / logistic; needs [readout])
+└── connectome/
+    ├── normalize.py # NT sign rules (feather source → arrays; needs [feather])
+    ├── compile.py   # arrays → graph.npz (multi-platform)
+    ├── sources.py   # MaleCNS v1.0 metadata + SHA256
+    ├── download.py  # resumable download (urllib only)
+    └── verify.py    # sha256 file/array helpers
+```
+
+## Optional dependencies
+
+| extra | adds | when needed |
+|---|---|---|
+| `feather` | `pandas`, `pyarrow` | `from flybrainer.connectome import normalize, compile_graph` |
+| `readout` | `scikit-learn`, `scipy`, `joblib` | `from flybrainer.readout import ReservoirReadout` |
+| `download` | `requests` | `download_source(...)` |
+| `dev` | `pytest`, `pytest-cov`, `ruff` | testing |
+
+Without `[feather]`, `compile_graph` still works if `.pre` arrays are
+already on disk (you just can't re-derive from raw `.feather` files).
+
+## Tests
+
+```bash
+pip install flybrainer[feather,readout,dev]
+pytest tests/ -v
+```
+
+## Citation
+
+* Brain model: Aso & Gorinov — *bioRxiv 2024*
+* Connectome: MaleCNS v1.0 — *https://www.malecns.org*
+* This extraction: OpenFly — *github.com/marketcalls/openfly*
+
+## Documentation
+
+Detailed Chinese user manual (API contracts, 7 worked scenarios, FAQ):
+
+* [`docs/USAGE.zh.md`](docs/USAGE.zh.md) — 991 lines / 10 chapters
+
+Quick look-up order: 第 3 章 (core concepts) → 第 5 章 (full API) → 第 6 章 (worked scenarios) → 第 10 章 (FAQ).
+
+## License
+
+MIT. The MaleCNS dataset is CC-BY 4.0 (separate license).

flybrainer-0.1.0/README.md

@@ -0,0 +1,115 @@
+# flybrainer
+
+A reusable, Numba-JIT accelerated **fruit-fly connectome** simulator —
+extracted from [OpenFly](https://github.com/marketcalls/openfly).
+
+* **Zero heavy deps** by default: `numpy` + `numba` + `pillow` only.
+* **MaleCNS v1.0 connectome** loadable via `[feather,download]` extras.
+* **3 encoders** + **2 readouts** + **optional plasticity**.
+* **Closable LIF** kernel (Numba `@njit`), 18M+ spikes/sec.
+
+## Why?
+
+OpenFly is a trading system. The brain model inside it is excellent but
+inseparable from the broker / market / front-end code. This package
+isolates the brain so it can be reused for **any** sensor → readout task:
+trading, robotics, audio classification, RL environments, etc.
+
+## Install
+
+```bash
+# Minimum (no MaleCNS, no sklearn):
+pip install flybrainer
+
+# With everything:
+pip install flybrainer[feather,readout,download]
+```
+
+## 30-second example
+
+```python
+import numpy as np
+from flybrainer import Brain, Stimulus
+
+# Build a tiny synthetic graph (no MaleCNS required)
+n = 100
+g = dict(
+    ptr=np.array([0, n], dtype=np.int64),
+    post=np.random.randint(0, n, size=n).astype(np.int32),
+    weight=np.where(np.random.rand(n) > 0.5, 0.275, -0.275),
+    modulatory=np.zeros(n, dtype=bool),
+    type=np.array(["L1"]*90 + ["KC"]*4 + ["MBON07"]*3 + ["MBON11"]*3),
+    superclass=np.array(["cb_int"]*n),
+    r16_uv=np.zeros((20, 2), dtype=np.float32),
+    r8_uv=np.zeros((20, 2), dtype=np.float32),
+    r16_eye=np.zeros(20, dtype=np.int8),
+    r8_eye=np.zeros(20, dtype=np.int8),
+    r8_channel=np.ones(20, dtype=np.int8),
+    r16=np.arange(20, dtype=np.int32),
+    r8=np.arange(20, dtype=np.int32),
+)
+brain = Brain(graph_path="<test>", graph=g)
+stim = Stimulus(r16=np.random.rand(20), r8=np.random.rand(20))
+result = brain.observe(stim, neural_ms=500.0)
+print("total spikes:", result.counts.sum())
+```
+
+See `examples/` for more.
+
+## Architecture
+
+```
+src/flybrainer/
+├── interfaces.py    # zero-dep contracts (Stimulus, BrainProtocol, SensorFrame)
+├── eyemap.py        # EyeMap dataclass + resolver
+├── encoders.py      # ChartEncoder, BarsEncoder, FeatureEncoder + make_encoder()
+├── kernel.py        # Numba @njit LIF kernel + KernelState
+├── plasticity.py    # KC→MBON plasticity (Ormond-style Oja)
+├── brain.py          # Brain class (the orchestrator)
+├── readout/
+│   ├── fixed.py     # FixedDecoder (no training)
+│   └── reservoir.py # ReservoirReadout (ridge / logistic; needs [readout])
+└── connectome/
+    ├── normalize.py # NT sign rules (feather source → arrays; needs [feather])
+    ├── compile.py   # arrays → graph.npz (multi-platform)
+    ├── sources.py   # MaleCNS v1.0 metadata + SHA256
+    ├── download.py  # resumable download (urllib only)
+    └── verify.py    # sha256 file/array helpers
+```
+
+## Optional dependencies
+
+| extra | adds | when needed |
+|---|---|---|
+| `feather` | `pandas`, `pyarrow` | `from flybrainer.connectome import normalize, compile_graph` |
+| `readout` | `scikit-learn`, `scipy`, `joblib` | `from flybrainer.readout import ReservoirReadout` |
+| `download` | `requests` | `download_source(...)` |
+| `dev` | `pytest`, `pytest-cov`, `ruff` | testing |
+
+Without `[feather]`, `compile_graph` still works if `.pre` arrays are
+already on disk (you just can't re-derive from raw `.feather` files).
+
+## Tests
+
+```bash
+pip install flybrainer[feather,readout,dev]
+pytest tests/ -v
+```
+
+## Citation
+
+* Brain model: Aso & Gorinov — *bioRxiv 2024*
+* Connectome: MaleCNS v1.0 — *https://www.malecns.org*
+* This extraction: OpenFly — *github.com/marketcalls/openfly*
+
+## Documentation
+
+Detailed Chinese user manual (API contracts, 7 worked scenarios, FAQ):
+
+* [`docs/USAGE.zh.md`](docs/USAGE.zh.md) — 991 lines / 10 chapters
+
+Quick look-up order: 第 3 章 (core concepts) → 第 5 章 (full API) → 第 6 章 (worked scenarios) → 第 10 章 (FAQ).
+
+## License
+
+MIT. The MaleCNS dataset is CC-BY 4.0 (separate license).

flybrainer-0.1.0/examples/quickstart.py

@@ -0,0 +1,161 @@
+"""End-to-end flybrainer example using a stub Brain (no MaleCNS download).
+
+This file is runnable as:
+
+    python examples/quickstart.py
+
+It demonstrates the full pipeline:
+    SensorFrame --[Encoder]--> Stimulus --[Brain]--> counts --[Decoder]--> Prediction
+
+The "Brain" here is a 256-neuron stub that satisfies ``BrainProtocol`` and
+produces deterministic-ish Poisson counts.  Replace it with the real
+``Brain.load_graph(...)`` once you have compiled a graph from the
+MaleCNS dataset.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+import numpy as np
+
+from flybrainer import (
+    REQUIRED_POPULATIONS,
+    BrainProtocol,
+    Decision,
+    ObservationResult,
+    Prediction,
+    SensorFrame,
+    Stimulus,
+)
+from flybrainer.encoders import make_encoder
+from flybrainer.readout.fixed import FixedDecoder
+
+# ---------------------------------------------------------------------------
+# Stub implementation of BrainProtocol.  Replace with:
+#     from flybrainer import Brain, load_graph
+#     brain = Brain(graph_path="connectome/...")
+# once you have a real compiled graph.
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class StubBrain(BrainProtocol):
+    """Tiny stub that satisfies BrainProtocol without a real connectome."""
+
+    n_neurons: int = 256
+    seed: int = 42
+
+    def __post_init__(self) -> None:
+        self.n: int = int(self.n_neurons)
+        self._rng = np.random.default_rng(self.seed)
+        self.populations: dict[str, np.ndarray] = {}
+        # Carve the neuron range into contiguous slices, one per population.
+        cursor = 0
+        for name in REQUIRED_POPULATIONS:
+            size = max(8, self.n // 32)
+            if cursor + size > self.n:
+                size = max(1, self.n - cursor)
+            self.populations[name] = np.arange(cursor, cursor + size, dtype=np.int32)
+            cursor += size
+            if cursor >= self.n:
+                cursor = self.n - 1
+
+    def observe(self, stimulus: Stimulus, neural_ms: float) -> ObservationResult:
+        """Fake 'spike' counts proportional to the stimulus drive."""
+        r16 = float(np.mean(stimulus.r16)) if stimulus.r16.size else 0.0
+        r8 = float(np.mean(stimulus.r8)) if stimulus.r8.size else 0.0
+        drive = 0.5 * (r16 + r8)
+        seconds = max(neural_ms, 1e-9) / 1000.0
+        lam = (2.0 + 25.0 * drive) * seconds
+        counts = self._rng.poisson(lam, size=self.n).astype(np.int32)
+        return ObservationResult(
+            counts=counts,
+            neural_ms=float(neural_ms),
+            sim_ms=0.0,
+            compute_seconds=0.0,
+        )
+
+    def checkpoint(self, path: str) -> None:
+        # Stub: nothing to do
+        pass
+
+    def restore(self, path: str) -> None:
+        pass
+
+    def provenance(self) -> dict[str, Any]:
+        return {"stub": True, "n": self.n}
+
+
+# ---------------------------------------------------------------------------
+# Build a synthetic SensorFrame (past-only, frozen).
+# ---------------------------------------------------------------------------
+
+
+def make_sensor_frame() -> SensorFrame:
+    IST = timezone(timedelta(hours=5, minutes=30))
+    bars = tuple(
+        Bar(  # type: ignore[name-defined]
+            timestamp=datetime(2024, 1, 15, 9, 25 + i, tzinfo=IST),
+            open=21600 + i * 5,
+            high=21650 + i * 5,
+            low=21580 + i * 5,
+            close=21630 + i * 5,
+            volume=1000 + i * 50,
+        )
+        for i in range(3)
+    )
+    return SensorFrame(
+        timestamp=datetime(2024, 1, 15, 9, 30, tzinfo=IST),
+        index_bars=bars,
+        vix=14.2,
+        vix_bars=bars,
+        straddle_premium=120.5,
+        entry_credit=None,
+        days_to_expiry=4.0,
+        minutes_since_open=10,
+        position_lots=0,
+    )
+
+
+# Need Bar from interfaces to build the sensor frame
+from flybrainer.interfaces import Bar  # noqa: E402
+
+# ---------------------------------------------------------------------------
+# Pipeline
+# ---------------------------------------------------------------------------
+
+
+def main() -> Prediction:
+    # ---- 1.  Set up the brain ----------------------------------------------
+    brain = StubBrain(n_neurons=256)
+
+    # ---- 2.  Encode the market snapshot into photoreceptor currents --------
+    encoder = make_encoder("bars")
+    sf = make_sensor_frame()
+    stimulus = encoder.encode(sf, brain)
+    print(f"Stimulus: r16={stimulus.r16.shape} r8={stimulus.r8.shape}")
+
+    # ---- 3.  Run 200 ms of neural dynamics --------------------------------
+    result = brain.observe(stimulus, neural_ms=200.0)
+    total_spikes = int(result.counts.sum())
+    print(f"Observed: {total_spikes} spikes across {brain.n} neurons "
+          f"in {result.neural_ms:.0f} ms")
+
+    # ---- 4.  Decode into a Decision ---------------------------------------
+    decoder = FixedDecoder(neural_ms=200.0, threshold_hz=2.0)
+    pred = decoder.predict(result.counts, brain, sf)
+    print(f"Prediction: decision={pred.decision.value} "
+          f"roi={pred.realized_over_implied:.3f} "
+          f"confidence={pred.confidence:.3f}")
+
+    # Sanity check on the protocol types
+    assert isinstance(pred, Prediction)
+    assert pred.decision in {Decision.ENTER, Decision.EXIT, Decision.HOLD}
+
+    return pred
+
+
+if __name__ == "__main__":
+    main()