monkeybot-cli 0.2.1__py3-none-any.whl

monkeybot_cli/realtime/client.py

@@ -0,0 +1,17 @@
+"""Deprecated shim — use ``encode_client_frame`` and ``is_exit_command``."""
+
+from __future__ import annotations
+
+from monkeybot_cli.exit_commands import is_exit_command
+from monkeybot_cli.realtime.wire_encode import encode_client_frame
+
+
+class RealtimeClientError(RuntimeError):
+    """Deprecated alias; prefer ``RuntimeError``."""
+
+
+__all__ = [
+    "RealtimeClientError",
+    "encode_client_frame",
+    "is_exit_command",
+]

monkeybot_cli/realtime/gateway_manager.py

@@ -0,0 +1,142 @@
+"""Helpers for starting the combined (SSE + realtime) gateway from the CLI."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import urllib.parse
+from pathlib import Path
+
+import httpx
+
+from monkeybot_cli.runtime_python import (
+    COMBINED_GATEWAY_MODULE,
+    gateway_argv,
+    resolve_runtime_python,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _find_workspace_dir(start: Path | None = None) -> Path | None:
+    """Find the directory containing ``monkeybot_config/monkeybot.yaml``."""
+    start = start or Path.cwd()
+    for path in [start, *start.parents]:
+        if (path / "monkeybot_config" / "monkeybot.yaml").exists():
+            return path
+    return None
+
+
+def _load_dotenv(workspace_dir: Path) -> None:
+    """Load workspace ``.env`` into the current process environment."""
+    env_file = workspace_dir / ".env"
+    if not env_file.exists():
+        return
+    try:
+        from dotenv import load_dotenv
+
+        load_dotenv(env_file, override=False)
+    except Exception:
+        logger.warning("Failed to load %s", env_file, exc_info=True)
+
+
+def _http_base_from_ws_url(url: str) -> str:
+    parsed = urllib.parse.urlparse(url)
+    host = parsed.hostname or "localhost"
+    port = parsed.port or (443 if parsed.scheme == "wss" else 80)
+    scheme = "https" if parsed.scheme == "wss" else "http"
+    return f"{scheme}://{host}:{port}"
+
+
+async def _is_gateway_healthy(url: str, timeout: float = 2.0) -> bool:
+    """Return True if ``GET {http_base}/health`` succeeds."""
+    base = _http_base_from_ws_url(url)
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.get(f"{base}/health")
+            return resp.status_code == 200
+    except Exception as exc:
+        logger.debug("Gateway health check failed at %s: %s", base, exc)
+        return False
+
+
+async def _wait_for_gateway(url: str, max_wait: float = 30.0) -> bool:
+    """Poll health until ready or timeout."""
+    deadline = asyncio.get_event_loop().time() + max_wait
+    while asyncio.get_event_loop().time() < deadline:
+        if await _is_gateway_healthy(url):
+            return True
+        await asyncio.sleep(0.5)
+    return False
+
+
+def _url_is_local(url: str) -> bool:
+    """Return True if the URL points to localhost/127.0.0.1."""
+    parsed = urllib.parse.urlparse(url)
+    host = (parsed.hostname or "").lower()
+    return host in {"localhost", "127.0.0.1", "::1"}
+
+
+async def start_gateway_if_needed(
+    url: str,
+    *,
+    start: bool = True,
+) -> asyncio.subprocess.Process | None:
+    """Start a local combined gateway if requested and not already healthy."""
+    if not start:
+        return None
+    if not _url_is_local(url):
+        return None
+    if await _is_gateway_healthy(url):
+        logger.info("Gateway already reachable at %s", url)
+        return None
+
+    workspace = _find_workspace_dir()
+    if workspace is None:
+        raise RuntimeError(
+            "Could not find monkeybot_config/monkeybot.yaml to start the gateway. "
+            "Run the command from a MonkeyBot workspace or start the gateway manually."
+        )
+
+    _load_dotenv(workspace)
+    parsed = urllib.parse.urlparse(url)
+    port = parsed.port or (443 if parsed.scheme == "wss" else 80)
+
+    env = {**os.environ, "PORT": str(port)}
+    env.setdefault("LOG_LEVEL", "error")
+    runtime = resolve_runtime_python(workspace)
+    cmd = gateway_argv(runtime, module=COMBINED_GATEWAY_MODULE)
+
+    logger.info("Starting combined gateway on port %s from %s", port, workspace)
+    proc = await asyncio.create_subprocess_exec(
+        *cmd,
+        cwd=str(workspace),
+        env=env,
+        stdout=None,
+        stderr=None,
+    )
+
+    if not await _wait_for_gateway(url):
+        proc.terminate()
+        try:
+            await asyncio.wait_for(proc.wait(), timeout=5.0)
+        except asyncio.TimeoutError:
+            proc.kill()
+            await proc.wait()
+        raise RuntimeError(f"Gateway failed to become reachable at {url}")
+
+    logger.info("Gateway ready at %s", url)
+    return proc
+
+
+async def stop_gateway(proc: asyncio.subprocess.Process | None) -> None:
+    """Terminate a gateway subprocess started by :func:`start_gateway_if_needed`."""
+    if proc is None or proc.returncode is not None:
+        return
+    proc.terminate()
+    try:
+        await asyncio.wait_for(proc.wait(), timeout=5.0)
+    except asyncio.TimeoutError:
+        proc.kill()
+        await proc.wait()

monkeybot_cli/realtime/push_to_talk.py

@@ -0,0 +1,128 @@
+"""Push-to-talk key gate for the realtime CLI.
+
+Hold the configured modifier (Command on macOS by default) to unmute the
+microphone. Requires ``pynput`` (installed via ``monkeybot[cli-realtime]``).
+On macOS, grant Accessibility permission to the terminal app if key events
+are not detected.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+try:
+    from pynput import keyboard
+
+    _HAS_PYNPUT = True
+except ImportError:
+    keyboard = None
+    _HAS_PYNPUT = False
+
+
+class PushToTalkError(Exception):
+    """Push-to-talk setup failed."""
+
+
+class PushToTalkGate:
+    """Tracks whether the push-to-talk key is currently held."""
+
+    def __init__(self, *, key_name: str = "cmd") -> None:
+        if not _HAS_PYNPUT:
+            raise PushToTalkError(
+                "pynput is required for push-to-talk. Install with: uv sync --extra cli-realtime"
+            )
+        self._key_name = key_name.lower().strip()
+        self._held = False
+        self._lock = threading.Lock()
+        self._listener: Any | None = None
+        self._target_keys = self._resolve_keys(self._key_name)
+
+    @staticmethod
+    def _resolve_keys(key_name: str) -> set[Any]:
+        assert keyboard is not None
+        aliases: dict[str, set[Any]] = {
+            "cmd": {keyboard.Key.cmd, keyboard.Key.cmd_l, keyboard.Key.cmd_r},
+            "command": {keyboard.Key.cmd, keyboard.Key.cmd_l, keyboard.Key.cmd_r},
+            "meta": {keyboard.Key.cmd, keyboard.Key.cmd_l, keyboard.Key.cmd_r},
+            "alt": {keyboard.Key.alt, keyboard.Key.alt_l, keyboard.Key.alt_r},
+            "option": {keyboard.Key.alt, keyboard.Key.alt_l, keyboard.Key.alt_r},
+            "ctrl": {keyboard.Key.ctrl, keyboard.Key.ctrl_l, keyboard.Key.ctrl_r},
+            "control": {keyboard.Key.ctrl, keyboard.Key.ctrl_l, keyboard.Key.ctrl_r},
+            "space": {keyboard.Key.space},
+        }
+        keys = aliases.get(key_name)
+        if keys is None:
+            raise PushToTalkError(
+                f"Unsupported push-to-talk key '{key_name}'. "
+                "Use one of: cmd, alt, ctrl, space"
+            )
+        return keys
+
+    @property
+    def key_label(self) -> str:
+        labels = {
+            "cmd": "⌘ Command",
+            "command": "⌘ Command",
+            "meta": "⌘ Command",
+            "alt": "⌥ Option",
+            "option": "⌥ Option",
+            "ctrl": "⌃ Control",
+            "control": "⌃ Control",
+            "space": "Space",
+        }
+        return labels.get(self._key_name, self._key_name)
+
+    def is_held(self) -> bool:
+        with self._lock:
+            return self._held
+
+    def _on_press(self, key: Any) -> None:
+        if key in self._target_keys:
+            with self._lock:
+                was_held = self._held
+                self._held = True
+            if not was_held:
+                logger.debug("push-to-talk pressed (%s)", self._key_name)
+
+    def _on_release(self, key: Any) -> None:
+        if key in self._target_keys:
+            with self._lock:
+                was_held = self._held
+                self._held = False
+            if was_held:
+                logger.debug("push-to-talk released (%s)", self._key_name)
+
+    def start(self) -> None:
+        assert keyboard is not None
+        if self._listener is not None:
+            return
+        self._listener = keyboard.Listener(
+            on_press=self._on_press,
+            on_release=self._on_release,
+        )
+        self._listener.daemon = True
+        try:
+            self._listener.start()
+        except Exception as exc:
+            self._listener = None
+            raise PushToTalkError(
+                f"Failed to start push-to-talk listener: {exc}. "
+                "On macOS, grant Accessibility permission to your terminal app "
+                "(System Settings → Privacy & Security → Accessibility)."
+            ) from exc
+        logger.info("push-to-talk ready: hold %s to speak", self.key_label)
+
+    def stop(self) -> None:
+        listener = self._listener
+        self._listener = None
+        if listener is not None:
+            try:
+                listener.stop()
+            except Exception:
+                logger.exception("push-to-talk listener stop failed")
+        with self._lock:
+            self._held = False

monkeybot_cli/realtime/session.py

@@ -0,0 +1,256 @@
+"""Talk session orchestration (audio + text entrypoints)."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import uuid
+from typing import Annotated
+
+import typer
+from monkeybot.core.config.realtime_config import get_realtime_config
+from monkeybot.core.logging_utils import normalize_log_level
+
+from monkeybot_cli.realtime.audio_io import AudioIOError, AudioPlayer, AudioRecorder
+from monkeybot_cli.realtime.push_to_talk import PushToTalkError, PushToTalkGate
+from monkeybot_cli.runtime_python import DEFAULT_PORT
+
+app = typer.Typer(help="MonkeyBot realtime CLI helpers (prefer the monkeybot-cli package)")
+
+
+def _setup_logging(*, verbose: bool = False) -> None:
+    level = logging.DEBUG if verbose else normalize_log_level(os.getenv("LOG_LEVEL"))
+    logging.basicConfig(
+        level=level,
+        format="%(levelname)s:%(name)s:%(message)s",
+    )
+
+
+def _generate_session_id() -> str:
+    return uuid.uuid4().hex
+
+
+def _parse_sample_rate(fmt: str) -> int:
+    parts = fmt.lower().split("_")
+    for p in parts:
+        if p.endswith("khz"):
+            try:
+                return int(p.replace("khz", "")) * 1000
+            except ValueError:
+                pass
+    return 24000
+
+
+def default_gateway_ws_url() -> str:
+    """Default WebSocket URL from env or ``runtime.port`` (DEFAULT_PORT)."""
+    env = os.getenv("MONKEYBOT_GATEWAY_URL")
+    if env:
+        return env.rstrip("/")
+    return f"ws://127.0.0.1:{DEFAULT_PORT}"
+
+
+def _setup_audio_devices(
+    *,
+    text: bool,
+    input_format: str,
+    chunk_ms: int,
+    ptt_key: str,
+) -> tuple[bool, AudioRecorder | None, AudioPlayer | None, PushToTalkGate | None, int]:
+    """Open player/recorder/PTT for talk. Returns (audio_enabled, recorder, player, ptt, exit_code).
+
+    ``exit_code`` is non-zero when setup failed fatally (caller should return it).
+    """
+    audio_input_enabled = not text
+    recorder: AudioRecorder | None = None
+    player: AudioPlayer | None = None
+    ptt: PushToTalkGate | None = None
+    device_hints: list[str] = []
+
+    if text:
+        return False, None, None, None, 0
+
+    try:
+        player = AudioPlayer(
+            sample_rate=_parse_sample_rate(input_format),
+            channels=1,
+            format_name=input_format,
+        )
+    except AudioIOError as exc:
+        device_hints.append(f"Audio output unavailable: {exc}")
+
+    try:
+        recorder = AudioRecorder(
+            sample_rate=_parse_sample_rate(input_format),
+            channels=1,
+            chunk_ms=chunk_ms,
+            format_name=input_format,
+        )
+    except AudioIOError as exc:
+        if player is None:
+            print(f"Audio setup failed: {exc}", file=sys.stderr)
+            print(
+                "Tip: install PortAudio (brew install portaudio) and sync with "
+                "'uv sync --extra cli-realtime', or use --text for text-only mode.",
+                file=sys.stderr,
+            )
+            return False, None, None, None, 1
+        device_hints.append(f"Microphone unavailable: {exc} Continuing with text input.")
+        audio_input_enabled = False
+
+    if audio_input_enabled:
+        try:
+            ptt = PushToTalkGate(key_name=ptt_key)
+        except PushToTalkError as exc:
+            print(f"Push-to-talk unavailable: {exc}", file=sys.stderr)
+            print(
+                "Tip: sync with 'uv sync --extra cli-realtime'. "
+                "On macOS, grant Accessibility permission to your terminal app. "
+                "Space in an empty composer toggles in-TUI PTT.",
+                file=sys.stderr,
+            )
+            # Continue without global PTT — in-TUI Space still works when TTY.
+            ptt = None
+
+    for hint in device_hints:
+        print(hint, file=sys.stderr)
+
+    return audio_input_enabled and recorder is not None, recorder, player, ptt, 0
+
+
+def run_talk_session(
+    *,
+    gateway_url: str | None = None,
+    session_id: str | None = None,
+    text: bool = False,
+    ptt_key: str = "cmd",
+    start_gateway: bool = True,
+    input_format: str = "pcm_s16le_24khz_mono",
+    chunk_ms: int = 200,
+    verbose: bool = False,
+) -> int:
+    """Run a realtime talk session via ``RealtimeSessionController``. Returns exit code."""
+    _setup_logging(verbose=verbose)
+    get_realtime_config()
+    if not session_id:
+        session_id = _generate_session_id()
+    if not gateway_url:
+        gateway_url = default_gateway_ws_url()
+
+    from monkeybot_cli.realtime.talk_ui import run_talk_ui_session
+
+    audio_enabled, recorder, player, ptt, setup_code = _setup_audio_devices(
+        text=text,
+        input_format=input_format,
+        chunk_ms=chunk_ms,
+        ptt_key=ptt_key,
+    )
+    if setup_code != 0:
+        return setup_code
+
+    try:
+        return run_talk_ui_session(
+            gateway_url=gateway_url,
+            session_id=session_id,
+            start_gateway=start_gateway,
+            verbose=verbose,
+            audio_enabled=audio_enabled,
+            audio_recorder=recorder,
+            audio_player=player,
+            push_to_talk=ptt,
+        )
+    finally:
+        if recorder is not None:
+            recorder.close()
+        if player is not None:
+            player.close()
+
+
+@app.command("talk")
+def talk(
+    gateway_url: Annotated[
+        str,
+        typer.Option(
+            "--gateway-url",
+            help="Base URL of the MonkeyBot realtime gateway, e.g. ws://127.0.0.1:8080",
+            envvar="MONKEYBOT_GATEWAY_URL",
+        ),
+    ] = "",
+    session_id: Annotated[
+        str | None,
+        typer.Option(
+            "--session-id",
+            help="Session ID to connect to; generated if not provided",
+            envvar="MONKEYBOT_SESSION_ID",
+        ),
+    ] = None,
+    text: Annotated[
+        bool,
+        typer.Option(
+            "--text/--no-text",
+            help="Text-only input (no microphone). Audio output is still used when available.",
+        ),
+    ] = False,
+    ptt_key: Annotated[
+        str,
+        typer.Option(
+            "--ptt-key",
+            help="Push-to-talk key to hold while speaking: cmd, alt, ctrl, or space",
+        ),
+    ] = "cmd",
+    start_gateway: Annotated[
+        bool,
+        typer.Option(
+            "--start-gateway/--no-start-gateway",
+            help="Start a local realtime gateway if one is not already reachable",
+        ),
+    ] = True,
+    input_format: Annotated[
+        str,
+        typer.Option(
+            "--input-format",
+            help="Audio format, e.g. pcm_s16le_24khz_mono",
+        ),
+    ] = "pcm_s16le_24khz_mono",
+    chunk_ms: Annotated[
+        int,
+        typer.Option("--chunk-ms", help="Audio chunk size in milliseconds"),
+    ] = 200,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose/--no-verbose",
+            help="Enable debug logging for audio chunks and gateway events",
+        ),
+    ] = False,
+) -> None:
+    """Talk with a MonkeyBot realtime agent."""
+    code = run_talk_session(
+        gateway_url=gateway_url or None,
+        session_id=session_id,
+        text=text,
+        ptt_key=ptt_key,
+        start_gateway=start_gateway,
+        input_format=input_format,
+        chunk_ms=chunk_ms,
+        verbose=verbose,
+    )
+    if code != 0:
+        raise typer.Exit(code)
+
+
+@app.command()
+def version() -> None:
+    """Show MonkeyBot version."""
+    from importlib.metadata import version as get_version
+
+    typer.echo(get_version("monkeybot"))
+
+
+def main() -> None:
+    """Console entrypoint for realtime helpers (prefer ``monkeybot`` from monkeybot-cli)."""
+    app()
+
+
+if __name__ == "__main__":
+    main()