whatpull/neuronface

1---2title: NeuronFace3emoji: 🧠4colorFrom: purple5colorTo: blue6sdk: docker7app_file: app.py8pinned: false9---10 11# NeuronFace12 13> **PatternKey API는 완전 무료입니다.**14> API 횟수 제한 없음 · 오픈소스 · MIT 라이선스15 16생물학적 LIF (Leaky Integrate-and-Fire) 뉴런과 피질 계층 구조 기반의 연구용 신경망 백엔드. 별도 브라우저 라이브러리 [handface](https://github.com/whatpull/handface) (MediaPipe 기반 손 제스처/시선 추적) 가 추출한 이벤트를 자극으로 받아 발화 패턴을 시뮬레이션합니다. FastAPI 위에서 동작하며 뉴런 코어는 표준 라이브러리만으로 구현되어 추가 의존성이 없습니다.17 18## Quickstart19 20```bash21pip install -r requirements.txt22uvicorn app:app --reload --port 786023```24 25기동 후 [http://localhost:7860/docs](http://localhost:7860/docs) 에서 Swagger UI 로 모든 엔드포인트를 확인할 수 있습니다.26 27## Docker28 29```bash30docker build -t neuronface .31docker run -p 7860:7860 neuronface32```33 34API 키 보호가 필요하면 `NEURONFACE_API_KEY` 환경변수를 전달:35 36```bash37docker run -p 7860:7860 -e NEURONFACE_API_KEY=your-secret neuronface38```39 40키가 설정되면 모든 엔드포인트에 `Authorization: Bearer <key>` 또는 `X-API-Key: <key>` 헤더가 필요합니다. 미설정 시 오픈 모드 (연구 환경 기본값).41 42## Version43 44`v0.2.4-zero-init-dynamic-cluster` (2026-05-10) — zero-init dynamic cluster paradigm. `build_feature16_preset` default `n_cluster=0` (legacy 4-cluster baseline 폐기). 모든 cluster 영역 사용자 입력 영역 `_grow_cluster` 영역 동적 spawn. 신규 endpoint `POST /networks/{id}/cluster/auto_train_or_spawn` — vigilance evaluate + spawn-or-reinforce 1-call (사용자 catch: 첫 입력 영역 cluster 0 first-spawn, 신규 distinct pattern 영역 cluster N+1 spawn, 동일 입력 영역 기존 cluster 강화). novel decision = (n_cluster=0 OR top_rate < min_winner_rate_hz=30 OR top_share < ρ). 회귀: test_stdp 29/29 PASS, e2e 3/3 PASS (n_cluster=4 명시 fixture 정합), n=20 spawn path 10/10 PASS.45 46`v0.2.3-anchor-sync` (2026-05-10) — STDP_W_MAX 3-way SOT 정합 (CLAUDE/PAPER/test_stdp). SOT=40 (PAPER §5.2 학술 정합, Diehl-Cook 2015 normalized w_max 1.0 + base 0.2-0.5 의 3× ratio). Phase 4 historic baseline 정직 명시 (README Roadmap L110). 회로 변경 0, sanity recalc only.47 48 49`v0.2.2-cascade-restore` (2026-05-10) — selectivity 0/4 → 10/10 회복 (B+17 V2 cascade wiring restore: `_grow_cluster` 영역 stale B+15 weight (0.30/5.0, 0.45/9.0) → B+17 (0.40/7.0, 0.65/11.0, 0.70/12.0, 0.65/13.0) sync. audit round 4 fix #11). vigilance spawn 후 신규 cluster cascade dead 영역 root cause 해소.50 51`v0.2.1-dynamic-cluster` (2026-05-10) — backend ART vigilance scaffolding (Carpenter-Grossberg ρ share metric + `_grow_cluster` + dynamic `range(N)` training). `POST /networks/{id}/cluster/vigilance` (share metric, novel→spawn, max_clusters cap=64), `cluster_train_supervised` / `cluster_train_rstdp` 영역 dynamic cluster N (`_active_n_clusters` 영역 out_*_* prefix scan).52 53**v0.2.2 검증**: `tests/probes/probe_dynamic_cluster_n20.py` 영역 spawn 10/10 PASS + match 10/10 PASS. novel-then-train: `_grow_cluster` cascade weights B+17 sync 정합 (weight_changes_count=457, cluster 4 STDP 직접 증거) — 단 inject self-match 미달성, root cause = probe `[0.7]*16` uniform pattern 영역 cluster 1 의 canonical IN[4..7] strong cascade 영역 불일치 (probe wiring 한계, 별 turn 추적).54 55## API 개요 (~70 endpoints, 2026-05-05 현재)56 57전체 endpoint 는 `/docs` 또는 [app.py](app.py) 참조. 아래는 (a) handface frontend 가 실제로 호출하는 main path 와 (b) backend 에는 구현되어 있으나 handface 가 호출하지 않는 advanced/research path 를 정직하게 분리한다.58 59### Main path — handface 가 실제로 사용60 61handface 클라이언트 ([src/lib/backend/client.ts](https://github.com/whatpull/handface/blob/main/src/lib/backend/client.ts)) 가 호출하는 4 단계:62 63| 단계 | Method | Path | 설명 |64|------|--------|------|------|65| 1 | `POST` | `/networks` | 새 시뮬레이션 세션 생성 |66| 2 | `POST` | `/networks/{id}/presets/feature16` (또는 `/presets/basic`) | N3 cortical preset (default `v1_l4e_count=200` → 472 neurons / OUT 32 cluster 4×8 / WTA / NMDA; handface default `v1_l4e_count=50` → 322 neurons) |67| 3a | `POST` | `/networks/{id}/inject_feature16` | 16-dim 자극 + cascade fire (B+3 응답 schema: `out_rates` 32 OUT Hz / `cluster_rates` 4-cluster mean Hz / `winner_cluster` argmax (idle 시 -1) / `winner_margin` (top−2nd)/max(top,1.0) ∈ [0..1] / `synapses_changed` delta only — handface state_payload round-trip 절감 목적) |68| 3b | `POST` | `/networks/{id}/cluster_train_supervised` | cluster prefix `out_{c}_` 8 OUT 모두 supervisor batch 학습 (N3 핵심 학습 path) |69| 3c | `POST` | `/networks/{id}/cluster_lock` | TRAINED cluster 8 OUT incoming 시냅스 freeze |70| 4 | `DELETE` | `/networks/{id}` | 세션 삭제 |71 72이 경로가 handface 실시간 hand-gesture → SNN 학습 루프의 전부이다. cluster_lock 이후 backend STDP gate 만 frozen 으로 정합되며, 추가 reward-modulated 펄스나 V_th regulation 은 적용되지 않는다.73 74### Advanced / research path — backend 구현, handface 미호출75 76아래 endpoint 는 backend 에 사실로 구현되어 있고 `/docs` 에서 직접 호출 가능하지만, 현재 handface frontend 는 호출하지 않는다. 학술 reference / 다른 클라이언트 / 향후 확장을 위해 보존된다.77 78| Method | Path | 설명 | handface 사용 |79|--------|------|------|--------------|80| `POST` | `/networks/{id}/snapshot-weights` + `/rstdp-pulse` | R-STDP 2-step reward-modulated 증폭 | 미사용 |81| `POST` | `/networks/{id}/astrocytes/homeostasis_step` | per-neuron V_th regulation (Turrigiano 1998 정합, silence escape) | 미사용 |82| `POST` | `/networks/{id}/homeostatic` | synaptic scaling | 미사용 (client method 정의만 존재, callsite 0) |83| `GET` | `/networks/{id}/training/snapshot` + `POST /training/load` | 학습 weight Save/Load | 미사용 |84| `POST` | `/networks/{id}/reset` | 동력만 reset (구조 보존) | 미사용 |85| `POST` | `/networks/{id}/run` | 지정 시간만큼 시뮬레이션 진행 후 스파이크 시점 반환 | 미사용 |86 87추가 90+ brain regions / verification suite / oscillation tools / paper export endpoint 도 동일한 advanced 범주이며 `/docs` 에서 확인 가능하다.88 89## Project structure90 91```92neuronface/93├── app.py                  FastAPI 서버94├── modules/95│   ├── __init__.py96│   ├── neuron.py           LIF 뉴런 + Synapse97│   ├── monitoring.py       SpikeMonitor (ring buffer + 발화율)98│   ├── network.py          REST 세션용 평탄 NeuralNetwork + Registry (런타임 핵심)99│   ├── vectorized.py       NumPy vectorization 모드 (옵션)100│   ├── d1_db.py            Cloudflare D1 marketplace 연동101│   └── _archive/102│       └── brain.py        계층 구조 데모 (Network/Region/Column/Population)103│                           — runtime import 0, 학술 reference 보존용 archived (commit de4a658)104├── requirements.txt105├── Dockerfile106├── README.md107├── CLAUDE.md               개발자용 상세 가이드 (생물학 상수, 제약, 회귀 기준선)108└── .gitignore109```110 111설계 원칙·생물학적 상수·내부 제약·결정론 기준선은 [CLAUDE.md](CLAUDE.md) 참조.112 113## Roadmap114 115- [x] Phase 1 — LIF neurons116- [x] Phase 2 — Cortical hierarchy117- [x] Phase 3 — Monitoring layer (SpikeMonitor)118- [x] Phase 4 — STDP (A_LTP=0.01, A_LTD=0.0105, W_MAX=320, tau=20ms) [historic baseline; SOT v0.2.2: A_LTP=0.0005, W_MAX=40, see PAPER §5.2 / Phase E commit 25ba2aa]119- [x] Phase 5 — Neuromodulation (DA/ACh/5-HT/NE)120- [x] Phase 6 — FastAPI backend121- [x] Phase 7 — NumPy vectorization (`modules/vectorized.py`, 활성 여부는 모드 선택)122- [x] P200 milestone — 90+ brain regions, ~70 endpoints, 6 verification suite, 5 oscillation tools, 4 cluster preset, E2E pipeline, paper export123- [x] Session 53 (2026-05-05) — N3 cortical preset (feature16: default `v1_l4e_count=200` → 472 neurons; handface client default `v1_l4e_count=50` → 322 neurons / OUT 32 cluster) + cluster_train_supervised + cluster_lock + R-STDP 2-step (snapshot-weights + rstdp-pulse) + per-neuron astrocyte homeostasis124 125## License126 127Apache License 2.0. See [LICENSE](./LICENSE) for details.128