Metadata-Version: 2.4
Name: neuroskill-dev
Version: 0.0.1
Summary: Command-line interface for the NeuroSkill real-time EEG analysis API
Project-URL: Homepage, https://neuroskill.dev
Project-URL: Repository, https://github.com/NeuroSkill-com/neuroskill
Project-URL: Documentation, https://neuroskill.dev/docs
Project-URL: Bug Tracker, https://github.com/NeuroSkill-com/neuroskill/issues
Author-email: Nataliya Kosmyna <nkosmyna@mit.edu>, Eugene Hauptmann <eugenehp@mit.edu>
License: GPL-3.0-only
License-File: LICENSE
Keywords: bci,brainwave,eeg,eeg-analysis,muse,neuroskill
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Requires-Dist: websockets>=11.0
Requires-Dist: zeroconf>=0.131.0
Description-Content-Type: text/markdown

# neuroskill

**neuroskill** is a command-line interface for the [NeuroSkill](https://neuroskill.com) real-time EXG analysis API. It communicates with a locally running Skill server over **WebSocket** or **HTTP**, giving you instant terminal access to EEG brain-state scores, sleep staging, session history, annotations, similarity search, and more.

This is the **Python** port of the [TypeScript neuroskill CLI](https://github.com/NeuroSkill-com/neuroskill). It is a faithful port — same commands, same flags, same output format, same transport negotiation.

> ⚠️ **Research Use Only.** All metrics are experimental outputs derived from consumer-grade EXG hardware. They are **not** validated clinical measurements, not FDA/CE-cleared, and must not be used for diagnosis, treatment decisions, or any medical purpose.

[Paper](https://arxiv.org/abs/2603.03212)

---

## Table of Contents

1. [Features](#features)
2. [Requirements](#requirements)
3. [Installation](#installation)
4. [Quick Start](#quick-start)
5. [Transport](#transport)
6. [Commands](#commands)
7. [Output Modes](#output-modes)
8. [Global Options](#global-options)
9. [Examples](#examples)
10. [How to Cite](#how-to-cite)
11. [License](#license)

---

## Features

- **Real-time EEG scores** — focus, relaxation, engagement, meditation, cognitive load, drowsiness
- **Consciousness metrics** — Lempel-Ziv Complexity proxy, wakefulness, information integration
- **PPG / HRV** — heart rate, RMSSD, SDNN, pNN50, LF/HF, SpO₂, Baevsky stress index
- **Sleep staging** — automatic per-epoch classification and session-level summary
- **Session history** — list, compare, and UMAP-project all past recording sessions
- **Annotations** — create timestamped labels and search them by free text or EEG similarity
- **Interactive graph search** — cross-modal 4-layer graph (labels → EEG → labels)
- **Dual transport** — WebSocket (full-duplex, live events) and HTTP REST (curl-friendly)
- **Pipe-friendly** — `--json` flag emits clean JSON to stdout; informational lines go to stderr
- **Cross-platform** — Python ≥ 3.9, Windows / macOS / Linux

---

## Requirements

| Dependency | Version |
|------------|---------|
| Python | ≥ 3.9 |
| Skill server | running locally (auto-discovered via mDNS or `lsof`) |

---

## Installation

### Via pip / uv (recommended)

```bash
pip install neuroskill
```

or with [uv](https://github.com/astral-sh/uv):

```bash
uv tool install neuroskill
```

After installation the `neuroskill` binary is available globally:

```bash
neuroskill status
```

### From source

```bash
git clone https://github.com/NeuroSkill-com/neuroskill-py
cd neuroskill-py
uv sync
uv run neuroskill status
```

---

## Quick Start

```bash
# Full device / session / scores snapshot
neuroskill status

# Pipe raw JSON to jq (or python -m json.tool)
neuroskill status --json | python3 -m json.tool
neuroskill status --json | jq '.scores'

# Stream broadcast events for 10 seconds
neuroskill listen --seconds 10

# Print full help with examples
neuroskill --help
```

---

## Transport

neuroskill auto-discovers the Skill server port via:

1. `--port <n>` flag (skips all discovery)
2. mDNS (`_skill._tcp` service advertisement, 5 s timeout)
3. `lsof` / `pgrep` fallback (probes each TCP LISTEN port)

### WebSocket (default)

Full-duplex, low-latency. Supports live event streaming. Used automatically when the server is reachable.

```bash
neuroskill status --ws          # force WebSocket
```

### HTTP REST

Request/response only. Compatible with `curl`, Python `requests`, or any HTTP client.

```bash
neuroskill status --http        # force HTTP

# Equivalent curl call:
curl -s -X POST http://127.0.0.1:8375/ \
  -H "Content-Type: application/json" \
  -d '{"command":"status"}'
```

### Auto (neither flag)

The CLI probes WebSocket first and silently falls back to HTTP. Informational messages go to **stderr** so JSON piping is never polluted.

---

## Commands

| Command | Description |
|---------|-------------|
| `status` | Full device / session / embeddings / scores snapshot |
| `session [index]` | All metrics + trends for one session (`0` = latest, `1` = previous, …) |
| `sessions` | List all recording sessions across all days |
| `label "text"` | Create a timestamped annotation on the current moment |
| `search-labels "query"` | Search labels by free text (text / context / both modes) |
| `interactive "keyword"` | Cross-modal 4-layer graph search (labels → EEG → found labels) |
| `search` | ANN EEG-similarity search (auto: last session, k = 5) |
| `compare` | Side-by-side A/B metrics (auto: last 2 sessions) |
| `sleep [index]` | Sleep staging — index selects session (`0` = latest) |
| `calibrations [list\|get <id>]` | List calibration profiles or inspect one by ID |
| `calibrate` | Open calibration window and start immediately |
| `timer` | Open focus-timer window and start work phase immediately |
| `notify "title" ["body"]` | Show a native OS notification |
| `say "text"` | Speak text aloud via on-device TTS |
| `umap` | 3-D UMAP projection with live progress bar |
| `listen` | Stream broadcast events for N seconds |
| `raw '{"command":"..."}'` | Send arbitrary JSON and print full response |

---

## Output Modes

| Flag | Behaviour |
|------|-----------|
| _(none)_ | Human-readable colored summary to stdout |
| `--json` | Raw JSON only — pipe-safe, no colors |
| `--full` | Human-readable summary **and** colorized JSON |

---

## Global Options

```
--port <n>       Connect to explicit port (skips mDNS discovery)
--ws             Force WebSocket transport
--http           Force HTTP REST transport
--json           Output raw JSON (pipeable to jq / python -m json.tool)
--full           Print JSON in addition to human-readable summary
--poll <n>       (status) Re-poll every N seconds
--mode <m>       Search mode for search-labels: text|context|both (default: text)
--k <n>          Number of nearest neighbors for search / search-labels
--ef <n>         HNSW ef parameter for search-labels (default: max(k×4, 64))
--k-text <n>     (interactive) k for text-label search (default: 5)
--k-eeg <n>      (interactive) k for EEG-similarity search (default: 5)
--k-labels <n>   (interactive) k for label-proximity search (default: 3)
--reach <n>      (interactive) temporal reach in minutes around EEG points (default: 10)
--dot            (interactive) Output Graphviz DOT format
--context "..."  (label) Long-form annotation body stored with the label
--at <utc>       (label) Backdate to a specific unix second (default: now)
--voice <name>   (say) Voice name (e.g. Jasper); uses server default when omitted
--profile <p>    (calibrate) Profile name or UUID to run (default: active profile)
--seconds <n>    (listen) Duration in seconds (default: 5)
--trends         (sessions) Show per-session metric trends
--no-color       Disable ANSI colors (also honours NO_COLOR env var)
--version        Print CLI version and exit
--help           Show full help with examples
```

---

## Examples

```bash
# Device snapshot
neuroskill status

# Pipe scores to jq or python
neuroskill status --json | jq '.scores.focus'
neuroskill status --json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['scores']['focus'])"

# Poll status every 5 seconds
neuroskill status --poll 5

# Latest session metrics + trends
neuroskill session 0

# List sessions, show per-session metric trends
neuroskill sessions --trends

# Label the current moment
neuroskill label "started meditation"
neuroskill label "breathwork" --context "box breathing 4-4-4-4, 10 min"
neuroskill label "retrospective note" --at 1740412800

# Search past labels
neuroskill search-labels "meditation" --mode both --k 10

# 4-layer interactive graph search
neuroskill interactive "focus" --k-eeg 10 --reach 15
neuroskill interactive "anxiety" --dot | dot -Tsvg > graph.svg

# Sleep staging for latest session
neuroskill sleep 0

# Compare last two sessions
neuroskill compare

# ANN EEG similarity search
neuroskill search

# UMAP projection
neuroskill umap

# Calibration management
neuroskill calibrations
neuroskill calibrations get 3
neuroskill calibrate --profile "Eyes Open/Closed"

# Focus timer
neuroskill timer

# TTS and notification
neuroskill say "Calibration complete."
neuroskill say "Break time." --voice Jasper
neuroskill notify "Session done" "Great work!"

# Stream events for 30 seconds
neuroskill listen --seconds 30

# Send arbitrary JSON command
neuroskill raw '{"command":"status"}'
neuroskill raw '{"command":"search","start_utc":1740412800,"end_utc":1740415500,"k":3}'

# Force HTTP + specific port
neuroskill status --http --port 8375
```

---

## How to Cite

If you use **neuroskill** or the Skill EEG platform in academic work, please cite it as:

### BibTeX

```bibtex
@software{neuroskill2025,
  title        = {neuroskill: A Command-Line Interface for the Skill Real-Time EEG Analysis API},
  author       = {Nataliya Kosmyna and Eugene Hauptmann},
  year         = {2026},
  version      = {0.0.1},
  url          = {https://github.com/NeuroSkill-com/neuroskill},
  note         = {Research use only. Not a validated clinical tool.}
}
```

If you are citing the underlying **Skill** EEG analysis platform specifically:

```bibtex
@software{skill2025,
  title        = {NeuroSkill: Real-Time EEG Analysis Platform},
  author       = {Nataliya Kosmyna and Eugene Hauptmann},
  year         = {2026},
  url          = {https://neuroskill.com},
  note         = {Consumer-grade EEG processing pipeline with WebSocket and HTTP APIs.
                  Research use only. Not FDA/CE-cleared.}
}
```

---

## License

GPLv3 — see [LICENSE](LICENSE).
