Skip to content

Neural MRI Scanner

Model Resonance Imaging for AI Interpretability

CI License: MIT Python 3.11+ Node 20+ HF Spaces

Neural MRI Scanner visualizes the internals of open-source LLMs like a brain MRI — mapping five medical imaging modalities to AI model analysis techniques. Feed a model and a prompt, get back a full diagnostic scan of what's happening inside.

Neural MRI — fMRI activation scan

Scan Modes

Mode Full Name What It Shows
T1 Topology Layer 1 Static architecture — layers, parameters, structure
T2 Tensor Layer 2 Weight distribution & magnitude
fMRI functional Model Resonance Imaging Activation patterns for a given prompt
DTI Data Tractography Imaging Information flow pathways & circuits
FLAIR Feature-Level Anomaly Identification & Reporting Bias, hallucination & anomaly detection

DTI circuit tracing FLAIR anomaly detection

Features

  • 5 scan modes with real-time visualization (T1, T2, fMRI, DTI, FLAIR)
  • Token-by-token streaming via WebSocket — watch activations unfold live
  • Perturbation engine — zero, amplify, or ablate individual components and measure impact (KL divergence, logit shift)
  • Causal tracing — clean/corrupt prompt comparison with layer-by-layer recovery scores
  • SAE integration — multi-backend Sparse Autoencoder feature analysis (SAELens + EleutherAI)
  • Emotion vector analysis — extract emotion probes from model internals and steer behavior with emotion vectors (inspired by Anthropic's emotion concepts research)
  • Cross-model comparison — run two models side-by-side on the same prompt
  • 4 layout modes — vertical, brain, network, radial
  • Recording & export — WebM video, animated GIF, SVG/PNG snapshots, JSON data, Markdown reports
  • Real-time collaboration — share scan sessions with peers via WebSocket
  • HuggingFace Hub search — dynamically discover and load TransformerLens-compatible models
  • i18n — English and Korean
  • Medical dark theme — DICOM viewer aesthetic with CRT scan effects

Quick Start

Local

# Backend
cd backend
uv sync
uv run uvicorn neural_mri.main:app --reload --port 8000

# Frontend (new terminal)
cd frontend
pnpm install
pnpm dev

Open http://localhost:5173

Docker

docker compose up --build

Open http://localhost

See INSTALL.md for detailed setup instructions including GPU configuration and environment variables.

Supported Models

Model Params SAE 8GB 12GB 16GB+ VRAM Peak
GPT-2 124M SAELens All All All 2.2 GB
GPT-2 Medium 355M — All All All 3.0 GB
Pythia-1.4B 1.4B — All All All 4.4 GB
Qwen-2.5-3B 3B — — All All 8.4 GB
Llama-3.2-3B 3B — — All All 8.7 GB
Phi-3 Mini 3.8B — — All All 9.6 GB
Gemma-2-2B 2.6B SAELens — — All >12 GB
Llama-3.1-8B 8B EleutherAI — — — >16 GB
Mistral-7B 7.2B — — — — TL unsupported

All = scan + emotion steering + sweep. — = cannot load. VRAM peaks measured on RTX 4070 Ti.

See Hardware Requirements for detailed measurements and Mac MPS guidance.

Additional models can be loaded dynamically via HuggingFace Hub search — any model with a TransformerLens-compatible architecture works.

Emotion Vector Analysis

Neural MRI can extract and manipulate emotion representations inside language models, based on Anthropic's emotion concepts research.

# 1. Extract emotion probes (20 emotions x 3 passages, comprehension mode)
POST /api/emotion/extract-probes  {"mode": "comprehension"}

# 2. Steer model behavior with an emotion vector
POST /api/emotion/steer  {
  "prompt": "I'm going to destroy everything.",
  "emotion": "calm",
  "strength": 0.05
}

The engine supports comprehension mode (works on both base and instruct models) using pre-written emotional passages, and returns side-by-side original vs steered outputs with full emotion activation profiles.

Available emotions: happy, sad, calm, desperate, afraid, angry, proud, guilty, nervous, hopeful, brooding, gloomy, reflective, enthusiastic, hostile, loving, exasperated, blissful, anxious, grateful, neutral.

Architecture

┌─────────────────────────────────────────────────┐
│                   Frontend                       │
│  React 18 + TypeScript + D3.js + Zustand         │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ ScanCanvas│ │ModeTabs  │ │ Panels (Perturb, │ │
│  │ (D3 viz) │ │(T1-FLAIR)│ │ CausalTrace,SAE) │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
│            ↕ REST + WebSocket ↕                  │
├─────────────────────────────────────────────────┤
│                   Backend                        │
│  FastAPI + TransformerLens + PyTorch             │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │  Scanner  │ │  Model   │ │   Perturbation   │ │
│  │  Engine   │ │ Registry │ │     Engine        │ │
│  ├──────────┤ ├──────────┤ ├──────────────────┤ │
│  │  Emotion  │ │   SAE    │ │   SAE Providers  │ │
│  │  Engine   │ │ Manager  │ │ (Lens+EleutherAI)│ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
│            ↕ TransformerLens ↕                   │
├─────────────────────────────────────────────────┤
│              Model Weights                       │
│  HuggingFace Hub / Local Cache                   │
└─────────────────────────────────────────────────┘

Tech Stack

Layer Technology
Frontend React 18, TypeScript, D3.js, Zustand, Tailwind CSS v3
Backend FastAPI, TransformerLens, PyTorch, SAE-Lens, EleutherAI Sparsify
Infra Docker Compose, GitHub Actions CI
Theme Medical Dark (DICOM viewer aesthetic)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT