Apppublic

whatpull/neuronface

sourceHugging Faceupdated 4mo agoView on Hugging Face

0likes

App README

NeuronFace

PatternKey API는 완전 무료입니다. API 횟수 제한 없음 · 오픈소스 · MIT 라이선스

생물학적 LIF (Leaky Integrate-and-Fire) 뉴런과 피질 계층 구조 기반의 연구용 신경망 백엔드. 별도 브라우저 라이브러리 handface (MediaPipe 기반 손 제스처/시선 추적) 가 추출한 이벤트를 자극으로 받아 발화 패턴을 시뮬레이션합니다. FastAPI 위에서 동작하며 뉴런 코어는 표준 라이브러리만으로 구현되어 추가 의존성이 없습니다.

Quickstart

bash

pip install -r requirements.txt
uvicorn app:app --reload --port 7860

기동 후 http://localhost:7860/docs 에서 Swagger UI 로 모든 엔드포인트를 확인할 수 있습니다.

Docker

bash

docker build -t neuronface .
docker run -p 7860:7860 neuronface

API 키 보호가 필요하면 NEURONFACE_API_KEY 환경변수를 전달:

bash

docker run -p 7860:7860 -e NEURONFACE_API_KEY=your-secret neuronface

키가 설정되면 모든 엔드포인트에 Authorization: Bearer <key> 또는 X-API-Key: <key> 헤더가 필요합니다. 미설정 시 오픈 모드 (연구 환경 기본값).

Version

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 = (ncluster=0 OR toprate < minwinnerratehz=30 OR topshare < ρ). 회귀: teststdp 29/29 PASS, e2e 3/3 PASS (ncluster=4 명시 fixture 정합), n=20 spawn path 10/10 PASS.

v0.2.3-anchor-sync (2026-05-10) — STDPWMAX 3-way SOT 정합 (CLAUDE/PAPER/teststdp). SOT=40 (PAPER §5.2 학술 정합, Diehl-Cook 2015 normalized wmax 1.0 + base 0.2-0.5 의 3× ratio). Phase 4 historic baseline 정직 명시 (README Roadmap L110). 회로 변경 0, sanity recalc only.

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 해소.

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, maxclusters cap=64), `clustertrainsupervised` / `clustertrainrstdp` 영역 dynamic cluster N (`activenclusters` 영역 out** prefix scan).

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 정합 (weightchangescount=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 추적).

API 개요 (~70 endpoints, 2026-05-05 현재)

전체 endpoint 는 /docs 또는 app.py 참조. 아래는 (a) handface frontend 가 실제로 호출하는 main path 와 (b) backend 에는 구현되어 있으나 handface 가 호출하지 않는 advanced/research path 를 정직하게 분리한다.

Main path — handface 가 실제로 사용

handface 클라이언트 (src/lib/backend/client.ts) 가 호출하는 4 단계:

단계	Method	Path	설명
1	`POST`	`/networks`	새 시뮬레이션 세션 생성
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)
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 절감 목적)
3b	`POST`	`/networks/{id}/cluster_train_supervised`	cluster prefix `out_{c}_` 8 OUT 모두 supervisor batch 학습 (N3 핵심 학습 path)
3c	`POST`	`/networks/{id}/cluster_lock`	TRAINED cluster 8 OUT incoming 시냅스 freeze
4	`DELETE`	`/networks/{id}`	세션 삭제

이 경로가 handface 실시간 hand-gesture → SNN 학습 루프의 전부이다. clusterlock 이후 backend STDP gate 만 frozen 으로 정합되며, 추가 reward-modulated 펄스나 Vth regulation 은 적용되지 않는다.

Advanced / research path — backend 구현, handface 미호출

아래 endpoint 는 backend 에 사실로 구현되어 있고 /docs 에서 직접 호출 가능하지만, 현재 handface frontend 는 호출하지 않는다. 학술 reference / 다른 클라이언트 / 향후 확장을 위해 보존된다.

Method	Path	설명	handface 사용
`POST`	`/networks/{id}/snapshot-weights` + `/rstdp-pulse`	R-STDP 2-step reward-modulated 증폭	미사용
`POST`	`/networks/{id}/astrocytes/homeostasis_step`	per-neuron V_th regulation (Turrigiano 1998 정합, silence escape)	미사용
`POST`	`/networks/{id}/homeostatic`	synaptic scaling	미사용 (client method 정의만 존재, callsite 0)
`GET`	`/networks/{id}/training/snapshot` + `POST /training/load`	학습 weight Save/Load	미사용
`POST`	`/networks/{id}/reset`	동력만 reset (구조 보존)	미사용
`POST`	`/networks/{id}/run`	지정 시간만큼 시뮬레이션 진행 후 스파이크 시점 반환	미사용

추가 90+ brain regions / verification suite / oscillation tools / paper export endpoint 도 동일한 advanced 범주이며 /docs 에서 확인 가능하다.

Project structure

neuronface/
├── app.py                  FastAPI 서버
├── modules/
│   ├── __init__.py
│   ├── neuron.py           LIF 뉴런 + Synapse
│   ├── monitoring.py       SpikeMonitor (ring buffer + 발화율)
│   ├── network.py          REST 세션용 평탄 NeuralNetwork + Registry (런타임 핵심)
│   ├── vectorized.py       NumPy vectorization 모드 (옵션)
│   ├── d1_db.py            Cloudflare D1 marketplace 연동
│   └── _archive/
│       └── brain.py        계층 구조 데모 (Network/Region/Column/Population)
│                           — runtime import 0, 학술 reference 보존용 archived (commit de4a658)
├── requirements.txt
├── Dockerfile
├── README.md
├── CLAUDE.md               개발자용 상세 가이드 (생물학 상수, 제약, 회귀 기준선)
└── .gitignore

설계 원칙·생물학적 상수·내부 제약·결정론 기준선은 CLAUDE.md 참조.

Roadmap

—[x] Phase 1 — LIF neurons
—[x] Phase 2 — Cortical hierarchy
—[x] Phase 3 — Monitoring layer (SpikeMonitor)
—[x] Phase 4 — STDP (ALTP=0.01, ALTD=0.0105, WMAX=320, tau=20ms) [historic baseline; SOT v0.2.2: ALTP=0.0005, W_MAX=40, see PAPER §5.2 / Phase E commit 25ba2aa]
—[x] Phase 5 — Neuromodulation (DA/ACh/5-HT/NE)
—[x] Phase 6 — FastAPI backend
—[x] Phase 7 — NumPy vectorization (modules/vectorized.py, 활성 여부는 모드 선택)
—[x] P200 milestone — 90+ brain regions, ~70 endpoints, 6 verification suite, 5 oscillation tools, 4 cluster preset, E2E pipeline, paper export
—[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) + clustertrainsupervised + cluster_lock + R-STDP 2-step (snapshot-weights + rstdp-pulse) + per-neuron astrocyte homeostasis

License

Apache License 2.0. See LICENSE for details.