Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Skieriya/fMRI-key-generation-with-TRIBEv2/llms.txt

Use this file to discover all available pages before exploring further.

run_integrated_pipeline() executes all six benchmark stages — model training, few-shot evaluation, multi-method key generation, NeuralVault verification, AWGN noise sweep, and motion artifact sweep — and returns a single results dictionary. This dictionary is serialized to JSON and used as the source of truth for all downstream reports and visualizations.

​
Results Dictionary Schema

The results dict produced by run_integrated_pipeline() has the following top-level structure: 
{
    "timestamp": "2026-05-24T15:30:24.041182",
    "baseline_metrics": {
        "SHA256":      { "d_prime": 0.136, "eer": 48.39 },
        "HMAC":        { "d_prime": 0.250, "eer": 52.58 },
        "BioHashing":  { "d_prime": 2.208, "eer": 15.09 },
        "Neural":      { "d_prime": 5.950, "eer": 0.75 },
        "NeuralVault": { "d_prime": 4.835, "eer": 0.94, "roc_auc": 0.000356, "threshold": 0.316 }
    },
    "neural_metrics": {
        "accuracy": 0.98125,
        "f1_score": 0.9810,
        "roc_auc": 0.9995
    },
    "noise_tests": {
        "SNR_LEVELS": [30, 20, 15, 10, 5, 0],
        "SHA256":     [49.20, 49.03, 49.74, 51.51, 50.13, 49.33],
        "HMAC":       [50.00, 51.06, 51.15, 50.67, 51.72, 48.75],
        "BioHashing": [15.63, 16.98, 15.28, 16.98, 14.34, 11.49],
        "Neural":     [0.75,  0.75,  0.75,  1.13,  0.47,  1.13]
    },
    "artifact_tests": {
        "ARTIFACT_LEVELS": [0.0, 0.05, 0.10, 0.15, 0.20, 0.30],
        "SHA256":     [48.39, 50.83, 51.55, 50.27, 50.56, 47.73],
        "HMAC":       [52.58, 50.53, 50.76, 50.67, 49.09, 51.17],
        "BioHashing": [15.09, 13.21, 11.79, 11.32, 12.74, 10.06],
        "Neural":     [0.75,  1.26,  1.42,  0.94,  1.13,  0.94]
    },
    "vault_scores": {
        "genuine":   [...],
        "impostor":  [...],
        "threshold": 0.31643475697002743
    },
    "vault_prototype_keys": [
        "1eaa2877f253315cecb77828e30f707d8fe381b07ba83851725c84a2e240c69b",
        "5f4da41c3524a593bd6a9cec804a75e2167b33aa324c1d73daa2479adbd2eef4",
        "b2948b9ff884a445721658e63c4c8540c3b025c06f7a6b4c12a26f62dc9db12a",
        "f6cce4665919dd4d1598f41bb0bfd0ecb1de9b48672599509170e49bb123e1a0",
        "bef2c1b2013102138abf20696101f69ab1d6629d17e6935121ad0f7a2b4fe284"
    ]
}
Key fields:
  • timestamp — ISO 8601 string recording when the pipeline was executed.
  • baseline_metrics — Dict mapping each method name to its d_prime and eer values. The NeuralVault entry additionally carries roc_auc (from cosine-distance ROC scoring) and the optimal threshold for the genuine/impostor decision boundary.
  • neural_metrics — Aggregated few-shot classification performance: accuracy, f1_score, and roc_auc averaged over 40 evaluation episodes.
  • noise_tests — Contains SNR_LEVELS (the list [30, 20, 15, 10, 5, 0]) and one EER list per method, indexed positionally against SNR_LEVELS.
  • artifact_tests — Contains ARTIFACT_LEVELS (the list [0.0, 0.05, 0.10, 0.15, 0.20, 0.30]) and one EER list per method, indexed positionally.
  • vault_scores — Raw cosine distance arrays for all genuine and impostor pairs evaluated by the NeuralVault verification path, plus the threshold value at the EER operating point (0.31643475697002743).
  • vault_prototype_keys — List of 5 hex-encoded 256-bit keys, one per stimulus class, derived from the mean embedding of each class via derive_key().
The vault_scores genuine and impostor arrays contain the full set of per-sample cosine distances and are omitted from display here due to their size, but are available in full in benchmark/results/keygen_benchmark_results.json.

​
Prototype Keys

Each class prototype key is derived by computing the mean embedding over all training samples for that class, quantizing to int16 with a scaling factor of 1000, and passing the result through HKDF-SHA256 with the info string b"neural-vault-few-shot-v1". The resulting 32-byte (256-bit) keys are:
ClassKey (hex)
01eaa2877f253315cecb77828e30f707d8fe381b07ba83851725c84a2e240c69b
15f4da41c3524a593bd6a9cec804a75e2167b33aa324c1d73daa2479adbd2eef4
2b2948b9ff884a445721658e63c4c8540c3b025c06f7a6b4c12a26f62dc9db12a
3f6cce4665919dd4d1598f41bb0bfd0ecb1de9b48672599509170e49bb123e1a0
4bef2c1b2013102138abf20696101f69ab1d6629d17e6935121ad0f7a2b4fe284
These keys are the canonical identifiers for each fMRI stimulus class in the Neural Vault. They are reproducible given the same model weights, feature matrix, and HKDF parameters.
If cryptography is not installed, derive_key() falls back to a raw hashlib.sha256 digest over the quantized embedding bytes. Install cryptography to use the full HKDF-SHA256 derivation with the neural-vault-few-shot-v1 info string.

​
Output Files

run_integrated_pipeline(), generate_reports(), and generate_visualizations() collectively produce the following files:
FileDescription
benchmark/results/keygen_benchmark_results.jsonComplete results dictionary including all metrics, noise/artifact sweeps, raw vault scores, and prototype keys
benchmark/reports/benchmark_summary.jsonCondensed summary with neural model evaluation, NeuralVault evaluation, and the winners block identifying the best method by d-prime and EER
benchmark/reports/BENCHMARK_REPORT.mdHuman-readable markdown report with formatted tables for d-prime, EER, and per-method noise robustness profiles
benchmark/visualizations/neuralvault_extended_dashboard.png6-panel matplotlib figure at 200 DPI (see below)
neural_vault_benchmarks.pngStandalone dark-theme benchmark plot generated by model.py

​
generate_reports(results)

generate_reports determines the winning method for each metric before writing output: 
best_sep_name = max(methods, key=lambda k: methods[k]['d_prime'])
best_eer_name = min(methods, key=lambda k: methods[k]['eer'])
On the benchmark run: Neural wins both categories (d′ = 5.950, EER = 0.75%). The summary JSON captures these as "highest_separability_method": "Neural" and "lowest_error_rate_method": "Neural".

​
generate_visualizations(results) — 6-Panel Dashboard

The neuralvault_extended_dashboard.png is a 3×2 grid figure (18×18 inches, 200 DPI):
PanelTitleContent
AKey Generation Separability (d-prime)Vertical bar chart comparing d-prime for SHA256, HMAC, BioHashing, and Neural
BKey Generation Error Rate ComparisonVertical bar chart comparing EER (%) for the same three methods
CNoise Robustness for Key Generation MethodsLine chart of EER vs. SNR (dB, x-axis inverted) for all four methods
DModel Performance MetricsHorizontal bar chart showing Accuracy, Macro F1, and ROC-AUC for the NeuralVaultFewShot model
ETraining Loss CurveTriplet loss over 100 training epochs
FEmbedding Space Class Mapping (PCA)2D PCA scatter of the learned embedding space, colored by class label
The standalone neural_vault_benchmarks.png generated by model.py uses a dark background theme and includes six different panels: distribution histograms for genuine/impostor scores, the ROC curve, the DET curve, a 1D cosine similarity mapping, the training loss curve, and a d-prime Gaussian overlay illustrating score distribution separability.

Build docs developers (and LLMs) love

Get started for freeTalk to us