scitex 2.14.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

scitex/audio/_branding.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""Configuration constants for scitex.audio.
+
+Provides environment variable helpers and default values for the audio module.
+"""
+
+import os
+from typing import Optional
+
+# Fixed branding (scitex.audio is part of scitex, not rebranded)
+BRAND_NAME = "scitex.audio"
+BRAND_ALIAS = "audio"
+ENV_PREFIX = "SCITEX_AUDIO"
+
+# Default port: 31293 (SCITEX port scheme: 3129X where X=3 for audio)
+DEFAULT_PORT = 31293
+DEFAULT_HOST = "0.0.0.0"
+
+
+def get_env(key: str, default: Optional[str] = None) -> Optional[str]:
+    """Get environment variable with SCITEX_AUDIO_ prefix.
+
+    Args:
+        key: Variable name without prefix (e.g., "PORT", "HOST", "MODE")
+        default: Default value if not found
+
+    Returns
+    -------
+        Environment variable value or default
+
+    Examples
+    --------
+        get_env("PORT")  # Checks SCITEX_AUDIO_PORT
+        get_env("MODE", "local")  # With default
+    """
+    return os.environ.get(f"SCITEX_AUDIO_{key}", default)
+
+
+def get_port() -> int:
+    """Get configured port number."""
+    port_str = get_env("PORT", str(DEFAULT_PORT))
+    return int(port_str)
+
+
+def get_host() -> str:
+    """Get configured host."""
+    return get_env("HOST", DEFAULT_HOST)
+
+
+def get_mode() -> str:
+    """Get audio mode: 'local', 'remote', or 'auto'.
+
+    - local: Always play locally (direct TTS)
+    - remote: Always forward to relay server
+    - auto: Try local first, fall back to remote
+    """
+    return get_env("MODE", "auto").lower()
+
+
+def get_ssh_client_ip() -> Optional[str]:
+    """Get IP address of SSH client if running in SSH session.
+
+    Extracts client IP from SSH_CLIENT or SSH_CONNECTION env vars.
+    Returns None if not in SSH session.
+    """
+    # SSH_CLIENT format: "client_ip client_port server_port"
+    ssh_client = os.environ.get("SSH_CLIENT", "")
+    if ssh_client:
+        parts = ssh_client.split()
+        if parts:
+            return parts[0]
+
+    # SSH_CONNECTION format: "client_ip client_port server_ip server_port"
+    ssh_connection = os.environ.get("SSH_CONNECTION", "")
+    if ssh_connection:
+        parts = ssh_connection.split()
+        if parts:
+            return parts[0]
+
+    return None
+
+
+def _check_relay_reachable(url: str, timeout: float = 1.0) -> bool:
+    """Quick check if relay URL is reachable."""
+    import socket
+    import urllib.parse
+
+    try:
+        parsed = urllib.parse.urlparse(url)
+        host = parsed.hostname or "localhost"
+        port = parsed.port or DEFAULT_PORT
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(timeout)
+        result = sock.connect_ex((host, port))
+        sock.close()
+        return result == 0
+    except Exception:
+        return False
+
+
+def get_relay_url() -> Optional[str]:
+    """Get relay server URL for remote mode.
+
+    Priority:
+    1. SCITEX_AUDIO_RELAY_URL env var
+    2. SCITEX_AUDIO_RELAY_HOST env var + port
+    3. localhost:31293 (SSH reverse tunnel - if reachable)
+    4. Auto-detect from SSH_CLIENT (if in SSH session)
+
+    Returns URL like 'http://192.168.1.100:31293' or None.
+    """
+    url = get_env("RELAY_URL")
+    if url:
+        return url.rstrip("/")
+
+    # Build from host/port if relay host is set
+    relay_host = get_env("RELAY_HOST")
+    if relay_host:
+        relay_port = get_env("RELAY_PORT", str(DEFAULT_PORT))
+        return f"http://{relay_host}:{relay_port}"
+
+    # Check localhost first (SSH reverse tunnel)
+    localhost_url = f"http://localhost:{DEFAULT_PORT}"
+    if _check_relay_reachable(localhost_url):
+        return localhost_url
+
+    # Auto-detect from SSH client IP
+    ssh_client_ip = get_ssh_client_ip()
+    if ssh_client_ip:
+        return f"http://{ssh_client_ip}:{DEFAULT_PORT}"
+
+    return None
+
+
+def get_mcp_server_name() -> str:
+    """Get the MCP server name."""
+    return "scitex-audio"
+
+
+def get_mcp_instructions() -> str:
+    """Get MCP server instructions."""
+    return """\
+scitex.audio - Text-to-Speech with Multiple Backends
+
+Backends (fallback order): elevenlabs -> gtts -> pyttsx3
+
+## Quick Start
+```python
+from scitex.audio import speak
+speak("Hello, world!")  # Auto-selects backend
+speak("Fast", backend="gtts", speed=1.5)
+```
+
+## MCP Tools
+- **speak**: Convert text to speech
+- **list_backends**: Show available TTS backends
+- **check_audio_status**: Check WSL audio connectivity
+- **announce_context**: Announce current directory and git branch
+
+## Remote Audio Relay
+Run locally: `scitex audio serve -t http --port 31293`
+Remote agents connect via HTTP to play audio on local speakers.
+
+## Environment Variables
+- SCITEX_AUDIO_MODE: 'local', 'remote', or 'auto' (default: auto)
+- SCITEX_AUDIO_RELAY_URL: Remote relay server URL
+- SCITEX_AUDIO_PORT: Server port (default: 31293)
+"""
+
+
+__all__ = [
+    "BRAND_NAME",
+    "BRAND_ALIAS",
+    "ENV_PREFIX",
+    "DEFAULT_PORT",
+    "DEFAULT_HOST",
+    "get_env",
+    "get_port",
+    "get_host",
+    "get_mode",
+    "get_relay_url",
+    "get_ssh_client_ip",
+    "get_mcp_server_name",
+    "get_mcp_instructions",
+]

scitex/audio/_mcp/__init__.py

@@ -2,3 +2,35 @@
 # File: __init__.py
 """MCP server components."""
 
+from .handlers import (
+    announce_context_handler,
+    check_audio_status_handler,
+    clear_audio_cache_handler,
+    generate_audio_handler,
+    list_audio_files_handler,
+    list_backends_handler,
+    list_voices_handler,
+    play_audio_handler,
+    speak_handler,
+    speech_queue_status_handler,
+)
+from .speak_handlers import (
+    speak_local_handler,
+    speak_relay_handler,
+)
+
+__all__ = [
+    "speak_handler",
+    "speak_local_handler",
+    "speak_relay_handler",
+    "generate_audio_handler",
+    "list_backends_handler",
+    "list_voices_handler",
+    "play_audio_handler",
+    "list_audio_files_handler",
+    "clear_audio_cache_handler",
+    "check_audio_status_handler",
+    "speech_queue_status_handler",
+    "announce_context_handler",
+]
+

scitex/audio/_mcp/handlers.py

@@ -36,6 +36,37 @@ def _get_audio_dir() -> Path:
     return audio_dir
 
 
+def _get_signature() -> str:
+    """Get signature string with hostname, project, and branch."""
+    import os
+    import socket
+    import subprocess
+
+    hostname = socket.gethostname()
+    cwd = os.getcwd()
+    project = os.path.basename(cwd)
+
+    branch = None
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            branch = result.stdout.strip()
+    except Exception:
+        pass
+
+    parts = [f"Hostname: {hostname}", f"Project: {project}"]
+    if branch:
+        parts.append(f"Branch: {branch}")
+
+    return ". ".join(parts) + ". "
+
+
 async def generate_audio_handler(
     text: str,
     backend: str | None = None,
@@ -89,16 +120,16 @@ async def generate_audio_handler(
 async def list_backends_handler() -> dict:
     """List available TTS backends."""
     try:
-        from .. import available_backends
+        from .. import FALLBACK_ORDER, available_backends
 
         backends = available_backends()
 
         info = []
-        for b in ["gtts", "elevenlabs", "pyttsx3"]:
+        for b in FALLBACK_ORDER:
             available = b in backends
             desc = {
-                "gtts": "Google TTS - Free, requires internet",
                 "elevenlabs": "ElevenLabs - Paid, high quality",
+                "gtts": "Google TTS - Free, requires internet",
                 "pyttsx3": "System TTS - Offline, uses espeak/SAPI5",
             }
             info.append(
@@ -109,11 +140,18 @@ async def list_backends_handler() -> dict:
                 }
             )
 
+        # Determine actual default based on FALLBACK_ORDER
+        default = None
+        for b in FALLBACK_ORDER:
+            if b in backends:
+                default = b
+                break
+
         return {
             "success": True,
             "backends": info,
             "available": backends,
-            "default": backends[0] if backends else None,
+            "default": default,
         }
 
     except Exception as e:
@@ -267,13 +305,25 @@ async def speak_handler(
     fallback: bool = True,
     agent_id: str | None = None,
     wait: bool = True,
+    signature: bool = False,
 ) -> dict:
-    """Convert text to speech with fallback."""
+    """Convert text to speech with fallback.
+
+    Args:
+        signature: If True, prepend hostname/project/branch to text.
+    """
     try:
         from .. import speak as tts_speak
 
         loop = asyncio.get_event_loop()
 
+        # Prepend signature if requested
+        final_text = text
+        sig = None
+        if signature:
+            sig = _get_signature()
+            final_text = sig + text
+
         output_path = None
         if save:
             timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
@@ -281,7 +331,7 @@ async def speak_handler(
 
         def do_speak():
             return tts_speak(
-                text=text,
+                text=final_text,
                 backend=backend,
                 voice=voice,
                 rate=rate,
@@ -300,6 +350,9 @@ async def speak_handler(
             "played": play,
             "timestamp": datetime.now().isoformat(),
         }
+        if signature:
+            result["signature"] = sig
+            result["full_text"] = final_text
         if result_path:
             result["path"] = str(result_path)
 

scitex/audio/_mcp/speak_handlers.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""Speak handlers for scitex.audio MCP server.
+
+Provides speak_local_handler and speak_relay_handler for explicit control
+over audio playback location (server vs relay).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+from pathlib import Path
+
+__all__ = [
+    "speak_local_handler",
+    "speak_relay_handler",
+]
+
+
+def _get_audio_dir() -> Path:
+    """Get the audio output directory."""
+    import os
+
+    base_dir = Path(os.getenv("SCITEX_DIR", Path.home() / ".scitex"))
+    audio_dir = base_dir / "audio"
+    audio_dir.mkdir(parents=True, exist_ok=True)
+    return audio_dir
+
+
+def _get_signature() -> str:
+    """Get signature string with hostname, project, and branch."""
+    import os
+    import socket
+    import subprocess
+
+    hostname = socket.gethostname()
+    cwd = os.getcwd()
+    project = os.path.basename(cwd)
+
+    branch = None
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            branch = result.stdout.strip()
+    except Exception:
+        pass
+
+    parts = [f"Hostname: {hostname}", f"Project: {project}"]
+    if branch:
+        parts.append(f"Branch: {branch}")
+
+    return ". ".join(parts) + ". "
+
+
+async def speak_local_handler(
+    text: str,
+    backend: str | None = None,
+    voice: str | None = None,
+    rate: int = 150,
+    speed: float = 1.5,
+    play: bool = True,
+    save: bool = False,
+    fallback: bool = True,
+    agent_id: str | None = None,
+    signature: bool = False,
+) -> dict:
+    """Play audio on the LOCAL/SERVER machine.
+
+    Use when running Claude Code directly on your local machine.
+    Audio plays on the machine where the MCP server is running.
+    """
+    try:
+        from .. import speak as tts_speak
+        from .._cross_process_lock import AudioPlaybackLock
+
+        loop = asyncio.get_event_loop()
+
+        final_text = text
+        sig = None
+        if signature:
+            sig = _get_signature()
+            final_text = sig + text
+
+        output_path = None
+        if save:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            output_path = str(_get_audio_dir() / f"tts_{timestamp}.mp3")
+
+        def do_speak():
+            # Acquire cross-process lock for FIFO audio playback
+            lock = AudioPlaybackLock()
+            lock.acquire(timeout=120.0)
+            try:
+                return tts_speak(
+                    text=final_text,
+                    backend=backend,
+                    voice=voice,
+                    rate=rate,
+                    speed=speed,
+                    play=play,
+                    output_path=output_path,
+                    fallback=fallback,
+                    mode="local",  # Force local mode
+                )
+            finally:
+                lock.release()
+
+        result_path = await loop.run_in_executor(None, do_speak)
+
+        result = {
+            "success": True,
+            "text": text,
+            "backend": backend,
+            "played": play,
+            "played_on": "server",
+            "agent_id": agent_id,
+            "timestamp": datetime.now().isoformat(),
+        }
+        if signature:
+            result["signature"] = sig
+            result["full_text"] = final_text
+        if result_path:
+            result["path"] = str(result_path)
+
+        return result
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def speak_relay_handler(
+    text: str,
+    backend: str | None = None,
+    voice: str | None = None,
+    rate: int = 150,
+    speed: float = 1.5,
+    play: bool = True,
+    save: bool = False,
+    fallback: bool = True,
+    agent_id: str | None = None,
+) -> dict:
+    """Forward speech to RELAY server for remote playback.
+
+    Use when running on a remote server and want audio on your local machine.
+    Returns detailed error with setup instructions if relay unavailable.
+    """
+    from .._branding import DEFAULT_PORT, get_relay_url, get_ssh_client_ip
+    from .._relay import RelayClient, is_relay_available
+
+    # Get relay URL (auto-detects from SSH_CLIENT if not configured)
+    relay_url = get_relay_url()
+    ssh_client_ip = get_ssh_client_ip()
+
+    if not relay_url:
+        return {
+            "success": False,
+            "error": "Relay server URL not configured",
+            "reason": "No SSH session detected and no env vars set",
+            "instructions": [
+                "1. Start relay server on your LOCAL machine:",
+                f"   scitex audio serve -t http --port {DEFAULT_PORT}",
+                "",
+                "2. SSH to this server (relay URL auto-detected from SSH_CLIENT)",
+                "",
+                "3. Or set env var manually:",
+                f"   export SCITEX_AUDIO_RELAY_URL=http://YOUR_LOCAL_IP:{DEFAULT_PORT}",
+            ],
+        }
+
+    # Check if relay server is reachable
+    if not is_relay_available():
+        source = "auto-detected from SSH_CLIENT" if ssh_client_ip else "from env var"
+        return {
+            "success": False,
+            "error": "Relay server not reachable",
+            "reason": f"Cannot connect to {relay_url} ({source})",
+            "relay_url": relay_url,
+            "auto_detected": ssh_client_ip is not None,
+            "ssh_client_ip": ssh_client_ip,
+            "instructions": [
+                "1. Start relay server on your LOCAL machine:",
+                f"   scitex audio serve -t http --port {DEFAULT_PORT}",
+                "",
+                f"2. Current relay URL: {relay_url}",
+                f"   Source: {source}",
+                "",
+                "3. Test connectivity:",
+                f"   curl {relay_url}/health",
+            ],
+        }
+
+    # Forward to relay server
+    try:
+        loop = asyncio.get_event_loop()
+
+        def do_relay():
+            client = RelayClient(relay_url)
+            return client.speak(
+                text=text,
+                backend=backend,
+                voice=voice,
+                rate=rate,
+                speed=speed,
+                play=play,
+                save=save,
+                fallback=fallback,
+                agent_id=agent_id,
+            )
+
+        result = await loop.run_in_executor(None, do_relay)
+
+        result["played_on"] = "relay"
+        result["relay_url"] = relay_url
+        result["timestamp"] = datetime.now().isoformat()
+
+        return result
+
+    except Exception as e:
+        return {
+            "success": False,
+            "error": f"Relay request failed: {str(e)}",
+            "relay_url": relay_url,
+            "instructions": [
+                "1. Check relay server is still running",
+                "2. Check network connectivity",
+                f"3. Test: curl -X POST {relay_url}/speak "
+                "-H 'Content-Type: application/json' -d '{\"text\": \"test\"}'",
+            ],
+        }
+
+
+# EOF