nucleuskit-toolkit 2.2.0__py3-none-any.whl

nucleuskit_toolkit/__init__.py

@@ -0,0 +1,3 @@
+"""Nucleus-Kit offline processing toolkit (``python -m nucleuskit_toolkit``)."""
+
+__version__ = "2.2.0"

nucleuskit_toolkit/__main__.py

@@ -0,0 +1,60 @@
+"""Entry point: ``python -m nucleuskit_toolkit`` or ``nucleuskit-toolkit`` CLI."""
+
+from __future__ import annotations
+
+import argparse
+
+import matplotlib
+
+matplotlib.use("Agg")
+
+
+def main(argv: list[str] | None = None) -> int:
+    from reak_core.models import DEFAULT_MODEL, available_models
+
+    from nucleuskit_toolkit.logging_utils import configure_logging
+
+    configure_logging()
+
+    parser = argparse.ArgumentParser(
+        description="Nucleus-Kit offline processing toolkit (Hermes EEG/EMG, Shimmer PPG/EDA)."
+    )
+    parser.add_argument(
+        "--session",
+        metavar="DIR",
+        help="Process this session folder and exit (no GUI).",
+    )
+    parser.add_argument(
+        "--config",
+        metavar="JSON",
+        help="Optional POV / ffmpeg JSON (merged after cwd defaults).",
+    )
+
+    parser.add_argument(
+        "--emotion-model",
+        metavar="NAME",
+        default=DEFAULT_MODEL,
+        help=(
+            "Emotion model registry key "
+            f"(default: {DEFAULT_MODEL}). Available: {', '.join(available_models())}."
+        ),
+    )
+    ns = parser.parse_args(argv)
+
+    if ns.session:
+        from nucleuskit_toolkit.pipeline import NucleusKitProcessingToolkit
+        from nucleuskit_toolkit.session_job import session_job_from_folder
+
+        job = session_job_from_folder(ns.session, pov_config_json=ns.config)
+        pipe = NucleusKitProcessingToolkit(None, emotion_model=ns.emotion_model)
+        pipe.processSession(job)
+        return 0
+
+    from nucleuskit_toolkit.app import run_app
+
+    run_app()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nucleuskit_toolkit/app.py

@@ -0,0 +1,34 @@
+"""
+PySide6 GUI: sidebar navigation between processing, real-time viewer, playback, tools, MQTT, settings and about.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def run_app() -> None:
+    try:
+        from PySide6.QtCore import QTimer
+        from PySide6.QtWidgets import QApplication
+    except ImportError as e:
+        raise SystemExit(
+            "PySide6 is required for the graphical interface. "
+            "Install with: pip install 'nucleuskit-toolkit[gui]'"
+        ) from e
+
+    from nucleuskit_toolkit.ui.main_window import MainWindow
+    from nucleuskit_toolkit.ui.pages.settings_page import load_theme_setting
+    from nucleuskit_toolkit.ui.theme import apply_theme
+
+    app = QApplication(sys.argv)
+    app.setOrganizationName("REAK")
+    app.setApplicationName("NucleusKitToolkit")
+
+    apply_theme(app, load_theme_setting())
+
+    window = MainWindow()
+    window.show()
+    # Load the pages' libraries in the background once the window is on screen.
+    QTimer.singleShot(300, window.start_warmup)
+    sys.exit(app.exec())

nucleuskit_toolkit/camera/__init__.py

@@ -0,0 +1,9 @@
+"""Camera and video processing: POV conversion, session video rotation, and faststart."""
+
+from nucleuskit_toolkit.camera.processing import (
+    convertPOVMovieClip,
+    ensure_session_video_rotated_180,
+    ensure_video_faststart,
+)
+
+__all__ = ["convertPOVMovieClip", "ensure_session_video_rotated_180", "ensure_video_faststart"]

nucleuskit_toolkit/camera/processing.py

@@ -0,0 +1,374 @@
+"""
+Camera and video processing utilities.
+
+Covers three operations that run as part of offline session processing or
+playback preparation:
+
+1. ``convertPOVMovieClip``       — rename UUID POV file to MKV then re-mux to MP4.
+2. ``ensure_session_video_rotated_180`` — rotate rawData/video.mp4 180° in place
+   using ffmpeg (idempotent, guarded by a marker file).
+3. ``ensure_video_faststart``    — remux rawData/video.mp4 so the MOOV atom sits at
+   the front of the file (idempotent, guarded by a marker file).  Required for
+   smooth Qt ``QMediaPlayer`` playback of large recordings.
+
+All functions are thin ffmpeg wrappers; the shared ``_ffmpeg_executable``
+helper resolves the binary from either an explicit directory or the system PATH
+(with an optional fallback through the pipeline config).
+
+Author(s):
+    RE-AK Technologies Inc.
+    Winter – Spring 2026
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+from nucleuskit_toolkit.config import resolve_pov_settings
+from nucleuskit_toolkit.logging_utils import printInfo, printWarning
+
+# ---------------------------------------------------------------------------
+# Shared ffmpeg helper
+# ---------------------------------------------------------------------------
+
+def _ffmpeg_executable(ffmpeg_bin_dir: str | None = None) -> str | None:
+    """
+    Resolve the ffmpeg binary path.
+
+    Resolution order:
+    1. ``ffmpeg_bin_dir`` if provided explicitly.
+    2. ``ffmpeg_bin_dir`` from the pipeline config (``nucleuskit_toolkit_config.json``).
+    3. System PATH via ``shutil.which``.
+
+    Returns the full path to the executable, or *None* if not found.
+    """
+    name = "ffmpeg.exe" if sys.platform.startswith("win") else "ffmpeg"
+
+    if ffmpeg_bin_dir:
+        candidate = os.path.join(ffmpeg_bin_dir, name)
+        if os.path.isfile(candidate):
+            return candidate
+
+    pov = resolve_pov_settings(None)
+    if pov and pov.ffmpeg_bin_dir:
+        candidate = os.path.join(pov.ffmpeg_bin_dir, name)
+        if os.path.isfile(candidate):
+            return candidate
+
+    return shutil.which("ffmpeg")
+
+
+# ---------------------------------------------------------------------------
+# POV clip conversion  (MKV → MP4)
+# ---------------------------------------------------------------------------
+
+def convertPOVMovieClip(
+    screen_id: str | None,
+    data_root: str | None,
+    ffmpeg_bin_dir: str | None,
+) -> None:
+    """
+    Convert a UUID-named POV camera recording from MKV to MP4.
+
+    The source file lives at ``<data_root>/<screen_id>`` (no extension).
+    It is first renamed to ``<screen_id>.mkv``, then re-muxed to
+    ``<screen_id>.mp4`` via ``ffmpeg -c copy``.  On failure the original
+    name is restored.
+
+    Args:
+        screen_id:      File base name (UUID, no extension) inside ``data_root``.
+        data_root:      Directory containing the UUID-named POV file.
+        ffmpeg_bin_dir: Directory containing the ffmpeg executable.
+    """
+    if not screen_id or not data_root or not ffmpeg_bin_dir:
+        printWarning("[camera] Missing screen_id, data_root, or ffmpeg_bin_dir; skipping POV conversion")
+        return
+
+    ffmpeg = _ffmpeg_executable(ffmpeg_bin_dir)
+    if not ffmpeg:
+        printWarning(f"[camera] ffmpeg not found in {ffmpeg_bin_dir}; skipping POV conversion")
+        return
+
+    if not os.path.isdir(data_root):
+        printWarning("[camera] data_root not found; skipping POV conversion")
+        return
+
+    uuid_full = os.path.join(data_root, screen_id)
+    if not os.path.exists(uuid_full):
+        printWarning(f"[camera] Source file not found: {uuid_full}; skipping POV conversion")
+        return
+
+    mkv_full = os.path.join(data_root, screen_id + ".mkv")
+    mp4_full = os.path.join(data_root, screen_id + ".mp4")
+
+    if os.path.exists(mkv_full):
+        printInfo("[camera] POV conversion already done; skipping")
+        return
+
+    printInfo(f"[camera] Converting POV clip: {screen_id}")
+    os.rename(uuid_full, mkv_full)
+    try:
+        rc = subprocess.run(
+            [ffmpeg, "-i", mkv_full, "-c", "copy", mp4_full],
+            check=False,
+        ).returncode
+        if rc != 0 or not os.path.isfile(mp4_full):
+            printWarning("[camera] ffmpeg failed or produced no mp4; restoring original name")
+            if os.path.isfile(mkv_full):
+                os.rename(mkv_full, uuid_full)
+            return
+        os.rename(mp4_full, uuid_full)
+    except OSError as e:
+        printWarning(f"[camera] POV conversion failed: {e}")
+        if os.path.isfile(mkv_full) and not os.path.exists(uuid_full):
+            os.rename(mkv_full, uuid_full)
+        return
+
+    if os.path.isfile(mkv_full):
+        os.remove(mkv_full)
+
+    printInfo("[camera] POV conversion completed")
+
+
+# ---------------------------------------------------------------------------
+# Session video rotation  (rawData/video.mp4 → 180°)
+# ---------------------------------------------------------------------------
+
+# Written under <session>/rawData/ after a successful rotation (idempotent flag).
+MARKER_FILENAME = "nucleuskit_video_rotated_180.json"
+
+# Session video expected by the playback UI.
+VIDEO_BASENAME = "video.mp4"
+
+_MARKER_SCHEMA = "nucleuskit.video_rotation.v1"
+
+
+def ensure_session_video_rotated_180(recpath: str) -> None:
+    """
+    Rotate ``rawData/video.mp4`` 180° in place using ffmpeg (idempotent).
+
+    If ``rawData/nucleuskit_video_rotated_180.json`` already exists the
+    function returns immediately, preserving any previous rotation and
+    avoiding redundant re-encoding on repeated pipeline runs.
+
+    If the video file or ffmpeg are absent, a warning is logged and the
+    function returns without error.
+
+    Args:
+        recpath: Root directory of the recording session.
+    """
+    recpath = os.path.abspath(recpath)
+    raw_data = os.path.join(recpath, "rawData")
+    marker_path = os.path.join(raw_data, MARKER_FILENAME)
+    video_path = os.path.join(raw_data, VIDEO_BASENAME)
+
+    if os.path.isfile(marker_path):
+        printInfo(f"[camera] Marker present ({MARKER_FILENAME}); skipping 180° rotation")
+        return
+
+    if not os.path.isdir(raw_data):
+        printWarning(f"[camera] No rawData folder at {raw_data}; skipping")
+        return
+
+    if not os.path.isfile(video_path):
+        printInfo(f"[camera] No {VIDEO_BASENAME} under rawData; nothing to rotate")
+        return
+
+    ffmpeg = _ffmpeg_executable()
+    if not ffmpeg:
+        printWarning(
+            "[camera] ffmpeg not found (configure ffmpeg_dir in "
+            "nucleuskit_toolkit_config.json or add it to PATH); skipping rotation"
+        )
+        return
+
+    tmp_path = os.path.join(raw_data, ".video_rot180_tmp.mp4")
+    printInfo(f"[camera] Rotating 180° in place: {video_path}")
+
+    base_cmd = [
+        ffmpeg,
+        "-hide_banner", "-loglevel", "error",
+        "-y", "-i", video_path,
+        "-vf", "hflip,vflip",
+        "-c:v", "libx264",
+        "-preset", "medium",
+        "-crf", "23",
+        "-movflags", "+faststart",
+    ]
+
+    def _run_with_audio() -> subprocess.CompletedProcess[str]:
+        return subprocess.run(base_cmd + ["-c:a", "copy", tmp_path],
+                              check=False, capture_output=True, text=True)
+
+    def _run_video_only() -> subprocess.CompletedProcess[str]:
+        return subprocess.run(base_cmd + ["-an", tmp_path],
+                              check=False, capture_output=True, text=True)
+
+    try:
+        completed = _run_with_audio()
+        if completed.returncode != 0:
+            completed = _run_video_only()
+        if completed.returncode != 0:
+            err = (completed.stderr or completed.stdout or "").strip()
+            printWarning(f"[camera] ffmpeg failed (exit {completed.returncode}): {err}")
+            return
+        if not os.path.isfile(tmp_path) or os.path.getsize(tmp_path) == 0:
+            printWarning("[camera] ffmpeg produced no output; aborting")
+            return
+
+        os.replace(tmp_path, video_path)
+
+        payload = {
+            "schema": _MARKER_SCHEMA,
+            "rotation_degrees": 180,
+            "media_file": VIDEO_BASENAME,
+            "completed_at": datetime.now(timezone.utc).isoformat(),
+        }
+        with open(marker_path, "w", encoding="utf-8") as f:
+            json.dump(payload, f, indent=2)
+            f.write("\n")
+
+        printInfo(f"[camera] Rotation complete; wrote marker {marker_path}")
+    except OSError as e:
+        printWarning(f"[camera] I/O error during rotation: {e}")
+    finally:
+        if os.path.isfile(tmp_path):
+            try:
+                os.remove(tmp_path)
+            except OSError:
+                pass
+
+
+# ---------------------------------------------------------------------------
+# Session video faststart  (rawData/video.mp4 → MOOV atom at front)
+# ---------------------------------------------------------------------------
+
+_FASTSTART_MARKER_FILENAME = "nucleuskit_video_faststart.json"
+_FASTSTART_MARKER_SCHEMA = "nucleuskit.video_faststart.v2"
+
+
+def ensure_video_faststart(recpath: str) -> None:
+    """
+    Remux ``rawData/video.mp4`` so the MOOV atom is at the front and the video
+    track timescale is normalised to 30 000 ticks/sec.
+
+    ``QMediaPlayer`` on Windows (Windows Media Foundation backend) requires the
+    MOOV atom at the beginning of the file to seek and buffer large recordings
+    efficiently.  Without it the player must scan the entire file before it can
+    decode any frame — which manifests as audio continuing while the video
+    rendering stalls partway through.
+
+    Some cameras record with a 1 000 000 ticks/sec (microsecond) timescale.
+    Because MP4 stores track timestamps as uint32, a microsecond-timescale file
+    wraps at exactly 2^32 µs = 71 min 35 s, causing WMF to stall video decode
+    at that point while audio continues.  Setting ``-video_track_timescale 30000``
+    rescales all timestamps to 30 000 ticks/sec (stream copy, no quality loss),
+    which pushes the uint32 wrap out to ~39.8 hours.
+
+    The remux uses ``-c copy`` (no re-encoding) and completes in seconds
+    regardless of file size.  The function is idempotent: if
+    ``rawData/nucleuskit_video_faststart.json`` exists **and** carries the
+    current schema version the function returns immediately.  An older v1 marker
+    (faststart without timescale fix) triggers a one-time reprocess.
+
+    The rotation marker (``nucleuskit_video_rotated_180.json``) implies both
+    faststart and a full re-encode, so FFmpeg already resets the timescale; the
+    function short-circuits in that case.
+
+    If ``video.mp4`` or ffmpeg are absent a warning is logged and the function
+    returns without error.
+
+    Args:
+        recpath: Root directory of the recording session.
+    """
+    recpath = os.path.abspath(recpath)
+    raw_data = os.path.join(recpath, "rawData")
+    faststart_marker = os.path.join(raw_data, _FASTSTART_MARKER_FILENAME)
+    rotation_marker = os.path.join(raw_data, MARKER_FILENAME)
+    video_path = os.path.join(raw_data, VIDEO_BASENAME)
+
+    if os.path.isfile(faststart_marker):
+        try:
+            with open(faststart_marker, encoding="utf-8") as _f:
+                _marker_data = json.load(_f)
+            if _marker_data.get("schema") == _FASTSTART_MARKER_SCHEMA:
+                printInfo(f"[camera] Faststart marker v2 present ({_FASTSTART_MARKER_FILENAME}); skipping")
+                return
+            printInfo("[camera] Faststart marker is v1 (no timescale fix); reprocessing")
+        except Exception:
+            printInfo("[camera] Faststart marker unreadable; reprocessing")
+
+    # Rotation already applies +faststart; no remux needed.
+    if os.path.isfile(rotation_marker):
+        printInfo("[camera] Rotation marker implies faststart already applied; skipping")
+        return
+
+    if not os.path.isdir(raw_data):
+        printWarning(f"[camera] No rawData folder at {raw_data}; skipping faststart")
+        return
+
+    if not os.path.isfile(video_path):
+        printInfo(f"[camera] No {VIDEO_BASENAME} under rawData; nothing to prepare")
+        return
+
+    ffmpeg = _ffmpeg_executable()
+    if not ffmpeg:
+        printWarning(
+            "[camera] ffmpeg not found (configure ffmpeg_dir in "
+            "nucleuskit_toolkit_config.json or add it to PATH); skipping faststart"
+        )
+        return
+
+    tmp_path = os.path.join(raw_data, ".video_faststart_tmp.mp4")
+    printInfo(f"[camera] Applying faststart remux + timescale normalisation (stream copy): {video_path}")
+
+    try:
+        completed = subprocess.run(
+            [
+                ffmpeg,
+                "-hide_banner", "-loglevel", "error",
+                "-y", "-i", video_path,
+                "-c", "copy",
+                "-video_track_timescale", "30000",
+                "-movflags", "+faststart",
+                tmp_path,
+            ],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+
+        if completed.returncode != 0:
+            err = (completed.stderr or completed.stdout or "").strip()
+            printWarning(f"[camera] ffmpeg faststart failed (exit {completed.returncode}): {err}")
+            return
+
+        if not os.path.isfile(tmp_path) or os.path.getsize(tmp_path) == 0:
+            printWarning("[camera] ffmpeg faststart produced no output; aborting")
+            return
+
+        os.replace(tmp_path, video_path)
+
+        payload = {
+            "schema": _FASTSTART_MARKER_SCHEMA,
+            "media_file": VIDEO_BASENAME,
+            "completed_at": datetime.now(timezone.utc).isoformat(),
+        }
+        with open(faststart_marker, "w", encoding="utf-8") as f:
+            json.dump(payload, f, indent=2)
+            f.write("\n")
+
+        printInfo(f"[camera] Faststart remux complete; wrote marker {faststart_marker}")
+    except OSError as e:
+        printWarning(f"[camera] I/O error during faststart remux: {e}")
+    finally:
+        if os.path.isfile(tmp_path):
+            try:
+                os.remove(tmp_path)
+            except OSError:
+                pass

nucleuskit_toolkit/config.py

@@ -0,0 +1,86 @@
+"""
+Optional POV / ffmpeg settings for the Nucleus-Kit processing toolkit.
+
+Precedence: merge JSON from the working directory (legacy filenames in order, then
+canonical filename), then ``extra_json_path``, then environment variables override each field.
+
+Environment variables:
+  HERMES_POV_DATA_ROOT — directory containing the UUID-named POV file
+  HERMES_FFMPEG_DIR    — directory containing the ffmpeg executable
+  HERMES_POV_SCREEN_ID — optional default screen / file id (no extension)
+
+JSON keys (same semantics): pov_data_root, ffmpeg_dir, screen_id
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional
+
+DEFAULT_JSON_NAME = "nucleuskit_toolkit_config.json"
+LEGACY_JSON_NAME = "hermes_standalone_config.json"
+PIPELINE_LEGACY_JSON_NAME = "nucleuskit_pipeline_config.json"
+
+
+@dataclass
+class PovSettings:
+    data_root: Optional[str] = None
+    ffmpeg_bin_dir: Optional[str] = None
+    screen_id: Optional[str] = None
+
+
+def _strip_str(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        return None
+    value = value.strip()
+    return value or None
+
+
+def _load_json(path: str) -> dict[str, Any]:
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    return data if isinstance(data, dict) else {}
+
+
+def _merge_pov_dict(base: Mapping[str, Any], overlay: Mapping[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for k, v in overlay.items():
+        if v is not None:
+            out[k] = v
+    return out
+
+
+def resolve_pov_settings(extra_json_path: Optional[str] = None) -> PovSettings:
+    """
+    Merge optional JSON config from cwd (legacy then canonical), then extra_json_path,
+    then apply env overrides.
+    """
+    merged: dict[str, Any] = {}
+    legacy = os.path.join(os.getcwd(), LEGACY_JSON_NAME)
+    if os.path.isfile(legacy):
+        merged = _merge_pov_dict(merged, _load_json(legacy))
+    pipeline_legacy = os.path.join(os.getcwd(), PIPELINE_LEGACY_JSON_NAME)
+    if os.path.isfile(pipeline_legacy):
+        merged = _merge_pov_dict(merged, _load_json(pipeline_legacy))
+    cwd_json = os.path.join(os.getcwd(), DEFAULT_JSON_NAME)
+    if os.path.isfile(cwd_json):
+        merged = _merge_pov_dict(merged, _load_json(cwd_json))
+    if extra_json_path and os.path.isfile(extra_json_path):
+        merged = _merge_pov_dict(merged, _load_json(extra_json_path))
+
+    data_root = _strip_str(merged.get("pov_data_root"))
+    ffmpeg_dir = _strip_str(merged.get("ffmpeg_dir"))
+    screen_id = _strip_str(merged.get("screen_id"))
+
+    if _strip_str(os.environ.get("HERMES_POV_DATA_ROOT")):
+        data_root = _strip_str(os.environ.get("HERMES_POV_DATA_ROOT"))
+    if _strip_str(os.environ.get("HERMES_FFMPEG_DIR")):
+        ffmpeg_dir = _strip_str(os.environ.get("HERMES_FFMPEG_DIR"))
+    if _strip_str(os.environ.get("HERMES_POV_SCREEN_ID")):
+        screen_id = _strip_str(os.environ.get("HERMES_POV_SCREEN_ID"))
+
+    return PovSettings(data_root=data_root, ffmpeg_bin_dir=ffmpeg_dir, screen_id=screen_id)

nucleuskit_toolkit/hermes/constants.py

@@ -0,0 +1,77 @@
+"""Constants for the Hermes EEG/EMG headset hardware."""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Hardware acquisition
+# ---------------------------------------------------------------------------
+SAMPLING_RATE: int = 250
+"""EEG/EMG acquisition rate in Hz."""
+
+DISCONNECT_VALUE: float = 187500.0
+"""Raw ADC saturation value indicating an electrode disconnect."""
+
+# ---------------------------------------------------------------------------
+# Channel layout (canonical electrode names, index 0..7)
+# ---------------------------------------------------------------------------
+CHANNEL_NAMES: tuple[str, ...] = (
+    "AF8",
+    "AF7",
+    "CHEEK_R",
+    "CHEEK_L",
+    "EAR_R",
+    "AFz",
+    "BROW_L",
+    "NOSE",
+)
+
+# Names written to emotion feature files. Same hardware order as CHANNEL_NAMES
+# and as raw columns ch1..ch8.
+OUTPUT_RMS_COLUMNS: tuple[str, ...] = (
+    "HEAD_R_RMS",
+    "HEAD_L_RMS",
+    "CHEEK_R_RMS",
+    "CHEEK_L_RMS",
+    "EAR_R_RMS",
+    "FOREHEAD_L_RMS",
+    "BROW_RMS",
+    "NOSE_RMS",
+)
+
+CHANNELS: dict[str, int] = {name: i for i, name in enumerate(CHANNEL_NAMES)}
+N_CHANNELS: int = len(CHANNEL_NAMES)
+
+# Accepted raw / legacy headers → hardware index (ch1 = AF8 = HEAD_R_RMS).
+_RAW_COLUMN_INDEX: dict[str, int] = {}
+for _i, _electrode in enumerate(CHANNEL_NAMES):
+    _RAW_COLUMN_INDEX[_electrode.lower()] = _i
+    _RAW_COLUMN_INDEX[f"ch{_i + 1}"] = _i
+    _RAW_COLUMN_INDEX[OUTPUT_RMS_COLUMNS[_i].lower()] = _i
+_RAW_COLUMN_INDEX.update(
+    {
+        "head_r": 0,
+        "head_l": 1,
+        "forehead_l": 5,
+        "brow": 6,
+    }
+)
+
+
+def hardware_channel_index(column_name: str) -> int | None:
+    """Map a raw or legacy column header to hardware index 0..7.
+
+    Accepts ``ch1``..``ch8``, electrode names (``AF8`` …), legacy labels
+    (``HEAD_R`` …), and the output RMS names (``HEAD_R_RMS`` …).
+    """
+    return _RAW_COLUMN_INDEX.get(str(column_name).strip().lower())
+
+
+class HermesConstants:
+    """Backward-compatible namespace for existing ``HermesConstants.*`` imports."""
+
+    SAMPLING_RATE = SAMPLING_RATE
+    CHANNEL_NAMES = list(CHANNEL_NAMES)
+    OUTPUT_RMS_COLUMNS = list(OUTPUT_RMS_COLUMNS)
+    CHANNELS = CHANNELS
+    N_CHANNELS = N_CHANNELS
+    DISCONNECT_VALUE = DISCONNECT_VALUE

nucleuskit_toolkit/hermes/realtime/__init__.py

@@ -0,0 +1,8 @@
+"""Hermes headset BLE streaming (real-time)."""
+
+from nucleuskit_toolkit.hermes.realtime.proxy import (
+    HERMES_NAME_SUBSTRING,
+    HermesBleProxy,
+)
+
+__all__ = ["HERMES_NAME_SUBSTRING", "HermesBleProxy"]