python-voiceio 0.2.0__py3-none-any.whl

voiceio/health.py

@@ -0,0 +1,194 @@
+"""Health check / diagnostic report for all backends."""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from voiceio import platform as plat
+from voiceio.hotkeys import chain as hotkey_chain
+from voiceio.typers import chain as typer_chain
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class BackendStatus:
+    name: str
+    ok: bool
+    reason: str = ""
+    fix_hint: str = ""
+    fix_cmd: list[str] = field(default_factory=list)
+
+
+@dataclass
+class IBusStatus:
+    component_installed: bool = False
+    daemon_running: bool = False
+    socket_reachable: bool = False
+    gnome_source_configured: bool = False
+    env_persisted: bool = False
+
+@dataclass
+class HealthReport:
+    platform: plat.Platform
+    hotkey_backends: list[BackendStatus] = field(default_factory=list)
+    typer_backends: list[BackendStatus] = field(default_factory=list)
+    audio_ok: bool = False
+    audio_reason: str = ""
+    cli_in_path: bool = False
+    ibus_checks: IBusStatus | None = None
+
+    @property
+    def all_ok(self) -> bool:
+        has_hotkey = any(b.ok for b in self.hotkey_backends)
+        has_typer = any(b.ok for b in self.typer_backends)
+        return has_hotkey and has_typer and self.audio_ok
+
+
+def check_health(p: plat.Platform | None = None) -> HealthReport:
+    """Run all probes and return a health report."""
+    if p is None:
+        p = plat.detect()
+
+    report = HealthReport(platform=p)
+
+    # Probe hotkey backends
+    for name, backend, probe in hotkey_chain.resolve(p):
+        report.hotkey_backends.append(BackendStatus(
+            name=name, ok=probe.ok, reason=probe.reason,
+            fix_hint=probe.fix_hint, fix_cmd=probe.fix_cmd,
+        ))
+
+    # Probe typer backends
+    for name, backend, probe in typer_chain.resolve(p):
+        report.typer_backends.append(BackendStatus(
+            name=name, ok=probe.ok, reason=probe.reason,
+            fix_hint=probe.fix_hint, fix_cmd=probe.fix_cmd,
+        ))
+
+    # Check audio
+    try:
+        import sounddevice as _sd
+        _sd.query_devices(kind="input")
+        report.audio_ok = True
+    except Exception as e:
+        report.audio_reason = str(e)
+
+    # Check CLI in PATH
+    from voiceio.service import symlinks_installed
+    report.cli_in_path = symlinks_installed()
+
+    # IBus-specific checks (only if IBus is in the typer chain)
+    ibus_backends = [b for b in report.typer_backends if b.name == "ibus"]
+    if ibus_backends and ibus_backends[0].ok:
+        report.ibus_checks = _check_ibus()
+
+    return report
+
+
+def _check_ibus() -> IBusStatus:
+    """Run detailed IBus health checks."""
+    from pathlib import Path
+    from voiceio.ibus import SOCKET_PATH
+    from voiceio.typers.ibus import (
+        _ibus_daemon_running, _component_installed,
+    )
+
+    status = IBusStatus()
+    status.component_installed = _component_installed()
+    status.daemon_running = _ibus_daemon_running()
+    status.socket_reachable = SOCKET_PATH.exists()
+
+    # Check GNOME input source
+    try:
+        from voiceio.platform import detect
+        if detect().is_gnome:
+            import subprocess
+            result = subprocess.run(
+                ["gsettings", "get", "org.gnome.desktop.input-sources", "sources"],
+                capture_output=True, text=True, timeout=3,
+            )
+            status.gnome_source_configured = (
+                result.returncode == 0 and "('ibus', 'voiceio')" in result.stdout
+            )
+    except Exception:
+        pass
+
+    # Check env persistence
+    env_file = Path.home() / ".config" / "environment.d" / "voiceio.conf"
+    status.env_persisted = env_file.exists()
+
+    return status
+
+
+def _icon(ok: bool, warn: bool = False) -> str:
+    if ok:
+        return "\u2714"  # ✔
+    if warn:
+        return "\u26A0"  # ⚠
+    return "\u2718"  # ✘
+
+
+def _backend_line(b: BackendStatus, active: bool = False) -> list[str]:
+    lines = []
+    icon = _icon(b.ok)
+    suffix = " \u25C0 active" if active else ""
+    line = f"  {icon} {b.name}{suffix}"
+    if not b.ok:
+        line += f"  \u2014 {b.reason}"
+    lines.append(line)
+    if b.fix_hint and not b.ok:
+        lines.append(f"    \u2192 {b.fix_hint}")
+    return lines
+
+
+def format_report(report: HealthReport) -> str:
+    """Format a health report as a human-readable string."""
+    lines = []
+    lines.append(f"Platform: {report.platform.os} / {report.platform.display_server} / {report.platform.desktop}")
+    lines.append("")
+
+    # Find which backends are active (first OK in each list)
+    active_hotkey = next((b.name for b in report.hotkey_backends if b.ok), None)
+    active_typer = next((b.name for b in report.typer_backends if b.ok), None)
+
+    lines.append("Hotkey backends:")
+    for b in report.hotkey_backends:
+        lines.extend(_backend_line(b, active=(b.name == active_hotkey)))
+
+    lines.append("")
+    lines.append("Typer backends:")
+    for b in report.typer_backends:
+        lines.extend(_backend_line(b, active=(b.name == active_typer)))
+
+    lines.append("")
+    icon = _icon(report.audio_ok)
+    line = f"Audio: {icon}"
+    if not report.audio_ok:
+        line += f"  \u2014 {report.audio_reason}"
+    lines.append(line)
+
+    icon = _icon(report.cli_in_path)
+    line = f"CLI in PATH: {icon}"
+    if not report.cli_in_path:
+        line += "  \u2014 run 'voiceio setup' or 'voiceio doctor --fix'"
+    lines.append(line)
+
+    if report.ibus_checks is not None:
+        ibus = report.ibus_checks
+        lines.append("")
+        lines.append("IBus pipeline:")
+        for label, ok, hint in [
+            ("Component installed", ibus.component_installed, "voiceio setup"),
+            ("Daemon running", ibus.daemon_running, "ibus-daemon -drxR"),
+            ("Engine socket", ibus.socket_reachable, "start voiceio to activate"),
+            ("GNOME input source", ibus.gnome_source_configured, "voiceio setup"),
+            ("Env persisted (reboot-safe)", ibus.env_persisted, "voiceio setup"),
+        ]:
+            icon = _icon(ok, warn=True)
+            line = f"  {icon} {label}"
+            if not ok:
+                line += f"  \u2014 {hint}"
+            lines.append(line)
+
+    return "\n".join(lines)

voiceio/hotkeys/__init__.py

@@ -0,0 +1,22 @@
+"""Hotkey detection backends."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from voiceio.hotkeys.base import HotkeyBackend
+    from voiceio.platform import Platform
+
+
+def create_hotkey_backend(name: str, platform: Platform) -> HotkeyBackend:
+    """Create a hotkey backend by name."""
+    if name == "evdev":
+        from voiceio.hotkeys.evdev import EvdevHotkey
+        return EvdevHotkey()
+    if name == "pynput":
+        from voiceio.hotkeys.pynput_backend import PynputHotkey
+        return PynputHotkey()
+    if name == "socket":
+        from voiceio.hotkeys.socket_backend import SocketHotkey
+        return SocketHotkey()
+    raise ValueError(f"Unknown hotkey backend: {name}")

voiceio/hotkeys/base.py

@@ -0,0 +1,27 @@
+"""Base protocol and types for hotkey backends."""
+from __future__ import annotations
+
+from typing import Callable, Protocol, runtime_checkable
+
+from voiceio.backends import ProbeResult
+
+__all__ = ["ProbeResult", "HotkeyBackend"]
+
+
+@runtime_checkable
+class HotkeyBackend(Protocol):
+    """Protocol for hotkey detection backends."""
+
+    name: str
+
+    def probe(self) -> ProbeResult:
+        """Check if this backend can work on the current system."""
+        ...
+
+    def start(self, combo: str, on_trigger: Callable[[], None]) -> None:
+        """Start listening for the hotkey combo. Non-blocking."""
+        ...
+
+    def stop(self) -> None:
+        """Stop listening. Idempotent."""
+        ...

voiceio/hotkeys/chain.py

@@ -0,0 +1,83 @@
+"""Fallback chain for hotkey backends."""
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from voiceio.backends import ProbeResult
+from voiceio.hotkeys.base import HotkeyBackend
+
+if TYPE_CHECKING:
+    from voiceio.platform import Platform
+
+log = logging.getLogger(__name__)
+
+# Preference order by platform
+_CHAINS: dict[tuple[str, str], list[str]] = {
+    # (display_server, desktop) -> backend list
+    ("x11", "*"):       ["pynput", "evdev", "socket"],
+    ("wayland", "*"):   ["evdev", "socket"],
+    ("quartz", "*"):    ["pynput"],
+}
+
+
+def _get_chain(platform: Platform) -> list[str]:
+    """Get the preference chain for this platform."""
+    # Try exact match first
+    key = (platform.display_server, platform.desktop)
+    if key in _CHAINS:
+        return _CHAINS[key]
+    # Try wildcard desktop
+    key = (platform.display_server, "*")
+    if key in _CHAINS:
+        return _CHAINS[key]
+    # Fallback
+    return ["socket"]
+
+
+def resolve(platform: Platform, override: str | None = None) -> list[tuple[str, HotkeyBackend, ProbeResult]]:
+    """Probe backends in preference order, return list of (name, backend, probe_result).
+
+    If override is set (not "auto"/None), only probe that one backend.
+    """
+    from voiceio.hotkeys import create_hotkey_backend
+
+    if override and override != "auto":
+        backend = create_hotkey_backend(override, platform)
+        result = backend.probe()
+        return [(override, backend, result)]
+
+    chain = _get_chain(platform)
+    results = []
+    for name in chain:
+        try:
+            backend = create_hotkey_backend(name, platform)
+            result = backend.probe()
+            results.append((name, backend, result))
+        except Exception as e:
+            log.debug("Failed to create backend '%s': %s", name, e)
+            results.append((name, None, ProbeResult(ok=False, reason=str(e))))
+
+    return results
+
+
+def select(platform: Platform, override: str | None = None) -> HotkeyBackend:
+    """Select the first working hotkey backend.
+
+    Raises RuntimeError if none work.
+    """
+    results = resolve(platform, override)
+
+    for name, backend, probe in results:
+        if probe.ok and backend is not None:
+            log.info("Selected hotkey backend: %s", name)
+            return backend
+        log.debug("Hotkey backend '%s' unavailable: %s", name, probe.reason)
+
+    # Build error message
+    reasons = [f"  {name}: {probe.reason}" for name, _, probe in results if not probe.ok]
+    hints = [probe.fix_hint for _, _, probe in results if probe.fix_hint]
+    msg = "No working hotkey backend found:\n" + "\n".join(reasons)
+    if hints:
+        msg += "\n\nTo fix:\n" + "\n".join(f"  - {h}" for h in hints)
+    raise RuntimeError(msg)

voiceio/hotkeys/evdev.py

@@ -0,0 +1,134 @@
+"""Evdev hotkey backend: reads /dev/input directly."""
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from pathlib import Path
+from typing import Callable
+
+from voiceio.backends import ProbeResult
+
+log = logging.getLogger(__name__)
+
+DEBOUNCE_SECS = 0.8
+
+
+class EvdevHotkey:
+    """Hotkey detection via Linux evdev (needs input group)."""
+
+    name = "evdev"
+
+    def probe(self) -> ProbeResult:
+        try:
+            import evdev  # noqa: F401
+        except ImportError:
+            return ProbeResult(ok=False, reason="evdev package not installed",
+                               fix_hint="pip install evdev")
+
+        # Check if we can open any keyboard device
+        for path in sorted(Path("/dev/input/").glob("event*")):
+            try:
+                with open(path, "rb"):
+                    return ProbeResult(ok=True)
+            except PermissionError:
+                import getpass
+                return ProbeResult(
+                    ok=False, reason="No permission to read /dev/input",
+                    fix_hint="sudo usermod -aG input $USER && newgrp input",
+                    fix_cmd=["sudo", "usermod", "-aG", "input", getpass.getuser()],
+                )
+            except OSError:
+                continue
+
+        return ProbeResult(ok=False, reason="No input devices found")
+
+    def start(self, combo: str, on_trigger: Callable[[], None]) -> None:
+        import evdev
+        from evdev import ecodes
+
+        MODIFIER_MAP = {
+            "super": {ecodes.KEY_LEFTMETA, ecodes.KEY_RIGHTMETA},
+            "ctrl": {ecodes.KEY_LEFTCTRL, ecodes.KEY_RIGHTCTRL},
+            "alt": {ecodes.KEY_LEFTALT, ecodes.KEY_RIGHTALT},
+            "shift": {ecodes.KEY_LEFTSHIFT, ecodes.KEY_RIGHTSHIFT},
+        }
+
+        KEY_MAP = {
+            **{chr(c): getattr(ecodes, f"KEY_{chr(c).upper()}") for c in range(ord("a"), ord("z") + 1)},
+            **{str(i): getattr(ecodes, f"KEY_{i}") for i in range(10)},
+            **{f"f{i}": getattr(ecodes, f"KEY_F{i}") for i in range(1, 13)},
+            "space": ecodes.KEY_SPACE,
+            "pause": ecodes.KEY_PAUSE,
+            "insert": ecodes.KEY_INSERT,
+            "scroll_lock": ecodes.KEY_SCROLLLOCK,
+            "print_screen": ecodes.KEY_SYSRQ,
+        }
+
+        parts = [p.strip().lower() for p in combo.split("+")]
+        required_mods: set[int] = set()
+        for mod in parts[:-1]:
+            required_mods.update(MODIFIER_MAP.get(mod, set()))
+        key_code = KEY_MAP.get(parts[-1])
+        if key_code is None:
+            raise ValueError(f"Unknown key: {parts[-1]}")
+
+        keyboards = []
+        for path in sorted(Path("/dev/input/").glob("event*")):
+            try:
+                dev = evdev.InputDevice(str(path))
+                caps = dev.capabilities(verbose=False)
+                if ecodes.EV_KEY in caps:
+                    keys = caps[ecodes.EV_KEY]
+                    if ecodes.KEY_A in keys and ecodes.KEY_Z in keys:
+                        keyboards.append(dev)
+            except (PermissionError, OSError):
+                continue
+
+        if not keyboards:
+            raise RuntimeError("No keyboard devices accessible")
+
+        self._running = threading.Event()
+        self._running.set()
+        pressed: set[int] = set()
+        pressed_lock = threading.Lock()
+        last_trigger = [0.0]
+
+        def check_mods() -> bool:
+            for codes in MODIFIER_MAP.values():
+                if codes & required_mods and not (codes & pressed):
+                    return False
+            return True
+
+        def read_device(dev: evdev.InputDevice) -> None:
+            try:
+                for event in dev.read_loop():
+                    if not self._running.is_set():
+                        break
+                    if event.type != ecodes.EV_KEY:
+                        continue
+                    key_event = evdev.categorize(event)
+                    with pressed_lock:
+                        if key_event.keystate == evdev.KeyEvent.key_down:
+                            pressed.add(event.code)
+                            if event.code == key_code and check_mods():
+                                now = time.monotonic()
+                                if now - last_trigger[0] >= DEBOUNCE_SECS:
+                                    last_trigger[0] = now
+                                    on_trigger()
+                        elif key_event.keystate == evdev.KeyEvent.key_up:
+                            pressed.discard(event.code)
+            except OSError:
+                pass
+
+        self._threads = []
+        for dev in keyboards:
+            t = threading.Thread(target=read_device, args=(dev,), daemon=True)
+            t.start()
+            self._threads.append(t)
+
+        log.info("Evdev hotkey listener started on %d keyboards", len(keyboards))
+
+    def stop(self) -> None:
+        if hasattr(self, "_running"):
+            self._running.clear()

voiceio/hotkeys/pynput_backend.py

@@ -0,0 +1,80 @@
+"""Pynput hotkey backend for X11 and macOS."""
+from __future__ import annotations
+
+import logging
+import time
+from typing import Callable
+
+from voiceio.backends import ProbeResult
+
+log = logging.getLogger(__name__)
+
+DEBOUNCE_SECS = 0.8
+
+
+class PynputHotkey:
+    """Hotkey detection via pynput (X11 + macOS)."""
+
+    name = "pynput"
+
+    def probe(self) -> ProbeResult:
+        try:
+            import pynput  # noqa: F401
+        except ImportError:
+            return ProbeResult(ok=False, reason="pynput package not installed",
+                               fix_hint="pip install pynput")
+
+        import os
+        session = os.environ.get("XDG_SESSION_TYPE", "")
+        if session == "wayland":
+            return ProbeResult(ok=False, reason="pynput does not work on Wayland",
+                               fix_hint="Use evdev or socket backend instead.")
+
+        return ProbeResult(ok=True)
+
+    def start(self, combo: str, on_trigger: Callable[[], None]) -> None:
+        from pynput import keyboard
+
+        MOD_MAP = {
+            "super": {keyboard.Key.cmd, keyboard.Key.cmd_l, keyboard.Key.cmd_r},
+            "ctrl": {keyboard.Key.ctrl, keyboard.Key.ctrl_l, keyboard.Key.ctrl_r},
+            "alt": {keyboard.Key.alt, keyboard.Key.alt_l, keyboard.Key.alt_r},
+            "shift": {keyboard.Key.shift, keyboard.Key.shift_l, keyboard.Key.shift_r},
+        }
+
+        parts = [p.strip().lower() for p in combo.split("+")]
+        required_mods = [parts[i] for i in range(len(parts) - 1)]
+        key_name = parts[-1]
+        if len(key_name) == 1:
+            target_key = keyboard.KeyCode.from_char(key_name)
+        else:
+            target_key = getattr(keyboard.Key, key_name)
+
+        pressed_mods: set = set()
+        last_trigger = [0.0]
+
+        def on_press(key):
+            for mod_keys in MOD_MAP.values():
+                if key in mod_keys:
+                    pressed_mods.add(key)
+            if key == target_key:
+                for mod_name in required_mods:
+                    if not (MOD_MAP[mod_name] & pressed_mods):
+                        return
+                now = time.monotonic()
+                if now - last_trigger[0] >= DEBOUNCE_SECS:
+                    last_trigger[0] = now
+                    on_trigger()
+
+        def on_release(key):
+            for mod_keys in MOD_MAP.values():
+                if key in mod_keys:
+                    pressed_mods.discard(key)
+
+        self._listener = keyboard.Listener(on_press=on_press, on_release=on_release)
+        self._listener.start()
+        log.info("Pynput hotkey listener started")
+
+    def stop(self) -> None:
+        if hasattr(self, "_listener"):
+            self._listener.stop()

voiceio/hotkeys/socket_backend.py

@@ -0,0 +1,77 @@
+"""Socket-based hotkey backend: DE shortcut fires voiceio-toggle."""
+from __future__ import annotations
+
+import logging
+import os
+import socket
+import threading
+import time
+from pathlib import Path
+from typing import Callable
+
+from voiceio.backends import ProbeResult
+
+log = logging.getLogger(__name__)
+
+SOCKET_PATH = Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / "voiceio.sock"
+DEBOUNCE_SECS = 0.8
+
+
+class SocketHotkey:
+    """Listens on a Unix DGRAM socket for 'toggle' commands."""
+
+    name = "socket"
+
+    def probe(self) -> ProbeResult:
+        runtime_dir = os.environ.get("XDG_RUNTIME_DIR")
+        if not runtime_dir:
+            return ProbeResult(ok=False, reason="XDG_RUNTIME_DIR not set",
+                               fix_hint="Running under a normal user session should set this.")
+        return ProbeResult(ok=True)
+
+    def start(self, combo: str, on_trigger: Callable[[], None]) -> None:
+        SOCKET_PATH.unlink(missing_ok=True)
+
+        self._on_trigger = on_trigger
+        self._sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+        self._sock.bind(str(SOCKET_PATH))
+        self._sock.settimeout(1.0)
+        self._running = True
+        self._last_trigger: float = 0
+        self._thread = threading.Thread(target=self._loop, daemon=True)
+        self._thread.start()
+        log.debug("Socket listener started at %s", SOCKET_PATH)
+
+    def _loop(self) -> None:
+        while self._running:
+            try:
+                data = self._sock.recv(64)
+                if data != b"toggle":
+                    continue
+                now = time.monotonic()
+                if now - self._last_trigger < DEBOUNCE_SECS:
+                    continue
+                self._last_trigger = now
+                self._on_trigger()
+            except socket.timeout:
+                continue
+            except OSError:
+                break
+
+    def stop(self) -> None:
+        self._running = False
+        if hasattr(self, "_sock") and self._sock:
+            self._sock.close()
+        SOCKET_PATH.unlink(missing_ok=True)
+
+
+def send_toggle() -> bool:
+    """Send a toggle command to the running daemon."""
+    try:
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+        sock.sendto(b"toggle", str(SOCKET_PATH))
+        sock.close()
+        return True
+    except (ConnectionRefusedError, FileNotFoundError, OSError) as e:
+        log.error("Could not reach voiceio daemon: %s", e)
+        return False

voiceio/ibus/__init__.py

@@ -0,0 +1,8 @@
+"""IBus input method engine for VoiceIO."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+SOCKET_PATH = Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / "voiceio-ibus.sock"
+READY_PATH = Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / "voiceio-ibus.ready"