[models] Add EEG-CLIP dual encoder - #1200

Reviewer map

Fast path (~60 s):

1. braindecode/models/eeg_clip.py — model/API semantics;
2. test/unit_tests/models/test_eeg_clip.py — released-source parity and edge-case contracts;
3. registry/docs files — standard Braindecode integration only.

Four invariants worth checking first:

• default forward(X) stays Tensor-valued for Braindecode/skorch;
• paired EEG/text behavior is isolated in forward_paired(...); no Transformers core dependency;
• released-source projection / raw learned-logit-scale contrastive semantics are preserved;
• reconstructable default models save/load through the Hub config path, while custom encoders fail explicitly instead of serializing an incomplete config.

Review-ready: latest head bc52ca7 passed its complete public validation suite: six cross-platform test jobs (Ubuntu/Windows/macOS × Python 3.12/3.13), acceptance, Codecov project, Codacy, docs, pre-commit and What's New (12/12 green). GitHub reports mergeable=true; maintainer review is the remaining gate.

Summary

Adds EEGCLIP, a Braindecode-native EEG/text dual encoder based on the 2025 EEG-CLIP work.

Closes #999.

API contract

• forward(X) remains Tensor-valued for Braindecode/skorch integration and returns raw projected EEG vectors.
• forward_paired(...) is the explicit eager multimodal API for paired EEG/text embeddings and bidirectional logits.
• encode_text(...) accepts dependency-injected text encoders or precomputed text features; Transformers is not added as a core dependency.
• compute_logits(...) preserves the released model's raw projection geometry without hidden L2 normalization.

Pinned-source fidelity

Audited public source:

tidiane-camaret/EEGClip@1d6b89b33d56edcf35037ed7cc27e445885532ea

The implemented training path preserves the pinned released source semantics:

• EEG/text projection-head structure matches the current public source.
• learned logit_scale initializes as log(1 / 0.07) and is used directly as the released ClipLoss multiplier;
• bidirectional logits and symmetric cross-entropy match under copied parameters;
• input, projection-layer, and learned-logit_scale gradients were included in the parity audit.

Observed numerical envelope in the pinned-source CPU parity audit:

• EEG→text logits max abs error: 0.0
• text→EEG logits max abs error: 4.47e-8
• symmetric loss max abs error: 1.19e-7
• learned-logit_scale gradient max abs error: 2.79e-9

The repository's historical modelsexample.ckpt predates the public source's projection-head simplification. This PR therefore does not force-map that checkpoint and does not claim historical-checkpoint parity.

Braindecode integration

• EEGModuleMixin registration, model summary, API docs, categorization, reference and What's New entry;
• default Deep4Net EEG path plus custom EEG/text encoders;
• masked and CLS text pooling;
• paired contrastive loss and zero-shot logits;
• reset_head() preserves device, dtype, and module train/eval state;
• Hub/config round-trip for the reconstructable default-encoder path;
• custom encoder architectures fail explicitly rather than serializing an incomplete reconstruction config.

Current validation state

Current head: bc52ca754c676d3a33a7106e2c41c7ef704d989f.
Upstream master at last synchronization: 63b0d026a62e4094f706170f04e27b663876a2ee.
GitHub reports the PR as mergeable and 0 commits behind, with the same 9-file EEG-CLIP-only diff.

New upstream regression resolved: after #1252 landed, test_pretrained_compat.py::test_compat_covers_every_pretrained_model failed solely because its source-scanning _SHIPS_WEIGHTS regex matched AutoModel.from_pretrained(...) inside the EEGCLIP class docstring example. It incorrectly classified EEGCLIP as distributing an official pretrained EEG model. The optional external text-encoder example now lives in the module docstring, outside inspect.getsource(EEGCLIP); the class retains a dependency-free paired-tensor example. The new upstream source-scanner regex was reproduced against the updated class text with no matches. No model parameter, pretrained artifact, or runtime logic was added/changed in this fix.

Latest-head CI (confirmed at bc52ca7): 12/12 checks completed successfully — Ubuntu 3.12/3.13, Windows 3.12/3.13, macOS 3.12/3.13, acceptance, Codecov project, Codacy, build_docs, pre-commit, check-whats-news. No remaining CI failures or pending checks were visible at verification time. The earlier source-regex false positive has been resolved without changing the model implementation.

Claim boundary

This PR claims a library-native EEG-CLIP implementation with pinned projection and active contrastive-loss semantics fidelity to the current public source.

It does not claim:

• reproduction of the paper's TUH/TUAB training results;
• full-model parity to the historical public checkpoint;
• that the released source's raw learned-logit-scale convention is identical to standard CLIP temperature parameterization.

Reviewer-facing diff hygiene

The branch was re-synchronized after upstream advanced again. Shared registry and documentation files were rebuilt from current master plus only the EEG-CLIP additions. The PR therefore remains a 9-file method/integration diff with no unrelated upstream deletions carried by the feature branch.

No further code changes are planned unless CI or review identifies a reproducible defect.