---
license: mit
tags:
- brain-decoding
- eeg
- fmri
- image-reconstruction
- language-decoding
- neuroscience
library_name: pytorch
---

# Eigenbrain: frozen brain-decoding inference bundle

This repository contains frozen inference assets for three independent
brain-decoding demonstrations: EEG classification, neural language decoding,
and NSD Subject-1 fMRI-to-image reconstruction. It is an inference/replay
bundle; it does not train a model and does not fit preprocessing transforms.

## Contents

| Task | Input | Frozen route | Main output |
|---|---|---|---|
| EEG classification | SEED-V eigenmode EEG | temporal/mode-attention encoder + 5-class head | predicted class |
| Language decoding | Alice BCI observation and prior | PoE + subject layer + QFormer + BGE tokens + Phi-4 LoRA | decoded English text |
| Image reconstruction | NSD Subject-1 CIFTI-4096 and modes-2000 | anchored PoE + MindEye2 BrainNetwork + diffusion prior + SDXL-unCLIP | reconstructed PNG |

The language route uses the public base models `microsoft/Phi-4-mini-instruct`
and `BAAI/bge-m3`; the files in this repository are the project-specific
alignment, projector, and LoRA weights. The image route uses a large frozen
unCLIP checkpoint and requires a CUDA GPU with substantial storage and memory.

## Download

Download this repository together with the companion inference code. The
project code expects the following local layout:

```text
assets/
weights/
weights/alice_lora/
weights/nsd_sub01/
models/Phi-4-mini-instruct/
models/bge-m3/
```

The companion `download_assets.py` downloads the project files from this
repository and the two public base models:

```bash
export EIGEN_HF_REPO=SSp1ash/Eigenbrain
python download_assets.py
```

For classification and language only, omit the large NSD image files with
`python download_assets.py --skip-nsd`.

## Run

```bash
python run_demo.py --task classification --device cuda

python run_demo.py --task language --device cuda \
  --phi-path models/Phi-4-mini-instruct \
  --bge-path models/bge-m3

python run_demo.py --task image --device cuda
```

The image command evaluates the default ten held-out NSD examples and writes
the selected qualitative reconstructions and image-level metrics under
`outputs/nsd_sub01/`.

## Reference results

The fixed compact replay gives approximately 40% accuracy for EEG
classification on 10 examples. The language text route gives a mean BGE
sentence cosine of approximately 0.81 on 5 examples. The NSD image route has
an archived full-test CLIP 2-way identification score of 0.783; the default
ten-example smoke test is not a replacement for the full benchmark.

These values describe the shipped frozen replay assets and should not be
interpreted as a new independent held-out evaluation. The language alignment
checkpoint includes historical oracle-style provenance, and the NSD visual
demo saves only a small qualitative subset of the evaluated examples.

## Files

Custom project files are stored under `assets/` and `weights/`. The largest
file is `weights/nsd_sub01/unclip6_epoch0_step110000.ckpt` (about 18 GB).
Public base models are intentionally not duplicated here.

## License and limitations

The code and frozen assets are provided for research demonstration and
reproducibility. Check the licenses and terms of the public Phi-4, BGE-M3,
MindEye2/SDXL-unCLIP components and the NSD data before redistribution or
commercial use. The NSD route is within-subject reconstruction for Subject 1,
not a cross-subject general-purpose image decoder.