[models] Add NeuroRVQ residual tokenizer - #1223

Model information

• Model name: NeuroRVQTokenizer
• Paper: Barmpas et al. (2025), NeuroRVQ: Multi-Scale Biosignal Tokenization for Generative Foundation Models
• Motivation: Add the released EEG residual-vector-quantization tokenizer as a Braindecode model for signal reconstruction and discrete EEG token extraction in downstream generative models.

Implementation fidelity

• Reference implementation: KonstantinosBarmpas/NeuroRVQ, source commit 926e770d9d16b6aa308404280fa0cc0211a6f9fb; CC BY-NC 4.0. Released checkpoint is pinned to Hugging Face revision d944b87f44ae0ba2923b2f10d0518f23f6803b76.
• Deviations: Adds Braindecode mixin/API integration, strict checkpoint loading and cold-codebook initialization. The released architecture and preprocessing contract are preserved (200 Hz, 200-sample patches, released 104-channel montage). Required transformer and multiscale embedding layers are included as private helpers, so this PR has no dependency on another open PR. In training, EMA counts and sums follow the reference distributed all-reduce path. Eval/tokenize inference is state-pure; the reference increments a usage-statistics buffer in eval, but that buffer does not affect weights, codes, reconstruction, or gradients.
• Checkpoint/parity evidence: CPU parity against the released source and pinned checkpoint: exact eval/train targets and reconstructions, exact token indices, input gradients, and EMA state after one training update; maximum absolute difference across 345 trainable parameter gradients is 7.11e-15. The script asserts every trainable parameter receives a gradient. This is implementation parity, not reproduction of paper benchmark scores.

Checklist

Implementation

• EEGModuleMixin integration, source attribution, license declaration and NOTICE.txt entry
• Documented and tested task-specific inputs/outputs: standardized patches and discrete codes, not class logits
• Model docstring describes architecture, parameters and paper
• No new runtime dependency; Hub loading uses existing optional dependency
• Classifier final_layer convention: N/A; tokenizer returns reconstructed patches and codes, and is registered as a non-classification model

Registration and documentation

• Public export and model registry integration
• Mandatory-parameter integration and summary.csv row
• API entry, model guide, and docs/whats_new.rst
• Architecture figure: N/A; the tokenizer is documented with its patch/token data flow and does not introduce a separate figure

Validation and compatibility

• Model-specific and integration regression tests
• Checkpoint save/load round trip covered by model tests
• Shared helpers are private to this port; no existing model/API behavior is changed
• reset_head and mixed classifier head modes: N/A; tokenizer has no classification head
• Released checkpoint parity script covers train/eval forward, gradients, discrete codes and EMA update

Validation evidence

• pytest test/unit_tests/models/test_neurorvq_tokenizer.py -q — 7 passed.
• pytest test/unit_tests/models/test_integration.py -k NeuroRVQTokenizer -q — 6 passed, 6 skipped, 911 deselected.
• python scripts/validate_neurorvq_tokenizer_parity.py --neurorvq-source <NeuroRVQ clone> --checkpoint <pinned checkpoint> — exact reference outputs/codes/input gradients/EMA state; max parameter-gradient error 7.11e-15 over 345 trainable parameters.
• pre-commit run --files <changed files> — passed, including ruff, mypy, docstrfmt, sphinx-lint and isort; git diff --check passed.
• Full repository test suite was not run. A full Sphinx build was attempted earlier but was blocked by unrelated optional MOABB and local TensorBoard/protobuf environment issues; the tokenizer documentation checks pass.

Benchmark reproduction

The paper's public-dataset benchmark is not claimed as reproduced. This contribution integrates the released tokenizer and verifies implementation parity; benchmark reproduction requires the paper's complete datasets and training/evaluation protocol.

Current upstream gate status — 2026-10-09

Release-ready review surface: the model integration prerequisite
Braindecode #1218
has already been merged and independently replicated on public EEG
by the upstream maintainers (5 seeds × 10 subject-independent folds,
BAcc 0.8370 ± 0.0028 against the published 0.869 ± 0.026, inside
their predeclared 5% band). That is the upstream EEG foundation-model
port's maintainer-run replication, not a tokenizer Table-10 benchmark or
a new task improvement claimed for this PR.

For the current tokenizer PR head
f5307aa08242e3bb9f5d84866f84decb90ac5ca5, GitHub Actions reports:

• Full test matrix: 8/8 jobs green (Ubuntu, Windows, macOS;
  Python 3.12 and 3.13, including 2 real-data acceptance jobs).
• Code style: green; What's New check: green.
• Sphinx docs job: still in progress when checked; do not
  mark documentation green until that particular upstream job succeeds.
• PR state: open, non-draft and mergeable; actual merge remains
  at maintainer discretion.

Current-source CI checks.
The public author-run reference-parity artifact
was frozen at earlier maintainer-refactored head 61194d5
and compares checkpoint/reconstruction/discrete IDs/EMA and gradients.
The current f5307aa head passes the full upstream test matrix;
the author parity run is not claimed to be freshly rerun against
every intervening upstream commit. No full 14-subject High Gamma
reconstruction benchmark has been independently audited.

Suggested minimal review decision: assess whether the self-contained
tokenizer's checkpoint-loading, source license, quantizer EMA and public
API are acceptable. A future EEG benchmark reproduction can be a
separate research deliverable rather than an implied current PR result.

Notes for reviewers

The tokenizer is self-contained with respect to Braindecode: it does not import from or require another open PR. The original NeuroRVQ license is noncommercial (CC BY-NC 4.0), recorded in the model and repository notices.