> ## 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.
# Nimbus Development Workflow
> Build production BCI applications with Nimbus using practical project structure, testing, debugging, and deployment guidance.
This guide covers project organization and production workflow. It does not repeat SDK installation or full examples; use the linked pages for those details.
* Python product path: [Personalizer & Middleware](/personalizer/overview)
* Python setup: [Python SDK Installation](/python-sdk/installation)
* Julia setup: [Julia SDK Quickstart](/julia-sdk/quickstart)
* Recipes: [Basic Examples](/examples/basic-examples) and [Advanced Applications](/examples/advanced-applications)
## Recommended Project Structure
Keep acquisition, preprocessing / encoding, personalization, and application logic separate. That makes it easier to test each stage and swap trunks, heads, or SDKs later.
```text theme={null}
my-bci-project/
src/
acquisition/ # LSL, BrainFlow, hardware adapters
preprocessing/ # filtering, artifact handling, feature extraction
encoders/ # frozen trunk wrappers (optional product path)
models/ # Personalizer profiles / head training, normalization
inference/ # batch and streaming inference → BrainState
app/ # UI, control, feedback, safety policy
data/
raw/
processed/
calibration/
tests/
notebooks/
README.md
```
## Development Workflow
1. **Define the BCI paradigm**: motor imagery, P300, SSVEP, or another task.
2. **Lock the input contract**: frozen encoder (`model_id`, `embedding_dim`) **or** classical feature type, sampling rate, channels, window, normalization.
3. **Fit a baseline**: start with `Personalizer(head="lda")` on embeddings, or `NimbusLDA` on classical features; compare heads only if the baseline fails.
4. **Evaluate offline**: use held-out sessions / CV before streaming; inspect `BrainState` gating.
5. **Add streaming**: process embedding or feature chunks and aggregate trial decisions.
6. **Add safety policy**: reject low confidence / high uncertainty (`need_more_data`) and log decisions.
7. **Deploy with monitoring**: track latency, confidence, rejection rate, and drift.
## Data Contracts
Document these invariants in your project:
| Field | Why It Matters |
| - | - |
| Sampling rate | Required for reproducible windows and chunk sizes. |
| Feature type | Models trained on CSP should not receive ERP features. |
| Feature count | Must match the model and metadata. |
| Label encoding | Python workflows can use sklearn-style labels; Julia examples typically use 1-indexed labels. |
| Normalization params | Must be estimated on training data and reused for deployment. |
## Model Lifecycle
Treat a deployed model as more than weights. Save:
* model object or model identifier
* SDK version
* feature extraction settings
* normalization parameters
* class labels and label mapping
* training session metadata
* validation metrics
Example metadata (Personalizer profile):
```json theme={null}
{
"surface": "Personalizer",
"head": "lda",
"model_id": "partner-encoder",
"embedding_dim": 64,
"sdk": "nimbus-bci",
"classes": ["left", "right"],
"preset": "research",
"trained_on": "2026-04-25"
}
```
Classical-head metadata can still use `"model": "NimbusLDA"` + `"feature_type": "csp"`. Persist `Personalizer.save(...)` profiles separately from the frozen trunk weights.
## Testing Strategy
Prioritize small tests around contracts and failure modes:
* Encoder / preprocessing output has expected shape and finite values.
* Labels match the number of trials.
* Normalization params are reused, not recomputed on test data.
* Personalizer rejects incompatible `embedding_dim` / `model_id` on load.
* Streaming chunks match `chunk_size`.
* Low-confidence / high-uncertainty `BrainState` triggers the expected safety path.
For numerical tests, avoid hardcoding exact posteriors unless the model is fully deterministic. Prefer shape, range, monotonicity, and threshold checks.
## Debugging Checklist
When accuracy or confidence is poor:
1. Confirm data shape and label encoding.
2. Check for NaN, Inf, constant features, logits passed as embeddings, or raw EEG as features.
3. Verify the encode contract or preprocessing band / time window match the paradigm.
4. Reuse training normalization parameters on test data.
5. Compare against `Personalizer.for_deployment` / `NimbusLDA` as a baseline.
6. Inspect `BrainState` confidence, uncertainty, and `need_more_data`, not only accuracy.
7. Run preprocessing diagnostics before tuning model hyperparameters.
## Performance Guidance
* Warm up streaming inference before a live session.
* Preallocate buffers in real-time loops.
* Keep filtering and feature extraction outside hot model code when possible.
* Prefer batch inference for offline evaluation.
* Log per-stage latency: acquisition, preprocessing, inference, and application action.
## Production Guardrails
Production BCI systems should include:
* confidence thresholds by action risk
* trial rejection and retry flows
* session-level health monitoring
* model/version audit logs
* fallback behavior when the stream drops
* clear separation between prediction and command execution
See [Error Handling](/inference-configuration/error-handling) for a focused checklist.
## Next Read
Export/import handoff from MNE, EEGLAB, OpenViBE, or MATLAB.
Cross-session scaling strategy.
Chunking, aggregation, and quality gates.
Choose the right model family.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.