docs/SPEC.md

Neural MRI Scanner — Implementation Specification

Model Resonance Imaging for AI Interpretability

Project Codename: NeuralMRI
Full Name: Neural MRI — Model Resonance Imaging
Version: 0.1 (MVP)
Date: 2026-02-24
Author: JJ (Asia2G Capital / ModuLabs)

---

1. Executive Summary

Neural MRI Scanner는 오픈소스 LLM 내부를 뇌 MRI처럼 시각화하고, 실시간으로 자극(perturbation)을 가해 변화를 관찰할 수 있는 AI 모델 해석 도구(interpretability tool)다. MRI는 Model Resonance Imaging의 약자로, 의료 MRI(Magnetic Resonance Imaging)가 뇌의 내부를 들여다보듯 AI 모델 내부에서 특정 입력에 "공명(resonate)"하는 뉴런과 회로를 찾아 영상화한다는 의미를 담고 있다.

핵심 아이디어: 의료 영상(T1, T2, fMRI, DTI, FLAIR)의 멀티모달 스캔 패러다임을 그대로 AI 모델 내부 분석에 매핑한다. 연구자뿐 아니라 엔지니어, 의사결정자도 "이 모델 내부에서 무슨 일이 일어나는지" 직관적으로 파악할 수 있게 한다.

대상 사용자:

• AI 엔지니어 (모델 디버깅, 파인튜닝 문제 진단)
• 연구자 (mechanistic interpretability 연구 보조)
• 기술 리더/의사결정자 (모델 행동에 대한 직관 확보)

---

2. MRI Modality → AI Interpretability 매핑

이 프로젝트의 핵심 프레임워크. 각 의료 영상 기법이 AI 모델의 어떤 측면을 보여주는지 정의한다. 의료 MRI의 용어 체계를 AI 맥락으로 완전히 재정의하여 프로젝트 고유의 용어 세계관을 구축한다.

Terminology Map

의료 원본	Neural MRI 재정의	풀네임	의미
MRI (Magnetic Resonance Imaging)	MRI	Model Resonance Imaging	AI 모델 내부 공명 영상
T1-weighted	T1	Topology Layer 1	1차 구조 — 정적 아키텍처 토폴로지
T2-weighted	T2	Tensor Layer 2	2차 구조 — 텐서(가중치) 분포
fMRI (functional Magnetic Resonance Imaging)	fMRI	functional Model Resonance Imaging	기능적 활성화 영상
DTI (Diffusion Tensor Imaging)	DTI	Data Tractography Imaging	데이터 흐름 경로 추적
FLAIR (Fluid-Attenuated Inversion Recovery)	FLAIR	Feature-Level Anomaly Identification & Reporting	피처 수준 이상 탐지 및 보고

2.1 T1 — Topology Layer 1 (Model Architecture)

항목	설명
의료 원본	T1-weighted MRI: 조직의 해부학적 구조를 보여줌
AI 매핑	모델의 정적 구조 — 레이어 수, 각 레이어의 뉴런/head 수, 파라미터 카운트
시각화	각 레이어를 노드 클러스터로, 크기는 파라미터 수에 비례. 그레이스케일 톤
데이터 소스	model.config 에서 직접 추출 (정적)
인터랙션	호버 시 레이어 상세 정보 표시 (hidden_size, num_heads, intermediate_size 등)

2.2 T2 — Tensor Layer 2 (Weight Distribution)

항목	설명
의료 원본	T2-weighted MRI: T1과 다른 타이밍으로 다른 조직 대조를 보여줌
AI 매핑	가중치(weight)의 분포, magnitude, 통계적 특성
시각화	각 뉴런/head의 weight magnitude를 블루 스케일 히트맵으로 표현. 밝을수록 큰 가중치
데이터 소스	model.state_dict()에서 각 레이어의 weight tensor → 통계 (mean, std, max, L2 norm)
인터랙션	레이어별/head별 weight 히스토그램 표시. 이상치(outlier) 가중치 하이라이트

2.3 fMRI — functional Model Resonance Imaging (Activation Patterns)

항목	설명
의료 원본	fMRI: 혈류 변화로 뇌의 활성화 영역을 실시간으로 보여줌
AI 매핑	특정 입력(prompt)에 대한 각 레이어/뉴런의 활성화(activation) 패턴
시각화	Cool-to-Hot 컬러맵 (파랑→노랑→빨강). 활성화가 높은 뉴런이 "뜨겁게" 표시. 실시간 펄스 애니메이션
데이터 소스	TransformerLens의 run_with_cache() → 각 레이어별 activation tensor
인터랙션	프롬프트를 바꾸면 activation이 실시간으로 변화. 토큰별 step-through 가능
핵심 기술	hook_resid_post, hook_attn_out, hook_mlp_out 에서 캐싱

2.4 DTI — Data Tractography Imaging (Circuit Tracing)

항목	설명
의료 원본	DTI: 백질의 신경섬유 트랙을 추적하여 뇌 영역 간 연결을 보여줌
AI 매핑	정보가 어떤 경로(attention head → MLP → 다음 레이어)로 흐르는지 추적
시각화	방향별 색상 인코딩(directional color encoding). 유의미한 정보 흐름 경로만 굵은 곡선으로 표시. 흐름 방향 애니메이션
데이터 소스	(1) Attention pattern: 각 head의 attention matrix. (2) Attribution patching: 각 컴포넌트의 출력 기여도
인터랙션	특정 출력 토큰 선택 시 해당 토큰에 가장 기여한 경로가 하이라이트됨
핵심 기술	TransformerLens의 activation patching, attention pattern 추출

2.5 FLAIR — Feature-Level Anomaly Identification & Reporting (Bias & Hallucination Detection)

항목	설명
의료 원본	FLAIR: 병변(lesion)을 강조하여 이상 부위를 명확하게 보여줌
AI 매핑	모델의 "문제 지점" — 할루시네이션, 편향, 불확실성이 높은 영역
시각화	정상 영역은 어둡게, 이상 영역은 빨간색/핑크색으로 펄스. 이상 점수에 따른 강도
데이터 소스	(1) Logit lens: 중간 레이어의 예측이 최종 예측과 얼마나 다른지. (2) Entropy: 각 위치의 다음 토큰 예측 불확실성. (3) SAE feature 중 알려진 편향/할루시네이션 관련 feature의 활성화
인터랙션	이상 노드 클릭 시 해당 뉴런/feature의 상세 정보, 관련 학습 데이터 패턴 추정

---

3. System Architecture

┌─────────────────────────────────────────────────────┐
│                    Frontend (React)                   │
│  ┌───────────┐  ┌───────────┐  ┌──────────────────┐ │
│  │ MRI Canvas │  │ Mode Tabs │  │ Control Panels   │ │
│  │ (D3 / SVG) │  │ T1~FLAIR  │  │ Stim, Perturb,  │ │
│  │            │  │           │  │ Layer Summary    │ │
│  └─────┬─────┘  └───────────┘  └──────────────────┘ │
│        │  WebSocket (real-time activation stream)     │
├────────┼────────────────────────────────────────────┤
│        ▼          Backend (FastAPI + Python)          │
│  ┌───────────┐  ┌───────────┐  ┌──────────────────┐ │
│  │ Model      │  │ Analysis  │  │ Perturbation     │ │
│  │ Manager    │  │ Engine    │  │ Engine           │ │
│  │ (load/     │  │ (Trans-   │  │ (activation      │ │
│  │  swap)     │  │  formerLens│ │  patching, etc.) │ │
│  └───────────┘  └───────────┘  └──────────────────┘ │
│        │                                              │
│  ┌─────▼───────────────────────────────────────────┐ │
│  │  Model Registry (HuggingFace Hub cache)          │ │
│  │  Llama-3.2-3B, Qwen-2.5-3B, Gemma-2-2B, etc.   │ │
│  └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

3.1 Frontend

항목	기술
Framework	React 18+ (Vite)
시각화 엔진	D3.js (SVG 기반) — 뉴런/연결 렌더링
실시간 통신	WebSocket (activation 스트리밍)
상태 관리	Zustand (경량)
스타일	Tailwind CSS + CSS Variables (DICOM 테마)
애니메이션	requestAnimationFrame (캔버스 펄스), CSS transitions (UI)

3.2 Backend

항목	기술
서버	FastAPI (Python 3.11+)
모델 인트로스펙션	TransformerLens (HookedTransformer)
SAE 분석	SAELens (선택사항, Phase 2)
텐서 연산	PyTorch 2.x
모델 로딩	HuggingFace transformers + accelerate
WebSocket	fastapi[websockets]
시리얼라이즈	orjson (대용량 텐서 데이터 직렬화)

3.3 지원 모델 (MVP)

모델	파라미터	TransformerLens 지원	우선순위
GPT-2 small (124M)	124M	✅ 공식 지원	P0 (개발/테스트용)
GPT-2 medium (355M)	355M	✅ 공식 지원	P0
Pythia-1.4B	1.4B	✅ 공식 지원	P0
Gemma-2-2B	2B	✅ 지원	P1
Llama-3.2-3B	3.21B	⚠️ 커뮤니티 지원	P1
Qwen-2.5-3B	3B	⚠️ 커뮤니티/커스텀	P1
Mistral-7B-v0.3	7.24B	⚠️ 커뮤니티 지원	P2 (GPU 필요)
Phi-3-mini-3.8B	3.8B	⚠️ 커스텀 필요	P2

참고: TransformerLens는 GPT-2, Pythia 계열이 가장 안정적. Llama/Qwen 등은 HookedTransformer.from_pretrained() 호환성 확인 필요. 미지원 모델은 nnsight로 대체 가능.

---

4. API Design

4.1 REST Endpoints

POST   /api/model/load          모델 로드 (HuggingFace ID 또는 로컬 경로)
GET    /api/model/info           현재 로드된 모델의 구조 정보 (T1 데이터)
DELETE /api/model/unload         모델 언로드 (메모리 해제)

POST   /api/scan/structural      T1 스캔: 정적 구조 데이터 반환
POST   /api/scan/weights         T2 스캔: weight 통계 반환
POST   /api/scan/activation      fMRI 스캔: 프롬프트 기반 activation 반환
POST   /api/scan/circuits        DTI 스캔: attention + attribution 경로 반환
POST   /api/scan/anomaly         FLAIR 스캔: 이상 탐지 결과 반환

POST   /api/perturb/zero         특정 컴포넌트 zero-out
POST   /api/perturb/amplify      특정 컴포넌트 amplify (factor)
POST   /api/perturb/ablate       특정 컴포넌트 ablate (제거)
POST   /api/perturb/inject       특정 위치에 activation 주입
POST   /api/perturb/patch        activation patching (causal tracing)
POST   /api/perturb/reset        perturbation 초기화 (원본 복원)

GET    /api/features/list        SAE feature 목록 (Phase 2)
POST   /api/features/activate    특정 SAE feature 활성화/비활성화 (Phase 2)

4.2 WebSocket Endpoint

WS  /ws/stream

클라이언트 → 서버:
{
  "type": "scan_stream",
  "mode": "fMRI",
  "prompt": "The capital of France is",
  "token_step": true       // true면 토큰별로 스트리밍
}

서버 → 클라이언트:
{
  "type": "activation_frame",
  "token_idx": 3,
  "token": "capital",
  "layers": [
    {
      "layer_id": "blocks.0.attn",
      "type": "attention",
      "activations": [0.12, 0.87, ...],   // 요약된 per-head 값
      "attention_pattern": [[...], ...]     // DTI 모드 시 포함
    },
    ...
  ]
}

4.3 요청/응답 스키마 예시

POST /api/scan/activation

Request:

{
  "prompt": "The Eiffel Tower is located in",
  "layers": "all",              // 또는 ["blocks.3.mlp", "blocks.4.attn"]
  "aggregation": "l2_norm",     // "l2_norm" | "max" | "mean" | "raw"
  "include_residual": true,
  "token_positions": "all"      // 또는 [0, 1, 5]  (특정 토큰 위치)
}

Response:

{
  "model": "gpt2-small",
  "prompt_tokens": ["The", " Eiff", "el", " Tower", " is", " located", " in"],
  "scan_mode": "fMRI",
  "data": {
    "embed": {
      "type": "embedding",
      "shape": [7, 768],
      "activations_summary": [0.45, 0.52, 0.48, 0.61, 0.33, 0.55, 0.41]
    },
    "blocks.0.attn": {
      "type": "attention",
      "num_heads": 12,
      "per_head_activation": [0.12, 0.87, 0.34, ...],
      "attention_patterns": {
        "shape": [12, 7, 7],
        "data_url": "/api/tensor/attn_0_patterns"
      }
    },
    "blocks.0.mlp": {
      "type": "mlp",
      "activation_summary": [0.22, 0.91, 0.45, ...],
      "top_neurons": [
        {"idx": 1247, "activation": 3.82, "label": null},
        {"idx": 892, "activation": 2.91, "label": null}
      ]
    }
  },
  "metadata": {
    "compute_time_ms": 342,
    "gpu_memory_mb": 1240
  }
}

POST /api/perturb/patch

Request:

{
  "prompt": "The Eiffel Tower is located in",
  "target_token_idx": -1,
  "target_component": "blocks.5.mlp",
  "method": "zero",
  "compare_logits": true
}

Response:

{
  "original_prediction": {
    "token": " Paris",
    "logit": 12.34,
    "prob": 0.87
  },
  "perturbed_prediction": {
    "token": " the",
    "logit": 8.12,
    "prob": 0.23
  },
  "logit_diff": -4.22,
  "affected_components": [
    {"id": "blocks.5.mlp", "impact_score": 0.92},
    {"id": "blocks.6.attn.head_3", "impact_score": 0.45}
  ]
}

---

5. Frontend Specification

5.1 전체 레이아웃

┌─ Top Bar ──────────────────────────────────────────────────┐
│ [●] NEURAL MRI  │  Model Resonance Imaging  │  Model: [Dropdown ▾]  │  GPU: 2.1GB/8GB │
├─ Mode Tabs ────────────────────────────────────────────────┤
│ [ T1 Topology ] [ T2 Tensor ] [ fMRI ]                    │
│ [ DTI ] [ FLAIR ]                                          │
├────────────────────────────────┬────────────────────────────┤
│                                │  Layer Summary             │
│   DICOM Header                 │  ├─ Embed:  ████░░ 0.45  │
│   ┌──────────────────────┐     │  ├─ Attn1:  ██████ 0.87  │
│   │                      │     │  ├─ MLP1:   ███░░░ 0.34  │
│   │    Main Scan Canvas   │     │  └─ ...                   │
│   │    (SVG/D3)           │     │                            │
│   │                      │     │  ◉ Stimulation Panel       │
│   │    - neurons          │     │  ID: blocks.3.attn.h7     │
│   │    - connections      │     │  Activation: 0.8721       │
│   │    - flow animations  │     │  [Zero] [Amp] [Inv]       │
│   │                      │     │  [Noise] [Ablate]          │
│   └──────────────────────┘     │                            │
│                                │  Comparison Panel          │
│   PROMPT: [________________]   │  Original: "Paris" (0.87)  │
│   [▶ SCAN] [⏸ PAUSE] [↺ RESET]│  Perturbed: "the" (0.23)  │
│                                │                            │
├── Log Panel ───────────────────┴────────────────────────────┤
│ [00:12] Scan complete — Mode: fMRI, 7 tokens processed     │
│ [00:14] Perturbation: Zero-out on blocks.3.attn.head_7     │
└─────────────────────────────────────────────────────────────┘

5.2 디자인 시스템

테마: "Medical Dark" — DICOM 뷰어 + 수술실 모니터 미학

/* Color Palette */
--bg-primary:     #0a0c10;     /* 거의 검정, 약간 블루 */
--bg-secondary:   #0c0e14;     /* 패널 배경 */
--bg-surface:     #12151c;     /* 카드/입력 배경 */
--border:         rgba(100, 170, 136, 0.15);  /* 의료 그린 보더 */
--text-primary:   #66aa88;     /* 의료 그린 텍스트 */
--text-secondary: #556;        /* 회색 보조 텍스트 */
--text-data:      #aabbcc;     /* 데이터 값 */
--accent-active:  #00ffaa;     /* 선택/활성 하이라이트 */
--scan-line:      rgba(255, 255, 255, 0.04);  /* 스캔라인 오버레이 */

/* Mode-specific Colors (T1=Topology, T2=Tensor, fMRI=functional MRI, DTI=Data Tractography, FLAIR=Feature-Level Anomaly) */
--t1-base:     #8899aa;   --t1-accent:  #e0e0e0;
--t2-base:     #4488cc;   --t2-accent:  #aaccee;
--fmri-cold:   #1a2a5a;   --fmri-warm:  #cc8830;  --fmri-hot: #ff4420;
--dti-green:   #44ddaa;   --dti-purple: #8866ff;
--flair-normal:#334;       --flair-hot:  #ff4466;

/* Typography — Monospace only */
--font-primary: 'JetBrains Mono', 'Fira Code', 'Courier New', monospace;
--font-size-xs:  9px;   /* 로그, 범례 */
--font-size-sm:  10px;  /* 라벨, 탭 */
--font-size-md:  11px;  /* 본문 데이터 */
--font-size-lg:  14px;  /* 타이틀 */

필수 비주얼 요소:

1. 스캔라인 오버레이 — 캔버스 위에 1px 간격의 수평선. opacity 0.03~0.05. CRT 모니터 느낌
2. DICOM 헤더 — 캔버스 상단에 의료 영상 스타일의 메타데이터 (모델명, 시퀀스, 날짜/시간, FOV, "Model Resonance Imaging" 표기)
3. Vignette 효과 — 캔버스 가장자리가 살짝 어두워지는 효과
4. Pulse 애니메이션 — fMRI 모드에서 활성화된 뉴런의 크기와 밝기가 주기적으로 미세하게 변동
5. Flow 애니메이션 — DTI 모드에서 연결선을 따라 작은 입자/밝기가 흐르는 효과

5.3 Canvas 렌더링 사양

뉴런(노드) 렌더링

각 뉴런은 원(circle)으로 표현.

위치 결정:
- Y축: 레이어 순서 (상단 = embedding, 하단 = output)
- X축: 같은 레이어 내 뉴런들이 수평으로 분포
- 레이어 간 간격: 60~80px
- 뉴런 간 간격: 레이어 내 뉴런 수에 따라 자동 조정

크기 결정 (모드별):
- T1: 파라미터 수에 비례 (4~10px 반지름)
- T2: weight magnitude에 비례
- fMRI: base 크기 × (0.5 + activation × 1.0) × pulse_factor
- DTI: 일정 크기, 색상으로 방향 인코딩
- FLAIR: 정상=작게, 이상=크게 + 펄스

색상 결정 (모드별):
- T1: 그레이스케일 (rgb(v,v,v+10), v = 160~220)
- T2: 블루 스케일 (weight 작으면 어두운 남색, 크면 밝은 하늘색)
- fMRI: cool-to-hot colormap
  - activation < 0.3: 어두운 파랑 rgb(30+a*80, 30+a*100, 80+a*120)
  - activation 0.3~0.6: 노랑/주황 rgb(a*200, a*160, 40+a*60)
  - activation > 0.6: 빨강/흰 rgb(200+a*55, a*120, a*30)
- DTI: HSL, hue = (x/width)*120 + (y/height)*120, saturation 70%, lightness 55%
- FLAIR: 정상=rgb(60,65,75), 이상=rgb(255, 50+a*60, 80+a*40) 펄스

연결(엣지) 렌더링

연결은 레이어 간 정보 흐름을 표현.

모드별 표현:
- T1: 얇은 회색 선 (opacity 0.15, width 0.5)
- T2: weight 크기에 따라 opacity와 두께 변화
- fMRI: 양끝 뉴런의 평균 activation에 따라 색상/두께 변화
  - 높은 activation: 핫 컬러, 굵은 선
  - 낮은 activation: 거의 투명
- DTI: 유의미한 pathway만 표시
  - 곡선(quadratic bezier) 사용
  - 방향에 따른 HSL 색상
  - flow 애니메이션 (sin wave로 opacity 변동)
  - 비-pathway 연결은 거의 투명
- FLAIR: 이상 노드에 연결된 엣지만 빨간색 하이라이트

토폴로지 레이아웃 옵션 (Phase 2 이후)

MVP: 수직 레이어 스택 (위→아래)
Phase 2: 사용자가 레이아웃 모드를 선택 가능
  - Stack (기본): 수직 레이어 스택
  - Brain: 타원형 뇌 모양으로 감싸서 배치 (코르티컬 매핑 비유)
  - Network: force-directed 그래프 (D3 force simulation)
  - Radial: 중심에서 바깥으로 레이어가 확장

5.4 인터랙션 사양

뉴런 선택 (Stimulation Mode)

1. 뉴런 클릭 → 선택 상태 진입
2. 선택된 뉴런 주위에 동심원 애니메이션 (green glow)
3. 우측 패널에 상세 정보 표시:
   - Node ID (layer.component.index)
   - Layer type (attention / mlp / embedding / output)
   - 현재 모드의 주요 값 (activation, weight, anomaly score)
   - Top-k 연결된 뉴런 (가장 강한 연결)
4. Perturbation 버튼 활성화:
   - Zero-out: 해당 컴포넌트 출력을 0으로
   - Amplify 2×: 출력을 2배로
   - Invert: 출력 부호 반전
   - Noise ±σ: 가우시안 노이즈 추가
   - Ablate: 완전 제거 (zero + gradient 차단)
5. Perturbation 적용 시:
   - 백엔드에 perturbation 요청 → 새로운 activation 수신
   - 캔버스 전체가 0.3초간 재스캔 애니메이션
   - 변화된 부분이 잠시 하이라이트
   - 우측 Comparison Panel에 before/after 표시

프롬프트 입력 & 스캔

1. 프롬프트 입력 → SCAN 버튼 클릭 (또는 Enter)
2. 스캔 프로그레스 바 표시 (실제 백엔드 처리 시간 반영)
3. WebSocket으로 토큰별 activation 스트리밍
4. 토큰 step-through 가능:
   - 프롬프트 영역에 각 토큰이 칩(chip)으로 표시
   - 토큰 칩 클릭 → 해당 토큰 시점의 activation만 표시
   - ← → 화살표로 토큰 간 이동
   - 자동 재생 (0.5초 간격)

모드 전환

1. 모드 탭 클릭 → 0.3초 크로스페이드 전환
2. 동일한 토폴로지(뉴런 위치)를 유지하면서 색상/크기/연결 표현만 변경
3. 이는 실제 MRI에서 같은 환자의 T1→fMRI 전환과 동일한 경험

5.5 반응형 고려사항

- 최소 지원 해상도: 1280×720
- 권장 해상도: 1920×1080
- 캔버스 크기: 컨테이너에 맞게 스케일링 (SVG viewBox 사용)
- 모바일: 미지원 (데스크톱 전용 도구)

---

6. Backend Specification

6.1 모델 매니저 (ModelManager)

class ModelManager:
    """모델 로딩, 스왑, 메모리 관리"""

    def load_model(self, model_id: str, device: str = "auto") -> ModelInfo:
        """
        HuggingFace 모델을 TransformerLens HookedTransformer로 로드.
        - model_id: "gpt2", "EleutherAI/pythia-1.4b", "meta-llama/Llama-3.2-3B" 등
        - device: "cpu", "cuda", "mps", "auto"
        - 반환: 모델 메타데이터 (레이어 수, hidden size, head 수 등)
        """

    def unload_model(self) -> None:
        """현재 모델 언로드 + GPU 메모리 해제 (gc + torch.cuda.empty_cache)"""

    def get_model_info(self) -> ModelInfo:
        """현재 로드된 모델의 아키텍처 정보 반환 (T1 데이터)"""

    def get_model(self) -> HookedTransformer:
        """현재 로드된 모델 인스턴스 반환"""

6.2 분석 엔진 (AnalysisEngine)

class AnalysisEngine:
    """각 스캔 모드에 대한 분석 수행"""

    def scan_structural(self) -> StructuralData:
        """T1: model.cfg에서 정적 구조 추출"""

    def scan_weights(self, layers: list[str] | None = None) -> WeightData:
        """T2: state_dict에서 weight 통계 추출"""

    def scan_activation(self, prompt: str, **kwargs) -> ActivationData:
        """
        fMRI: prompt에 대한 activation 캐시.
        TransformerLens run_with_cache() 사용.

        핵심 구현:
        logits, cache = model.run_with_cache(prompt)

        추출 대상 hook points:
        - hook_embed: 임베딩 레이어
        - blocks.{i}.hook_resid_pre: 각 블록 입력 residual
        - blocks.{i}.attn.hook_result: attention 출력
        - blocks.{i}.hook_mlp_out: MLP 출력
        - blocks.{i}.hook_resid_post: 각 블록 출력 residual

        aggregation 옵션:
        - "l2_norm": L2 norm per position (스칼라)
        - "max": max absolute value
        - "mean": mean absolute value
        - "raw": 전체 텐서 반환 (대용량, 선택적)
        """

    def scan_circuits(self, prompt: str, target_token: int = -1) -> CircuitData:
        """
        DTI: attention pattern + attribution 경로 추출.

        (1) Attention Pattern:
        _, cache = model.run_with_cache(prompt)
        attn_patterns = cache["blocks.{i}.attn.hook_pattern"]
        → shape: [num_heads, seq_len, seq_len]

        (2) Attribution (간이 버전):
        각 head/mlp의 출력을 zero-out 했을 때 target logit 변화량 계산.
        → 절대값이 큰 컴포넌트 = 중요 경로
        """

    def scan_anomaly(self, prompt: str) -> AnomalyData:
        """
        FLAIR: 이상 탐지.

        (1) Logit Lens:
        각 중간 레이어의 residual stream을 unembed하여
        중간 예측 vs 최종 예측의 KL divergence 계산.
        큰 divergence = 해당 레이어에서 "생각이 크게 바뀜" = 잠재적 이상

        (2) Entropy:
        각 위치의 logit에서 softmax → entropy 계산.
        높은 entropy = 모델이 불확실 = 할루시네이션 위험

        (3) 이상 점수:
        anomaly_score = α * normalized_kl_div + β * normalized_entropy
        α = 0.6, β = 0.4 (튜닝 가능)
        """

6.3 Perturbation 엔진 (PerturbationEngine)

class PerturbationEngine:
    """모델 내부에 자극/변형을 가하고 결과를 비교"""

    def zero_out(self, component: str, prompt: str) -> PerturbResult:
        """
        특정 컴포넌트의 출력을 0으로 만들고 재실행.

        구현:
        def zero_hook(value, hook):
            value[:, :, :] = 0  # 또는 특정 head만
            return value

        model.run_with_hooks(prompt, fwd_hooks=[(component, zero_hook)])
        """

    def amplify(self, component: str, factor: float, prompt: str) -> PerturbResult:
        """출력에 factor를 곱하여 증폭"""

    def ablate(self, component: str, prompt: str) -> PerturbResult:
        """컴포넌트를 완전히 제거 (mean ablation: 평균값으로 대체)"""

    def inject_activation(self, component: str, values: list, prompt: str) -> PerturbResult:
        """특정 activation 값을 직접 주입"""

    def activation_patch(
        self,
        clean_prompt: str,
        corrupt_prompt: str,
        component: str
    ) -> PatchResult:
        """
        Activation Patching (Causal Tracing).

        clean_prompt의 특정 컴포넌트 activation을
        corrupt_prompt 실행 중에 교체하여 복구 정도를 측정.

        구현:
        _, clean_cache = model.run_with_cache(clean_prompt)
        clean_activation = clean_cache[component]

        def patch_hook(value, hook):
            value[:] = clean_activation
            return value

        patched_logits = model.run_with_hooks(
            corrupt_prompt,
            fwd_hooks=[(component, patch_hook)]
        )

        recovery = (patched_logit - corrupt_logit) / (clean_logit - corrupt_logit)
        """

    def compare_results(self, original: Logits, perturbed: Logits) -> ComparisonData:
        """원본과 변형 결과 비교: top-k 예측, logit diff, KL divergence"""

6.4 데이터 요약 전략

대용량 텐서를 프론트엔드로 전송할 때의 요약 전략:

문제: GPT-2 small만 해도 단일 프롬프트에 대한 전체 activation cache가 수백MB.

해결:
1. 기본 응답: 레이어별/head별 요약 통계만 전송 (L2 norm, max, mean → 스칼라 배열)
2. 온디맨드: 사용자가 특정 레이어/head를 선택하면 해당 부분만 상세 데이터 전송
3. 어텐션 패턴: full attention matrix는 요청 시에만 전송 (shape: [heads, seq, seq])
4. 스트리밍: 토큰별 step-through 시 각 토큰의 데이터만 증분 전송
5. 캐싱: 동일 프롬프트에 대한 캐시는 서버 메모리에 보관 (LRU, 최대 5개 프롬프트)

---

7. Implementation Phases

Phase 0: Foundation (1~2주)

목표: 프로젝트 구조 셋업 + GPT-2 small로 T1/T2 모드 작동

Backend:
- [ ] FastAPI 프로젝트 셋업 (poetry/uv 기반 dependency 관리)
- [ ] ModelManager 구현 (GPT-2 small 로드)
- [ ] scan_structural() 구현 → T1 데이터 반환
- [ ] scan_weights() 구현 → T2 데이터 반환
- [ ] 기본 REST API 엔드포인트 (/model/load, /model/info, /scan/structural, /scan/weights)

Frontend:
- [ ] Vite + React 프로젝트 셋업
- [ ] DICOM 테마 CSS 변수 정의
- [ ] 기본 레이아웃 구현 (Top Bar, Mode Tabs, Canvas, Panels)
- [ ] T1 Canvas 렌더링: 모델 구조를 노드/엣지로 시각화
- [ ] T2 Canvas 렌더링: weight 히트맵
- [ ] Model selector dropdown

테스트:
- [ ] GPT-2 small 로드 → T1 데이터 표시 → T2 모드 전환 검증

Phase 1: Core Scanning (2~3주)

목표: fMRI + DTI 모드 작동. 프롬프트 입력 → activation 시각화

Backend:
- [ ] TransformerLens 통합 (HookedTransformer.from_pretrained)
- [ ] scan_activation() 구현 → fMRI 데이터 반환
- [ ] scan_circuits() 구현 → DTI 데이터 반환
- [ ] WebSocket 엔드포인트 (토큰별 activation 스트리밍)
- [ ] 데이터 요약/직렬화 파이프라인 (orjson)

Frontend:
- [ ] fMRI Canvas: cool-to-hot 컬러맵, 펄스 애니메이션
- [ ] DTI Canvas: 곡선 경로, 방향별 색상, flow 애니메이션
- [ ] Prompt 입력 UI + SCAN 버튼 + 프로그레스 바
- [ ] 토큰 step-through UI (토큰 칩 + 화살표 내비게이션)
- [ ] Layer Summary 바 차트 (모드별 적응)
- [ ] WebSocket 연결 + 실시간 업데이트

테스트:
- [ ] "The capital of France is" → fMRI에서 "France" 토큰 시 관련 뉴런 활성화 확인
- [ ] DTI에서 유의미한 information flow 경로 시각화 확인

Phase 2: Perturbation + FLAIR (2~3주)

목표: 자극/변형 실험 + 이상 탐지

Backend:
- [ ] PerturbationEngine 전체 구현 (zero, amplify, ablate, inject, patch)
- [ ] scan_anomaly() 구현 (logit lens + entropy)
- [ ] compare_results() 구현 (before/after 비교)
- [ ] Activation patching (causal tracing) 구현

Frontend:
- [ ] FLAIR Canvas: 이상 영역 하이라이트, 펄스 애니메이션
- [ ] Stimulation Panel: 뉴런 클릭 → 상세 정보 + perturbation 버튼
- [ ] Comparison Panel: 원본 vs 변형 결과 나란히 표시
- [ ] Perturbation 적용 시 재스캔 애니메이션
- [ ] Reset 기능 (모든 perturbation 초기화)
- [ ] 스캔라인 오버레이 + vignette 효과

테스트:
- [ ] 특정 attention head zero-out → 예측 변화 확인
- [ ] "The Eiffel Tower is in" → 사실 관련 컴포넌트 ablation → 할루시네이션 유도 확인
- [ ] FLAIR에서 entropy가 높은 위치가 올바르게 하이라이트되는지 확인

Phase 3: Polish + Multi-Model (2주)

목표: 다중 모델 지원 + UX 완성

Backend:
- [ ] Pythia-1.4B, Gemma-2-2B 지원 추가 및 테스트
- [ ] Llama-3.2-3B 지원 (TransformerLens 호환성 확인, 필요 시 nnsight 대체)
- [ ] 모델 스왑 시 메모리 관리 최적화
- [ ] API 응답 캐싱 레이어

Frontend:
- [ ] 모드 전환 크로스페이드 애니메이션
- [ ] 뉴런 호버 툴팁
- [ ] 전체 스캔라인 + CRT 미학 완성
- [ ] 성능 최적화 (large graph에서 60fps 유지)
- [ ] 에러/로딩 상태 UX

테스트:
- [ ] 모델 간 스왑 시 메모리 누수 없음 확인
- [ ] 3B 모델에서 전체 스캔 파이프라인 e2e 확인

Phase 4: Advanced Features (향후)

- [ ] SAE Feature 탐색기 (SAELens 통합)
- [ ] Brain 레이아웃 모드 (코르티컬 매핑)
- [ ] Multi-prompt 비교 (같은 모델에 다른 입력 시 activation 차이)
- [ ] 시계열 녹화/재생 (스캔 세션 저장)
- [ ] Export: 스캔 결과를 이미지/영상으로 내보내기
- [ ] 협업: 여러 사용자가 같은 스캔 세션을 공유
- [ ] 자동 진단: "이 모델은 이런 문제가 있을 수 있습니다" 보고서 생성

---

8. Development Environment

8.1 필수 요구사항

- Python 3.11+
- Node.js 20+
- GPU: NVIDIA GPU with 8GB+ VRAM (권장). CPU 전용도 가능 (GPT-2 small 한정)
- CUDA 12.x (GPU 사용 시)
- 메모리: 16GB+ RAM

8.2 Backend 의존성

[project]
name = "neural-mri"
requires-python = ">=3.11"

dependencies = [
    "fastapi>=0.110",
    "uvicorn[standard]>=0.27",
    "websockets>=12.0",
    "transformer-lens>=2.0",
    "torch>=2.2",
    "transformers>=4.40",
    "accelerate>=0.28",
    "sae-lens>=3.0",         # Phase 2
    "orjson>=3.9",
    "numpy>=1.26",
    "pydantic>=2.6",
]

8.3 Frontend 의존성

{
  "dependencies": {
    "react": "^18.3",
    "react-dom": "^18.3",
    "d3": "^7.9",
    "zustand": "^4.5",
    "use-websocket": "^4.8"
  },
  "devDependencies": {
    "vite": "^5.4",
    "@vitejs/plugin-react": "^4.2",
    "tailwindcss": "^3.4",
    "autoprefixer": "^10.4",
    "postcss": "^8.4"
  }
}

8.4 프로젝트 구조

neural-mri/
├── README.md
├── docker-compose.yml
│
├── backend/
│   ├── pyproject.toml
│   ├── neural_mri/
│   │   ├── __init__.py
│   │   ├── main.py              # FastAPI app entry
│   │   ├── config.py            # 설정 (모델 경로, 캐시, GPU)
│   │   ├── api/
│   │   │   ├── __init__.py
│   │   │   ├── routes_model.py  # /api/model/* 라우트
│   │   │   ├── routes_scan.py   # /api/scan/* 라우트
│   │   │   ├── routes_perturb.py # /api/perturb/* 라우트
│   │   │   └── ws_stream.py     # WebSocket 핸들러
│   │   ├── core/
│   │   │   ├── __init__.py
│   │   │   ├── model_manager.py
│   │   │   ├── analysis_engine.py
│   │   │   └── perturbation_engine.py
│   │   ├── schemas/
│   │   │   ├── __init__.py
│   │   │   ├── model.py         # ModelInfo, ModelConfig
│   │   │   ├── scan.py          # ActivationData, CircuitData 등
│   │   │   └── perturb.py       # PerturbResult, PatchResult
│   │   └── utils/
│   │       ├── __init__.py
│   │       ├── tensor_summary.py # 텐서 → 요약 변환
│   │       └── serialization.py  # orjson 커스텀 직렬화
│   └── tests/
│       ├── test_model_manager.py
│       ├── test_analysis.py
│       └── test_perturbation.py
│
├── frontend/
│   ├── package.json
│   ├── vite.config.js
│   ├── tailwind.config.js
│   ├── index.html
│   ├── src/
│   │   ├── main.jsx
│   │   ├── App.jsx
│   │   ├── theme/
│   │   │   ├── variables.css    # DICOM 테마 CSS 변수
│   │   │   └── globals.css
│   │   ├── store/
│   │   │   ├── useModelStore.js
│   │   │   ├── useScanStore.js
│   │   │   └── usePerturbStore.js
│   │   ├── components/
│   │   │   ├── TopBar.jsx
│   │   │   ├── ModeTabs.jsx
│   │   │   ├── DicomHeader.jsx
│   │   │   ├── ScanCanvas/
│   │   │   │   ├── ScanCanvas.jsx       # 메인 SVG 캔버스
│   │   │   │   ├── NeuronRenderer.jsx   # 뉴런 렌더링 로직
│   │   │   │   ├── ConnectionRenderer.jsx # 엣지 렌더링 로직
│   │   │   │   ├── ScanLineOverlay.jsx  # CRT 스캔라인
│   │   │   │   └── colorMaps.js         # 모드별 색상 함수
│   │   │   ├── Panels/
│   │   │   │   ├── LayerSummary.jsx     # 레이어별 막대 차트
│   │   │   │   ├── StimPanel.jsx        # 뉴런 선택 + perturbation
│   │   │   │   ├── ComparisonPanel.jsx  # before/after 비교
│   │   │   │   └── LogPanel.jsx         # 하단 로그
│   │   │   ├── PromptInput.jsx
│   │   │   └── TokenStepper.jsx         # 토큰별 step-through
│   │   ├── hooks/
│   │   │   ├── useWebSocket.js
│   │   │   └── useAnimationFrame.js
│   │   └── api/
│   │       ├── client.js                # REST API 클라이언트
│   │       └── ws.js                    # WebSocket 클라이언트
│   └── public/
│       └── fonts/                       # JetBrains Mono
│
└── docs/
    ├── SPEC.md                          # 이 문서
    ├── API.md                           # API 상세 문서
    └── ARCHITECTURE.md                  # 아키텍처 다이어그램

---

9. Key Technical Decisions & Risks

9.1 TransformerLens 호환성

리스크: TransformerLens는 GPT-2, Pythia 등 일부 모델만 공식 지원.
       Llama, Qwen 등은 커뮤니티 구현에 의존하며 버전에 따라 깨질 수 있음.

대응:
1. MVP는 GPT-2 small/medium + Pythia로 시작 (확실한 지원)
2. 새 모델 추가 시 from_pretrained() 호환성 테스트 스크립트 작성
3. TransformerLens 미지원 모델은 nnsight 백엔드로 폴백
4. 모델별 hook point 이름이 다를 수 있으므로 추상화 레이어 필요

9.2 성능

리스크: 3B+ 모델의 full activation cache가 수GB에 달할 수 있음.

대응:
1. 요약 우선 전략: 전체 텐서 대신 per-layer/per-head 통계만 기본 전송
2. Lazy loading: 사용자가 특정 레이어 선택 시에만 상세 데이터 전송
3. 서버사이드 캐싱: 동일 프롬프트에 대한 캐시 유지 (LRU 5개)
4. 토큰 스트리밍: 전체 시퀀스를 한번에 처리하되, 프론트엔드에는 토큰별 전송
5. GPU 메모리: 모델 + 캐시가 VRAM 초과 시 자동으로 CPU 오프로드

9.3 시각화 성능

리스크: 노드/엣지가 수백 개일 때 SVG 렌더링이 느려질 수 있음.

대응:
1. 집약 표현: 개별 뉴런이 아닌 "head" 또는 "layer component" 단위로 노드 표현
   (GPT-2 small: 12 layers × 3 components = ~36 nodes + embedding + output)
2. Viewport culling: 화면에 보이는 노드만 렌더링
3. 엣지 간소화: 모드에 따라 비활성 엣지를 아예 렌더링하지 않음
4. Canvas 전환: SVG 성능 한계 시 WebGL (Three.js) 또는 Canvas 2D로 전환

9.4 Perturbation 안전성

리스크: perturbation이 모델 weight 자체를 수정하면 복구가 어려움.

대응:
1. run_with_hooks()만 사용: 모델 weight는 절대 수정하지 않음. Hook으로 activation만 변형.
2. Reset 버튼: 모든 hook을 제거하고 원본 상태로 복귀
3. 모든 perturbation은 stateless: 각 요청마다 새로 hook을 설정

---

10. Success Metrics

MVP (Phase 0~2 완료 기준)

1. GPT-2 small에 대해 5개 모드 모두 작동
2. 프롬프트 입력 → 스캔 완료까지 2초 이내 (GPU 기준)
3. 토큰 step-through가 smooth하게 작동 (프레임 드롭 없이)
4. perturbation 적용 → 결과 비교가 1초 이내
5. 모드 전환 시 토폴로지 유지하면서 0.3초 이내 전환

확장 (Phase 3 이후)

1. 3B 모델에서 전체 파이프라인 5초 이내
2. 최소 3개 이상의 오픈소스 모델 지원
3. Activation patching (causal tracing) 시각화가 논문 Figure 수준

---

11. References

핵심 라이브러리

• TransformerLens: https://github.com/TransformerLensOrg/TransformerLens
• SAELens: https://github.com/jbloomAus/SAELens
• nnsight: https://github.com/ndif-team/nnsight

핵심 논문/자료

• Elhage et al. (2022) "Toy Models of Superposition" — 중첩(superposition) 이론
• Wang et al. (2022) "Interpretability in the Wild: IOI Circuit" — 회로 분석
• Meng et al. (2022) "ROME: Rank-One Model Editing" — 사실 저장 위치 추적
• Anthropic (2024) "Scaling Monosemanticity" — SAE feature 추출
• Neel Nanda's TransformerLens tutorials: https://neelnanda.io/

영감

• 3D Slicer (의료 영상 시각화): https://www.slicer.org/
• FreeSurfer (뇌 영상 분석): https://surfer.nmr.mgh.harvard.edu/
• Neuronpedia (SAE feature 탐색기): https://www.neuronpedia.org/

---

End of Specification