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

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

scitex/audio/_relay.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""Audio relay client for remote TTS playback.
+
+Forwards speak requests to a remote audio server via HTTP.
+This allows agents running on remote machines (e.g., NAS) to play
+audio through the user's local speakers.
+
+Usage:
+    from scitex.audio._relay import RelayClient
+
+    # Connect to local relay server
+    client = RelayClient("http://localhost:31293")
+
+    # Speak through relay
+    client.speak("Hello from remote!")
+
+Environment Variables:
+    SCITEX_AUDIO_RELAY_URL: Relay server URL
+    SCITEX_AUDIO_RELAY_HOST: Relay server host (builds URL with port)
+    SCITEX_AUDIO_RELAY_PORT: Relay server port (default: 31293)
+"""
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Optional
+
+from ._branding import DEFAULT_PORT, get_relay_url
+
+
+class RelayClient:
+    """HTTP client for audio relay server.
+
+    Forwards TTS requests to a remote server running the audio MCP
+    in HTTP mode. Enables remote agents to play audio locally.
+
+    Example:
+        >>> client = RelayClient("http://localhost:31293")
+        >>> client.speak("Hello!")
+        {'success': True, 'text': 'Hello!', ...}
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        timeout: int = 30,
+    ):
+        """Initialize relay client.
+
+        Args:
+            base_url: Relay server URL. Auto-detects from env if None.
+            timeout: Request timeout in seconds.
+        """
+        self.base_url = (
+            base_url or get_relay_url() or f"http://localhost:{DEFAULT_PORT}"
+        ).rstrip("/")
+        self.timeout = timeout
+
+    def _request(
+        self,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        method: str = "POST",
+    ) -> Dict[str, Any]:
+        """Make HTTP request to relay server."""
+        url = f"{self.base_url}{endpoint}"
+
+        try:
+            if data is not None:
+                req_data = json.dumps(data).encode("utf-8")
+                req = urllib.request.Request(url, data=req_data, method=method)
+                req.add_header("Content-Type", "application/json")
+            else:
+                req = urllib.request.Request(url, method=method)
+
+            req.add_header("Accept", "application/json")
+
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                return json.loads(response.read().decode("utf-8"))
+
+        except urllib.error.HTTPError as e:
+            raise ConnectionError(f"Relay request failed: {e.code} {e.reason}") from e
+        except urllib.error.URLError as e:
+            raise ConnectionError(
+                f"Cannot connect to relay at {self.base_url}: {e.reason}"
+            ) from e
+
+    def health(self) -> Dict[str, Any]:
+        """Check relay server health."""
+        try:
+            # Try MCP health endpoint
+            return self._request("/health", method="GET")
+        except Exception:
+            # Relay may not have /health, try simple request
+            return {"status": "unknown", "url": self.base_url}
+
+    def is_available(self) -> bool:
+        """Check if relay server is reachable."""
+        try:
+            self.health()
+            return True
+        except Exception:
+            return False
+
+    def speak(
+        self,
+        text: str,
+        backend: Optional[str] = None,
+        voice: Optional[str] = None,
+        rate: int = 150,
+        speed: float = 1.5,
+        play: bool = True,
+        save: bool = False,
+        fallback: bool = True,
+        agent_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Forward speak request to relay server.
+
+        Args:
+            text: Text to speak
+            backend: TTS backend (auto if None)
+            voice: Voice/language
+            rate: Speech rate (pyttsx3)
+            speed: Speed multiplier (gtts)
+            play: Play audio
+            save: Save audio file
+            fallback: Try fallback backends
+            agent_id: Agent identifier
+
+        Returns
+        -------
+            Response dict with success status
+        """
+        data = {
+            "text": text,
+            "backend": backend,
+            "voice": voice,
+            "rate": rate,
+            "speed": speed,
+            "play": play,
+            "save": save,
+            "fallback": fallback,
+            "agent_id": agent_id,
+        }
+
+        # Remove None values
+        data = {k: v for k, v in data.items() if v is not None}
+
+        return self._request("/speak", data)
+
+    def list_backends(self) -> Dict[str, Any]:
+        """Get available backends from relay server."""
+        return self._request("/list_backends", method="GET")
+
+
+# Module-level client singleton
+_client: Optional[RelayClient] = None
+
+
+def get_relay_client(base_url: Optional[str] = None) -> RelayClient:
+    """Get or create relay client singleton."""
+    global _client
+    if _client is None or (base_url and _client.base_url != base_url):
+        _client = RelayClient(base_url)
+    return _client
+
+
+def reset_relay_client() -> None:
+    """Reset relay client singleton."""
+    global _client
+    _client = None
+
+
+def relay_speak(
+    text: str,
+    backend: Optional[str] = None,
+    voice: Optional[str] = None,
+    rate: int = 150,
+    speed: float = 1.5,
+    play: bool = True,
+    **kwargs,
+) -> Dict[str, Any]:
+    """Convenience function to speak via relay.
+
+    Args:
+        text: Text to speak
+        backend: TTS backend
+        voice: Voice/language
+        rate: Speech rate
+        speed: Speed multiplier
+        play: Play audio
+        **kwargs: Additional options
+
+    Returns
+    -------
+        Response dict
+    """
+    client = get_relay_client()
+    return client.speak(
+        text=text,
+        backend=backend,
+        voice=voice,
+        rate=rate,
+        speed=speed,
+        play=play,
+        **kwargs,
+    )
+
+
+def is_relay_available() -> bool:
+    """Check if relay server is available."""
+    try:
+        client = get_relay_client()
+        return client.is_available()
+    except Exception:
+        return False
+
+
+__all__ = [
+    "RelayClient",
+    "get_relay_client",
+    "reset_relay_client",
+    "relay_speak",
+    "is_relay_available",
+]

scitex/audio/_tts.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 # Timestamp: "2025-12-11 (ywatanabe)"
 # File: /home/ywatanabe/proj/scitex-code/src/scitex/audio/_tts.py
 # ----------------------------------------
@@ -20,7 +19,7 @@ from __future__ import annotations
 import os
 import subprocess
 import tempfile
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 
@@ -44,7 +43,8 @@ class TTSConfig:
 class TTS:
     """Text-to-Speech using ElevenLabs API.
 
-    Examples:
+    Examples
+    --------
         # Basic usage
         tts = TTS()
         tts.speak("Hello, world!")
@@ -84,7 +84,11 @@ class TTS:
             voice_id: Direct voice ID (overrides voice_name).
             **kwargs: Additional config options (stability, speed, etc.)
         """
-        self.api_key = api_key or os.environ.get("ELEVENLABS_API_KEY")
+        self.api_key = (
+            api_key
+            or os.environ.get("SCITEX_AUDIO_ELEVENLABS_API_KEY")
+            or os.environ.get("ELEVENLABS_API_KEY")
+        )
         self.config = TTSConfig(**kwargs)
 
         if voice_id:
@@ -129,7 +133,8 @@ class TTS:
             voice_name: Override voice name for this call.
             voice_id: Override voice ID for this call.
 
-        Returns:
+        Returns
+        -------
             Path to the generated audio file, or None if only played.
         """
         # Determine voice
@@ -228,14 +233,15 @@ class TTS:
         try:
             # SoundPlayer only supports WAV, so convert if needed
             wav_path = path
-            if path.suffix.lower() in ('.mp3', '.ogg', '.m4a'):
+            if path.suffix.lower() in (".mp3", ".ogg", ".m4a"):
                 try:
                     from pydub import AudioSegment
-                    fd, tmp_wav = tempfile.mkstemp(suffix='.wav', prefix='scitex_')
+
+                    fd, tmp_wav = tempfile.mkstemp(suffix=".wav", prefix="scitex_")
                     os.close(fd)
                     wav_path = Path(tmp_wav)
                     audio = AudioSegment.from_file(str(path))
-                    audio.export(str(wav_path), format='wav')
+                    audio.export(str(wav_path), format="wav")
                 except ImportError:
                     pass
 
@@ -303,10 +309,12 @@ def speak(
         output_path: Optional path to save audio.
         **kwargs: Additional TTS config options.
 
-    Returns:
+    Returns
+    -------
         Path to audio file if output_path specified, else None.
 
-    Examples:
+    Examples
+    --------
         import scitex
 
         # Simple speak

scitex/audio/engines/base.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 # Timestamp: "2025-12-11 (ywatanabe)"
 # File: /home/ywatanabe/proj/scitex-code/src/scitex/audio/engines/base.py
 # ----------------------------------------
@@ -49,10 +48,13 @@ class TTSBackend:
 
         # Check ElevenLabs
         try:
-            import elevenlabs
             import os
 
-            if os.environ.get("ELEVENLABS_API_KEY"):
+            import elevenlabs
+
+            if os.environ.get("SCITEX_AUDIO_ELEVENLABS_API_KEY") or os.environ.get(
+                "ELEVENLABS_API_KEY"
+            ):
                 backends.append(cls.ELEVENLABS)
         except ImportError:
             pass
@@ -74,7 +76,8 @@ class BaseTTS(ABC):
             text: Text to convert to speech.
             output_path: Path to save the audio file.
 
-        Returns:
+        Returns
+        -------
             Path to the generated audio file.
         """
         pass
@@ -83,7 +86,8 @@ class BaseTTS(ABC):
     def get_voices(self) -> List[dict]:
         """Get available voices for this backend.
 
-        Returns:
+        Returns
+        -------
             List of voice dictionaries with 'name' and 'id' keys.
         """
         pass
@@ -119,7 +123,8 @@ class BaseTTS(ABC):
             play: Whether to play the audio.
             voice: Optional voice name/id.
 
-        Returns:
+        Returns
+        -------
             Path to audio file if output_path specified, else None.
         """
         import tempfile
@@ -201,7 +206,8 @@ class BaseTTS(ABC):
         Args:
             path: Path to audio file (in WSL filesystem)
 
-        Returns:
+        Returns
+        -------
             True if playback succeeded, False otherwise
         """
         import os
@@ -220,16 +226,17 @@ class BaseTTS(ABC):
         try:
             # SoundPlayer only supports WAV, so convert if needed
             wav_path = path
-            if path.suffix.lower() in ('.mp3', '.ogg', '.m4a'):
+            if path.suffix.lower() in (".mp3", ".ogg", ".m4a"):
                 try:
                     from pydub import AudioSegment
+
                     # Create temp WAV file
-                    fd, tmp_wav = tempfile.mkstemp(suffix='.wav', prefix='scitex_')
+                    fd, tmp_wav = tempfile.mkstemp(suffix=".wav", prefix="scitex_")
                     os.close(fd)
                     wav_path = Path(tmp_wav)
 
                     audio = AudioSegment.from_file(str(path))
-                    audio.export(str(wav_path), format='wav')
+                    audio.export(str(wav_path), format="wav")
                 except ImportError:
                     # pydub not available, try direct playback anyway
                     pass

scitex/audio/engines/elevenlabs_engine.py

@@ -38,6 +38,10 @@ class ElevenLabsTTS(BaseTTS):
         "sam": "yoZ06aMxZJJ28mfd3POQ",
     }
 
+    # ElevenLabs API speed limits
+    MIN_SPEED = 0.7
+    MAX_SPEED = 1.2
+
     def __init__(
         self,
         api_key: Optional[str] = None,
@@ -51,14 +55,15 @@ class ElevenLabsTTS(BaseTTS):
         super().__init__(**kwargs)
         self.api_key = (
             api_key
+            or os.environ.get("SCITEX_AUDIO_ELEVENLABS_API_KEY")
             or os.environ.get("ELEVENLABS_API_KEY")
-            or os.environ.get("ELEVENLABS_API_KEY_SCITEX_AUDIO")
         )
         self.voice = voice
         self.model_id = model_id
         self.stability = stability
         self.similarity_boost = similarity_boost
-        self.speed = speed
+        # Clamp speed to ElevenLabs API limits (0.7-1.2)
+        self.speed = max(self.MIN_SPEED, min(self.MAX_SPEED, speed))
         self._client = None
 
     @property