nimbus-bci 0.5.0

Nimbus Personalizer: Bayesian personalization head for frozen neural EEG embeddings — wrap any encode(X)→Z trunk, adapt online, ship BrainState

nimbus-bci

Nimbus Personalizer — Bayesian personalization head for frozen neural EEG embeddings.
Plug any frozen trunk that emits encode(X) → Z, adapt online with a Nimbus head, ship apps on BrainState — without owning or retraining the encoder.

Also ships sklearn-compatible Bayesian classifiers (LDA / QDA / Softmax / STS) for classical feature pipelines (CSP, Riemann, …); those heads power Personalizer and can be used alone.

Docs · Personalizer · API reference · PyPI · License

Install

pip install nimbus-bci
# optional: pip install nimbus-bci[softmax]   # JAX Softmax head
# optional: pip install nimbus-bci[riemann]   # pyRiemann pipelines
# optional: pip install nimbus-bci[mne]       # MNE helpers

From source: pip install -e ".[all]" after cloning.

Quick start — encoder contract

Anything that maps inputs to embeddings (n, d) plugs in. Nimbus does not own DL architectures.

from nimbus_bci import Personalizer, wrap

enc = wrap(model.encode, model_id="partner-encoder", embedding_dim=64)
adapter = Personalizer(
    encoder=enc,
    head="lda",
    user="subject_001",
    classes=["left", "right"],
    preset="research",
)
adapter.fit(X_cal, y_cal)
states = adapter.predict(X_test)  # list[BrainState]

adapter.save("subject_001_profile")
loaded = Personalizer.load("subject_001_profile", encoder=enc)  # re-attach trunk

Optional shortcuts for common external trunks: wrap_eegnet, wrap_braindecode (see encoder contract).

Examples in this repo: examples/middleware_personalizer.py, middleware_braindecode.py, middleware_reve.py, middleware_recommend_adapt.py.
Bench EEGNet demo (needs nimbusbench[dl]): nimbusbench/scripts/middleware_eegnet.py.

When to adapt (thin helper)

Optional mean-shift check before spending labels on partial_fit. You choose the threshold tau.

dec = adapter.recommend_adapt(X_stream, tau=your_tau)  # stay vs stream update
if dec.should_adapt:
    adapter.partial_fit(X_lab, y_lab)

Trial rejection (BrainState.rejected / need_more_data) is a different gate — accept/reject the intent for the app.
Details: BrainState · recipe: examples/middleware_recommend_adapt.py.

Classical heads (CSP / features)

Same Bayesian heads without an encoder — inputs are already features:

from nimbus_bci import NimbusLDA

clf = NimbusLDA()
clf.fit(X_train, y_train)
proba = clf.predict_proba(X_test)
clf.partial_fit(X_new, y_new)

Also: streaming (StreamingSession), active learning (CalibrationSession), MNE helpers, optional Riemann pipelines. See docs.nimbusbci.com and examples/e2e_mne_csp_nimbus.py.

Head	Role
NimbusLDA / NimbusQDA	Conjugate Bayesian LDA/QDA
NimbusSoftmax	Polya–Gamma VI (optional JAX)
NimbusSTS	Latent-state / drift (experimental)

Evidence

Public Personalizer story (heads, cost vs fine-tune, multi-trunk / REVE):
Evidence · Overview.

License

Two-track proprietary license — see LICENSE.txt. Non-commercial use is free under the Non-Commercial terms; commercial use requires a paid license.