Improve model card with usage and provenance

README.md

@@ -1,3 +1,99 @@
 ---
 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.