Get Started with Neural Vault: Installation & First Run

Neural Vault derives 256-bit cryptographic keys directly from fMRI brain signals. A few-shot Transformer encoder is trained with triplet metric learning on cortical surface predictions produced by TRIBEv2, learning a metric space where genuine brain-signal samples cluster tightly while impostor signals are pushed apart. Once enrolled, each authentication session maps a new fMRI snapshot to the same prototype embedding and passes it through HKDF-SHA256 to reproduce the user’s stable key.

Install dependencies

Neural Vault requires PyTorch for the Transformer encoder, cryptography for HKDF-SHA256 key derivation, and a set of scientific Python libraries for benchmarking and visualization. Install everything in one command:

pip install torch numpy pandas scikit-learn scipy matplotlib cryptography tqdm nilearn

nilearn is used for brain surface visualization. All other packages are consumed directly by main.py and model.py.

Prepare your data

Neural Vault reads a single CSV file named 5classpreds.csv that must be present in your working directory before you run any pipeline script. This file contains per-vertex, per-timestep cortical surface predictions generated by TRIBEv2 for each of your five video stimuli.Expected schema:

Column	Type	Description
`video`	string	Video filename (e.g. `v1 (online-video-cutter.com).mp4`)
`timestep`	int	Zero-indexed temporal frame index within that video
`prediction`	float32	TRIBEv2 cortical vertex activation value

Each row encodes a single vertex at a single timestep for a single video. The full file covers 5 videos × N timesteps × 20,484 fsaverage5 vertices. See the Data Preparation guide for step-by-step instructions on generating this file with the data.py script and the TRIBEv2 API.

Run the full benchmark pipeline

With 5classpreds.csv in place, run main.py to execute the complete six-step evaluation pipeline:

python main.py

The script prints progress for each stage to stdout:

Step	Output
`[STEP 1]`	Deep Neural Optimization & Multi-Metric Inference — trains the `NeuralVaultFewShot` Transformer with triplet loss for 100 epochs, then runs 40 few-shot classification episodes and reports Accuracy, Macro F1, and ROC-AUC.
`[STEP 2]`	Multi-Method Benchmarking Suite — evaluates SHA-256, HMAC, BioHashing, and Neural key-generation methods, computing d-prime and EER for each.
`[STEP 3]`	Neural Vault verification benchmarks — derives class prototypes from embeddings, runs genuine vs. impostor cosine-similarity scoring, and derives a 256-bit prototype key per class.
`[STEP 4]`	System corruption/environmental testing — sweeps AWGN noise levels (`SNR_LEVELS = [30, 20, 15, 10, 5, 0]` dB) and motion-artifact probabilities (`ARTIFACT_LEVELS = [0.0, 0.05, 0.10, 0.15, 0.20, 0.30]`) to measure robustness.
`[STEP 5]`	4-Quadrant Neural & Cryptographic Visual Dashboard — writes a 3×2 matplotlib figure with d-prime bar charts, EER comparisons, noise-robustness curves, model-performance bars, training-loss curve, and PCA embedding scatter.
`[STEP 6]`	Executive System Reports — writes a human-readable Markdown benchmark report and a machine-readable JSON summary to `benchmark/reports/`.

Run the standalone enrollment demo

model.py is a self-contained single-user enrollment and verification demo. It trains the model independently and prints a full cryptographic key report:

python model.py

After training for 150 epochs with a cosine-annealing schedule, the script prints:

────────────────────────────────────────────────────
  NEURAL VAULT — BIOMETRIC KEY PIPELINE REPORT
────────────────────────────────────────────────────
  Model parameters        : <count>
  Latent dimensionality   : 40
  Training loss (final)   : <value>
────────────────────────────────────────────────────
  CRYPTOGRAPHIC KEY
  Key length              : 256 bits
  Key (hex, sample)       : <first 32 hex chars>…
  Avalanche effect        : <pct>% bit-flip on 0.05 perturbation
────────────────────────────────────────────────────
  FEW-SHOT BIOMETRIC BENCHMARKS
  d-prime (d')            : <value>  (>3 = excellent)
  ROC AUC                 : <value>
  Equal Error Rate (EER)  : <value>%  (lower = better)
  EER threshold (Sim)     : <value>
  FAR @ EER               : <value>%
  FRR @ EER               : <value>%
────────────────────────────────────────────────────

A demo end-to-end key generation block follows, showing the verification similarity score, the accept/reject decision against the EER threshold, and the final derived 256-bit key hex string.

Inspect outputs

Both scripts write artifacts to predictable locations. After a successful run of main.py you will find:

benchmark/results/keygen_benchmark_results.json
benchmark/reports/BENCHMARK_REPORT.md
benchmark/reports/benchmark_summary.json
benchmark/visualizations/neuralvault_extended_dashboard.png

File	Description
`benchmark/results/keygen_benchmark_results.json`	Full benchmark metrics including d-prime, EER, ROC-AUC, noise-sweep results, artifact-sweep results, prototype keys, and raw genuine/impostor score arrays.
`benchmark/reports/BENCHMARK_REPORT.md`	Human-readable Markdown report covering classifier evaluation, separability rankings, EER tables, and noise-robustness profiles for all four key-generation methods.
`benchmark/reports/benchmark_summary.json`	Compact JSON summary recording neural model evaluation scores, vault evaluation metrics, and the winner methods for highest separability and lowest error rate.
`benchmark/visualizations/neuralvault_extended_dashboard.png`	Six-panel dashboard (d-prime bars, EER bars, noise-robustness curves, model metrics, training loss curve, PCA embedding scatter).
`neural_vault_benchmarks.png`	Six-panel standalone benchmark plot from `model.py`: score distributions, ROC curve, DET curve, 1D similarity mapping, triplet loss curve, and d-prime Gaussian separation.

The prototype key for each class is printed to stdout during Step 3 and stored inside keygen_benchmark_results.json under the vault_prototype_keys key. Keys look like this:

class 0: key='1eaa2877f253315c...e240c69b'
class 1: key='5f4da41c3524a593...dbd2eef4'

Each key is a 256-bit value encoded as a 64-character lowercase hex string, derived via HKDF-SHA256 from the quantized prototype embedding.

5classpreds.csv cannot be auto-generated by Neural Vault. It must be produced by running data.py against your own fMRI video stimuli using the TRIBEv2 brain-encoding model. If the file is absent when you run main.py, the script raises:

FileNotFoundError: 5classpreds.csv is required and cannot be autogenerated.

You do not need real fMRI data to test model.py. If 5classpreds.csv is not found, model.py automatically falls back to a synthetic stand-in:

raw_np = np.random.randn(20, 20484).astype(np.float32)

This 20-sample × 20,484-feature random matrix mirrors the exact shape of real TRIBEv2 output, so every downstream step — normalization, sequence chunking, Transformer training, enrollment, and key derivation — runs identically. Benchmark numbers produced from synthetic data are not meaningful, but the code path is fully exercised.

Overview

Getting Started

Pipeline

Benchmarking

Reference