fly-instinct 0.1.0__py3-none-any.whl

fly_instinct/__init__.py

@@ -0,0 +1,29 @@
+"""
+fly-instinct — 基于真实果蝇连接组的“本能引擎” (Instinct Engine)
+================================================================
+
+一个可复用、非学习（权重永久冻结）的“本能”信号源：
+把输入刺激打散成高维、非平凡、结构化的反应信号。
+它既不是白噪声（死的），也不是脚本规则（可预测），
+而是“像活物一样对刺激有反应”。
+
+快速开始：
+    # 1) 替身模式（零依赖数据，直接跑）
+    >>> from fly_instinct import FlyInstinct
+    >>> fly = FlyInstinct(n_neurons=150, seed=7)
+    >>> reaction, spikes = fly.react(stimulus)
+
+    # 2) 真实 MaleCNS 连接组模式
+    >>> python -m fly_instinct fetch-data --out data   # 一次性下载 25MB 数据
+    >>> fly = FlyInstinct.from_malecns("data/edges.csv")
+    >>> reaction, spikes = fly.react(stimulus)
+
+数据出处：MaleCNS v1.0, Janelia FlyEM (CC-BY-4.0)
+"""
+from .engine import FlyInstinct
+from .loader import load_malecns
+from .datafetch import fetch_data, DATA_URLS, EXPECTED_SIZES
+
+__version__ = "0.1.0"
+__all__ = ["FlyInstinct", "load_malecns", "fetch_data",
+           "DATA_URLS", "EXPECTED_SIZES", "__version__"]

fly_instinct/__main__.py

@@ -0,0 +1,12 @@
+"""支持：
+    python -m fly_instinct fetch-data [--out data] [--force]
+    python -m fly_instinct [--out data] [--force]   # 省略子命令亦可
+"""
+import sys
+
+from .datafetch import main
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] == "fetch-data":
+        sys.argv.pop(1)
+    main()

fly_instinct/datafetch.py

@@ -0,0 +1,106 @@
+"""
+datafetch.py — 下载 MaleCNS 真实连接组子集（25MB，3 个 CSV）
+============================================================
+
+数据出处（CC-BY-4.0，发布时须署名）：
+  - 上游：MaleCNS v1.0, Janelia FlyEM, https://male-cns.janelia.org
+  - 子集：nosuchstudios/fruit-fly-brain-runtime (HuggingFace)
+    9,999 节点 / 1,587,930 条边，从 CX/MBON/descending 等核心类抽取。
+
+用法：
+  python -m fly_instinct fetch-data --out data
+  # 或安装后：
+  fly-instinct-fetch-data --out data
+
+只标准库（urllib），无额外依赖；支持断点续传（Range 头）。
+"""
+from __future__ import annotations
+import argparse
+import os
+import sys
+import urllib.request
+
+_BASE = ("https://hf-mirror.com/datasets/nosuchstudios/"
+         "fruit-fly-brain-runtime/resolve/main/artifacts/malecns-v1.0")
+
+# 文件名 -> (URL, 预期字节数；与上游 PROVENANCE.md 一致)
+DATA_URLS = {
+    "edges.csv": f"{_BASE}/edges.csv",
+    "annotations.csv": f"{_BASE}/annotations.csv",
+    "neurotransmitters.csv": f"{_BASE}/neurotransmitters.csv",
+}
+EXPECTED_SIZES = {
+    "edges.csv": 25_207_711,
+    "annotations.csv": 283_053,
+    "neurotransmitters.csv": 364_160,
+}
+
+_UA = "Mozilla/5.0 (fly-instinct datafetch)"
+
+
+def _download_one(url: str, dest: str) -> int:
+    """下载单个文件（已存在且大小正确则跳过；否则断点续传）。返回最终字节数。"""
+    expected = EXPECTED_SIZES.get(os.path.basename(dest))
+    if os.path.exists(dest):
+        sz = os.path.getsize(dest)
+        if expected is None or sz == expected:
+            print(f"  [skip] {os.path.basename(dest)} 已存在 ({sz:,} B)")
+            return sz
+
+    req = urllib.request.Request(url, headers={"User-Agent": _UA})
+    # 断点续传：若已有部分文件
+    start = os.path.getsize(dest) if os.path.exists(dest) else 0
+    if start > 0:
+        req.add_header("Range", f"bytes={start}-")
+
+    with urllib.request.urlopen(req, timeout=60) as resp, \
+            open(dest, "ab" if start > 0 else "wb") as f:
+        total = start + int(resp.headers.get("Content-Length") or 0)
+        got = start
+        chunk = 1024 * 256
+        while True:
+            b = resp.read(chunk)
+            if not b:
+                break
+            f.write(b)
+            got += len(b)
+            if total:
+                pct = 100.0 * got / total
+                sys.stdout.write(f"\r  {os.path.basename(dest)}: "
+                                 f"{got/1e6:.1f}/{total/1e6:.1f} MB "
+                                 f"({pct:.0f}%)")
+                sys.stdout.flush()
+    sys.stdout.write("\n")
+    sz = os.path.getsize(dest)
+    if expected is not None and sz != expected:
+        raise IOError(f"{dest}: 大小 {sz:,} != 预期 {expected:,}，"
+                      f"文件可能损坏，请删除后重试")
+    print(f"  [ok] {os.path.basename(dest)} ({sz:,} B)")
+    return sz
+
+
+def fetch_data(out_dir: str, force: bool = False) -> dict:
+    """下载全部 3 个 CSV 到 out_dir，校验大小。返回 {文件名: 字节数}。"""
+    os.makedirs(out_dir, exist_ok=True)
+    print(f"下载 MaleCNS 子集数据 -> {os.path.abspath(out_dir)}")
+    sizes = {}
+    for name, url in DATA_URLS.items():
+        dest = os.path.join(out_dir, name)
+        if force and os.path.exists(dest):
+            os.remove(dest)
+        sizes[name] = _download_one(url, dest)
+    print("完成。用法：FlyInstinct.from_malecns('<out_dir>/edges.csv')")
+    return sizes
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(
+        description="下载 MaleCNS 真实连接组子集 (25MB, 3 个 CSV)")
+    p.add_argument("--out", default="data", help="输出目录 (默认 ./data)")
+    p.add_argument("--force", action="store_true", help="删除已有文件重新下载")
+    a = p.parse_args(argv)
+    fetch_data(a.out, force=a.force)
+
+
+if __name__ == "__main__":
+    main()

fly_instinct/engine.py

@@ -0,0 +1,197 @@
+"""
+fly_instinct.py — “本能引擎” (Instinct Engine)
+================================================
+
+一个可复用、非学习的“本能”信号源。
+
+核心思想（储备池计算 / Reservoir Computing）：
+  用一个【权重冻结、不学习】的递归网络，把输入刺激打散成
+  高维、非平凡、结构化的“本能反应”。它既不是白噪声（死的），
+  也不是脚本规则（可预测），而是“像活物一样对刺激有反应”。
+
+真实完整版会加载 MaleCNS 连接组（~16.67 万神经元）的某个采样子图
+作为冻结网络；本 PoC 用一个【结构匹配的冻结递归网络】扮演这个角色，
+接口与行为完全一致，后续可直接替换为真实连接组子图。
+
+用法：
+    from fly_instinct import FlyInstinct
+    fly = FlyInstinct(n_neurons=150, seed=7)
+    reaction, spikes = fly.react(stimulus)      # stimulus: 1D/2D 数组
+
+设计原则：
+  - 权重在 __init__ 时生成后【永久冻结】，react() 不做任何学习。
+  - 给定 seed + 刺激，输出是【确定性的】（除非显式注入噪声）。
+  - 噪声是可选的：真实动物的本能也带一点热噪声，可加可不加。
+"""
+
+from __future__ import annotations
+import numpy as np
+
+
+class FlyInstinct:
+    """冻结递归网络 + LIF 动力学 组成的“本能”信号源。"""
+
+    def __init__(self, n_neurons: int = 150, n_input: int = 1,
+                 n_output: int = 1, seed: int = 0,
+                 tau: float = 20.0, dt: float = 1.0,
+                 v_th: float = 1.0, v_reset: float = 0.0,
+                 gain: float = 6.0, spectral_radius: float = 0.95):
+        self.n = n_neurons
+        self.n_in = n_input
+        self.n_out = n_output
+        self.tau = tau
+        self.dt = dt
+        self.v_th = v_th
+        self.v_reset = v_reset
+        self.gain = gain
+
+        rng = np.random.default_rng(seed)
+
+        # 递归权重：冻结的“本能回路”。缩放到临界点附近以保留丰富动力学。
+        W = rng.normal(0.0, 1.0, size=(n_neurons, n_neurons))
+        W *= spectral_radius / np.linalg.norm(W, ord=2)
+
+        # 输入权重：刺激 -> 网络。
+        Win = rng.normal(0.0, 1.0, size=(n_neurons, n_input)) * (1.0 / np.sqrt(n_input + 1.0))
+
+        # 读出权重：网络活动 -> 单一“反应”标量（冻结，不训练）。
+        Wout = rng.normal(0.0, 1.0, size=(n_output, n_neurons)) / np.sqrt(n_neurons)
+
+        # —— 冻结：之后不再改变 ——
+        self.W = W
+        self.Win = Win
+        self.Wout = Wout
+        self._rng = np.random.default_rng(seed + 1)
+
+        self._v = np.zeros(n_neurons)
+        self._sp_prev = np.zeros(n_neurons)
+        self._reset_internal()
+
+    def _reset_internal(self):
+        self._v = np.zeros(self.n)
+        self._sp_prev = np.zeros(self.n)
+
+    def reset(self):
+        """清空网络内部状态（保留冻结权重）。"""
+        self._reset_internal()
+
+    def step(self, stimulus: np.ndarray, noise: float = 0.0) -> np.ndarray:
+        """推进一个时间步，返回该步的“反应”标量数组（长度 n_out）。"""
+        stim = np.asarray(stimulus, dtype=float).ravel()
+        I = self.W @ self._sp_prev + self.Win @ stim
+        if noise and noise > 0.0:
+            I = I + self._rng.normal(0.0, noise, size=self.n)
+        self._v = self._v + (self.dt / self.tau) * (0.0 - self._v) + self.dt * (I * self.gain)
+        sp = (self._v >= self.v_th).astype(float)
+        self._v = np.where(sp == 1.0, self.v_reset, self._v)
+        self._sp_prev = sp
+        return (self.Wout @ sp.T).ravel()
+
+    def react(self, stimulus: np.ndarray, noise: float = 0.0,
+              smooth: int = 1):
+        """
+        对一段刺激序列做“本能反应”。
+
+        参数
+        ----
+        stimulus : 1D 或 2D 数组，形状 (T,) 或 (T, n_input)
+        noise    : 注入的网络内噪声幅度（0=确定性）
+        smooth   : 输出滑动平均窗宽（1=不平滑）
+
+        返回
+        ----
+        reaction : (T,) 反应强度序列（静息基线对齐 0、峰值对齐 1；
+                   若网络被抑制到低于静息水平会出现小幅负值）
+        spikes   : (n, T) 每个神经元的发放（0/1），供可视化
+        """
+        stimulus = np.asarray(stimulus, dtype=float)
+        if stimulus.ndim == 1:
+            stimulus = stimulus[:, None]
+        T = stimulus.shape[0]
+        self.reset()
+
+        # 先测静息读出（零输入，待动力学稳定后取均值），作为反应基线
+        for _ in range(max(10, int(self.tau))):
+            self.step(np.zeros(self.n_in), noise=0.0)
+        resting = float((self.Wout @ self._sp_prev).ravel()[0])
+
+        reaction = np.zeros(T)
+        spikes = np.zeros((self.n, T))
+        for t in range(T):
+            reaction[t] = self.step(stimulus[t], noise=noise)[0] - resting
+            spikes[:, t] = self._sp_prev
+
+        if smooth > 1:
+            k = min(smooth, T)
+            kernel = np.ones(k) / k
+            reaction = np.convolve(reaction, kernel, mode="same")
+
+        # 归一化：静息基线对齐 0，峰值对齐 1（便于跨项目复用）
+        peak = reaction.max()
+        if peak > 0:
+            reaction = reaction / peak
+        return reaction, spikes
+
+    @classmethod
+    def from_malecns(cls, edges_path, ann_path=None, nt_path=None,
+                     seed=0, in_neurons=800, tau=20.0, dt=1.0,
+                     v_th=1.0, v_reset=0.0, gain=1.0, spectral_radius=0.9):
+        """
+        用【真实 MaleCNS 稀疏连接组】作为冻结递归核心构造本能引擎。
+
+        - 递归权重 W：真实连接组（按递质赋兴奋/抑制符号，谱半径归一到临界点），永久冻结。
+        - 输入接口 Win：刺激 -> 顶层 out-degree 神经元的固定兴奋投影（冻结、非学习）。
+        - 读出接口 Wout：全部神经元 -> 单一反应标量的固定随机投影（冻结、非学习）。
+          （该子集未标注明确的感受/运动神经元，用冻结投影是诚实且非学习的做法。）
+
+        与替身版接口完全一致：fly.react(stimulus) -> (reaction, spikes)
+        """
+        from scipy import sparse
+        from .loader import load_malecns
+
+        d = load_malecns(edges_path, ann_path, nt_path,
+                         spectral_radius=spectral_radius)
+        W = d["W"]
+        n = d["n"]
+
+        obj = cls.__new__(cls)
+        obj.n = n
+        obj.n_in = 1
+        obj.n_out = 1
+        obj.tau = tau
+        obj.dt = dt
+        obj.v_th = v_th
+        obj.v_reset = v_reset
+        obj.gain = gain
+        obj.W = W  # 冻结：真实连接组
+
+        rng = np.random.default_rng(seed)
+
+        # 输入接口：刺激投到顶层 out-degree 神经元（兴奋驱动）
+        coo = W.tocoo()
+        outdeg = np.bincount(coo.col, minlength=n)
+        order = np.lexsort((np.arange(n), -outdeg))  # out-degree 降序，同度按 idx 升序
+        top = order[:min(in_neurons, n)]
+        in_w = rng.uniform(0.6, 1.2, size=top.size)
+        Win = sparse.csr_matrix((in_w, (top, np.zeros(top.size, dtype=int))),
+                                shape=(n, 1))
+
+        # 读出接口：固定随机投影 -> 单一反应
+        Wout = sparse.csr_matrix(rng.normal(0.0, 1.0, (1, n)) / np.sqrt(n))
+
+        obj.Win = Win
+        obj.Wout = Wout
+        obj._rng = np.random.default_rng(seed + 1)
+        obj._v = np.zeros(n)
+        obj._sp_prev = np.zeros(n)
+
+        obj.is_real = True
+        obj.meta = {
+            "n_nodes": n,
+            "n_edges": d["n_edges"],
+            "inhibit_frac": d["inhibit_frac"],
+            "sr_raw": d["sr_raw"],
+            "sr_target": spectral_radius,
+            "in_neurons": int(top.size),
+        }
+        return obj

fly_instinct/loader.py

@@ -0,0 +1,130 @@
+"""
+malecns_loader.py — 读取 MaleCNS 真实连接组子集，产出“冻结”稀疏权重矩阵
+=======================================================================
+
+只做数据这一件事：
+  - 读 edges.csv (pre, post, weight) -> 节点 ID 映射 -> scipy 稀疏矩阵 W[post, pre]
+  - 用 neurotransmitters.csv 给突触赋符号：GABA/glycine = 抑制(-)，其余 = 兴奋(+)
+      * 注意（PROVENANCE 明确）：递质符号是“先验预测”，不是 ground truth
+  - 按谱半径把 |W| 归一到临界点附近，保证递归网络有丰富而不爆炸的动力学
+  - 权重一经生成即视为“冻结”（本模块不做任何学习）
+
+不依赖引擎代码，可单独测试。返回一个 dict（W + 元信息），交给 FlyInstinct 组装。
+"""
+from __future__ import annotations
+import csv
+import os
+import numpy as np
+from scipy import sparse
+
+# 抑制性递质（小写比对）
+INHIBIT = {"gaba", "glycine"}
+
+
+def _spectral_radius(M, iters: int = 60, seed: int = 0) -> float:
+    """用幂迭代近似 |M| 的谱半径（M 为稀疏矩阵，速度快）。"""
+    n = M.shape[0]
+    v = np.abs(np.random.default_rng(seed).random(n)) + 1e-9
+    v /= np.linalg.norm(v)
+    sr = 0.0
+    for _ in range(iters):
+        w = np.abs(M @ v)
+        nr = np.linalg.norm(w)
+        if nr < 1e-12:
+            return 0.0
+        v = w / nr
+        sr = float(nr)
+    return sr
+
+
+def load_malecns(edges_path: str, ann_path: str | None = None,
+                 nt_path: str | None = None,
+                 spectral_radius: float = 0.9) -> dict:
+    """
+    加载 MaleCNS 真实连接组子集。
+
+    参数
+    ----
+    edges_path : edges.csv，列 pre,post,weight
+    ann_path   : annotations.csv（root_id,cell_type,superclass），可选
+    nt_path    : neurotransmitters.csv（root_id,transmitter,confidence），可选
+    spectral_radius : 目标谱半径（递归强度的标尺，近临界 ~0.9）
+
+    返回
+    ----
+    dict: W(稀疏 CSR, post x pre, 带符号已缩放), n, n_edges, node_ids,
+          id2idx, inhibit_frac, sr_raw, sr_target, cell_type
+    """
+    # 1) 读边表，收集节点
+    rows = []
+    ids = set()
+    with open(edges_path, newline="") as f:
+        r = csv.reader(f)
+        next(r)  # header
+        for row in r:
+            if len(row) < 3:
+                continue
+            pre, post, w = int(row[0]), int(row[1]), float(row[2])
+            rows.append((pre, post, w))
+            ids.add(pre)
+            ids.add(post)
+
+    # 2) 读细胞类型注释（顺带把注释里的节点也纳入，保证 ID 覆盖）
+    cell_type = {}
+    if ann_path and os.path.exists(ann_path):
+        with open(ann_path, newline="") as f:
+            r = csv.reader(f)
+            next(r)
+            for row in r:
+                if len(row) < 2:
+                    continue
+                rid = int(row[0])
+                ids.add(rid)
+                ct = row[1]
+                sup = row[2] if len(row) > 2 else ""
+                cell_type[rid] = (ct, sup)
+
+    id2idx = {i: k for k, i in enumerate(sorted(ids))}
+    n = len(id2idx)
+
+    # 3) 每个（突触前）神经元的符号
+    sign = np.ones(n)  # 默认兴奋
+    if nt_path and os.path.exists(nt_path):
+        with open(nt_path, newline="") as f:
+            r = csv.reader(f)
+            next(r)
+            for row in r:
+                if len(row) < 2:
+                    continue
+                rid = int(row[0])
+                tr = row[1].strip().lower()
+                if rid in id2idx and tr in INHIBIT:
+                    sign[id2idx[rid]] = -1.0
+
+    # 4) 组装 W[post, pre]
+    ii, jj, data = [], [], []
+    for pre, post, w in rows:
+        if pre in id2idx and post in id2idx:
+            ii.append(id2idx[post])
+            jj.append(id2idx[pre])
+            data.append(w * sign[id2idx[pre]])
+    W = sparse.csr_matrix((data, (ii, jj)), shape=(n, n))
+    W.sum_duplicates()
+
+    # 5) 谱半径归一到临界点附近
+    sr_raw = _spectral_radius(W, seed=0)
+    if sr_raw > 0:
+        W = W * (spectral_radius / sr_raw)
+
+    n_inhib = int((sign < 0).sum())
+    return {
+        "W": W,
+        "n": n,
+        "n_edges": len(rows),
+        "node_ids": sorted(ids),
+        "id2idx": id2idx,
+        "inhibit_frac": n_inhib / n,
+        "sr_raw": sr_raw,
+        "sr_target": spectral_radius,
+        "cell_type": cell_type,
+    }

fly_instinct-0.1.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: fly-instinct
+Version: 0.1.0
+Summary: Instinct Engine: a frozen, non-learning 'instinct' signal source driven by a real fruit-fly (MaleCNS) connectome
+Author: roblitz
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/roblitz-spec/fly-instinct
+Project-URL: Data, https://male-cns.janelia.org
+Keywords: connectome,fruit-fly,neuroscience,reservoir-computing,spiking-neurons,generative
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: demo
+Requires-Dist: matplotlib>=3.6; extra == "demo"
+Dynamic: license-file
+
+# fly-instinct · 果蝇连接组“本能引擎”
+
+一个**可复用、非学习、纯本地**的“本能”信号源：把输入刺激喂进一个**权重冻结、不训练**的递归网络（核心是**真实果蝇 MaleCNS 连接组子图**），得到一个“像活物本能反应”的信号——**既不是白噪声（死的），也不是脚本规则（可预测）**。
+
+> 定位一句话：它是一个**有结构的、非学习的反应算子**，用于给“需要‘活的反应’”的项目提供信号。
+> 它**不是智能、不是大脑、没有意识、不会学习**。
+
+---
+
+## 文件结构
+
+```
+fly-instinct/
+├── pyproject.toml          # 打包配置（pip install . 或从 PyPI 安装）
+├── fly_instinct/           # Python 包（发布进 PyPI 的部分）
+│   ├── engine.py           #   引擎（FlyInstinct）：冻结递归网络 + LIF 动力学
+│   ├── loader.py           #   数据加载：真实 MaleCNS 子集 -> 冻结稀疏矩阵
+│   ├── datafetch.py        #   数据下载工具（25MB 子集，断点续传+校验）
+│   └── __main__.py         #   python -m fly_instinct fetch-data 入口
+├── examples/
+│   ├── poc_demo.py         # PoC（替身网络版，150 节点，无需数据）
+│   └── poc_real.py         # PoC（真实 MaleCNS 连接组版）
+├── data/                   # 真实 MaleCNS 子集（~25 MB，不进 pip 包）
+│   ├── edges.csv           #   连接权重图 pre,post,weight（1,587,930 条边）
+│   ├── annotations.csv     #   细胞类型/超类（root_id,cell_type,superclass）
+│   └── neurotransmitters.csv#  递质（root_id,transmitter,confidence）
+├── instinct_poc.png        # 替身版三方对比图
+├── instinct_poc_real.png   # 真实数据三方对比图
+├── README.md               # 本文件（操作文档）
+├── MODEL.md                # 模型说明（架构/数据出处/完整连接组接入）
+├── LICENSE.md              # 许可与署名
+└── PUBLISH.md              # 发布清单（署名/合规/商用边界）
+```
+
+---
+
+## 安装
+
+**方式 A：pip 安装（发布后）**
+
+```bash
+pip install fly-instinct          # 核心（numpy + scipy）
+pip install fly-instinct[demo]    # 含 matplotlib，可跑 examples 出图
+```
+
+**方式 B：从本仓库安装**
+
+```bash
+cd fly-instinct
+pip install .                      # 或 pip install .[demo]
+```
+
+**下载数据（一次性，25MB）**
+
+```bash
+python -m fly_instinct fetch-data --out data
+# 或安装后的命令行入口：
+fly-instinct-fetch-data --out data
+```
+
+> 数据是 **CC-BY 4.0 的 MaleCNS 子集**（上游 Janelia），体积 25MB 故不进 pip 包；
+> 下载走 HuggingFace 镜像（国内可达），断点续传 + 大小校验，已存在则自动跳过。
+
+**纯本地、无 API、无密钥、数据不外传。** 计算全部在本机 CPU 完成（唯一联网动作是上面这一次性数据下载）。
+
+---
+
+## 快速开始：跑 PoC
+
+```bash
+cd fly-instinct
+
+# 真实连接组版（推荐，需先 fetch-data 到 data/）
+python examples/poc_real.py     # 自动选增益 + 三方对比 + 输出 instinct_poc_real.png
+
+# 替身版（不需要数据，150 节点，秒级）
+python examples/poc_demo.py     # 输出 instinct_poc.png
+```
+
+`poc_real.py` 在同一“威胁逼近”刺激下对比三种反应：
+
+| 反应 | 响应延迟* | lag-1 自相关（结构） | 与刺激相关 | 威胁期发放率 |
+|---|---|---|---|---|
+| 纯随机（白噪声·死的） | 47 | ≈0 | ≈0 | — |
+| 纯脚本（规则·可预测） | 131 | 1.000 | 0.998 | — |
+| **真实本能（MaleCNS·非学习）** | 128 | 0.551 | −0.204 | 15.9% |
+
+\* 响应延迟 = 相对刺激前基线上升超过 0.25 的第一个时间步（威胁在 t=120 出现）。
+
+---
+
+## 作为插件使用（一行）
+
+```python
+from fly_instinct import FlyInstinct
+
+# 真实连接组（推荐）
+fly = FlyInstinct.from_malecns(
+    "data/edges.csv",
+    ann_path="data/annotations.csv",
+    nt_path="data/neurotransmitters.csv",
+    seed=7, in_neurons=800, gain=2.0, spectral_radius=0.9,
+)
+reaction, spikes = fly.react(stimulus)   # stimulus: 1D/2D 数组
+# reaction: (T,) 本能反应强度（静息基线=0，峰值=1；被抑制时可能有小幅负值）
+# spikes:   (n, T) 每个神经元发放（0/1），供可视化
+
+# 或替身版（不需要数据）
+fly = FlyInstinct(n_neurons=150, seed=7, gain=6.0)
+reaction, spikes = fly.react(stimulus)
+```
+
+**接口约定**
+- `fly.react(stimulus, noise=0.0, smooth=1) -> (reaction, spikes)`
+- 权重在构造时**永久冻结**，`react()` 不做任何学习；给定 `seed`+刺激，输出**确定性**（除非显式 `noise>0`）。
+- `noise>0` 可叠加一点“热噪声”，更接近真实生物（可选）。
+
+**典型用途**：游戏 NPC 本能行为、生成艺术/ComfyUI 的有机扰动、交互装置（“碰它，它有本能反应”）、科普 demo。
+
+---
+
+## 接入完整版 MaleCNS（1.05 GB）
+
+当前 `data/` 是**真实子集**（约 1 万节点，够跑、够真）。要升级到**完整校对版**（16.67 万神经元 / 2560 万条连接），用官方 **1.05 GB** 连接权重文件：
+
+**下载地址（官方，CC-BY 4.0）**
+- 官方下载页：<https://male-cns.janelia.org/download/>
+- 直链（GCS，可断点续传）：
+  `https://storage.googleapis.com/flyem-male-cns/v1.0/connectome-data/flat-connectome/connectome-weights-male-cns-v1.0-minconf-0.5.feather`
+- 文件：`connectome-weights-male-cns-v1.0-minconf-0.5.feather`（feather 格式，列同 `pre,post,weight`）
+
+> 说明：`storage.googleapis.com` 在部分网络（含中国大陆）可能不可达；届时可用可达的镜像/代理下载该文件，**只要列名仍是 pre/post/weight 即可**。
+
+**接入步骤**
+1. 下载 `.feather` 到本地。
+2. 转成 CSV（或扩展 loader 直接读 feather）：
+   ```python
+   import pandas as pd
+   df = pd.read_feather("connectome-weights-male-cns-v1.0-minconf-0.5.feather")
+   df.to_csv("full_edges.csv", index=False)   # 列：pre,post,weight
+   ```
+3. 用同一接口加载（完整版的 `annotations`/`neurotransmitters` feather 同理转 CSV 后传入）：
+   ```python
+   from fly_instinct import FlyInstinct
+   fly = FlyInstinct.from_malecns("full_edges.csv",
+                                  ann_path="full_annotations.csv",
+                                  nt_path="full_neurotransmitters.csv",
+                                  seed=7, in_neurons=2000, gain=2.0, spectral_radius=0.9)
+   reaction, spikes = fly.react(stimulus)
+   ```
+
+**代价与注意**
+- 完整版稀疏矩阵约 2560 万非零元，加载后内存数百 MB；单次 `react(T)` 计算量约为当前子集的 ~16 倍，建议 T 不要太大、机器内存 ≥ 8 GB。
+- 完整版的**递质符号仍是先验预测**（见 MODEL.md 诚实边界）。
+
+---
+
+## 许可与署名（必须）
+
+底层连接组数据为 **MaleCNS v1.0（Janelia FlyEM），CC-BY 4.0，需署名**；本包代码为你可自定授权的衍生作品。商用/分发前请阅读 `LICENSE.md` 与 `PUBLISH.md`。
+
+## 诚实声明
+
+本引擎输出的是“**冻结结构对刺激给出的、非学习的本能式反应**”。它**不具备智能、记忆、学习或意识**；递质兴奋/抑制符号是**先验预测**而非实验测定。请勿以“果蝇大脑 / 有意识 / 能学习”等措辞宣传。

fly_instinct-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+fly_instinct/__init__.py,sha256=na_eFwO0sz4Ukvr5E1iIFMzU47lNNuBEsSLNp1MMIZw,1196
+fly_instinct/__main__.py,sha256=60iZgZylcTsxajUXvcO0P4e7TsxXWHcP55JT2mDu0xs,315
+fly_instinct/datafetch.py,sha256=dBm59pb0-EFzSdBI_3SNqYPJyRDRm-gArtE9Imqj5oo,3896
+fly_instinct/engine.py,sha256=xwbpXEzpb5kXGdCKMO0X3hnVVMaUIZvNoQbA_PC-Me0,7833
+fly_instinct/loader.py,sha256=_Ipf0_lgu0TbShpUPCbSgu8_wKnnsBR3ULNlQb4huNc,4388
+fly_instinct-0.1.0.dist-info/licenses/LICENSE.md,sha256=92tQJS2lLU-sZaYPKf1bNb9tKIAYcuZ3gb3VYlLGj9g,3548
+fly_instinct-0.1.0.dist-info/METADATA,sha256=TIaQJXS0G9wG6KB4FXeoSJiSh4f1EVJerZHKY3chQng,8520
+fly_instinct-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+fly_instinct-0.1.0.dist-info/entry_points.txt,sha256=qy0X0fciswZNsYe_NnYK30VFRT-EmO9aRJdnSFFThyI,72
+fly_instinct-0.1.0.dist-info/top_level.txt,sha256=kK7lE3K_j9VBDnA3EDG2xWXe1sBo5UQzh7RwH7rrXs8,13
+fly_instinct-0.1.0.dist-info/RECORD,,

fly_instinct-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fly_instinct-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fly-instinct-fetch-data = fly_instinct.datafetch:main

fly_instinct-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,71 @@
+# LICENSE.md · 许可与署名
+
+本包由**两部分**组成，许可不同，发布时**都要带上**。
+
+---
+
+## A. 连接组数据 —— CC-BY 4.0（不可改、必须署名）
+
+`data/` 下的连接组数据源自 **MaleCNS v1.0（Janelia FlyEM）**，许可为 **CC-BY 4.0**。
+CC-BY 4.0 **允许**：商用、修改、分发、做衍生作品。
+CC-BY 4.0 **要求**：署名；且**不得**施加比 CC-BY 更严格的限制（例如不能禁止他人再分发数据）。
+
+**发布时必须包含的署名块（可直接复制）：**
+
+> 本软件使用的果蝇连接组数据来自 **MaleCNS v1.0**（成年雄性果蝇中枢神经连接组），
+> 由 Janelia Research Campus / Howard Hughes Medical Institute 提供，
+> 来源 <https://male-cns.janelia.org/>，许可 **CC-BY 4.0**。
+> 本包内的 25 MB 子集取自 <https://huggingface.co/datasets/nosuchstudios/fruit-fly-brain-runtime>（CC-BY 4.0）。
+
+> ⚠️ 如果你把 `data/` 里的 CSV 随包一起分发，这些文件本身仍是 CC-BY 4.0，**不能**用“禁止再分发”之类的条款限制它们。
+
+---
+
+## B. 本包代码 —— 你的衍生作品（可自定授权）
+
+`fly_instinct/` 包（`engine.py`、`loader.py`、`datafetch.py`、`__init__.py`、`__main__.py`）与 `examples/` 下的 PoC 脚本，是**独立编写的衍生代码**，
+**你可以自由选择授权方式**：
+
+- **想开源 / 攒口碑 / 招人**：用 **MIT**（最宽松，允许商用、闭源集成）。
+- **想闭源卖产品 / 卖服务**：可用**专有许可**（保留所有权利，仅授予使用许可），
+  但**数据部分（A）仍须保持 CC-BY 4.0 + 署名**，不能把数据锁死。
+
+### 代码默认授权（MIT，可替换）
+
+```
+MIT License
+
+Copyright (c) 2026 roblitz
+
+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.
+```
+
+> 本包代码采用 **MIT**（署名 roblitz）。若日后改为专有许可，替换上面的 MIT 段即可，
+> 但**必须保留 A 部分的数据 CC-BY 4.0 署名**。
+
+---
+
+## 商用边界（一句话）
+
+- ✅ 可以：把“引擎 + 接口 + 体验”做成产品/插件/SaaS 并收费（你卖的是你的工程与产品）。
+- ✅ 必须：数据保持 CC-BY 4.0 + 署名；不得夸大（见 MODEL.md 诚实边界）。
+- ❌ 不能：宣称拥有/独占“果蝇大脑”数据；用更严条款锁死 CC-BY 数据；以“有意识/能学习”等虚假措辞宣传。
+
+> 本文件不构成法律意见。正式上架收费前，建议花小钱做一次快速合规审查，
+> 重点核对署名条款与“不得再限制”的表述。

fly_instinct-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fly_instinct