neurabridge 0.1.1

Neurabridge Python SDK for experiment access and analysis workflows

neurabridge

Neurabridge.io is the software layer for turning brain signal data into usable models and APIs.

It brings hardware-integrated research workflows, analysis pipelines, and application development into one system so teams can move from signal collection to deployable intelligence faster.

neurabridge is the official Python SDK for accessing that workflow programmatically. It provides a focused interface for discovering experiments, downloading run artifacts, decoding datasets, and organizing reproducible local analysis sessions.

Neurabridge is built for engineers, researchers, institutions, and hardware-adjacent product teams working with EEG and related brain signals. The platform is designed to support model development for studies, regressors, classifiers, and intent or activity segmentation systems, then expose those outputs through software interfaces that manufacturers and entrepreneurs can build on.

Table of Contents

• Installation
• What The SDK Covers
• Quick Start
• Standard Workflow
• Working Across Runs
• Public API Reference
• Notes

Installation

Install from PyPI using pip:

pip install neurabridge

For local development, clone the repository and install in editable mode:

git clone https://github.com/neurabridge-io/neurabridge_sdk.git
cd neurabridge_sdk/neurabridge_sdk/python
pip install -e .[dev]

What The SDK Covers

• Authenticate against a Neurabridge API environment
• List experiments and runs visible to the current token
• Download a single run or all runs in a collection
• Load decoded signal datasets as pandas DataFrames
• Load associated image artifacts with Pillow
• Create portable local analysis sessions with a manifest

Why It Exists

Brain-computer application development is fragmented across vendors, protocols, experimental setups, device integrations, raw data handling, one-off analysis scripts, and ad hoc model pipelines. Neurabridge consolidates those steps into a software-first foundation that makes brain signal data easier to inspect, organize, model, and expose through downstream products.

For technical teams, that means less time spent stitching together infrastructure and more time spent building useful systems on top of brain data.

Quick Start

import neurabridge as nb

client = nb.Client(
    base_url="https://api.neurabridge.dev",
    token="nbk_live_xxxxx",
)

whoami = client.whoami()
experiments = client.experiments()

experiment = experiments[0]
run = client.runs(experiment.id)[0]
local_run = client.download(experiment.id, run.id)

dataset = local_run.dataset
metadata_named_dataset = local_run.load_dataset(use_metadata_channel_names=True)
images = local_run.images()

Standard Workflow

import neurabridge as nb
from neurabridge import session

client = nb.Client(base_url="https://api.neurabridge.dev", token="nbk_live_xxxxx")

experiments = client.experiments()
selected_experiment = experiments[0]
selected_run = client.runs(selected_experiment.id)[0]

local_run = client.download(selected_experiment.id, selected_run.id, show_progress=False)

analysis_session = session.AnalysisSession.create(
    name="example-session",
    runs=[local_run],
    base_dir="./analysis",
)

signals = analysis_session.load_signals(
    exp_id=local_run.experiment_id,
    run_id=local_run.run_id,
)
images = analysis_session.load_images(
    exp_id=local_run.experiment_id,
    run_id=local_run.run_id,
)

Working Across Runs

client = nb.Client(base_url="https://api.neurabridge.dev", token="nbk_live_xxxxx")

experiments = client.experiments()
all_runs = experiments.download_all(show_progress=False)
stacked_dataset = all_runs.dataset

Platform Fit

Neurabridge does not build hardware devices today. It is intended to sit above hardware and unify the software layer around it: experiment data access, signal decoding, analysis workflows, model development, and API-ready outputs.

That makes it useful both for internal research teams and for external partners who want a faster path from hardware-generated brain data to applications.

Public API

The root package exposes the main stable entry points:

• neurabridge.Client
• neurabridge.AnalysisSession
• neurabridge.Experiment
• neurabridge.Run
• neurabridge.LocalRun
• neurabridge.ExperimentCollection
• neurabridge.LocalRunCollection

Segmented namespaces are also available when you want to keep imports explicit:

from neurabridge import experiment, session

Client

Main entry point for interacting with the Neurabridge API.

Method	Parameters	Returns	Description
whoami()	—	dict	Get the authenticated user information
experiments()	—	ExperimentCollection	List all experiments accessible to the token
runs(exp_id)	exp_id: str	list[Run]	Get all runs for a specific experiment
download(exp_id, run_id, show_progress)	exp_id: str, run_id: str, show_progress: bool = True	LocalRun	Download a single run to local cache
download_all(show_progress)	show_progress: bool = True	LocalRunCollection	Download all runs from all experiments
delete_run(exp_id, run_id)	exp_id: str, run_id: str	int	Delete a specific run from the server
delete_experiment(exp_id)	exp_id: str	int	Delete an entire experiment from the server
close()	—	—	Close the client and clean up resources

Experiment

Metadata and stats about a remote experiment.

Property	Type	Description
id	str	Unique experiment identifier
path	str	Experiment path/location on server
run_count	int	Number of runs in this experiment
updated_at	str | None	Last update timestamp

Run

Metadata about a remote run (before download).

Property	Type	Description
id	str	Unique run identifier
experiment_id	str	ID of parent experiment
path	str	Run path/location on server
artifact_count	int	Number of artifacts (signals, images, etc.)
size_bytes	int	Total size of run data in bytes
updated_at	str | None	Last update timestamp

LocalRun

A downloaded run with local file access and data loading capabilities.

Property/Method	Returns	Description
id	str	Alias for run_id
run_id	str	The run's unique identifier
experiment_id	str	Parent experiment ID
path	Path	Local filesystem path to downloaded run
signal_files	list[Path]	Paths to signal artifact files
image_files	list[Path]	Paths to image artifact files
dataset	DataFrame	Cached property: all signal data as pandas DataFrame
metadata	dict	Experiment metadata (channel names, sampling rates, etc.)
image	Image	First image artifact as PIL Image object
images	list[tuple[dict, Image]]	All image artifacts with metadata
load_dataset(use_metadata_channel_names)	DataFrame	Load signal data with optional metadata-based column names

ExperimentCollection

A list-like collection of Experiment objects with batch operations.

Method	Parameters	Returns	Description
download_all(show_progress)	show_progress: bool = True	LocalRunCollection	Download all runs from all experiments in collection

LocalRunCollection

A list-like collection of LocalRun objects with aggregation operations.

Property/Method	Returns	Description
dataset	DataFrame	Cached property: stacked signal data from all runs
load_dataset(use_metadata_channel_names, force_reload)	DataFrame	Load and concatenate all run datasets with optional cache control
profile_dataset_load(use_metadata_channel_names, force_reload)	dict	Load all datasets while measuring timing, row/column counts per run

AnalysisSession

Local writable workspace for reproducible analysis across downloaded runs.

Method	Parameters	Returns	Description
create(name, runs, base_dir)	name: str, runs: Iterable[LocalRun], base_dir: str | Path	AnalysisSession	Create a new analysis session workspace with run data
open(session_path)	session_path: str | Path	AnalysisSession	Open an existing session from disk
list(base_dir)	base_dir: str | Path	list[AnalysisSession]	List all valid sessions under a directory
load_signals(exp_id, run_id, use_metadata_channel_names)	exp_id: str, run_id: str, use_metadata_channel_names: bool = False	DataFrame	Load signal data from session workspace
load_images(exp_id, run_id)	exp_id: str, run_id: str	list[tuple[dict, Image]]	Load image artifacts from session workspace
delete()	—	—	Delete the session directory from disk

Session Properties

Property	Type	Description
name	str	Session name
path	Path	Local filesystem path to session directory
manifest	dict	Session metadata manifest (JSON-serializable dict with run info)

Notes

• Signal data is returned as pandas DataFrames
• Image artifacts are returned as Pillow images
• Downloads are cached locally under the SDK cache directory
• Analysis sessions store a lightweight manifest so downloaded runs can be reopened consistently
• The SDK is intentionally read-oriented and centered on analysis and downstream application workflows

Validation Notebook

The repository includes a smoke-test notebook that exercises the main SDK flow from authentication through dataset loading, manifest decoding, image rendering, and bulk download.

Getting Help

• Documentation: https://neurabridge.io
• PyPI Package: https://pypi.org/project/neurabridge/
• GitHub Issues: https://github.com/neurabridge-io/neurabridge_sdk/issues
• API Support: For API-related questions, contact [e-mail]

Contributing

We welcome contributions! To get started:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: pytest tests/
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a detailed history of changes and releases.