Metadata-Version: 2.4
Name: neuroflow-sdk
Version: 0.1.0
Summary: Python SDK for NeuroFlow — the hardware-agnostic neural data platform. Connect to EEG/BCI devices, stream real-time data, and extract features with zero neuro-expertise required.
Author: Cephios
License-Expression: MIT
Project-URL: Homepage, https://github.com/cephios/neuroflow
Project-URL: Documentation, https://docs.neuroflow.dev/sdk/python
Project-URL: Repository, https://github.com/cephios/neuroflow
Project-URL: Issues, https://github.com/cephios/neuroflow/issues
Keywords: eeg,bci,neuroscience,brainflow,neuroflow,brain-computer-interface
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24
Requires-Dist: websockets>=11.0
Requires-Dist: pydantic>=2.0
Provides-Extra: local
Requires-Dist: brainflow>=5.10; extra == "local"
Requires-Dist: numpy>=1.24; extra == "local"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Provides-Extra: all
Requires-Dist: brainflow>=5.10; extra == "all"
Requires-Dist: numpy>=1.24; extra == "all"
Requires-Dist: pytest>=7.4; extra == "all"
Requires-Dist: pytest-asyncio>=0.21; extra == "all"

# NeuroFlow SDK for Python

[![Version](https://img.shields.io/badge/version-0.1.0-blue)](https://pypi.org/project/neuroflow/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**Build brain-computer interfaces in Python.** Connect to 20+ EEG/BCI devices, stream real-time neural data, extract features, and run ML predictions — with zero neuroscience expertise required.

```python
from neuroflow import Client

client = Client(base_url="http://localhost:8000", api_key="your-key")

# Discover and connect
devices = client.discover_devices()
device = client.connect(devices[0].id)

# Stream with real-time features
session = device.start_session()
for packet in session.stream():
    print(f"Focus: {packet.features.focus_score:.2f}")
    print(f"Alpha: {packet.features.band_powers['alpha']:.2f}")

session.stop()
```

## Installation

```bash
pip install neuroflow
```

For local device access (no server needed):

```bash
pip install "neuroflow[local]"
```

## Quick Start

### Remote Mode (via API server)

```python
from neuroflow import Client

client = Client(base_url="http://localhost:8000", api_key="your-key")

# List available devices
devices = client.discover_devices()

# Connect and start session
device = client.connect(devices[0].id)
session = device.start_session()

# Get features
features = session.get_features()
print(f"Band powers: {features.band_powers}")
print(f"Focus score: {features.focus_score}")

session.stop()
device.disconnect()
```

### Local Mode (direct device access, no server)

```python
from neuroflow import LocalClient

# Connect to synthetic board for development
client = LocalClient(board_id=-1)
client.connect()

# Start streaming
client.start_stream()
data = client.get_data(num_samples=512)

# Extract features locally
features = client.get_features()
print(f"Alpha power: {features.band_powers['alpha']:.4f}")

client.stop_stream()
client.disconnect()
```

### Async Streaming

```python
import asyncio
from neuroflow import AsyncClient

async def main():
    client = AsyncClient(base_url="http://localhost:8000", api_key="your-key")

    devices = await client.discover_devices()
    device = await client.connect(devices[0].id)
    session = await device.start_session()

    async for packet in session.stream():
        print(f"Focus: {packet.features.focus_score:.2f}")
        if packet.features.focus_score > 0.8:
            print("High focus detected!")
            break

    await session.stop()

asyncio.run(main())
```

## Features

- **20+ Device Support** — Muse, OpenBCI, Emotiv, BrainBit, g.tec, and more via BrainFlow
- **Real-Time Processing** — Sub-millisecond Rust-accelerated DSP pipeline (0.18ms P95)
- **Feature Extraction** — Band powers, spectral entropy, Hjorth parameters, connectivity metrics
- **ML Inference** — ONNX model deployment for focus detection, relaxation, and custom classifiers
- **Dual Mode** — Remote (API server) or Local (direct device access)
- **Type-Safe** — Full Pydantic models with type hints throughout
- **Async Support** — Native async/await with `AsyncClient`

## Supported Devices

| Device | Board ID | Protocol |
|--------|----------|----------|
| Synthetic (dev) | -1 | Simulated |
| Muse 2 | 22 | Bluetooth |
| Muse S | 21 | Bluetooth |
| OpenBCI Cyton | 0 | Serial |
| OpenBCI Ganglion | 1 | Serial/BLE |
| Emotiv Insight | 25 | Bluetooth |
| BrainBit | 7 | Bluetooth |
| ... and 20+ more | | |

## Documentation

- [Quickstart Guide](https://docs.neuroflow.dev/docs/quickstart)
- [Python SDK Reference](https://docs.neuroflow.dev/docs/sdk-python)
- [API Reference](https://docs.neuroflow.dev/docs/api-reference)

## License

MIT
