Metadata-Version: 2.4
Name: flymind
Version: 0.2.0
Summary: Drosophila brain connectome as a compute substrate: rate & spiking reservoirs on real wiring, Hebbian/STDP plasticity, VFB/neuPrint access, MCP server
Author: voronindenis5
License: MIT License
        
        Copyright (c) 2026 voronindenis5
        
        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.
        
        ---
        
        Данные коннектомов распространяются по своим лицензиям и не включены в репозиторий:
        FlyWire v783 — CC-BY-4.0 (Zenodo 21549559); аннотации flywire_annotations v2.1.0
        (Schlegel et al.); личиночный коннектом — Winding et al., Science 2023.
        
Project-URL: Homepage, https://github.com/voronindenis5/flymind
Project-URL: Repository, https://github.com/voronindenis5/flymind
Project-URL: Issues, https://github.com/voronindenis5/flymind/issues
Keywords: drosophila,connectome,flywire,male-cns,neuroscience,reservoir-computing,spiking,stdp,mcp,brain simulation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: httpx>=0.24
Requires-Dist: pyarrow>=14
Requires-Dist: mcp[cli]<2,>=1.9
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x; extra == "gpu"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# 🧠 flymind — мозг дрозофилы как вычислитель

> **Быстрый старт:** [QUICKSTART.md](QUICKSTART.md) — от нуля до работающего
> мозга за 5 минут: установка, три «вау»-команды, карта всех возможностей
> (CLI / библиотека / веб / MCP / API / Docker) и рецепты «хочу…».
>
> **Не биолог?** Начните с [FOR_PROGRAMMERS.md](FOR_PROGRAMMERS.md) —
> практическое руководство для программистов: аналогии из ML/RNN, запускаемые
> примеры (классификатор, игровой бот, MCP-агент), API-шпаргалка и грабли,
> на которые мы наступили сами.
>
> **Далеки и от программирования?** Читайте [PROSTYMI-SLOVAMI.md](PROSTYMI-SLOVAMI.md) —
> объяснение без жаргона: что такое коннектом «на кухонном примере», что
> умеет и чего не умеет мозг мухи, словарик на одну минуту и частые вопросы.
>
> **Любите картинки?** [SCHEMY.md](SCHEMY.md) — пять диаграмм (Mermaid + ASCII):
> архитектура, путь сигнала через мозг, три паттерна использования,
> workflow разработки, топология MCP.

Обёртка, позволяющая **использовать настоящий мозг мухи для произвольных задач**:
коннектом загружается целиком, активность симулируется на реальных синапсах,
вход кодируется в сенсорные нейроны, выход читается с нисходящих/моторных
нейронов или обучаемого readout (reservoir computing на живой проводке).

## Данные (настоящие, публичные)

| Коннектом | Нейронов | Связей | Синапсов | Источник |
|---|---|---|---|---|
| **adult** (по умолчанию) | 139 255 | 15 091 983 | 54,5 млн | FlyWire v783, весь мозг взрослой Drosophila-самки (Dorkenwald et al. 2024; Zenodo 21549559) |
| **male** | 211 577 | 26 028 386 | 125,4 млн | Male CNS v1.0, вся ЦНС самца — мозг + VNC с настоящими мотонейронами (FlyEM/Janelia + Google, Cell 2026; CC-BY, без авторизации) |
| **larval** | 2 952 | 110 677 | 352 611 | Мозг личинки L1 (Winding et al., Science 2023) |

В аннотациях — иерархия типов, **предсказанные нейромедиаторы**, сторона,
VFB ID, координаты (adult). Связи знакуются медиатором пресинаптического
нейрона (gaba → тормозные) в режиме `signed=True`.

Классы: `sensory` (афференты; adult 19 265 / male 19 182), `inter`
(118 581 / 190 373), `motor` — «выход»: нисходящие DN, у male — и настоящие
мотонейроны VNC (1 409 / 2 022).

## Установка

```bash
cd flymind
python -m venv .venv
.venv/Scripts/python -m pip install -r requirements.txt
# данные скачаются и закэшируются при первом запуске (~187 МБ adult / 1.2 ГБ male)
.venv/Scripts/python -m flymind status
# GPU (опционально, CUDA 12): pip install cupy-cuda12x → device='auto'
```

## CLI

```bash
python -m flymind status                     # какой мозг загружен
python -m flymind info                       # сводка + топ нейронов
python -m flymind find "Tm9"                 # найти нейроны по типу
python -m flymind stimulate ORN              # стимулировать обонятельные рецепторы
python -m flymind fit tracking               # обучить readout на задаче
python -m flymind vfb-search "mushroom body" # поиск в Virtual Fly Brain
python -m flymind vfb-term FBbt_00005801     # метаданные термина VFB
python -m flymind serve                      # MCP-сервер (stdio)
```

Окружение: `FLYMIND_SOURCE=adult|male|larval`, `NEUPRINT_TOKEN=<jwt>`.

Запускаемые примеры (в `examples/`, все на личиночном мозге по умолчанию;
`FLYMIND_SOURCE=male|adult` — другой мозг):

| Пример | Практическая задача | Результат (реальный) |
|---|---|---|
| `anomaly_detection.py` | аномалии в потоке метрик (мониторинг) | recall 0.70 |
| `csv_classifier.py` | классификация вашего CSV (`--csv --target`) | 91% на iris |
| `digit_recognition.py` | «картинки» 3×5 с 15% шума (зрение) | 67% (10 классов) |
| `tone_detector.py` | частота тона по сырой волне (DSP) | 100% |
| `char_predictor.py` | следующий символ текста | 28% (случайно 5%) |
| `trend_forecast.py` | направление «цены» на шаг вперёд | 69% > инерция 63% |
| `navigator_2d.py` | 2D-навигация к цели (векторный выход) | 26/30 дошли, курс 7° |
| `flappy_fly.py` | флэппи-игра: махать/не махать | = эксперт (80 шагов) |
| `sensor_fusion_alarm.py` | IoT-тревога с памятью («давление падает») | P/R 0.6 |
| `brain_explorer.py` | стимуляция по модальностям: карта откликов | обоняние → DN 0.96 |
| `motor_reflex.py` | **мотонейроны VNC (male)**: рефлекторная дуга | латентность 2/4/9 шагов |
| `fly_legs.py` | **модель мухи с 6 лапами (male)**: какими лапами мозг командует двигать | T1/T2/T3+брюшко, реагирует на сторону стимула |
| `motor_steering.py` | **мотонейроны VNC (male)**: рулевой замкнутый цикл | декодер 15/15; сырая асимметрия 2/15 |
| `escape_reflex.py` | луминанс → гигантское волокно (кросс-чек с flybrain PyPI) | спайк на шаге 7 |
| `effectiveness_report.py` | сводный анализ: что мозгу даётся хорошо/плохо | таблица вердиктов |
| `plasticity_lab.py` | frozen vs Hebbian vs LIF+STDP | XOR 51% → 90% |
| `brain_features.py` | мозг как featurizer для вашей модели | 91% |
| `pong_minimal.py` | игровой бот: ракетка за мячом | 84% пойманных |
| `benchmark_adult.py` | полный бенчмарк двух динамик взрослого мозга | см. ниже |
| `test_mcp_client.py` | проверка MCP-сервера живым клиентом | 14 инструментов |
| `brain_viz_server.py` | **веб-визуализация живого мозга** (three.js + SSE + инфографика) | см. ниже |

Разбор примеров — в [FOR_PROGRAMMERS.md](FOR_PROGRAMMERS.md).

## MCP (для ZCode / Claude / Cursor)

Сервер зарегистрирован в workspace-конфиге `.zcode/config.json` (запускается
автоматически в новых сессиях ZCode; `python -m flymind serve` — руками).
Инструменты: `flymind_status / find_neurons / stimulate / step / read /
motor / reset`, `flymind_fit(task, spiking, plastic) / predict`,
`flymind_vfb_search / vfb_term / vfb_connectivity / neuprint_cypher`.

Пример диалога: *«Возбуди обонятельные рецепторы и скажи, какие нисходящие
нейроны активировались»* → `flymind_stimulate(text="ORN")` → анализ топа.

## Какие задачи мозгу даются лучше всего

Замерено на реальных прогонах (`examples/effectiveness_report.py` — таблица
с вердиктами; полные числа в таблице примеров выше):

| Класс задач | Способность мозга | Почему |
|---|---|---|
| Классификация статических образов | **отлично** (iris 91–93%, тоны 97–100%, цифры с шумом 67%) | резервуар нелинейно «разворачивает» вход в состояние 3k–211k измерений, дальше линейный readout разделяет классы |
| Детекция аномалий | **хорошо** (recall 0.7) | мозг выучивает нормальную динамику; аномалия = большая ошибка предсказания |
| Прогноз следующего значения (тренд, слежение) | **хорошо** (понг 84%, тренд 69% > инерции 63%) | линейная память: следы недавних входов сохраняются в состояниях (бит 1 шаг назад декодируется с 70%) |
| Память на 3–6 шагов | **частично** (0.69 → 0.61) | следы затухают; дальше — только линейные следы |
| НЕлинейная память (XOR через 3 шага) | **rate: нет** (~50%) / **спайки: да** (~90%) | линейному readout нужно нелинейно смешать два момента; LIF-динамика с STDP создаёт разделимые траектории — см. `examples/plasticity_lab.py` |
| Долгосрочное планирование, адаптация | **нет** | веса можно адаптировать только локальными правилами (Hebb/STDP), без градиентов |

## Пластичность и спайки

Мозг умеет адаптироваться двумя локальными правилами (без градиентов):

- **Hebbian (rate)**: `FlyBrainReservoir(..., plastic=True)` — самые сильные
  inter→inter синапсы получают обучаемую добавку ΔW; обновляется при
  `run(..., learn=True)`, на инференсе заморожена
- **Спайковый режим + STDP**: `SpikingFlyBrain(...)` — LIF-нейроны на той же
  проводке, STDP по экспоненциальным следам, readout по мембранному потенциалу;
  событийный API `brain.fired`

Замер (`examples/plasticity_lab.py`; личинка / взрослый мозг): temporal XOR
**frozen 51/49% → Hebbian 52/50% → LIF+STDP 89.5/86.7%**; линейная память
k=1..3 [0.73,0.73,0.71] → **[1.0,1.0,0.94]** (личинка) и [0.75,0.74,0.71] →
**[0.98,0.98,0.85]** (взрослый); iris сохраняется. Главный вывод: спайковая
дискретность сама по себе создаёт информативные траектории состояний.

## GPU

`FlyBrainReservoir(..., device='auto')` — cupy, если GPU виден, иначе numpy;
`'cuda'` — строгий режим с понятной ошибкой. hot-loop (sparse matvec,
bincount, tanh) на выбранном бэкенде; `step()/run()` всегда возвращают numpy
(readout/sklearn не меняются). Ставится опционально:
`pip install cupy-cuda12x`.

## Соседний проект: flybrain на PyPI (сравнение)

13.09.2026 на PyPI вышла библиотека [flybrain 0.1.0](https://pypi.org/project/flybrain/0.1.0/)
(MIT, [github.com/alextitonis/fly.ai](https://github.com/alextitonis/fly.ai)) —
движок симуляции того же Male CNS. Мы поставили её, прогнали канонический
пример и сравнили на одной машине:

| | flybrain (PyPI) | flymind (этот проект) |
|---|---|---|
| Коннектом | Male CNS (166k нейронов) | 3 шт.: самка 139k, самец 211k, личинка 3k |
| Модель | только LIF (Fly64), numba/GPU | rate + LIF, знаки ГАМК, Hebbian/STDP |
| Скорость шага (male, наш CPU) | **9.9 мс** (numba), 1.4 мс GPU | 143 мс (scipy), CuPy-бэкенд добавлен |
| Луминанс→гигантское волокно | спайк на шаге 1 | спайк на шаге 7 (gain=4) |
| Обучение | readout (PCA logistic) | readout + пластичность: XOR 51→90% |
| Задачи/примеры | eyes-энкодер, trace/run | 20 примеров: iris 91%, понг 84%, flappy=эксперт, руление 15/15... |
| Экосистема | CLI download/build | MCP (14 инструментов), веб-3D, VFB/neuPrint, скилл, 5 уровней доков |

Заимствовали у них (MIT): `conn.cells(types, side=...)` и событийный
`brain.fired`; кросс-чек — `examples/escape_reflex.py`. Их идеи в нашем
бэклоге: numba-JIT, преbuild-кэш с чексуммами, batching.

## Веб-визуализация живого мозга

```bash
python examples/brain_viz_server.py            # взрослый мозг (реальные координаты FlyWire)
FLYMIND_SOURCE=larval python examples/brain_viz_server.py   # личинка (схема-сфера)
FLYMIND_SOURCE=male python ...                 # ЦНС самца (схема-сфера)
# открыть http://127.0.0.1:8765
```

3D-облако всех нейронов в реальных координатах; Python-симулятор стримит
кадры активности по SSE (~30 fps), браузер подсвечивает активные нейроны
(возбуждение — тёплое, торможение — циан). Сценарии: волна по сенсорному
пулу, пульс, понг (с обучением на лету), детектор аномалий, покой,
**«Авто» — машинку Брайтенберга ведёт этот же мозг** (мини-арена в панели
динамики; проект `../braitenberg`); кнопки стимуляции модальностей;
«📊 Инфографика» — состав, медиаторы, топ-типы. Только stdlib на сервере;
three.js — с CDN.

**Динамика сигналов** (кнопка «📈 Динамика»):
- временные ряды активности по классам (сенсорные/интер/выход + max DN);
- рёбра между самыми активными нейронами — видно, как сигнал бежит
  по настоящим «проводам» (сильнейшие 200 синаптических связей текущего
  кадра, пульсируют);
- клик по яркой точке в 3D (или по топ-строке) — подписка на трейс
  активности нейрона (до 3 одновременно).

HTTP API визуализатора:

```
GET  /init    — координаты и классы всех нейронов (base64 float32/uint8)
GET  /stats   — статистика для инфографики
GET  /events  — SSE-поток кадров активности
POST /scenario {"name": "idle|pulse|sweep|pong|anomaly"}
POST /stimulate {"text": "ORN"} | {"cls": "motor"} | {"ids": [..]}
POST /reset
POST /info    {"idx": 123} — метаданные нейрона
```

## Docker

```bash
cd flymind
docker compose up --build     # → http://localhost:8765
```

Образ при сборке скачивает коннектомы в отдельный слой; при первом старте
том `flymind-data` засеивается из образа. Токен neuPrint — опционально в
`.env` (`NEUPRINT_TOKEN=...`).

## Как это устроено

```
вход (скаляр/вектор) ──гауссов бамп──► сенсорный пул
                                          │  x ← (1-α)x + α(W_eff·tanh(x) + I)
                              реальная проводка W (sparse CSR, CPU/GPU)
                                          │
                          состояние N нейронов ──► readout (ridge) ──► ответ задачи
                                          └─────────► нисходящие/моторные (естественный выход)
```

`W_eff` = W / средняя строчная сумма × gain (`scale_mode='row'`) либо
классическая спектральная нормализация. `signed=True` умножает связи
ГАМК-нейронов на −1 (с ослаблением `inh_scale`).

## «Мозг мухи играет в Pong»

Реальный прецедент — Fruit-Fly-Pong (Neurotech Leeds). Здесь тот же рецепт
воспроизводится честно: `fit tracking` / `pong_minimal.py` учит мозг вести
ракетку за блуждающим мячом (ошибка ~5% экрана, 84% пойманных). Полноценная
игра — свой цикл поверх `FlyBrainReservoir.step()` + обученного readout.

## Безопасность сети

Все исходящие запросы — только через `flymind.security`: allowlist хостов
(Zenodo, GitHub, Google Storage, *.virtualflybrain.org, *.janelia.org),
схемы http/https, DNS-резолв с блокировкой приватных/loopback/зарезервированных
адресов, редиректы перепроверяются, запись кэша — только внутри каталога
проекта.

## Источники

- FlyWire v783: Dorkenwald et al. 2024 (Nature); дамп: Zenodo 21549559
- Male CNS v1.0: FlyEM/Janelia + Google, Cell 2026; male-cns.janelia.org (CC-BY)
- Аннотации: flyconnectome/flywire_annotations v2.1.0 (Schlegel et al.)
- Личиночный мозг: Winding et al., Science 2023
- Virtual Fly Brain: virtualflybrain.org (VFBquery API v3-cached)
- neuPrint: Plaza et al. 2022, neuprint.janelia.org
