Nimbus BCI

Exploratory summary of a public EEG dataset (MOABB pack): channels, sampling rate, trial/class balance, per-channel µV stats, band powers and a PSD overview. Look at the data BEFORE building pipelines: class balance drives stratification choices (imbalanced classes skew accuracy), and flatlined channels mean a montage/reference problem worth fixing first. subject defaults to the dataset's catalog ``defaultSubject`` (see catalog.datasets), e.g. "S01"; a comma-list like "S01,S03" loads a cohort. mode: training | evaluation | all. Units note: values are ASSUMED volts by the loader — a µV-native …

Exploratory summary of an EEG file (.edf/.bdf/.mat/.csv/.tsv/.txt/.h5): channels, sampling rate, trial/class balance, per-channel µV stats, band powers and a PSD overview. The path shape picks the source: ABSOLUTE path → read the file from disk (only on a LOCAL backend: desktop app / MCP local mode — no upload needed); RELATIVE path (the one data.upload returns) → describe the uploaded file, which works on ANY backend (hosted or local). Look at the data BEFORE building pipelines: class balance drives stratification choices, and flatlined channels mean a montage/reference problem worth fixing…

Upload an EEG file (.edf/.bdf/.mat/.csv/.txt/.tsv/.h5/.hdf5, <=500MB) to the backend and get the registered path for a custom_data node. sampling_rate (Hz, e.g. 250.0) is REQUIRED for plain CSV/TSV/TXT files without embedded metadata — uploads without it are rejected (no silent 250 Hz assumption). format overrides extension-based detection (auto, mat, csv, tsv, txt, edf, bdf, h5, hdf5). Args: file_path: Local file to upload (.edf/.bdf/.mat/.csv/.txt/.tsv/.h5/.hdf5, <=500MB). dataset_name: Optional label for the uploaded dataset. sampling_rate: Hz for headerless CSV/TSV/TXT (REQUI…

EEG devices supported by this backend (OpenBCI, Muse, BrainBit, LSL, PiEEG...).

Test a device connection WITHOUT starting a stream (safe, no confirm needed). Args: device_type: Device id from device.list (e.g. "brainbit", "muse"). connection_type: Device-specific selector when several exist (e.g. serial vs wifi). port: Serial/COM port for wired devices. ip_address: Device IP for network/wifi devices. ip_port: Port for network devices. stream_name: LSL stream name (LSL devices). source_id: LSL source id. mac_address: Bluetooth MAC (BT devices). serial_number: Device serial (some BLE stacks).

Trained artifacts (models/filters, e.g. *.pkl) saved by an execution. Args: execution_id: Run whose artifacts to list.

Cancel a running execution. Args: execution_id: The run to terminate (from execution.run/execution.list).

Permanently delete one of your finished runs (completed/failed/cancelled) with its results. Running runs must be cancelled first (409 nimbus.execution.delete_not_terminal). Owner only. Args: execution_id: The run to delete (from execution.run/execution.list). confirm: MUST be true to delete — the explicit user go-ahead.

Download one artifact file. Local/stdio: saved to NIMBUS_EXPORT_DIR/executions/<id>/ and its path returned. Hosted gateway: returned inline as ``contentBase64`` (up to 1 MB of base64); larger files point to Nimbus Studio. Nothing is written on the gateway. Args: execution_id: Run that produced the artifact. artifact_name: File name from execution.artifacts (e.g. "nimbus_lda.pkl").

Execution status summary (status: running/completed/failed/cancelled). Summary fields: ``dataset`` is the human-readable display label (e.g. "BCIIV2a"); ``datasetId`` is the catalog id (e.g. "BNCI2014_001") accepted by other tools (data.inspect_dataset, public_data.dataset). ``title`` is the run name shown in Studio. Args: execution_id: The run to check (from execution.run/execution.list).

Recent executions. Optional status filter (running/completed/failed/cancelled). Per-run fields: ``dataset`` is the human-readable display label (e.g. "BCIIV2a"); ``datasetId`` is the catalog id (e.g. "BNCI2014_001") accepted by other tools (data.inspect_dataset, public_data.dataset). ``title`` is the run name shown in Studio. Args: limit: Maximum number of runs to return (default 20). status: Filter by run status: running/completed/failed/cancelled.

Metrics for a completed run. Trimmed by default (accuracy, kappa, ITR, confusion matrix, per-class); full=True returns the complete result object. Args: execution_id: The completed run to fetch metrics for. full: Return the backend's complete result object (all fields).

Start a pipeline run (NON-BLOCKING). Returns executionId — poll with execution.get() until status is completed/failed, then execution.results(). If an identical graph is already running for you, the run still starts but the response carries a ``warning`` + ``duplicateOf`` ids (cancel one with execution.cancel to avoid paying twice). The server runs a limited number of executions at once (3 by default); when all slots are busy the call fails immediately with 429 nimbus.execution.queue_full and a retryAfter (seconds) — wait, then retry. Args: train_graph: Pipeline graph {nodes: [{id, type, …

Delete one of your experiment records (server + this machine's local cache). Its individual runs are kept — delete them with execution.delete. A still-running experiment cannot be deleted. Args: experiment_id: The experiment to delete (from experiment.run). confirm: MUST be true to delete — the explicit user go-ahead.

Experiment snapshot: status (running/completed/failed), per-run rows ({name, executionId, status, error?, metrics?, evaluationKind?}) and, once finished, aggregates over completed runs only: per-metric {mean, std, best, n}, plus ``pooledExecutionIds`` / ``pooledRunNames`` / ``kindBreakdown`` (per-subject vs LOSO etc. — each row has kind, n, mean, std, executionIds, runNames; #470). Pooled headline means are unchanged; kindBreakdown labels what was pooled. std is population; None below 2 values. kindBreakdown is always present when aggregates exist (including single-kind experiments). PORTABIL…

Run 1-25 pipelines as ONE paced experiment (NON-BLOCKING). Returns an experimentId immediately; a background thread submits at most 2 runs at a time (min(max_concurrent, 2)), retries queue-full up to 3 times per run, and polls each execution to completion. Poll experiment.get() for per-run status and, once finished, aggregated metrics. PORTABILITY: the experiment record is written through to the Nimbus server under your account (at start and at completion), so experiment.get works from ANY entry point — local stdio, hosted gateway, another machine — signed in with the same account/token. If t…

Run every available pretrained backbone on YOUR data and see which wins — a ranked bar chart with CI whiskers, params, and wall time per backbone. Backbones that can't process your data (window size, channel count) are noted, not silently skipped. Each backbone embeds your trials frozen (the exact foundation_features preprocessing), a LDA is cross-validated on the embeddings. Returns a PNG image PLUS a JSON text block (and structuredContent.meta.results) with per-backbone accuracy, CI, embed dim, params, and time — pick the foundation_features backbone by measurement, not vibes. Args: sou…

List your leaderboard submissions (newest first), all datasets.

Fetch one of your leaderboard submissions (owner-only). Returns status (queued | scoring | done | failed), metrics when done (meanAccuracyPct + CI, same shape as leaderboard rows), or the error that failed it. Args: submission_id: The submissionId returned by leaderboard.submit.

Submit a BYO python_model to a leaderboard track for server-side scoring. Nimbus scores it server-side under the track's fixed protocol — you submit code, never results. Poll ``leaderboard.status`` with the returned ``submissionId``; scoring takes minutes (classical) to tens of minutes (deep). Requirements must be plain PyPI names/specs (max 20, no URLs). Identical code resubmission is idempotent per track (``deduplicated: true``). Verification contract (tier model X10): ``verification="verified"`` (default) is the server-side-scored submission above — on the hosted backend it is Pro-only; f…

Export the pipeline as a standalone runnable Python bundle (zip). Local/stdio: the zip is saved under NIMBUS_EXPORT_DIR/exports and its path returned. Hosted gateway: the zip is returned inline as ``contentBase64`` (up to 1 MB of base64). UI-only nodes (interactive_application) are left out and listed in ``exportNotes``. Args: train_graph: Pipeline graph {nodes, connections} to export. name: Optional name recorded inside the bundle.

Validate a pipeline graph before running. ExecGraphSnapshot: {nodes: [{id, type, config}], connections: [{from, to}]}. Build it from catalog.template(id).train or from scratch using catalog.nodes(). Args: train_graph: The graph to validate ({nodes, connections}).

Validate one node's config (schema + semantic checks). Catches the same value errors as pipeline.validate for a single node (inverted bandpass, CSP components vs channel count when dataset is set). Args: node_type: Node type id from catalog.nodes (e.g. "csp", "bandpass_filter"). config: The node's config object to check. dataset: Optional MOABB pack id (e.g. "BNCI2014_001") so CSP/Nyquist checks can use channel count and sampling rate. Omitted → those context checks are skipped; inverted-band checks still run.

Confusion-matrix figure for one execution: heatmap with trial counts + per-class accuracy bars, rendered as a PNG the assistant can see. Use it right after execution.results to eyeball WHICH classes are confused, not just the accuracy number. Args: execution_id: Run to plot (from execution.run / execution.results). matrix: "eval" (held-out, default) or "train" (fit-set / cross-validation). CV and evaluation-plan runs often have no eval matrix — use "train". save: Local/stdio: also write the PNG to NIMBUS_EXPORT_DIR/plots/ and return its path. Ignored on the hosted …

Figure over an EEG data source — the visual companion to data.inspect_dataset. kind=psd (Welch, channel mean bold), kind=bandpower (channel × band dB heatmap), kind=topomap (band-power scalp map), kind=spectrogram (time-frequency for one channel). Sources are the same ones inspect uses: MOABB packs, uploads, local files. Args: kind: Figure type: psd | topomap | bandpower | spectrogram. source: "dataset" (MOABB pack), "upload" (path from data.upload), or "local" (absolute path, local backend only). dataset: MOABB dataset id, e.g. "BNCI2014_001" (source=dataset). subject…

ERP butterfly figure from epoched data: one subplot per class, all channel means (thin) + across-channel mean (bold), time-locked to the trial event. Shows whether class-conditioned evoked structure exists BEFORE training anything. Args: source: "dataset" (MOABB pack), "upload" (path from data.upload), or "local" (absolute path, local backend only). dataset: MOABB dataset id, e.g. "BNCI2014_001" (source=dataset). subject: Subject id, e.g. "S01" (source=dataset). mode: Pack split to load: training | evaluation | all (source=dataset). path: Upload path (source=upload…

Leaderboard bar chart for one dataset: accuracy with 95% CI whiskers, best first; BYO python_model submissions highlighted in a distinct color. The visual companion to catalog.leaderboard. On the pretrained_few_trial track the figure also includes the classical LOSO baseline as a muted side panel for comparison. Args: dataset_id: Dataset to chart, e.g. "BNCI2014_001" (see catalog.leaderboard). track: "within_session" (curated 5-fold), "crossSubject" (LOSO, curated + BYO submissions), or "pretrained_few_trial" (the efficiency track: LOSO at the protocol's fixed per-subj…

Create a project (container for one pipeline document). Returns projectId. Args: name: Project display name (e.g. "MI CSP-LDA sweep"). description: Optional longer description shown in the studio.

Delete a project (and its saved pipeline document) from the studio workspace. Requires confirm=True: this removes the project from the user's project list. Executions already run from it are not affected. Find ids with project.list. Args: project_id: Project to delete (from project.create/project.list). confirm: MUST be true to delete — the explicit user go-ahead.

List projects owned by the current principal (agent work included).

Load a project's saved pipeline (train graph + meta) for editing/re-running. Args: project_id: Project whose pipeline document to load.

Rename a project you own (max 200 characters). Args: project_id: Project to rename (from project.create/project.list). name: New display name.

Save a pipeline graph into a project (visible on the studio canvas). Always pass expected_revision from the last project.load (or a prior save/create response). When it does not match the current server revision, the save fails with a conflict — it does NOT silently overwrite concurrent edits. Omitting it is rejected so a stale single-writer convenience path cannot wipe another client's work. Args: project_id: Target project (from project.create/project.list). train_graph: Pipeline graph {nodes, connections} to persist. name: Optional pipeline name stored on the document. sub…

Paired pre/post analysis for one assignment's recorded sessions: per-block aggregates (descriptive + CSV), paired t / Wilcoxon / dz (per-statistic minimums: paired t and Cohen's dz need ≥ 3 completed sessions, Wilcoxon needs ≥ 5), specificity notes, the adaptive-threshold trajectory, and a pre/post figure (base64 PNG — render or save it to look at the effect). An assignment with no recordings yet returns the empty payload with a note, never an error. Args: assignment_id: The assignment to analyze (from start_assignment).

Every saved protocol id at its latest version.

Pause a running protocol session (blocks freeze; the session and device stay alive — resume with protocol.resume). Simulated and playback sessions only while paused: no data is recorded. Args: session_id: The deploy session to pause.

Resume a paused protocol session (restarts the server-driven device loop). Live-hardware resume requires a Pro plan; simulated sessions are free. Pass the session's channel count (start_assignment reports it). Args: session_id: The deploy session to resume. chunk_size: Samples per streamed chunk (default 125). n_channels: Session channel count (the built-in template opens 4).

Validate and persist the NEXT VERSION of a protocol document (confirm-gated: each call appends a version row; accidental calls clutter the version history). Edits create a new version — the assignment pins the version it runs. Args: spec: Wire-format protocol document (validate first to iterate). confirm: MUST be true to write.

Live snapshot of a protocol deploy session: the scheduler block / session progress + threshold state (under ``protocol``) beside the telemetry window (recent indicators, quality, stats). Args: session_id: The deploy session to inspect (from start_assignment). window: How many recent predictions to include (1-200, default 50).

Enroll a subject and prepare their neurofeedback deploy session (confirm-gated — a session runs on a human). Creates the assignment (yoked sham arms REQUIRE yoked_donor_upload_id: a recorded simulated session's upload — mint one by running an active-arm session and data.upload-ing its recording), then persists the protocol graph as a deployable execution. Requires a Pro plan for LIVE hardware sessions; simulated-source sessions (the default template) are free. Graph source: execution_id reuses THAT run's stored graph (it must contain a protocol_session node; no device is pre-connected — the d…

Stop a protocol session (always safe to call): stops streaming, saves the block-annotated recording, advances the assignment when the scheduler reached its natural end, and disconnects the device (best-effort — a failed disconnect is reported, never raised). Args: session_id: The deploy session to stop.

Validate a neurofeedback protocol document WITHOUT saving it. Returns {valid: true, spec} on success, or {valid: false, errors: [...]} with the per-violation list (loc/msg) when the document is invalid — the verdict is data, never an exception. Args: spec: Wire-format protocol document (camelCase): id, name, indicator {name, transform}, armDefaults, blocks [{id, kind: assessment|training, durationSec, feedback?}], threshold, sessions, breakCriteria.

Statically check a python_model script (BYO model class) without running it. Compiles the source and verifies the contract — a class with fit(X, y, info) and predict(X); optional predict_proba(X) unlocks confidence panels. Never executes the code, so it is safe against the hosted backend. Use it before execution.run to catch syntax errors, missing methods, or the wrong class name cheaply. Args: code: Python source of the model class (<=256KB UTF-8). class_name: Contract class to instantiate; omit to auto-detect the first class defining fit+predict.

Cluster-aware group statistics across executions. REQUIREMENT (read first): each execution must have been run with an evaluation plan that STORED per-SUBJECT accuracies for at least 3 subjects — e.g. leave-one-subject-out (LOSO) or grouped CV over >= 3 subjects. Session groups within one subject (multi-session single-subject runs) are refused with ``nimbus.stats.non_subject_groups`` — those are not independent subjects. A plain single-subject CV run with no subject/session grouping stores no group stats and fails with ``nimbus.stats.insufficient_groups``. What it does: pools the per-subject …

Connect an EEG device and START a live streaming session on the user's head. Requires confirm=True; call device.test first. Track with stream.status(). Idle watchdog: if no stream.status()/stream.telemetry() poll happens for idle_timeout_sec (default 900), the session is stopped and the device disconnected automatically — an abandoned stream never keeps running on the user's head. Any poll resets the timer; idle_timeout_sec=0 disables the watchdog. Args: device_type: Device id from device.list (e.g. "brainbit"). confirm: MUST be true to start — the explicit user go-ahead for a live …

Live snapshot of a streaming session (running, deviceConnected). Polling this also feeds the idle watchdog: each call resets the session's idle timer (see stream.start's idle_timeout_sec). Args: session_id: The streaming session to inspect.

Stop a streaming session and disconnect the device (always safe to call). Also removes the session from the idle watchdog so it cannot fire after an explicit stop. Args: session_id: The streaming session to stop.

Live snapshot of a streaming session: latest prediction + recent window, signal quality (meanChannelQuality, snrDb, artifactProbability), indicators, running stats. Poll this while a session runs. Works with OR without a deployed model: modelless hardware streams (no classifier) report live signal quality + focus/relaxation band-power indicators with latestPrediction null; deployed sessions additionally carry predictions and confidence stats. Expect low confidence during filter/ASR warm-up (first seconds); quality < 0.5 or high artifactProbability means the signal is poor. 404 => session not a…