Metadata-Version: 2.4
Name: neurabridge
Version: 0.1.1
Summary: Neurabridge Python SDK for experiment access and analysis workflows
Project-URL: Homepage, https://neurabridge.io
Project-URL: Repository, https://github.com/neurabridge-io/neurabridge_sdk
Project-URL: Documentation, https://neurabridge.io
Project-URL: Bug Tracker, https://github.com/neurabridge-io/neurabridge_sdk/issues
Author: Neurabridge
License: MIT
License-File: LICENSE
Keywords: brain-computer-interface,data-analysis,eeg,neuroscience,signal-processing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: pillow>=10
Requires-Dist: tqdm>=4.66
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# neurabridge

[![PyPI version](https://img.shields.io/pypi/v/neurabridge.svg)](https://pypi.org/project/neurabridge/)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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](#installation)
- [What The SDK Covers](#what-the-sdk-covers)
- [Quick Start](#quick-start)
- [Standard Workflow](#standard-workflow)
- [Working Across Runs](#working-across-runs)
- [Public API Reference](#public-api)
- [Notes](#notes)

## Installation

Install from PyPI using pip:

```bash
pip install neurabridge
```

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

```bash
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

```python
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

```python
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

```python
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:

```python
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 support@neurabridge.io

## 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](LICENSE) file for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes and releases.
