scitex 2.15.5__py3-none-any.whl → 2.16.1__py3-none-any.whl

scitex/_mcp_tools/__init__.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 from .audio import register_audio_tools
 from .canvas import register_canvas_tools
 from .capture import register_capture_tools
+from .dataset import register_dataset_tools
 from .diagram import register_diagram_tools
 from .introspect import register_introspect_tools
 from .plt import register_plt_tools
@@ -26,6 +27,7 @@ def register_all_tools(mcp) -> None:
     register_audio_tools(mcp)
     register_canvas_tools(mcp)
     register_capture_tools(mcp)
+    register_dataset_tools(mcp)
     register_diagram_tools(mcp)
     register_introspect_tools(mcp)
     register_plt_tools(mcp)

scitex/_mcp_tools/audio.py

@@ -30,7 +30,17 @@ def register_audio_tools(mcp) -> None:
         wait: bool = True,
         signature: bool = False,
     ) -> str:
-        """[audio] Convert text to speech with fallback (pyttsx3 -> gtts -> elevenlabs)."""
+        """[audio] Convert text to speech with smart routing.
+
+        Smart routing (mode=auto, default):
+        - If local audio sink is SUSPENDED and relay available -> uses relay
+        - If local audio available -> uses local
+        - If neither available -> returns error with instructions
+
+        Environment variables:
+        - SCITEX_AUDIO_MODE: 'local', 'remote', or 'auto' (default: auto)
+        - SCITEX_AUDIO_RELAY_URL: Relay server URL for remote playback
+        """
         from scitex.audio._mcp.handlers import speak_handler
 
         result = await speak_handler(
@@ -132,69 +142,5 @@ def register_audio_tools(mcp) -> None:
         result = await announce_context_handler(include_full_path=include_full_path)
         return _json(result)
 
-    @mcp.tool()
-    async def audio_speak_local(
-        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,
-    ) -> str:
-        """[audio] Convert text to speech on the LOCAL/SERVER machine.
-
-        Use when running Claude Code directly on your local machine.
-        Audio plays where MCP server runs.
-        """
-        from scitex.audio._mcp.speak_handlers import speak_local_handler
-
-        result = await speak_local_handler(
-            text=text,
-            backend=backend,
-            voice=voice,
-            rate=rate,
-            speed=speed,
-            play=play,
-            save=save,
-            fallback=fallback,
-            agent_id=agent_id,
-        )
-        return _json(result)
-
-    @mcp.tool()
-    async def audio_speak_relay(
-        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,
-    ) -> str:
-        """[audio] Convert text to speech via RELAY server (remote playback).
-
-        Use when running on remote server (NAS) and want audio on your
-        local machine. Returns error with setup instructions if unavailable.
-        """
-        from scitex.audio._mcp.speak_handlers import speak_relay_handler
-
-        result = await speak_relay_handler(
-            text=text,
-            backend=backend,
-            voice=voice,
-            rate=rate,
-            speed=speed,
-            play=play,
-            save=save,
-            fallback=fallback,
-            agent_id=agent_id,
-        )
-        return _json(result)
-
 
 # EOF

scitex/_mcp_tools/canvas.py

@@ -24,12 +24,12 @@ def _json(data: dict) -> str:
 def register_canvas_tools(mcp) -> None:
     """Register canvas tools with FastMCP server.
 
-    Note: These tools are deprecated. figrecipe is mounted for composition.
+    Note: These tools are deprecated. Use plt_compose from figrecipe instead.
+    plt_* and diagram_* tools are registered via plt.py and diagram.py respectively.
     """
-    # Mount figrecipe MCP server if available (preferred)
-    _mount_figrecipe(mcp)
 
-    # Legacy canvas tools (deprecated, for backward compatibility)
+    # Legacy canvas tools only (deprecated, for backward compatibility)
+    # plt_* tools are registered in plt.py, diagram_* in diagram.py
     @mcp.tool()
     async def canvas_create_canvas(
         parent_dir: str,
@@ -146,17 +146,4 @@ def register_canvas_tools(mcp) -> None:
         return _json(result)
 
 
-def _mount_figrecipe(mcp) -> None:
-    """Mount figrecipe MCP server for composition tools.
-
-    Provides: plt_plot, plt_compose, plt_reproduce, plt_info, etc.
-    """
-    try:
-        from figrecipe._mcp.server import mcp as figrecipe_mcp
-
-        mcp.mount(figrecipe_mcp, prefix="plt")
-    except ImportError:
-        pass  # figrecipe not installed
-
-
 # EOF

scitex/_mcp_tools/dataset.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""Dataset module tools - thin wrapper delegating to scitex-dataset package.
+
+Single source of truth: scitex-dataset MCP tools.
+"""
+
+from __future__ import annotations
+
+
+def register_dataset_tools(mcp) -> None:
+    """Register dataset tools by delegating to scitex-dataset package."""
+    try:
+        from scitex_dataset._mcp.tools import register_all_tools
+
+        # Delegate all MCP tools to scitex-dataset
+        register_all_tools(mcp)
+    except ImportError:
+        # Fallback when scitex-dataset is not installed
+        @mcp.tool()
+        def dataset_usage() -> str:
+            """[dataset] Get usage guide for SciTeX Dataset (not installed)."""
+            return (
+                "scitex-dataset is required. Install with: pip install scitex-dataset"
+            )
+
+
+# EOF

scitex/_mcp_tools/plt.py

@@ -28,15 +28,16 @@ def register_plt_tools(mcp) -> None:
         from figrecipe._mcp import server as fr_mcp
 
         # Access underlying functions from FunctionTool objects
-        _plot = fr_mcp.plot.fn
-        _reproduce = fr_mcp.reproduce.fn
-        _compose = fr_mcp.compose.fn
-        _info = fr_mcp.info.fn
-        _validate = fr_mcp.validate.fn
-        _crop = fr_mcp.crop.fn
-        _extract_data = fr_mcp.extract_data.fn
-        _list_styles = fr_mcp.list_styles.fn
-        _get_plot_types = fr_mcp.get_plot_types.fn
+        # figrecipe tools are named plt_* for proper MCP categorization
+        _plot = fr_mcp.plt_plot.fn
+        _reproduce = fr_mcp.plt_reproduce.fn
+        _compose = fr_mcp.plt_compose.fn
+        _info = fr_mcp.plt_info.fn
+        _validate = fr_mcp.plt_validate.fn
+        _crop = fr_mcp.plt_crop.fn
+        _extract_data = fr_mcp.plt_extract_data.fn
+        _list_styles = fr_mcp.plt_list_styles.fn
+        _get_plot_types = fr_mcp.plt_get_plot_types.fn
 
         _FIGRECIPE_AVAILABLE = True
     except ImportError:
@@ -54,7 +55,6 @@ def register_plt_tools(mcp) -> None:
     # Delegate to figrecipe's MCP tools with plt_ prefix
     # Each wrapper simply calls the figrecipe function
 
-
     @mcp.tool()
     def plt_plot(
         spec: Dict[str, Any],

scitex/audio/README.md

@@ -1,20 +1,45 @@
 # SciTeX Audio
 
-Text-to-Speech with automatic fallback: pyttsx3 -> gtts -> elevenlabs
+Text-to-Speech with automatic fallback and smart routing.
+
+**Fallback order:** elevenlabs -> gtts -> pyttsx3
+
+## Smart Routing
+
+The `speak()` function automatically routes audio based on availability:
+
+| Local Sink | Relay Available | Result (mode=auto) |
+|------------|-----------------|-------------------|
+| SUSPENDED | Yes | Uses relay |
+| SUSPENDED | No | Returns error |
+| RUNNING | Yes | Prefers relay |
+| RUNNING | No | Uses local |
 
 ## Usage
 
 ```python
 import scitex
 
-# Basic
-scitex.audio.speak("Hello!")
+# Basic - auto mode (smart routing)
+result = scitex.audio.speak("Hello!")
+if result["played"]:
+    print(f"Played via {result['mode']}")
 
-# Faster speech (rate in words per minute)
-scitex.audio.speak("Hello!", rate=200)
+# Force local playback (fails if sink unavailable)
+result = scitex.audio.speak("Hello!", mode="local")
+
+# Force remote relay
+result = scitex.audio.speak("Hello!", mode="remote")
+
+# Faster speech (speed multiplier for gtts)
+scitex.audio.speak("Hello!", speed=1.5)
 
 # Specific backend
-scitex.audio.speak("Hello", backend="pyttsx3")
+scitex.audio.speak("Hello", backend="gtts")
+
+# Check local audio availability
+status = scitex.audio.check_local_audio_available()
+print(status)  # {'available': False, 'state': 'SUSPENDED', 'reason': '...'}
 
 # Stop speech
 scitex.audio.stop_speech()
@@ -58,8 +83,8 @@ Enable remote agents to play audio on local speakers using a simple HTTP relay.
 │  Remote (e.g., NAS)     │              │  Local (WSL/Windows)    │
 │                         │              │                         │
 │  Claude Agent uses      │              │  scitex audio relay     │
-│  audio_speak_relay ─────┼─ SSH ───────▶│  --port 31293           │
-│                         │ Reverse      │         │               │
+│  audio_speak ───────────┼─ SSH ───────▶│  --port 31293           │
+│  (auto-routes to relay) │ Reverse      │         │               │
 │  localhost:31293        │ Tunnel       │         ▼               │
 │                         │              │     🔊 Speakers         │
 └─────────────────────────┘              └─────────────────────────┘
@@ -85,7 +110,7 @@ Host nas
 
 **Step 3: Remote agent uses relay**
 
-The `audio_speak_relay` MCP tool auto-detects:
+The unified `audio_speak` MCP tool auto-detects relay:
 1. `SCITEX_AUDIO_RELAY_URL` env var
 2. Localhost:31293 (SSH reverse tunnel)
 3. SSH_CLIENT IP (auto-detected from SSH session)
@@ -113,13 +138,16 @@ The `audio_speak_relay` MCP tool auto-detects:
 
 | Tool | Description |
 |------|-------------|
-| `audio_speak` | Text to speech (plays on server) |
-| `audio_speak_local` | TTS on server machine |
-| `audio_speak_relay` | TTS via relay (remote playback) |
+| `audio_speak` | **Unified TTS with smart routing** (auto-selects local/relay) |
 | `audio_list_backends` | Show available backends |
 | `audio_check_audio_status` | Check WSL audio connectivity |
 | `audio_announce_context` | Announce current directory and git branch |
 
+The `audio_speak` tool automatically:
+- Checks if local audio sink is available (not SUSPENDED)
+- Uses relay server when local audio unavailable
+- Returns clear error messages when neither is available
+
 ## Backends
 
 | Backend | Cost | Internet | Install |

scitex/audio/__init__.py

@@ -3,6 +3,8 @@
 # File: /home/ywatanabe/proj/scitex-code/src/scitex/audio/__init__.py
 # ----------------------------------------
 
+from __future__ import annotations
+
 """
 SciTeX Audio Module - Text-to-Speech with Multiple Backends
 
@@ -31,28 +33,26 @@ Installation:
     pip install scitex[audio]
 """
 
-import subprocess
-from typing import List, Optional
+import subprocess as _subprocess
 
-# Check for missing dependencies and warn user
-from scitex._install_guide import warn_module_deps
+# Check for missing dependencies and warn user (internal)
+from scitex._install_guide import warn_module_deps as _warn_module_deps
 
-_missing = warn_module_deps("audio")
+_missing = _warn_module_deps("audio")
 
-# Import from engines subpackage
-from .engines import (
-    BaseTTS,
-    ElevenLabsTTS,
-    GoogleTTS,
-    SystemTTS,
-    TTSBackend,
-)
+# Import from engines subpackage (public TTS classes only)
+# Internal imports (prefixed with _ to hide from API)
+from . import engines as _engines_module
+from .engines import ElevenLabsTTS, GoogleTTS, SystemTTS
+from .engines._base import BaseTTS as _BaseTTS
+from .engines._base import TTSBackend as _TTSBackend
+del _engines_module
 
 
 def stop_speech() -> None:
     """Stop any currently playing speech by killing espeak processes."""
     try:
-        subprocess.run(["pkill", "-9", "espeak"], capture_output=True)
+        _subprocess.run(["pkill", "-9", "espeak"], capture_output=True)
     except Exception:
         pass
 
@@ -97,7 +97,7 @@ def check_wsl_audio() -> dict:
             try:
                 env = os.environ.copy()
                 env["PULSE_SERVER"] = "unix:/mnt/wslg/PulseServer"
-                proc = subprocess.run(
+                proc = _subprocess.run(
                     ["pactl", "info"],
                     capture_output=True,
                     timeout=5,
@@ -129,16 +129,18 @@ def check_wsl_audio() -> dict:
 # Keep legacy TTS import for backwards compatibility
 from ._tts import TTS
 
+# Import audio availability check
+from ._audio_check import check_local_audio_available
+
 __all__ = [
     "speak",
     "stop_speech",
     "check_wsl_audio",
+    "check_local_audio_available",
     "TTS",
     "GoogleTTS",
     "ElevenLabsTTS",
     "SystemTTS",
-    "BaseTTS",
-    "TTSBackend",
     "get_tts",
     "available_backends",
     "start_mcp_server",
@@ -149,7 +151,7 @@ __all__ = [
 FALLBACK_ORDER = ["elevenlabs", "gtts", "pyttsx3"]
 
 
-def available_backends() -> List[str]:
+def available_backends() -> list[str]:
     """Return list of available TTS backends in fallback order."""
     backends = []
 
@@ -182,7 +184,7 @@ def available_backends() -> List[str]:
     return backends
 
 
-def get_tts(backend: Optional[str] = None, **kwargs) -> BaseTTS:
+def get_tts(backend: str | None = None, **kwargs) -> _BaseTTS:
     """Get a TTS instance for the specified backend.
 
     Args:
@@ -224,229 +226,8 @@ def get_tts(backend: Optional[str] = None, **kwargs) -> BaseTTS:
         raise ValueError(f"Backend '{backend}' not available. Available: {backends}")
 
 
-def _try_speak_with_fallback(
-    text: str,
-    voice: Optional[str] = None,
-    play: bool = True,
-    output_path: Optional[str] = None,
-    **kwargs,
-) -> tuple:
-    """Try to speak with fallback through backends.
-
-    Returns:
-        (result, backend_used, error_log)
-    """
-    backends = available_backends()
-    errors = []
-
-    for backend in FALLBACK_ORDER:
-        if backend not in backends:
-            continue
-
-        try:
-            tts = get_tts(backend, **kwargs)
-            result = tts.speak(
-                text=text,
-                voice=voice,
-                play=play,
-                output_path=output_path,
-            )
-            return (result, backend, errors)
-        except Exception as e:
-            errors.append(f"{backend}: {str(e)}")
-            continue
-
-    return (None, None, errors)
-
-
-# Cache for default TTS instance
-_default_tts: Optional[BaseTTS] = None
-_default_backend: Optional[str] = None
-
-
-def _speak_local(
-    text: str,
-    backend: Optional[str] = None,
-    voice: Optional[str] = None,
-    play: bool = True,
-    output_path: Optional[str] = None,
-    fallback: bool = True,
-    **kwargs,
-) -> Optional[str]:
-    """Local TTS playback (original implementation)."""
-    global _default_tts, _default_backend
-
-    # Note: stop_speech() removed - FIFO locking handles queuing
-    # Call stop_speech() explicitly if you want to interrupt current audio
-
-    # If specific backend requested without fallback
-    if backend and not fallback:
-        tts = get_tts(backend, **kwargs)
-        result = tts.speak(
-            text=text,
-            voice=voice,
-            play=play,
-            output_path=output_path,
-        )
-        return str(result) if result else None
-
-    # Use fallback logic
-    if fallback and backend is None:
-        result, used_backend, errors = _try_speak_with_fallback(
-            text=text,
-            voice=voice,
-            play=play,
-            output_path=output_path,
-            **kwargs,
-        )
-        if result is None and errors:
-            raise RuntimeError("All TTS backends failed:\n" + "\n".join(errors))
-        return str(result) if result else None
-
-    # Specific backend with fallback enabled
-    try:
-        tts = get_tts(backend, **kwargs)
-        result = tts.speak(
-            text=text,
-            voice=voice,
-            play=play,
-            output_path=output_path,
-        )
-        return str(result) if result else None
-    except Exception as e:
-        if fallback:
-            result, used_backend, errors = _try_speak_with_fallback(
-                text=text,
-                voice=voice,
-                play=play,
-                output_path=output_path,
-                **kwargs,
-            )
-            if result is None:
-                raise RuntimeError(
-                    f"Primary backend '{backend}' failed: {e}\n"
-                    f"Fallback errors:\n" + "\n".join(errors)
-                )
-            return str(result) if result else None
-        raise
-
-
-def speak(
-    text: str,
-    backend: Optional[str] = None,
-    voice: Optional[str] = None,
-    play: bool = True,
-    output_path: Optional[str] = None,
-    fallback: bool = True,
-    rate: Optional[int] = None,
-    speed: Optional[float] = None,
-    mode: Optional[str] = None,
-    **kwargs,
-) -> Optional[str]:
-    """Convert text to speech with smart local/remote switching.
-
-    Modes:
-        - local: Always use local TTS backends
-        - remote: Always forward to relay server
-        - auto: Try remote first, fall back to local (default)
-
-    Fallback order (local): elevenlabs -> gtts -> pyttsx3
-
-    Args:
-        text: Text to speak.
-        backend: TTS backend ('pyttsx3', 'gtts', 'elevenlabs').
-                 Auto-selects with fallback if None.
-        voice: Voice name, ID, or language code.
-        play: Whether to play the audio.
-        output_path: Path to save audio file.
-        fallback: If True, try next backend on failure.
-        rate: Speech rate in words per minute (pyttsx3 only, default 150).
-        speed: Speed multiplier for gtts (1.0=normal, >1.0=faster, <1.0=slower).
-        mode: Override mode ('local', 'remote', 'auto'). Uses env if None.
-        **kwargs: Additional backend options.
-
-    Returns:
-        Path to audio file if output_path specified, else None.
-
-    Environment Variables:
-        SCITEX_AUDIO_MODE: Default mode ('local', 'remote', 'auto')
-        SCITEX_AUDIO_RELAY_URL: Relay server URL for remote mode
-
-    Examples:
-        import scitex
-
-        # Simple (auto mode - tries remote, falls back to local)
-        scitex.audio.speak("Hello!")
-
-        # Force local playback
-        scitex.audio.speak("Hello", mode="local")
-
-        # Force remote relay
-        scitex.audio.speak("Hello", mode="remote")
-
-        # Faster speech (gtts with pydub)
-        scitex.audio.speak("Hello", backend="gtts", speed=1.5)
-    """
-    from ._branding import get_mode, get_relay_url
-    from ._relay import is_relay_available, relay_speak
-
-    # Pass rate/speed to kwargs
-    if rate is not None:
-        kwargs["rate"] = rate
-    if speed is not None:
-        kwargs["speed"] = speed
-
-    # Determine mode
-    effective_mode = mode or get_mode()
-
-    # Remote mode: always use relay
-    if effective_mode == "remote":
-        relay_url = get_relay_url()
-        if not relay_url:
-            raise RuntimeError(
-                "Remote mode requires SCITEX_AUDIO_RELAY_URL or "
-                "SCITEX_AUDIO_RELAY_HOST to be set"
-            )
-        result = relay_speak(
-            text=text,
-            backend=backend,
-            voice=voice,
-            rate=rate or 150,
-            speed=speed or 1.5,
-            play=play,
-            **kwargs,
-        )
-        return result.get("saved_to") if result.get("success") else None
-
-    # Auto mode: try remote first, fall back to local
-    if effective_mode == "auto":
-        relay_url = get_relay_url()
-        if relay_url and is_relay_available():
-            try:
-                result = relay_speak(
-                    text=text,
-                    backend=backend,
-                    voice=voice,
-                    rate=rate or 150,
-                    speed=speed or 1.5,
-                    play=play,
-                    **kwargs,
-                )
-                if result.get("success"):
-                    return result.get("saved_to")
-            except Exception:
-                pass  # Fall through to local
-
-    # Local mode (or fallback from auto)
-    return _speak_local(
-        text=text,
-        backend=backend,
-        voice=voice,
-        play=play,
-        output_path=output_path,
-        fallback=fallback,
-        **kwargs,
-    )
+# Import speak function from refactored module
+from ._speak import speak
 
 
 def start_mcp_server():
@@ -457,4 +238,16 @@ def start_mcp_server():
     main()
 
 
+# Clean up internal imports from public namespace
+def _cleanup_namespace():
+    import sys
+    _module = sys.modules[__name__]
+    for _name in ["annotations", "engines"]:
+        if hasattr(_module, _name):
+            delattr(_module, _name)
+
+_cleanup_namespace()
+del _cleanup_namespace
+
+
 # EOF