CBraMod embedder Core ML fp32 (parity 1.3e-5, task-equivalent, Swift-validated)

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

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

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

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

CBraModEmbedder.mlpackage/Manifest.json

@@ -0,0 +1,18 @@
+{
+    "fileFormatVersion": "1.0.0",
+    "itemInfoEntries": {
+        "1DCDC5C2-D434-4197-82B9-2474DBDE3FAC": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Specification",
+            "name": "model.mlmodel",
+            "path": "com.apple.CoreML/model.mlmodel"
+        },
+        "CED5C91C-BA26-4A2C-8D38-2B3C8CF276F9": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Weights",
+            "name": "weights",
+            "path": "com.apple.CoreML/weights"
+        }
+    },
+    "rootModelIdentifier": "1DCDC5C2-D434-4197-82B9-2474DBDE3FAC"
+}

README.md

@@ -0,0 +1,112 @@
+---
+license: bsd-3-clause
+base_model: braindecode/cbramod-pretrained
+tags:
+- coreml
+- eeg
+- bci
+- motor-imagery
+- transformer
+- ios
+- macos
+- visionos
+language:
+- en
+---
+
+# CBraMod-CoreML-Apple
+
+**CBraMod as a native Core ML embedding extractor for Apple platforms (macOS / iOS / visionOS), fp32, validated to rel-L2 1.3e-5 against the PyTorch reference.**
+
+This repository packages the pretrained [CBraMod](https://github.com/wjq-learning/CBraMod) EEG foundation model (Wang et al., ICLR 2025) — via the [braindecode](https://braindecode.org) re-hosted checkpoint [`braindecode/cbramod-pretrained`](https://huggingface.co/braindecode/cbramod-pretrained) — as a single `.mlpackage` that maps a 14-channel EEG window to a 14,000-dimensional embedding, entirely on-device via CoreML.framework.
+
+It is published as a companion to the [ZUNA Core ML profiles](https://huggingface.co/oraculumai/ZUNA1.1-CoreML-Apple): in our 109-subject motor-imagery evaluation, CBraMod embeddings were the strongest foundation-model feature for sustained motor-imagery decoding, so this artifact is the MI engine of an on-device BCI stack.
+
+## What is in the package
+
+| Item | Value |
+|---|---|
+| Model | `CBraModEmbedder.mlpackage` (fp32 `mlprogram`) |
+| Backbone | CBraMod criss-cross transformer, pretrained weights, classification head removed (`Identity`) |
+| Input | `eeg` — `float32 [1, 14, 1000]` (14 channels × 5 s @ 200 Hz) |
+| Output | `embedding` — `float32 [1, 14000]` (flattened patch embeddings: 14 ch × 5 patches × 200 dims) |
+| Size | ~20 MB weights |
+| Conversion | coremltools 9.0, `torch.export` frontend (`TorchExport::ATEN` dialect) |
+
+The channel count (14) matches the Emotiv EPOC X montage (AF3, F7, F3, FC5, T7, P7, O1, O2, P8, T8, FC6, F4, F8, AF4), but nothing in the backbone is montage-specific beyond the fixed input shape: CBraMod treats channels symmetrically at the patch level, so any 14-channel montage at 200 Hz can use this package. For other channel counts, re-export from source (script linked below).
+
+## Expected preprocessing
+
+The parity and task-level validation below used this exact chain (matching the upstream evaluation convention of z-scored inputs):
+
+1. Window the raw EEG to 5 s.
+2. Average-reference across the available channels.
+3. Global z-score the window (single mean/std over all channels and samples).
+4. Resample to 200 Hz (polyphase), crop/zero-pad to exactly 1000 samples.
+
+## Validation
+
+All gates were run against the original PyTorch checkpoint on **real EEG** (PhysioNet EEGBCI motor-imagery recordings mapped to the 14-channel montage), not random tensors.
+
+| Check | Result |
+|---|---|
+| Numerical parity (worst rel-L2 over 36 real windows, two window regimes, CPU_ONLY) | **1.3e-5** (gate 1e-4) — see `parity.json` |
+| Export fidelity (`torch.export` module vs eager PyTorch) | bit-exact |
+| Task-level equivalence (held-out-run MI accuracy, subjects 1–5, Core ML vs PyTorch embeddings) | **identical** (max accuracy diff 0.000) |
+| Native Swift / CoreML.framework smoke (compile, load, predict, finite outputs) | PASS (0.44 s load, 1.27 s cold first prediction on an M3 Max) |
+
+Downstream context (not a property of this artifact, but of the underlying checkpoint): on 109 PhysioNet EEGBCI subjects with held-out-run evaluation, CBraMod embeddings + logistic regression reached **63.7% ± 13.8%** left/right-hand sustained motor-imagery accuracy on cue-offset windows (a control that excludes visual-cue-evoked confounds), significantly above every classical and FM baseline we tested (paired test vs best prior, p ≈ 2e-6).
+
+## Conversion notes (for reproducers)
+
+Two standard approaches fail on this architecture; both failures are worth knowing:
+
+- `torch.jit.trace` is non-deterministic here unless `torch.backends.mha.set_fastpath_enabled(False)` is set (nn.MultiheadAttention's fastpath produces divergent traces), and even then Core ML const-folding fails on ~349 symbolic-int (`aten::Int`) nodes arising from CBraMod's criss-cross reshape arithmetic.
+- `torch.export.export(...).run_decompositions({})` converts cleanly: the modern frontend specializes static shapes to constants, eliminating the symbolic-int nodes. This is the recommended path for reshape-heavy transformers.
+
+The export script (including the parity and task-equivalence gates) is open source: [`scripts/port_cbramod_coreml.py`](https://github.com/nschlaepfer/oraculum-gpt-mk1/blob/main/scripts/port_cbramod_coreml.py).
+
+## Usage
+
+### Python (coremltools)
+
+```python
+import numpy as np
+import coremltools as ct
+from huggingface_hub import snapshot_download
+
+repo = snapshot_download("oraculumai/CBraMod-CoreML-Apple")
+model = ct.models.MLModel(f"{repo}/CBraModEmbedder.mlpackage")
+
+eeg = np.random.randn(1, 14, 1000).astype(np.float32)  # preprocessed as above
+embedding = model.predict({"eeg": eeg})["embedding"]   # (1, 14000)
+```
+
+### Swift (CoreML.framework)
+
+```swift
+import CoreML
+
+// Compile once: xcrun coremlcompiler compile CBraModEmbedder.mlpackage <outdir>
+let model = try MLModel(contentsOf: compiledURL)
+let input = try MLMultiArray(shape: [1, 14, 1000], dataType: .float32)
+// ... fill input with the preprocessed window ...
+let out = try model.prediction(from: MLDictionaryFeatureProvider(dictionary: ["eeg": input]))
+let embedding = out.featureValue(for: "embedding")!.multiArrayValue!  // [1, 14000]
+```
+
+A typical decoder is a small linear head (e.g. logistic regression) trained on these embeddings; the 63.7% MI result above is exactly that.
+
+## Limitations
+
+- Fixed input shape `[1, 14, 1000]`. Other montages/window lengths require re-export.
+- fp32 only. We have not published a compressed variant; palettization/int8 were not validated for this model.
+- Research artifact. Not validated for medical diagnosis, treatment, or clinical decision-making. Use at your own risk and follow the base model's license (BSD-3-Clause).
+
+## Provenance & credit
+
+- **Original model:** CBraMod — *"CBraMod: A Criss-Cross Brain Foundation Model for EEG Decoding"*, Wang et al., ICLR 2025. Repository: <https://github.com/wjq-learning/CBraMod>
+- **Pretrained weights:** [`braindecode/cbramod-pretrained`](https://huggingface.co/braindecode/cbramod-pretrained) (safetensors, BSD-3-Clause), loaded through the [braindecode](https://braindecode.org) `CBraMod` implementation. The classification head (absent from the pretrained checkpoint) is replaced with `Identity`; all backbone tensors load cleanly.
+- **This conversion:** [oraculumai](https://huggingface.co/oraculumai) — Core ML export, parity/task-level validation, and packaging. Evaluation harness: <https://github.com/nschlaepfer/oraculum-gpt-mk1>
+
+If you use this model, please cite the original CBraMod paper and credit braindecode for the checkpoint distribution.

parity.json

@@ -0,0 +1 @@
+{"worst_rel_l2": 1.3118799870426301e-05, "gate": 0.0001, "pass": true, "n_windows": 36, "output_name": "embedding"}