# 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
