biosnn-mcp 0.2.0__tar.gz

biosnn_mcp-0.2.0/.gitignore

@@ -0,0 +1,102 @@
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# ---- 虚拟环境 ----
+.venv/
+venv/
+env/
+ENV/
+
+# ---- uv ----
+# uv.lock 需要提交（复现清单要求精确依赖版本）
+# 见 docs/reproducibility.md
+
+# ---- 数据 ----
+# 计划书 §12.1：本仓库不提供数据镜像。scripts/download_data.py 把数据集落到这里，
+# 并校验哈希。不下发，因为再分发要另看各数据源自己的许可。
+data/
+
+# ---- 测试与覆盖率 ----
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# ---- 类型检查与缓存 ----
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.pytype/
+
+# ---- Jupyter ----
+.ipynb_checkpoints/
+*.ipynb~
+
+# ---- 数据与实验产物 ----
+# 数据集不入库：按计划书 §12.1 不镜像数据，只提供 scripts/download_data.py（逐文件校验 + 打印哈希）。
+data/
+datasets/
+# 但**实验产物入库**（2026-09-23 起。原来这里忽略了 sweep_results/，即那些数据只存在于一块硬盘上）。
+# 理由：论文的图表要从它们出；目录清单与保留策略见 sweep_results/README.md。
+outputs/
+runs/
+wandb/
+*.ckpt
+*.pth
+*.pt
+*.npz
+*.h5
+
+# ---- 编辑器 / 系统 ----
+.idea/
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+*.swp
+*~
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# ---- 构建与文档 ----
+site/
+docs/_build/
+
+# ---- CI artifact ----
+# scripts/gap_report.py 在 CI 里生成并上传，不入库：它由记录现算，
+# 入库反而会多出一份需要跟着记录走、却没人会去核对的副本。
+gap-report.md
+gap-report.json
+
+# ---- 环境变量 ----
+# 本项目不使用任何环境变量；这里只是防止贡献者把本地的 .env 误提交。
+.env
+.env.*
+
+# ---- paper/ 的 LaTeX 中间产物（可再生成，不入库）----
+# PDF 是本地构建产物（latexmk -pdf main.tex），入库会每次重编译都产生一个二进制改动
+# （PDF 内嵌生成时间，哈希必变）。可编译性由 CI 的 latex-build job 保证。
+paper/*.pdf
+paper/*.aux
+paper/*.log
+paper/*.out
+paper/*.blg
+paper/*.bbl
+
+# ---- 本地编辑器 / 工具链（不进库）----
+.vscode/
+ToolsRuby/

biosnn_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.5
+Name: biosnn-mcp
+Version: 0.2.0
+Summary: BioSNN-Plug 阶段五 MCP 服务器：4 个只读工具 + 5 个提议工具（propose.*，只改内存替身核），默认只读、逐调用 JSONL 审计，不依赖 LLM
+Project-URL: Homepage, https://github.com/lzmd-arch/BioSNN-Plug
+Project-URL: Repository, https://github.com/lzmd-arch/BioSNN-Plug
+Author-email: 离中梦蝶 <269058959+lzmd-arch@users.noreply.github.com>
+License-Expression: Apache-2.0
+Keywords: mcp,orchestration,spiking-neural-network
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10

biosnn_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "biosnn-mcp"
+version = "0.2.0"
+description = "BioSNN-Plug 阶段五 MCP 服务器：4 个只读工具 + 5 个提议工具（propose.*，只改内存替身核），默认只读、逐调用 JSONL 审计，不依赖 LLM"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "离中梦蝶", email = "269058959+lzmd-arch@users.noreply.github.com" }]
+keywords = ["mcp", "spiking-neural-network", "orchestration"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = []
+
+[project.scripts]
+biosnn-mcp = "biosnn_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/lzmd-arch/BioSNN-Plug"
+Repository = "https://github.com/lzmd-arch/BioSNN-Plug"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/biosnn_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/"]

biosnn_mcp-0.2.0/src/biosnn_mcp/__init__.py

@@ -0,0 +1,53 @@
+"""BioSNN-Plug 阶段五 MCP：只读骨架（M0）+ 显式可写工具（M1）。"""
+
+from .consolidate import ConsolidationReport, MemoryItem, SleepConsolidator
+from .context import ContextCode, ZScoreTopKEncoder
+from .core import CognitiveCore, InMemoryCore, MemoryEntry, ToolError
+from .dialogue import Scenario, Turn, WritableMemory, build_scenarios, run_session
+from .embeddings import HashEmbedding, OllamaEmbedding
+from .episodic import EpisodicStore
+from .llm import LLMAdapter, MockLLM
+from .llm_ollama import OllamaLLM
+from .scheduling import SchedulingPolicy
+from .server import PROTOCOL_VERSION, TOOLS, AuditLog, handle_message, serve_stdio
+from .trace import SCHEMA_VERSION, DialogueTrace, TurnRecord
+from .trigger import TriggerDecision, TriggerPolicy
+from .trigger_spiking import SpikingTrigger
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "SCHEMA_VERSION",
+    "TOOLS",
+    "AuditLog",
+    "CognitiveCore",
+    "ConsolidationReport",
+    "ContextCode",
+    "DialogueTrace",
+    "EpisodicStore",
+    "HashEmbedding",
+    "InMemoryCore",
+    "LLMAdapter",
+    "MemoryEntry",
+    "MemoryItem",
+    "MockLLM",
+    "OllamaEmbedding",
+    "OllamaLLM",
+    "Scenario",
+    "SchedulingPolicy",
+    "SleepConsolidator",
+    "SpikingTrigger",
+    "ToolError",
+    "TriggerDecision",
+    "TriggerPolicy",
+    "Turn",
+    "TurnRecord",
+    "WritableMemory",
+    "ZScoreTopKEncoder",
+    "__version__",
+    "build_scenarios",
+    "handle_message",
+    "run_session",
+    "serve_stdio",
+]
+
+from ._version import __version__  # 单一版本源

biosnn_mcp-0.2.0/src/biosnn_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+raise SystemExit(main())

biosnn_mcp-0.2.0/src/biosnn_mcp/_version.py

@@ -0,0 +1,5 @@
+"""单一版本源：``__init__`` 与 MCP 的 ``serverInfo`` 都从这里取，避免两处漂移。"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

biosnn_mcp-0.2.0/src/biosnn_mcp/consolidate.py

@@ -0,0 +1,193 @@
+"""阶段五 M3d：睡眠期噪声回放的巩固协议（纯 stdlib，协议层）。
+
+计划书 §七 第五阶段任务 4 要求「LLM 输出的脉冲编码回注和记忆巩固（**含睡眠期噪声巩固**）」。
+本模块只实现**巩固协议**：
+
+1. 睡眠期对每个条目的嵌入做高斯噪声回放（``rng.gauss``，种子固定 → 可复现）；
+2. 回放后两两算余弦相似度，``≥ merge_threshold`` 的条目**合并**（保留先出现的 id 与文本，
+   嵌入取噪声回放后的均值）；
+3. 重复 ``rounds`` 轮，直到没有合并或轮数用尽；
+4. 返回合并后的条目与报告（合并对、轮数、平均余弦漂移）。
+
+**边界**：它不连接真实记忆库、不做语义改写、不生成新知识；噪声是各向同性的，
+合并判据是余弦阈值。这些都要写进结果 README，不能把它写成「睡眠巩固能力」。
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+
+__all__ = ["ConsolidationReport", "MemoryItem", "SleepConsolidator"]
+
+
+@dataclass(frozen=True)
+class MemoryItem:
+    """一条待巩固的记忆：id、文本、嵌入。"""
+
+    id: str
+    text: str
+    embedding: tuple[float, ...]
+
+    def __post_init__(self) -> None:
+        if not self.id:
+            raise ValueError("id 不能为空。")
+        if not self.embedding:
+            raise ValueError("embedding 不能为空。")
+        if not all(math.isfinite(value) for value in self.embedding):
+            raise ValueError("embedding 含非有限值。")
+
+
+@dataclass
+class ConsolidationReport:
+    """巩固报告。
+
+    Attributes:
+        merged_pairs: 每轮合并掉的 (保留 id, 被并入 id)。
+        rounds_used: 实际执行的轮数。
+        mean_cosine_drift: 噪声回放前后嵌入的余弦相似度均值（衡量回放扰动）。
+        original_count / final_count: 输入与输出的条目数。
+    """
+
+    merged_pairs: list[tuple[str, str]] = field(default_factory=list)
+    rounds_used: int = 0
+    mean_cosine_drift: float = 0.0
+    original_count: int = 0
+    final_count: int = 0
+
+
+def _cosine(left: Sequence[float], right: Sequence[float]) -> float:
+    dot = sum(a * b for a, b in zip(left, right, strict=True))
+    norm = math.sqrt(sum(a * a for a in left)) * math.sqrt(sum(b * b for b in right))
+    if norm == 0.0:
+        return 0.0
+    return dot / norm
+
+
+class SleepConsolidator:
+    """睡眠期噪声回放 + 余弦合并的协议实现。
+
+    Args:
+        noise_sigma: 每个维度的噪声标准差（相对嵌入的 L2 范数归一化后施加）。
+        merge_threshold: 合并阈值，余弦 ≥ 该值合并（应在 [-1, 1]）。
+        rounds: 最多巩固轮数（≥1）。
+        seed: 随机种子；同种子 → 同结果。
+    """
+
+    def __init__(
+        self,
+        *,
+        noise_sigma: float = 0.05,
+        merge_threshold: float = 0.95,
+        merge_margin: float = 0.0,
+        rounds: int = 3,
+        seed: int = 0,
+    ) -> None:
+        if not 0.0 <= noise_sigma <= 1.0:
+            raise ValueError(f"noise_sigma 应在 [0, 1]，收到 {noise_sigma!r}。")
+        if not -1.0 <= merge_threshold <= 1.0:
+            raise ValueError(f"merge_threshold 应在 [-1, 1]，收到 {merge_threshold!r}。")
+        if not 0.0 <= merge_margin <= 2.0:
+            raise ValueError(f"merge_margin 应在 [0, 2]，收到 {merge_margin!r}。")
+        if not isinstance(rounds, int) or isinstance(rounds, bool) or rounds < 1:
+            raise ValueError(f"rounds 必须是 ≥1 的整数，收到 {rounds!r}。")
+        self.noise_sigma = float(noise_sigma)
+        self.merge_threshold = float(merge_threshold)
+        # M3f：并入前还要求「最近邻与次近邻的余弦间隔 ≥ margin」，0 = 历史行为逐位不变。
+        self.merge_margin = float(merge_margin)
+        self.rounds = rounds
+        self.seed = int(seed)
+
+    def _replay(self, item: MemoryItem, rng: random.Random) -> tuple[float, ...]:
+        """对嵌入加各向同性噪声并重新归一化。"""
+        norm = math.sqrt(sum(value * value for value in item.embedding))
+        if norm == 0.0:
+            return item.embedding
+        # 每维标准差 = σ·‖x‖/√dim，使**总**噪声范数 ≈ σ·‖x‖（逐维用 σ·‖x‖ 会让
+        # 总噪声随 √dim 放大：768 维时达到信号的 1.4 倍，回放余弦被压到 0.58）。
+        scale = self.noise_sigma * norm / math.sqrt(len(item.embedding))
+        noisy = [value + rng.gauss(0.0, scale) for value in item.embedding]
+        noisy_norm = math.sqrt(sum(value * value for value in noisy))
+        if noisy_norm == 0.0:
+            return item.embedding
+        return tuple(value / noisy_norm * norm for value in noisy)
+
+    def consolidate(
+        self, items: Sequence[MemoryItem]
+    ) -> tuple[list[MemoryItem], ConsolidationReport]:
+        """执行睡眠巩固，返回（合并后的条目，报告）。"""
+        for item in items:
+            if not isinstance(item, MemoryItem):
+                raise TypeError(f"条目必须是 MemoryItem，收到 {type(item)!r}。")
+        ids = [item.id for item in items]
+        if len(set(ids)) != len(ids):
+            raise ValueError("条目 id 必须唯一。")
+
+        rng = random.Random(self.seed)
+        report = ConsolidationReport(original_count=len(items))
+        current = list(items)
+        drifts: list[float] = []
+
+        for round_index in range(1, self.rounds + 1):
+            replayed = [self._replay(item, rng) for item in current]
+            drifts.extend(
+                _cosine(item.embedding, noisy)
+                for item, noisy in zip(current, replayed, strict=True)
+            )
+            survivors: list[MemoryItem] = []
+            merged_this_round = 0
+            for item, noisy in zip(current, replayed, strict=True):
+                merged = False
+                if self.merge_margin > 0 and survivors:
+                    # 先选最近邻，再检查它与次近邻的间隔；间隔不足就不合并。
+                    scored = sorted(
+                        (
+                            (_cosine(noisy, survivor.embedding), index)
+                            for index, survivor in enumerate(survivors)
+                        ),
+                        reverse=True,
+                    )
+                    best_score, best_index = scored[0]
+                    margin_ok = len(scored) == 1 or best_score - scored[1][0] >= self.merge_margin
+                    if best_score >= self.merge_threshold and margin_ok:
+                        merged = True
+                        merged_this_round += 1
+                        survivor = survivors[best_index]
+                        report.merged_pairs.append((survivor.id, item.id))
+                        survivors[best_index] = MemoryItem(
+                            id=survivor.id,
+                            text=survivor.text,
+                            embedding=tuple(
+                                (a + b) / 2.0
+                                for a, b in zip(survivor.embedding, noisy, strict=True)
+                            ),
+                        )
+                    if not merged:
+                        survivors.append(MemoryItem(id=item.id, text=item.text, embedding=noisy))
+                    continue
+                for index, survivor in enumerate(survivors):
+                    if _cosine(noisy, survivor.embedding) >= self.merge_threshold:
+                        merged = True
+                        merged_this_round += 1
+                        report.merged_pairs.append((survivor.id, item.id))
+                        survivors[index] = MemoryItem(
+                            id=survivor.id,
+                            text=survivor.text,
+                            embedding=tuple(
+                                (a + b) / 2.0
+                                for a, b in zip(survivor.embedding, noisy, strict=True)
+                            ),
+                        )
+                        break
+                if not merged:
+                    survivors.append(MemoryItem(id=item.id, text=item.text, embedding=noisy))
+            current = survivors
+            report.rounds_used = round_index
+            if merged_this_round == 0:
+                break
+
+        report.final_count = len(current)
+        report.mean_cosine_drift = sum(drifts) / len(drifts) if drifts else 1.0
+        return current, report

biosnn_mcp-0.2.0/src/biosnn_mcp/context.py

@@ -0,0 +1,129 @@
+"""阶段五 M3c：z-score 标准化 top-k 群体编码（纯 stdlib，写入情景记忆用）。
+
+计划书 §七 第五阶段任务 2：把 LLM 嵌入做 **z-score 标准化 + top-k**，再用群体编码写成
+脉冲模式，供 SNN 情景记忆写入 [Savage, 2026]。本模块只做「嵌入 → 脉冲模式」这一段，
+不连接任何记忆库，也不依赖 torch/numpy（包本身零依赖）。
+
+编码步骤（写死，便于复现）：
+
+1. 对输入向量做**总体** z-score：``z_i = (x_i − mean) / std``（``std = 0`` 时全零）；
+2. 取 ``|z_i|`` 最大的 **top-k** 维（同值按下标升序，保证确定性）；
+3. 每个被选维在 ``[−span, +span]`` 上铺 ``n_centers`` 个高斯中心，
+   激活 ``a_j = exp(−(z_i − c_j)² / (2σ²))``；
+4. 激活 ≥ ``threshold`` 记 1，否则 0；按「先被选维、后中心」的顺序展平。
+
+输出长度恒为 ``k × n_centers``；它是**脉冲模式**，不是连续嵌入。
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+__all__ = ["ContextCode", "ZScoreTopKEncoder"]
+
+
+@dataclass(frozen=True)
+class ContextCode:
+    """一次编码的结果。
+
+    Attributes:
+        indices: 被选中的维度下标（按 ``|z|`` 降序、同值按位置升序）。
+        zscores: 对应维度的 z-score。
+        activations: 展平后的群体激活，长度 ``len(indices) × n_centers``。
+        spikes: 二值化后的脉冲模式，长度同上，取值 ``{0.0, 1.0}``。
+    """
+
+    indices: tuple[int, ...]
+    zscores: tuple[float, ...]
+    activations: tuple[float, ...]
+    spikes: tuple[float, ...]
+
+
+class ZScoreTopKEncoder:
+    """把任意维度的嵌入编码成定长脉冲模式。
+
+    Args:
+        top_k: 选多少个维度（必须 ≥1）。
+        n_centers: 每个维度的群体中心数（必须 ≥2）。
+        sigma: 高斯宽度（>0）。
+        span: 中心覆盖范围 ``[−span, +span]``（>0）。
+        threshold: 二值化阈值，激活 ≥ 该值记 1（应在 (0, 1]）。
+
+    Raises:
+        ValueError: 参数越界，或输入为空、含非有限值。
+    """
+
+    def __init__(
+        self,
+        *,
+        top_k: int = 16,
+        n_centers: int = 8,
+        sigma: float = 1.0,
+        span: float = 3.0,
+        threshold: float = 0.5,
+    ) -> None:
+        if not isinstance(top_k, int) or isinstance(top_k, bool) or top_k < 1:
+            raise ValueError(f"top_k 必须是 ≥1 的整数，收到 {top_k!r}。")
+        if not isinstance(n_centers, int) or isinstance(n_centers, bool) or n_centers < 2:
+            raise ValueError(f"n_centers 必须是 ≥2 的整数，收到 {n_centers!r}。")
+        if not sigma > 0:
+            raise ValueError(f"sigma 必须为正，收到 {sigma!r}。")
+        if not span > 0:
+            raise ValueError(f"span 必须为正，收到 {span!r}。")
+        if not 0 < threshold <= 1:
+            raise ValueError(f"threshold 应在 (0, 1]，收到 {threshold!r}。")
+        self.top_k = top_k
+        self.n_centers = n_centers
+        self.sigma = float(sigma)
+        self.span = float(span)
+        self.threshold = float(threshold)
+
+    @property
+    def dimension(self) -> int:
+        """脉冲模式的长度 ``top_k × n_centers``。"""
+        return self.top_k * self.n_centers
+
+    def centers(self) -> tuple[float, ...]:
+        """群体中心，``n_centers`` 个，均匀铺在 ``[−span, +span]``。"""
+        if self.n_centers == 1:  # pragma: no cover - 构造器已拒绝
+            return (0.0,)
+        step = 2.0 * self.span / (self.n_centers - 1)
+        return tuple(-self.span + step * index for index in range(self.n_centers))
+
+    def encode(self, embedding: Sequence[float]) -> ContextCode:
+        """把嵌入编码成脉冲模式。"""
+        values = [float(value) for value in embedding]
+        if not values:
+            raise ValueError("embedding 不能为空。")
+        if not all(math.isfinite(value) for value in values):
+            raise ValueError("embedding 含非有限值（nan/inf）。")
+
+        mean = sum(values) / len(values)
+        variance = sum((value - mean) ** 2 for value in values) / len(values)
+        std = math.sqrt(variance)
+        if std == 0.0:
+            zeros = (0.0,) * self.dimension
+            return ContextCode(indices=(), zscores=(), activations=zeros, spikes=zeros)
+
+        zscores = [(value - mean) / std for value in values]
+        order = sorted(range(len(zscores)), key=lambda index: (-abs(zscores[index]), index))
+        chosen = order[: min(self.top_k, len(order))]
+        centers = self.centers()
+
+        activations: list[float] = []
+        spikes: list[float] = []
+        for index in chosen:
+            z = zscores[index]
+            for center in centers:
+                activation = math.exp(-((z - center) ** 2) / (2.0 * self.sigma**2))
+                activations.append(activation)
+                spikes.append(1.0 if activation >= self.threshold else 0.0)
+
+        return ContextCode(
+            indices=tuple(chosen),
+            zscores=tuple(zscores[index] for index in chosen),
+            activations=tuple(activations),
+            spikes=tuple(spikes),
+        )