Python SDK - Nimbus

The nimbus-bci Python library is a Bayesian personalization head for frozen neural EEG embeddings — and sklearn-compatible classifiers for classical feature pipelines. Wrap any trunk that emits encode(X) → Z, adapt online with Personalizer, and ship apps on BrainState. Optional extras add NimbusSoftmax via JAX (pip install nimbus-bci[softmax]) and pyRiemann feature pipelines (pip install nimbus-bci[riemann]).

Start here

Install nimbus-bci

Install and verify your Python SDK environment.

Personalizer & Middleware

Encoder contract, BrainState, and decision presets.

Run Quickstart

Fit your first Personalizer in minutes.

Overview

nimbus-bci is a production-ready Python package on PyPI. The product surface is middleware; the Bayesian heads (NimbusLDA, …) power Personalizer and remain usable standalone.

pip install nimbus-bci

Product wedge: wrap → Personalizer → BrainState. Also: CalibrationSession for active learning, and nimbus_bci.riemann.make_riemann_nimbus_pipeline(...) for pyRiemann + Nimbus heads. See Personalizer & Middleware and Active Learning.

Key features

Personalizer Middleware

Plug any frozen trunk; personalize online; ship BrainState to apps.

sklearn Compatible Heads

Bayesian heads work as drop-in sklearn classifiers in pipelines and CV.

Streaming Inference

Real-time chunk-by-chunk processing with optional BrainState bridges.

MNE Integration

Works with MNE-Python for EEG preprocessing and feature extraction.

Riemannian Features

Optional pyRiemann covariance/tangent feature pipelines feeding Nimbus heads.

Rich Diagnostics

Entropy, calibration metrics (ECE/MCE), ITR calculation, and quality assessment.

Online Learning

Update heads incrementally with partial_fit() without retraining from scratch.

Active Learning

Rank unlabeled trials, request labels only when useful, and stop when the posterior stabilizes.

Fully Local

No API keys required. All processing happens on your machine.

Quick Example

from nimbus_bci import Personalizer, wrap
import numpy as np

# Toy frozen encoder — replace with partner / foundation encode(X) → Z
def encode(X):
    return X  # already embeddings or CSP features

enc = wrap(encode, model_id="demo-encoder", embedding_dim=16)
adapter = Personalizer(
    encoder=enc,
    head="lda",
    classes=["left", "right"],
    preset="research",
)
adapter.fit(X_cal, y_cal)
states = adapter.predict(X_test)  # list[BrainState]
print(states[0].intent, states[0].confidence)

Classical features without a trunk:

from nimbus_bci import NimbusLDA
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler

pipe = make_pipeline(StandardScaler(), NimbusLDA())
pipe.fit(X_train, y_train)

Available Heads

The Python SDK provides four Bayesian heads (used by Personalizer(head=...) or standalone):

Head	Description	Best For
NimbusLDA	Bayesian LDA with shared covariance	Default Personalizer head; motor imagery
NimbusQDA	Bayesian QDA with class-specific covariances	Complex distributions (P300)
NimbusSoftmax	Bayesian logistic regression (Polya-Gamma VI)	Non-Gaussian decision boundaries
NimbusSTS	Bayesian Structural Time Series (EKF)	Non-stationary data, long sessions

All heads provide:

Full posterior distributions
Uncertainty quantification
Online learning via partial_fit()
sklearn-compatible API

Note: NimbusSTS also includes state management methods (propagate_state(), get_latent_state(), set_latent_state()) for temporal adaptation.

Python vs Julia SDK

Both SDKs implement the same Bayesian models but with different design philosophies:

Feature	Python SDK	Julia SDK
Installation	`pip install nimbus-bci`	`Pkg.add("NimbusSDK")` + API key
API Style	sklearn-compatible classes	Functional + types
Integration	sklearn pipelines, MNE-Python	RxInfer.jl ecosystem
Performance	Fast local Python implementation; optional JAX Softmax	Fastest (native Julia)
API Key	Not required	Required
Use Case	Production ML pipelines	Research, custom models
License	Proprietary (Non-Commercial free + paid Commercial)	Commercial tiers

When to use the Python SDK

Choose the Python SDK if you:

Work primarily in Python
Use sklearn pipelines and MNE-Python
Want installation without API keys
Need a sklearn-compatible API
Prefer fully local processing

When to use the Julia SDK

Choose the Julia SDK if you:

Need native Julia performance
Want to build custom Bayesian models
Work with the RxInfer.jl ecosystem
Need pre-trained model distribution
Require enterprise support

Architecture

Product path:

EEG → frozen trunk encode(X)→Z → Personalizer → BrainState → Your Application

Classical path:

EEG → MNE / CSP / Riemann → Nimbus head → Your Application
         (Preprocessing)     (Classification)  (Control/Analysis)

Key Design Principles:

Encoder contract: Nimbus does not own DL architectures — integrators supply embeddings
App surface: BrainState for devices; BatchResult for research diagnostics
Local Processing: All computation happens on your machine
Privacy First: Your EEG data never leaves your computer
sklearn Compatible: Heads work with existing ML workflows
Uncertainty Aware: Full Bayesian posterior distributions

Use cases

Frozen Encoder Personalization

Plug EEGNet / BrainDecode / partner trunks into Personalizer

Motor Imagery BCI

Control devices with imagined movements using CSP features and NimbusLDA

P300 Speller

Communication interfaces using ERP features and NimbusQDA

Real-time Neurofeedback

Streaming inference for live brain state monitoring

What’s Included

The nimbus-bci package provides: Middleware (product surface):

Personalizer - Bayesian personalization head over a frozen encoder
wrap / FrozenEncoder / EncoderProtocol - encoder contract
BrainState / Prediction / IntentHypothesis - app contracts
decide / brain_states_from_batch / brain_state_from_streaming_result - bridges
wrap_eegnet / wrap_braindecode - optional named adapters

Heads (classifiers):

NimbusLDA - Bayesian Linear Discriminant Analysis
NimbusQDA - Bayesian Quadratic Discriminant Analysis
NimbusSoftmax - Bayesian Multinomial Logistic Regression
NimbusSTS - Bayesian Structural Time Series (Extended Kalman Filter)

Data Structures:

BCIData - Container for features, metadata, labels
BCIMetadata - Metadata for BCI experiments

Inference:

predict_batch() - Batch inference with diagnostics
StreamingSession - Real-time chunk processing

Active Learning:

CalibrationSession - Manage pool-based calibration rounds and stopping snapshots
suggest_next_trial() - Rank unlabeled feature pools by informativeness
should_query() - Decide whether an arriving trial is worth labeling
calibration_sufficient() - Stop calibration when the posterior stabilizes

Metrics:

compute_entropy() - Prediction uncertainty
compute_calibration_metrics() - ECE/MCE
calculate_itr() - Information Transfer Rate
assess_trial_quality() - Quality checks

Utilities:

estimate_normalization_params() - Feature normalization
diagnose_preprocessing() - Preprocessing diagnostics
compute_fisher_score() - Feature discriminability

MNE Integration:

from_mne_epochs() - Convert MNE Epochs to BCIData
extract_csp_features() - CSP feature extraction
extract_bandpower_features() - Bandpower features

Optional Riemannian Features:

make_riemann_nimbus_pipeline() - Build an EEG-epoch pipeline from pyRiemann covariance/tangent transforms to a Nimbus classifier head

Next read

Installation

Install nimbus-bci and verify your setup

Personalizer & Middleware

Encoder contract and BrainState

Quickstart

Fit your first Personalizer in minutes

API Reference

Complete API documentation with examples

Active Learning

Reduce calibration time with label-efficient trial selection

MNE Integration

Use nimbus-bci with MNE-Python

Support

Email: hello@nimbusbci.com
GitHub: github.com/nimbusbci/nimbuspysdk

Ready to get started? Head to the Installation Guide.

​Start here

Install nimbus-bci

Personalizer & Middleware

Run Quickstart

​Overview

​Key features

Personalizer Middleware

sklearn Compatible Heads

Streaming Inference

MNE Integration

Riemannian Features

Rich Diagnostics

Online Learning

Active Learning

Fully Local

​Quick Example

​Available Heads

​Python vs Julia SDK

​When to use the Python SDK

​When to use the Julia SDK

​Architecture

​Use cases

Frozen Encoder Personalization

Motor Imagery BCI

P300 Speller

Real-time Neurofeedback

​What’s Included

​Next read

Installation

Personalizer & Middleware

Quickstart

API Reference

Active Learning

MNE Integration

​Support

Start here

Overview

Key features

Quick Example

Available Heads

Python vs Julia SDK

When to use the Python SDK

When to use the Julia SDK

Architecture

Use cases

What’s Included

Next read

Support