Encoder contract

The encode hook is not a gap — it is the product boundary. Nimbus does not host DL architectures. Integrators (or thin shortcuts) supply embeddings.

Layer	Owner	Responsibility
Frozen trunk	You / partner / bench	`encode(X) → (n, d)` pre-classifier features
Wrap	Nimbus	`wrap` / `FrozenEncoder` (+ optional named shortcuts)
Head	Nimbus	`Personalizer` — LDA / QDA / Softmax, `fit` / `partial_fit`
App	You	`BrainState` + presets (`research` / `consumer`)

Rules:

Freeze the trunk before personalizing
Feed embeddings, never class logits
Personalizer.load requires re-attaching the encoder
Optional embedding_dim= validates embedding width

Canonical recipe

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",
    # Optional: MC epistemic → Prediction.uncertainty for upstream gating
    # mc_samples=64,
)
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)

Already have features / CSP / Riemann vectors? Skip the trunk:

from nimbus_bci import Personalizer

adapter = Personalizer(encoder=None, classes=["left", "right"], preset="consumer")
adapter.fit(X_cal, y_cal)
states = adapter.predict(X_test)

partial_fit is cumulative (no forgetting / decay). That matches session calibration and short stream budgets. Do not treat unbounded lifetime accumulation as a shipped product guarantee until a forgetting mechanism exists.

Foundation pooling: REVE / EEGPT adapters mean-pool (or flatten) token / patch features to flat (n, d) so LDA/QDA heads can consume them. Spatial/temporal structure is collapsed at the encoder boundary, not inside the Bayesian head.

Optional shortcuts

Named helpers only reduce boilerplate. Architectures stay outside core:

Shortcut	Trunk lives in	Notes
`wrap(...)`	Your code	Canonical — any callable / sklearn / torch
`wrap_eegnet(clf)`	`nimbusbench.models.eegnet`	Convenience over `.encode` / `.freeze`
`wrap_braindecode(..., kind="eegnetv4")`	`braindecode` (optional)	Or pass any `encode_fn`
`wrap_braindecode(..., kind="reve")`	`braindecode` REVE (optional)	Foundation EEG; electrode positions + pooled embeddings
`wrap_braindecode(..., kind="eegpt")`	`braindecode` EEGPT (optional)	Patch-pooled foundation embeddings

from nimbus_bci import wrap_braindecode, wrap_eegnet

enc = wrap_eegnet(clf, freeze=True)
enc = wrap_braindecode(module, kind="eegnetv4")
enc = wrap_braindecode(reve_module, kind="reve", channel_names=chans)
enc = wrap_braindecode(eegpt_module, kind="eegpt")
enc = wrap_braindecode(my_encode_fn)  # any other BrainDecode / custom net

Claim for second trunks: API interchangeability under the same Personalizer / BrainState contract — not a confirmatory accuracy bake-off.

Active learning → personalization

Use CalibrationSession (or suggest_next_trial) to choose labels, then:

adapter.partial_fit(X_queried, y_queried)

Label-free stopping on the head:

from copy import deepcopy
from nimbus_bci import calibration_sufficient

previous = deepcopy(adapter.head)
adapter.partial_fit(X_new, y_new)
status = calibration_sufficient(
    adapter.head,
    Z_pool,  # already-encoded pool, or identity-encoder features
    previous=previous,
    criterion="posterior_stability",
    threshold=0.05,
)

Getting Started

Personalizer & Middleware

Python SDK

Core Concepts

Heads & Models

Configuration & Setup

Examples

Development

Julia SDK

Encoder contract

Encoder contract

Canonical recipe

Optional shortcuts

Active learning → personalization

Next Read

BrainState

Evidence

Overview

API Reference

​Encoder contract

​Canonical recipe

​Optional shortcuts

​Active learning → personalization

​Next Read

BrainState

Evidence

Overview

API Reference

Encoder contract

Canonical recipe

Optional shortcuts

Active learning → personalization

Next Read