scitex 2.13.0__py3-none-any.whl → 2.15.1__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/_mcp/tool_schemas.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+# Timestamp: "2025-12-27 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/audio/_mcp.tool_schemas.py
+# ----------------------------------------
+
+"""Tool schemas for the scitex-audio MCP server."""
+
+from __future__ import annotations
+
+import mcp.types as types
+
+__all__ = ["get_tool_schemas"]
+
+
+def get_tool_schemas() -> list[types.Tool]:
+    """Return all tool schemas for the MCP server."""
+    return [
+        types.Tool(
+            name="speak",
+            description=(
+                "Convert text to speech with fallback (pyttsx3 -> gtts -> elevenlabs). "
+                "Requests are queued for sequential playback to prevent audio overlap."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "text": {
+                        "type": "string",
+                        "description": "Text to convert to speech",
+                    },
+                    "backend": {
+                        "type": "string",
+                        "description": "TTS backend (auto-selects with fallback if not specified)",
+                        "enum": ["pyttsx3", "gtts", "elevenlabs"],
+                    },
+                    "voice": {
+                        "type": "string",
+                        "description": "Voice/language (gtts: 'en','fr'; elevenlabs: 'rachel','adam')",
+                    },
+                    "rate": {
+                        "type": "integer",
+                        "description": "Speech rate in words per minute (pyttsx3 only, default 150, faster=200+)",
+                        "default": 150,
+                    },
+                    "speed": {
+                        "type": "number",
+                        "description": "Speed multiplier for gtts (1.0=normal, 1.5=faster, 0.7=slower)",
+                        "default": 1.5,
+                    },
+                    "play": {
+                        "type": "boolean",
+                        "description": "Play audio after generation",
+                        "default": True,
+                    },
+                    "save": {
+                        "type": "boolean",
+                        "description": "Save audio to file",
+                        "default": False,
+                    },
+                    "fallback": {
+                        "type": "boolean",
+                        "description": "Try next backend on failure",
+                        "default": True,
+                    },
+                    "agent_id": {
+                        "type": "string",
+                        "description": "Optional identifier for the agent making the request",
+                    },
+                    "wait": {
+                        "type": "boolean",
+                        "description": "Wait for speech to complete before returning (default: True)",
+                        "default": True,
+                    },
+                },
+                "required": ["text"],
+            },
+        ),
+        types.Tool(
+            name="generate_audio",
+            description="Generate speech audio file without playing",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "text": {
+                        "type": "string",
+                        "description": "Text to convert to speech",
+                    },
+                    "backend": {
+                        "type": "string",
+                        "description": "TTS backend",
+                        "enum": ["gtts", "elevenlabs", "pyttsx3"],
+                        "default": "gtts",
+                    },
+                    "voice": {
+                        "type": "string",
+                        "description": "Voice/language",
+                    },
+                    "output_path": {
+                        "type": "string",
+                        "description": "Output file path",
+                    },
+                    "return_base64": {
+                        "type": "boolean",
+                        "description": "Return audio as base64",
+                        "default": False,
+                    },
+                },
+                "required": ["text"],
+            },
+        ),
+        types.Tool(
+            name="list_backends",
+            description="List available TTS backends and their status",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        types.Tool(
+            name="list_voices",
+            description="List available voices for a backend",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "backend": {
+                        "type": "string",
+                        "description": "TTS backend",
+                        "enum": ["gtts", "elevenlabs", "pyttsx3"],
+                        "default": "gtts",
+                    },
+                },
+            },
+        ),
+        types.Tool(
+            name="play_audio",
+            description="Play an audio file",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Path to audio file",
+                    },
+                },
+                "required": ["path"],
+            },
+        ),
+        types.Tool(
+            name="list_audio_files",
+            description="List generated audio files",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum files to list",
+                        "default": 20,
+                    },
+                },
+            },
+        ),
+        types.Tool(
+            name="clear_audio_cache",
+            description="Clear generated audio files",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "max_age_hours": {
+                        "type": "number",
+                        "description": "Delete files older than N hours (0 = all)",
+                        "default": 24,
+                    },
+                },
+            },
+        ),
+        types.Tool(
+            name="speech_queue_status",
+            description="Get the current speech queue status (pending requests, currently playing, etc.)",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        types.Tool(
+            name="check_audio_status",
+            description="Check WSL audio connectivity and available playback methods",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        types.Tool(
+            name="announce_context",
+            description=(
+                "Announce the current working directory and git branch (if in a git repo). "
+                "Useful for orientation when starting work in a new session."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "include_full_path": {
+                        "type": "boolean",
+                        "description": "Include full path or just directory name",
+                        "default": False,
+                    },
+                },
+            },
+        ),
+    ]
+
+
+# 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/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,
@@ -58,7 +62,8 @@ class ElevenLabsTTS(BaseTTS):
         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