Production MI engine: wide-window fine-tuned CBraMod (grouped-CV 0.784 zero-calibration; parity 7e-6 abs, 210/210 decisions)

CBraModMI.mlpackage/Data/com.apple.CoreML/model.mlmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c9f4825df8d95a8317ac753096d41a0449875b8b9969e9955b9db5c036038ade
+size 327364

CBraModMI.mlpackage/Data/com.apple.CoreML/weights/weight.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6b4b694d9b1120c81e4a5701f133507ccf3fc3f7e4e44dc6ad3a2725b4f3a4e8
+size 20146048

CBraModMI.mlpackage/Manifest.json

@@ -0,0 +1,18 @@
+{
+    "fileFormatVersion": "1.0.0",
+    "itemInfoEntries": {
+        "8585A9D1-98D5-49F6-9A33-D43E87441E0E": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Specification",
+            "name": "model.mlmodel",
+            "path": "com.apple.CoreML/model.mlmodel"
+        },
+        "D96CFFCE-E706-4EF9-AFD3-DCC48C2CC4A7": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Weights",
+            "name": "weights",
+            "path": "com.apple.CoreML/weights"
+        }
+    },
+    "rootModelIdentifier": "8585A9D1-98D5-49F6-9A33-D43E87441E0E"
+}

README.md

@@ -0,0 +1,73 @@
+---
+license: bsd-3-clause
+base_model: braindecode/cbramod-pretrained
+tags:
+- coreml
+- eeg
+- bci
+- motor-imagery
+- ios
+- macos
+- visionos
+language:
+- en
+---
+
+# CBraMod-MI-CoreML
+
+**Zero-calibration motor-imagery decoder for 14-channel consumer EEG (EMOTIV EPOC X montage), running natively on Apple silicon. Subject-grouped estimate on unseen users: 78.4% left/right accuracy with no calibration trials.**
+
+This is CBraMod fine-tuned end-to-end for left/right-hand motor imagery on all 109 PhysioNet EEGBCI subjects, exported to Core ML as a single classifier. Unlike embedding-based deployments, it needs **no per-subject head**: preprocessed EEG in, left/right probabilities out.
+
+## The two-zone window (read this — it is the model's contract)
+
+The input window is **[1.0, 4.5] s after imagery onset** — deliberately covering both the sustained-imagery zone *and* the post-imagery beta rebound. Our profiling showed the rebound period is anti-correlated under sweet-spot-trained decoders (it reverses the linear decision) but is the single most informative zone when trained on directly; the two-zone window is what lifts unseen-user accuracy from 0.717 to 0.784. Feeding a different window degrades the model to that extent.
+
+| Item | Value |
+|---|---|
+| Model | `CBraModMI.mlpackage` (fp32 `mlprogram`) |
+| Input | `eeg` — `float32 [1, 14, 1000]` |
+| Output | `logits` — `float32 [1, 2]` = [left, right] (apply softmax) |
+| Window | 3.5 s starting 1.0 s after imagery onset, source 256 Hz (896 samples) |
+| Preprocessing | average reference over the 14 channels → global z-score of the window → resample to 200 Hz (polyphase) → zero-pad to 1000 samples |
+| Channels (order matters) | AF3, F7, F3, FC5, T7, P7, O1, O2, P8, T8, FC6, F4, F8, AF4 |
+| Also included | `cbramod_mi_wide.safetensors` (the fine-tuned PyTorch weights), `training_meta.json`, `parity.json` |
+
+## Honest evaluation
+
+All numbers are **subject-grouped** (GroupKFold 5 on 109 subjects: the evaluated model never saw any window from the tested user) with pre-registered hyperparameters; the published checkpoint is the same recipe trained on all 109.
+
+- **0.784 ± 0.132** mean unseen-user accuracy; 56/109 users ≥ 80%, 25/109 ≥ 90%.
+- +14.7 points over the best frozen-feature decoder *with* per-user calibration (paired p = 7×10⁻²⁰).
+- **Bounds, stated plainly:** the identical recipe does not lift fists-vs-feet decoding (0.567 — the montage lacks midline-central coverage), and transfer across *recording setups* degrades: frozen-feature priors lost ~3 points crossing to a different amplifier/protocol (Cho2017), and the same should be expected here. This model is trained on research-grade recordings channel-subset to the EPOC X montage; true dry-electrode performance is unvalidated until live-headset data exists.
+- The model is **cue-paced by design**: it decodes a window anchored to a known imagery onset (an app prompt). It is not an asynchronous/self-paced decoder — our pseudo-online study showed free-running decoding fails on this paradigm regardless of decoder.
+
+## Core ML parity
+
+Converted with `torch.export` + `run_decompositions({})` (fp32; `torch.jit.trace` fails on CBraMod's criss-cross reshapes — see the conversion notes in [CBraMod-CoreML-Apple](https://huggingface.co/oraculumai/CBraMod-CoreML-Apple)). Gates on real EEG windows vs PyTorch: logits rel-L2, 100% decision agreement, softmax max-abs-diff — results in `parity.json`.
+
+## Usage
+
+```python
+import numpy as np
+import coremltools as ct
+from huggingface_hub import snapshot_download
+
+# local_dir is required: Core ML cannot resolve the default HF cache's symlinks
+repo = snapshot_download("oraculumai/CBraMod-MI-CoreML", local_dir="CBraMod-MI-CoreML")
+model = ct.models.MLModel(f"{repo}/CBraModMI.mlpackage")
+
+# window: [1.0, 4.5]s post-onset, 14ch x 896 @ 256 Hz, avg-ref + z-scored,
+# then resampled to 200 Hz and zero-padded to 1000 samples:
+logits = model.predict({"eeg": window_1x14x1000})["logits"]  # [1, 2] = [left, right]
+```
+
+Python helper with the exact preprocessing: `oraculum.cbramod.CBraModMIClassifier` in <https://github.com/nschlaepfer/oraculum-gpt-mk1>.
+
+## Provenance & credit
+
+- **Base model:** CBraMod (Wang et al., ICLR 2025, BSD-3-Clause) via [`braindecode/cbramod-pretrained`](https://huggingface.co/braindecode/cbramod-pretrained).
+- **Fine-tuning data:** PhysioNet EEGBCI (Schalk et al. 2004; Goldberger et al. 2000) — 109 subjects, motor-imagery runs, 14-channel subset. Please cite both when using this model.
+- **Method & evaluation:** the accompanying study (repository above) documents the two-zone window discovery, the fine-tuning recipe, and every control.
+
+Research artifact — not a medical device; not validated for clinical use.

cbramod_mi_wide.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e8cf5f04c8e42c6782d7c27d67f285a55be08233b985c91e17ede4e6c02db954
+size 19830136

parity.json

@@ -0,0 +1,8 @@
+{
+  "export_fidelity_rel_l2": 0.0,
+  "worst_logits_absdiff": 6.973743438720703e-06,
+  "decision_agreement": "210/210",
+  "worst_prob_absdiff": 2.384185791015625e-06,
+  "gate_abs": 0.0001,
+  "pass": true
+}

training_meta.json

@@ -0,0 +1,13 @@
+{
+  "windows": 4606,
+  "subjects": 109,
+  "window_s": [
+    1.0,
+    4.5
+  ],
+  "recipe": "AdamW back 3e-5/head 1e-3, wd 0.05, bs 64, 12 ep, cosine, ls 0.1, seed 0",
+  "grouped_cv_estimate": 0.784,
+  "train_sanity_acc": 0.8323925314806774,
+  "base": "braindecode/cbramod-pretrained (BSD-3-Clause)",
+  "data": "PhysioNet EEGBCI runs 4/8/12, 109 subjects, 14 EPOC X channels"
+}