hermes-mobile-plugin 0.0.15__py3-none-any.whl

hermes_mobile_plugin/__init__.py

@@ -0,0 +1,215 @@
+"""Hermes Mobile QR Plugin - Clean architecture implementation.
+
+Generates a QR code for the Hermes Mobile App to connect directly to the
+Hermes Agent Desktop gateway (port 8642), and exposes voice STT/TTS routes
+on the gateway so the mobile app can speak and listen without an extra
+service.
+
+Both behaviors are opt-in via ``plugins.hermes-mobile-qr`` in
+``~/.hermes/config.yaml``:
+
+    plugins:
+      hermes-mobile-qr:
+        auto_generate: true     # QR code on startup
+        audio: true             # voice routes on api_server
+
+Audio routes are mounted via the standard plugin handler mechanism
+(``ctx.register_platform_handler("api_server", _wire)``), which gives
+the plugin a handle on the api_server's aiohttp ``web.Application``.
+"""
+
+import asyncio
+import logging
+import threading
+from pathlib import Path
+from typing import Any, Optional
+
+from .constants import PLUGIN_VERSION
+
+logger = logging.getLogger(__name__)
+
+
+class HermesMobileQRPlugin:
+    """Plugin that generates QR codes for mobile app connection to 8642 gateway.
+
+    Used by the legacy entry-point style loader. The standard
+    ``register(ctx)`` function below is the path the modern plugin loader
+    uses; both entry points are kept for backward compatibility.
+    """
+
+    def __init__(self, config: dict, plugin_dir: Path):
+        self.config = config
+        self.plugin_dir = plugin_dir
+        self._qr_generated = False
+
+    async def startup(self) -> None:
+        """Called when Hermes Agent starts up (legacy entry-point style)."""
+        try:
+            from .config import get_plugin_config
+            plugin_config = get_plugin_config(self.config)
+        except ImportError:
+            plugin_config = self.config.get("plugins", {}).get("hermes-mobile-qr", {})
+
+        if plugin_config.get("auto_generate", True):
+            logger.info("[Hermes Mobile QR v%s] Plugin starting...", PLUGIN_VERSION)
+            await self._generate_qr_and_start_supervisor()
+        else:
+            logger.info("[Hermes Mobile QR v%s] Auto-generate disabled", PLUGIN_VERSION)
+
+    async def shutdown(self) -> None:
+        logger.info("[Hermes Mobile QR] Plugin shutting down...")
+
+    async def _generate_qr_and_start_supervisor(self) -> None:
+        if self._qr_generated:
+            return
+        try:
+            from .qr_generator import generate_qr
+            await generate_qr(self.config, self.plugin_dir)
+            self._qr_generated = True
+            logger.info("[Hermes Mobile QR] QR code generated successfully")
+
+            from .supervisor import ensure_running
+            ensure_running()
+            logger.info("[Hermes Mobile QR] Gateway watchdog verified/spawned")
+
+        except Exception as e:
+            logger.warning("[Hermes Mobile QR] Failed to initialize: %s", e)
+
+# ---------------------------------------------------------------------------
+# Standard plugin entry point (register(ctx))
+# ---------------------------------------------------------------------------
+
+# Registration is keyed on the aiohttp app INSTANCE, not a global bool: a
+# second api_server connect onto a DIFFERENT app must still get its routes,
+# while a double-wire of the SAME app stays a no-op. (WeakSet so a dead app
+# never pins memory and tests get a clean slate per instance.)
+import weakref
+
+_audio_wired_apps = weakref.WeakSet()
+_audio_lock = threading.Lock()
+
+
+def _wire_audio_routes(native: Any, adapter: Any) -> None:
+    """Factory passed to ``ctx.register_platform_handler("api_server", ...)``.
+
+    Receives the api_server's aiohttp ``web.Application`` as ``native``
+    and registers the plugin's voice routes on it. Guarded per-app so a
+    second connect of the SAME app doesn't double-register, while a fresh
+    app (hot-reload, tests) still gets mounted.
+    """
+    with _audio_lock:
+        if native is not None and native in _audio_wired_apps:
+            logger.debug("[hermes-mobile-qr] Audio routes already registered on this app; skipping")
+            return
+        try:
+            from .audio_routes import register as _register_routes
+            from .system_routes import register as _register_system_routes
+            from .commands_routes import register as _register_command_routes
+            from .update_routes import register as _register_update_routes
+            from .providers_routes import register as _register_providers_routes
+        except Exception as exc:
+            logger.warning(
+                "[hermes-mobile-qr] Could not import route modules: %s", exc
+            )
+            return
+        if native is None:
+            logger.debug(
+                "[hermes-mobile-qr] api_server native is None; "
+                "audio routes not mounted on this run"
+            )
+            return
+        try:
+            _register_routes(native)
+            _register_system_routes(native)
+            _register_command_routes(native)
+            _register_update_routes(native)
+            _register_providers_routes(native)
+        except Exception as exc:
+            logger.exception(
+                "[hermes-mobile-qr] Failed to register audio routes: %s", exc
+            )
+            return
+        if native is not None:
+            _audio_wired_apps.add(native)
+
+
+async def _maybe_generate_qr(ctx: Any) -> None:
+    """Best-effort QR generation on startup, mirroring the legacy flow.
+
+    ``PluginContext`` exposes no ``.config``/``.plugin_dir`` attributes — the
+    QR payload needs the REAL platforms.api_server config, so load it from
+    config.yaml directly, and write the HTML next to the plugin package
+    (never the gateway's CWD).
+    """
+    try:
+        from .config import load_hermes_config, get_plugin_config
+        hermes_config = load_hermes_config()
+        plugin_config = get_plugin_config(hermes_config)
+    except ImportError:
+        hermes_config, plugin_config = {}, {}
+
+    if not plugin_config.get("auto_generate", True):
+        return
+
+    try:
+        from .constants import PLUGIN_DIR
+        from .qr_generator import generate_qr
+        out_dir = Path(ctx.plugin_dir) if getattr(ctx, "plugin_dir", None) else PLUGIN_DIR
+        await generate_qr(hermes_config, out_dir)
+        logger.info("[Hermes Mobile QR] QR code generated via register(ctx)")
+    except Exception as exc:
+        logger.warning("[Hermes Mobile QR] QR generation skipped: %s", exc)
+
+
+def register(ctx: Any) -> None:
+    """Standard plugin entry point. Called by Hermes plugin loader.
+
+    Registers the plugin's voice STT/TTS routes on the api_server
+    platform, and (if enabled) generates a QR code on startup.
+    """
+    logger.info(
+        "[Hermes Mobile QR v%s] register(ctx) called", PLUGIN_VERSION
+    )
+
+    # Register the api_server handler — always safe (idempotent guard).
+    try:
+        ctx.register_platform_handler("api_server", _wire_audio_routes)
+    except Exception as exc:
+        logger.warning(
+            "[Hermes Mobile QR] Could not register api_server handler: %s", exc
+        )
+
+    # Keep-alive: spawn the detached gateway watchdog. It lives OUTSIDE the
+    # gateway process, so if the gateway dies (crash, OOM, reboot script) it
+    # restarts it and the app reconnects. Idempotent via PID file.
+    try:
+        from .supervisor import ensure_running
+        ensure_running()
+    except Exception as exc:
+        logger.warning("[Hermes Mobile QR] Watchdog spawn failed: %s", exc)
+
+    # Fire-and-forget QR generation so we don't block loader. Scheduling
+    # only ever happens on an ALREADY-running loop: a run_until_complete
+    # fallback here could block the plugin loader (or start a stray loop
+    # beside the gateway's). No loop at register-time -> QR skipped until
+    # the next startup; the CLI covers the manual path.
+    try:
+        asyncio.get_running_loop().create_task(_maybe_generate_qr(ctx))
+    except RuntimeError:
+        logger.debug("[hermes-mobile-qr] no running loop at register(); QR gen deferred")
+
+
+# ---------------------------------------------------------------------------
+# Legacy entry point (kept for backward compatibility)
+# ---------------------------------------------------------------------------
+
+
+def create_plugin(config: dict, plugin_dir: Path) -> HermesMobileQRPlugin:
+    """Factory function called by the legacy Hermes plugin loader."""
+    return HermesMobileQRPlugin(config, plugin_dir)
+
+
+async def startup_hook(config: dict, plugin_dir: Path) -> None:
+    """Standalone startup hook if Hermes loader expects a function."""
+    plugin = create_plugin(config, plugin_dir)
+    await plugin.startup()

hermes_mobile_plugin/audio.py

@@ -0,0 +1,253 @@
+"""Voice backend: STT (Whisper) + TTS (Edge/OpenAI/ElevenLabs) via hermes-agent.
+
+Wraps the existing ``tools.voice_mode.transcribe_recording`` and
+``tools.tts_tool.text_to_speech_tool`` so the mobile app can use the same
+provider chain the desktop voice mode uses, without re-implementing any
+provider logic.
+
+Provider chain is configured in ``~/.hermes/config.yaml`` under ``tts.`` and
+``voice.`` — this module just delegates.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import logging
+import os
+import tempfile
+from contextlib import contextmanager, nullcontext
+from typing import Any, Iterator, Optional
+
+logger = logging.getLogger(__name__)
+
+# Mirrors hermes-agent's gateway MAX_REQUEST_BYTES (25 MB, api_server.py); a
+# 25 MB recording base64-encodes to ~33 MB and dies at the gateway first.
+_MAX_TRANSCRIPTION_UPLOAD_BYTES = 25 * 1024 * 1024  # 25 MB
+_AUDIO_MIME_EXTENSIONS = {
+    "audio/webm": ".webm",
+    "audio/ogg": ".ogg",
+    "audio/opus": ".opus",
+    "audio/mpeg": ".mp3",
+    "audio/mp3": ".mp3",
+    "audio/mp4": ".mp4",
+    "audio/wav": ".wav",
+    "audio/x-wav": ".wav",
+    "audio/flac": ".flac",
+    "audio/aac": ".aac",
+    "audio/x-m4a": ".m4a",
+    "video/webm": ".webm",
+}
+_AUDIO_EXT_TO_MIME = {
+    ".mp3": "audio/mpeg",
+    ".ogg": "audio/ogg",
+    ".opus": "audio/ogg",
+    ".wav": "audio/wav",
+    ".flac": "audio/flac",
+}
+
+
+def _audio_extension_for_mime(mime_type: str) -> str:
+    normalized = (mime_type or "").split(";", 1)[0].strip().lower()
+    return _AUDIO_MIME_EXTENSIONS.get(normalized, ".webm")
+
+
+def _is_supported_audio_mime(mime_type: str) -> bool:
+    if not mime_type:
+        return False
+    normalized = mime_type.split(";", 1)[0].strip().lower()
+    return normalized.startswith("audio/") or normalized == "video/webm"
+
+
+class AudioBackendError(Exception):
+    """Raised when STT or TTS fails. Carries an HTTP status for the route handler."""
+
+    def __init__(self, message: str, status: int = 500):
+        super().__init__(message)
+        self.status = status
+
+
+def _resolve_profile_scope(profile: Optional[str]) -> Any:
+    """Return a context manager that scopes config resolution to *profile*.
+
+    None / "" / "current" => no scope (use default home).
+    Mirrors ``_config_profile_scope`` in hermes_cli/web_server.py.
+    """
+    requested = (profile or "").strip()
+    if not requested or requested.lower() == "current":
+        return nullcontext()
+
+    # Imported lazily — these live inside hermes-agent and are not on the
+    # plugin's static-analysis path.
+    from hermes_constants import (
+        set_hermes_home_override,
+        reset_hermes_home_override,
+    )
+    try:
+        from hermes_cli.web_server import _resolve_profile_dir
+    except ImportError:
+        # Sep-2026 decomposition moved it to the sibling module; hosts that
+        # updated hermes-agent broke every profile-scoped speak/transcribe
+        # call until the plugin followed.
+        from hermes_cli.web_server_profiles import _resolve_profile_dir
+
+    profile_dir = _resolve_profile_dir(requested)
+
+    @contextmanager
+    def _scoped() -> Iterator[Any]:
+        token = set_hermes_home_override(str(profile_dir))
+        try:
+            yield profile_dir
+        finally:
+            reset_hermes_home_override(token)
+
+    return _scoped()
+
+
+def transcribe_audio(
+    audio_b64: str,
+    mime_type: str = "audio/webm",
+    profile: Optional[str] = None,
+    model: Optional[str] = None,
+) -> str:
+    """Decode base64 audio and return its transcript.
+
+    Args:
+        audio_b64: Base64-encoded audio bytes.
+        mime_type: MIME type (e.g. ``audio/webm``).
+        profile: Optional Hermes profile name.
+
+    Returns:
+        Transcript text. Empty string on silence (per
+        ``transcribe_recording`` contract).
+
+    Raises:
+        AudioBackendError: 400 for bad input, 413 for too-large, 500 for
+            provider failures, 503 if no transcription provider is available.
+    """
+    if not audio_b64 or not audio_b64.strip():
+        raise AudioBackendError("audio_b64 is required", status=400)
+    if not _is_supported_audio_mime(mime_type):
+        raise AudioBackendError("mime_type must be audio/*", status=400)
+
+    try:
+        audio_bytes = base64.b64decode(audio_b64, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise AudioBackendError(f"audio_b64 is not valid base64: {exc}", status=400)
+
+    if not audio_bytes:
+        raise AudioBackendError("Audio recording is empty", status=400)
+    if len(audio_bytes) > _MAX_TRANSCRIPTION_UPLOAD_BYTES:
+        raise AudioBackendError("Audio recording is too large", status=413)
+
+    suffix = _audio_extension_for_mime(mime_type)
+    temp_path = ""
+    try:
+        with tempfile.NamedTemporaryFile(
+            prefix="hermes-mobile-voice-", suffix=suffix, delete=False
+        ) as tmp:
+            tmp.write(audio_bytes)
+            temp_path = tmp.name
+
+        try:
+            from tools.voice_mode import transcribe_recording
+        except ImportError as exc:
+            raise AudioBackendError(
+                f"Transcription provider unavailable: {exc}", status=503
+            )
+
+        scope = _resolve_profile_scope(profile)
+        with scope:
+            try:
+                result = transcribe_recording(temp_path, model=model)
+            except Exception as exc:
+                logger.exception("Mobile voice transcription failed")
+                raise AudioBackendError(
+                    f"Transcription failed: {exc}", status=500
+                )
+
+        if not isinstance(result, dict):
+            # Defensive: if a provider returns a raw string, accept it.
+            return (str(result) if result else "").strip()
+
+        if not result.get("success"):
+            raise AudioBackendError(
+                result.get("error") or "Transcription failed",
+                status=400,
+            )
+
+        return (result.get("transcript") or "").strip()
+    finally:
+        if temp_path:
+            try:
+                os.unlink(temp_path)
+            except OSError:
+                pass
+
+
+def synthesize_speech(
+    text: str,
+    profile: Optional[str] = None,
+) -> tuple[bytes, str, Optional[str]]:
+    """Synthesize text to audio bytes.
+
+    Args:
+        text: Text to speak.
+        profile: Optional Hermes profile name.
+
+    Returns:
+        Tuple of ``(audio_bytes, mime_type, provider_name)``.
+
+    Raises:
+        AudioBackendError: 400 for empty text, 500 for provider failures,
+            503 if no TTS provider is available.
+    """
+    text = (text or "").strip()
+    if not text:
+        raise AudioBackendError("text is required", status=400)
+
+    try:
+        from tools.tts_tool import text_to_speech_tool
+    except ImportError as exc:
+        raise AudioBackendError(
+            f"TTS provider unavailable: {exc}", status=503
+        )
+
+    import json as _json
+
+    scope = _resolve_profile_scope(profile)
+    with scope:
+        try:
+            result_json = text_to_speech_tool(text)
+            result = _json.loads(result_json) if isinstance(result_json, str) else result_json
+        except Exception as exc:
+            logger.exception("Mobile voice TTS failed")
+            raise AudioBackendError(
+                f"Speech synthesis failed: {exc}", status=500
+            )
+
+    if not result.get("success"):
+        raise AudioBackendError(
+            result.get("error") or "Speech synthesis failed",
+            status=400,
+        )
+
+    file_path = result.get("file_path")
+    if not file_path or not os.path.isfile(file_path):
+        raise AudioBackendError("Audio file missing", status=500)
+
+    try:
+        with open(file_path, "rb") as fh:
+            audio_bytes = fh.read()
+    except OSError as exc:
+        raise AudioBackendError(f"Could not read audio: {exc}", status=500)
+    finally:
+        try:
+            os.unlink(file_path)
+        except OSError:
+            pass
+
+    ext = os.path.splitext(file_path)[1].lower()
+    mime_type = _AUDIO_EXT_TO_MIME.get(ext, "audio/mpeg")
+    provider = result.get("provider")
+    return audio_bytes, mime_type, provider