> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbusbci.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Python SDK
> Overview of the nimbus-bci Python SDK: Personalizer middleware for frozen encoders, BrainState app outputs, and sklearn-compatible Bayesian heads.
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: `[softmax]` (JAX), `[riemann]` (pyRiemann + `for_riemann` / `for_p300`), `[train]` (torch PEFT / BaLoRA), `[mne]`, `[viz]`, or `[all]`.
## Start here
Install and verify your Python SDK environment.
Encoder contract, BrainState, and decision presets.
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.
```bash theme={null}
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](/personalizer/overview) and [Active Learning](/python-sdk/active-learning).
## Key features
Plug any frozen trunk; personalize online; ship `BrainState` to apps.
Bayesian heads work as drop-in sklearn classifiers in pipelines and CV.
Real-time chunk-by-chunk processing with optional BrainState bridges.
Works with MNE-Python for EEG preprocessing and feature extraction.
Optional pyRiemann covariance/tangent feature pipelines feeding Nimbus heads.
Entropy, calibration metrics (ECE/MCE), ITR calculation, and quality assessment.
Update heads incrementally with `partial_fit()` without retraining from scratch.
Rank unlabeled trials, request labels only when useful, and stop when the posterior stabilizes.
No API keys required. All processing happens on your machine.
## Quick Example
```python theme={null}
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.for_deployment(enc, ["left", "right"])
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:
```python theme={null}
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:**
```text theme={null}
EEG → frozen trunk encode(X)→Z → Personalizer → BrainState → Your Application
```
**Classical path:**
```text theme={null}
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
Plug EEGNet / BrainDecode / partner trunks into Personalizer
Control devices with imagined movements using CSP features and NimbusLDA
Communication interfaces using ERP features and NimbusQDA
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
* Factories — `for_deployment`, `for_research`, `for_features`, `for_riemann`, `for_p300`, `for_balora`
* `Recipe` / `UserProfile` — paradigm recipes and portable profiles (`export_profile` / `from_profile`)
* `wrap` / `FrozenEncoder` / `EncoderProtocol` — encoder contract
* `BrainState` / `BrainStateBatch` / `Prediction` / `IntentHypothesis` — app contracts
* `decide` / `brain_states_from_batch` / `brain_state_from_streaming_result` — bridges
* `wrap_eegnet` / `wrap_braindecode` — optional named adapters
* Transforms — `StandardizeTransform`, `WhitenTransform`, `CoralTransform`, `RpaTransform`, `EuclideanAlignment`
**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
Install nimbus-bci and verify your setup
Encoder contract and BrainState
Fit your first Personalizer in minutes
Complete API documentation with examples
Reduce calibration time with label-efficient trial selection
Use nimbus-bci with MNE-Python
## Support
* **Email**: [hello@nimbusbci.com](mailto:hello@nimbusbci.com)
* **Docs**: [docs.nimbusbci.com](https://docs.nimbusbci.com)
* **PyPI**: [pypi.org/project/nimbus-bci](https://pypi.org/project/nimbus-bci/)
***
Ready to get started? Head to the [Installation Guide](/python-sdk/installation).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.