flybrain-connectome

flybrain-connectome

v3.01.3 · 2026-10-26 · 116 functional units · 270 module profiles · 64 gates · EPE 全栈 + AIBOM 供应链披露 + 收据完整性门禁 + Gate 60/61/62/63/64/65/66 + fail-loud 纪律 + 版本单一真源 + Xu 2026 树突计算前沿对照 + Xu 2026 双层认知计算参考实现（`tools/dendritic_rule_engine.py` + `examples/07_dendritic_rule_cache_demo.ipynb`）+ E4 区室边界 + S1 外部验证 + S2 lesion cascade + S3 统计强化 + 纪律有效性量化（catch-rate 100%，W1–W7 全部关闭）+ Gate 63 research_claims 顶层统计完整性 + 作者署名规范化（P-3 / P-4 → Li Xing + ORCID）+ bioRxiv 投稿准备包 + flybrain demo 一条命令 + 5 分钟上手 + flybrain audit CLI + JOSS 投稿包 + MCP 生态提交包 + 9 篇论文 DOI 补齐 + P1-3 HTTP/MCP 契约统一（Gate 66 · HTTP DISPATCH 从 12→47 全覆盖 MCP）+ P1-1 LangGraph runnable 后端（`--runnable` 生成含 MockLLM + MemorySaver checkpointing + OTel trace 的可执行 Python 脚本）

### The 89% problem

Deloitte's 2026 agent-pilot survey found **89% of enterprise agent pilots

never reach production**. Teradata: 78% have pilots, only 14% scaled. The

failure pattern repeats across industries in three words:

"跑不稳、管不住、查不清" — unstable, ungovernable, unauditable.

flybrain-connectome addresses the third word. Every agent edge in a

generated topology traces back to a real neuron or synapse class in the

*Drosophila* male brain connectome, serialized as W3C PROV-JSON — the

same format EU AI Act auditors expect. Your agent swarm isn't a black box;

it's a verifiable structure with biological provenance.

[5-minute quickstart](docs/QUICKSTART_5MIN.md) — from zero to an

interactive D3 topology graph in five minutes, no data download.

Auditable Agent Topology — 可审计的 Agent 拓扑生成与溯源, grounded in

the real *Drosophila* male-brain connectome (MaleCNS v1.0 — 166,700

neurons / 124,177,617 synapses, CC-BY).

flybrain-connectome turns a real, published brain wiring diagram into task-tailored multi-agent topologies you can instantiate as agent swarms — and it can prove, for every edge, *which real neuron / synapse class it came from*. The motif provenance is serialized as W3C PROV-JSON, the same standard EU AI Act auditors expect.

*5-module × 8-agent topology (predictive_coding_v2 blueprint) — the same graph you get from flybrain demo. Try it live →*

It is a developer toolkit and research artifact, not a trained model and not a simulation of a fly. Read the honest boundaries before you quote it.

Repo status: PUBLIC since 2026-10-18. History was audited and cleaned

before publicization (see CHANGELOG v1.3.0 for the original

Tier-2 IP leak and docs/D3_REPOSITORY_PUBLICITY_DECISION_2026-10-18.md

for the 16-step publicization runbook that was executed). The Tier-1 code is

MIT-licensed and reachable at https://github.com/lm203688/flybrain-connectome.

Tier-2 raw data (MaleCNS 5.63 GB, C. elegans Witvliet 2020, Drosophila larva

edges.csv, Petkova 2025 zebrafish) is fetched via the documented data pipeline

— see §"Requirements" and the S1 external-validation script.

---

What it is / what it is NOT

The killer offline feature: `generate` needs no data — it composes topologies from a 7 KB derived motif snapshot. The connectome data is only needed if you want to *query* the real brain.

---

Honest status of the unit library

The 116 functional units are split cleanly by how their evidence comes together. This is the number to remember when reading any downstream claim:

The 68.1 % bucket is not a defect and not a hidden error. It is a comparative-neuroscience scaffold: bird song, mammalian cortical layers, fish Mauthner, cephalopod vertical lobe, Aplysia and leech CPGs, insect mushroom-body — all are wired into the library with named references and can be composed like the anchored ones, but they are not measured in a real connectome the way the 37 anchored units are. Reading the library correctly means reading those two numbers together, not the 116 by itself.

How to use this — tiered by what you can actually get today

Rather than a single "this is a X" pitch, the useful things this project does break down into three tiers. Which one you actually need depends on what you are building.

Tier 1 — usable today, offline, no data download. Neuron-circuit search across 3 species × 4 axes (system / function / species / provenance); compose a virtual-organism topology from any subset of units; run the four canonical DEMOs (mammal, insect, electrosensory, swim) end-to-end. This is the *developer tool* the project actually is. flybrain search, flybrain compose, flybrain generate cover it.

Tier 2 — for people designing AI-agent scaffolds. The composed topologies trace back to real circuitry via W3C PROV-JSON, which means a downstream agent framework (LangGraph / CrewAI / AutoGen / SwarmLabs) can pick up a starting topology and audit where each wiring decision came from. This is not a general agent infra — it is a biology-prior layer you plug into one.

Tier 3 — what this project explicitly does not do. It does not beat biology at anything (Phase 3 measured negative and is not claimed). It does not replace any EM reconstruction pipeline. It does not ship a trained model or a spiking simulator. If someone reads a v1.x changelog entry that promises any of those, the honest answer is "that was aspirational; the withdrawal is documented in docs/PROJECT_REALITY_ASSESSMENT.md".

---

The four moats (measured, not marketed)

We ran the experiments. Two of the "obvious" advantages turned out to be false under controlled testing, and we say so.

What we explicitly do *not* claim

Honesty is a feature. The reproducible experiment scripts live in integrations/swarmlabs/diagnostics/ and the reports in the repo root (SNN_ENERGY_REPORT.md, MULTI_READOUT_REPORT.md, FAULT_ISOLATION_REPORT.md).

---

Install

The toolkit needs one runtime dependency (numpy, because the connectome engine imports it at module level) plus optional extras for provenance and columnar IO. No other third-party code is required. Pick either setup:

Repo status: PUBLIC since 2026-10-18. No authentication required —

the clone commands below work directly. History was audited and cleaned

before publicization (see CHANGELOG v1.3.0 for the original

Tier-2 IP leak and docs/D3_REPOSITORY_PUBLICITY_DECISION_2026-10-18.md

for the 16-step publicization runbook).

A. Clone and run (recommended, verified end-to-end)

git clone https://github.com/lm203688/flybrain-connectome.git

cd flybrain-connectome python flybrain_cli.py --help

B. Editable install (puts flybrain on your PATH)

git clone https://github.com/lm203688/flybrain-connectome.git

cd flybrain-connectome pip install -e . flybrain info

pip install -e . is *editable*: the flybrain entry point maps back to the checkout, which is precisely what lets it find the toolkit. A plain pip install . ships only the launcher, so point it at a checkout explicitly:

pip install .

export FLYBRAIN_HOME=/path/to/flybrain-connectome flybrain info

This path is verified in CI, not just documented. The package job in

.github/workflows/ci.yml runs pip install ".[prov]", invokes the console

script, resolves the toolkit via FLYBRAIN_HOME, generates an organism, and

asserts the artifact's invariants — so the install instructions cannot

silently rot.

C. Optional: the standardized provenance bundle

Structural provenance (motif_provenance, with the snapshot sha256) is always recorded. The *standardized* W3C PROV-JSON bundle (prov_json) is serialized by the optional dataprov package:

pip install dataprov                     # or: pip install "flybrain-connectome[prov]" (once on PyPI)

Without it the toolkit still runs: prov_json becomes null and get_provenance_bundle answers with prov_available: false plus the reason, rather than crashing. Both arms are asserted by scripts/check_degraded_mode.py — absent must degrade, present must actually produce the bundle.

Always check what you got

flybrain info

reports the resolved toolkit root, the motif snapshot, the data dir, API-key status, and how many tools are exposed. Run it first whenever something looks wrong — it turns "ImportError" into a named, fixable problem.

To query the real connectome you also need the data

MaleCNS v1.0 is CC-BY, ~5.63 GB, and deliberately not in this repo:

export FLYBRAIN_DATA_DIR=/path/to/your/male_cns

generate and the bundled motif snapshot need no data at all.

---

Quickstart

Every flybrain below also works as python flybrain_cli.py

(setup A), so you can try the project without installing anything.

###