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

scitex/ai/classification/reporters/_mixins/_storage.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/ai/classification/reporters/_mixins/_storage.py
+
+"""
+Storage mixin for classification reporter.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import pandas as pd
+
+from scitex.logging import getLogger
+
+from ..reporter_utils.storage import save_metric
+from ._constants import (
+    FILENAME_PATTERNS,
+    FOLD_DIR_PREFIX_PATTERN,
+    FOLD_FILE_PREFIX_PATTERN,
+)
+
+logger = getLogger(__name__)
+
+
+class StorageMixin:
+    """Mixin providing storage methods."""
+
+    def _save_fold_metrics(
+        self, metrics: Dict[str, Any], fold: int, labels: List[str]
+    ) -> None:
+        """Save metrics for a specific fold in shallow directory structure."""
+        fold_dir = FOLD_DIR_PREFIX_PATTERN.format(fold=fold)
+
+        balanced_acc = self._extract_metric_value(metrics.get("balanced-accuracy"))
+        mcc_value = self._extract_metric_value(metrics.get("mcc"))
+        roc_auc_value = self._extract_metric_value(metrics.get("roc-auc"))
+        pr_auc_value = self._extract_metric_value(metrics.get("pr-auc"))
+
+        for metric_name, metric_value in metrics.items():
+            if isinstance(metric_value, dict) and "value" in metric_value:
+                actual_value = metric_value["value"]
+            else:
+                actual_value = metric_value
+
+            if metric_name == "confusion_matrix":
+                self._save_confusion_matrix(
+                    actual_value, labels, fold, fold_dir, balanced_acc
+                )
+            elif metric_name == "classification_report":
+                self._save_classification_report(actual_value, fold, fold_dir)
+            elif metric_name == "balanced-accuracy" and balanced_acc is not None:
+                self._save_scalar_metric(
+                    actual_value, "balanced-accuracy", balanced_acc, fold, fold_dir
+                )
+            elif metric_name == "mcc" and mcc_value is not None:
+                self._save_scalar_metric(actual_value, "mcc", mcc_value, fold, fold_dir)
+            elif metric_name == "roc-auc" and roc_auc_value is not None:
+                self._save_scalar_metric(
+                    actual_value, "roc-auc", roc_auc_value, fold, fold_dir
+                )
+            elif metric_name == "pr-auc" and pr_auc_value is not None:
+                self._save_scalar_metric(
+                    actual_value, "pr-auc", pr_auc_value, fold, fold_dir
+                )
+
+    def _save_confusion_matrix(
+        self, actual_value, labels, fold, fold_dir, balanced_acc
+    ):
+        """Save confusion matrix as CSV."""
+        try:
+            if isinstance(actual_value, pd.DataFrame):
+                cm_df = actual_value.copy()
+                cm_df.index = [f"True_{label}" for label in labels]
+                cm_df.columns = [f"Pred_{label}" for label in labels]
+            else:
+                cm_df = pd.DataFrame(
+                    actual_value,
+                    index=[f"True_{label}" for label in labels],
+                    columns=[f"Pred_{label}" for label in labels],
+                )
+        except Exception as e:
+            logger.error(f"Error formatting confusion matrix: {e}")
+            return
+
+        if balanced_acc is not None:
+            cm_filename = FILENAME_PATTERNS["confusion_matrix_csv"].format(
+                fold=fold, bacc=balanced_acc
+            )
+        else:
+            cm_filename = FILENAME_PATTERNS["confusion_matrix_csv_no_bacc"].format(
+                fold=fold
+            )
+
+        self.storage.save(cm_df, f"{fold_dir}/{cm_filename}", index=True)
+
+    def _save_classification_report(self, actual_value, fold, fold_dir):
+        """Save classification report."""
+        report_filename = FILENAME_PATTERNS["classification_report"].format(fold=fold)
+
+        if isinstance(actual_value, pd.DataFrame):
+            report_df = actual_value.reset_index()
+            report_df = report_df.rename(columns={"index": "class"})
+            self.storage.save(report_df, f"{fold_dir}/{report_filename}")
+        elif isinstance(actual_value, dict):
+            try:
+                report_df = pd.DataFrame(actual_value).transpose()
+                self.storage.save(report_df, f"{fold_dir}/{report_filename}")
+            except Exception:
+                report_filename = FILENAME_PATTERNS[
+                    "classification_report_json"
+                ].format(fold=fold)
+                self.storage.save(actual_value, f"{fold_dir}/{report_filename}")
+        else:
+            report_filename = FILENAME_PATTERNS["classification_report_txt"].format(
+                fold=fold
+            )
+            self.storage.save(actual_value, f"{fold_dir}/{report_filename}")
+
+    def _save_scalar_metric(self, actual_value, metric_name, value, fold, fold_dir):
+        """Save scalar metric with value in filename."""
+        filename = FILENAME_PATTERNS["fold_metric_with_value"].format(
+            fold=fold, metric_name=metric_name, value=value
+        )
+        save_metric(
+            actual_value,
+            self.output_dir / f"{fold_dir}/{filename}",
+            fold=fold,
+            precision=self.precision,
+        )
+
+    def save(
+        self,
+        data: Any,
+        relative_path: Union[str, Path],
+        fold: Optional[int] = None,
+    ) -> Path:
+        """Save custom data with automatic fold organization and filename prefixing."""
+        if fold is not None:
+            path_obj = Path(relative_path)
+            filename = path_obj.name
+            parent = path_obj.parent
+
+            prefixed_filename = (
+                f"{FOLD_FILE_PREFIX_PATTERN.format(fold=fold)}_{filename}"
+            )
+
+            if parent and str(parent) != ".":
+                relative_path = f"{FOLD_DIR_PREFIX_PATTERN.format(fold=fold)}/{parent}/{prefixed_filename}"
+            else:
+                relative_path = (
+                    f"{FOLD_DIR_PREFIX_PATTERN.format(fold=fold)}/{prefixed_filename}"
+                )
+
+        return self.storage.save(data, relative_path)
+
+
+# EOF

scitex/audio/README.md

@@ -20,28 +20,105 @@ scitex.audio.speak("Hello", backend="pyttsx3")
 scitex.audio.stop_speech()
 ```
 
+## CLI
+
+```bash
+scitex audio speak "Hello world"
+scitex audio speak "Bonjour" --backend gtts --voice fr
+scitex audio backends       # List available backends
+scitex audio check          # Check audio status (WSL)
+scitex audio relay          # Start HTTP relay server (for remote audio)
+scitex audio serve          # Start MCP server
+```
+
 ## MCP Server
 
-Add to `~/.claude.json`:
+### Local (stdio - Claude Desktop)
+
+Add to `~/.claude/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "scitex-audio": {
-      "command": "/path/to/python",
-      "args": ["-m", "scitex.audio", "--mcp"]
+      "command": "python",
+      "args": ["-m", "scitex.audio"]
     }
   }
 }
 ```
 
-### Tools
+### Remote Audio (HTTP Relay)
+
+Enable remote agents to play audio on local speakers using a simple HTTP relay.
+
+**Architecture:**
+```
+┌─────────────────────────┐              ┌─────────────────────────┐
+│  Remote (e.g., NAS)     │              │  Local (WSL/Windows)    │
+│                         │              │                         │
+│  Claude Agent uses      │              │  scitex audio relay     │
+│  audio_speak_relay ─────┼─ SSH ───────▶│  --port 31293           │
+│                         │ Reverse      │         │               │
+│  localhost:31293        │ Tunnel       │         ▼               │
+│                         │              │     🔊 Speakers         │
+└─────────────────────────┘              └─────────────────────────┘
+```
+
+**Step 1: Local machine - Start relay server**
+```bash
+scitex audio relay --port 31293
+```
+
+**Step 2: SSH with reverse tunnel**
+```bash
+ssh -R 31293:localhost:31293 remote-server
+```
+
+Or add to `~/.ssh/config`:
+```
+Host nas
+  HostName 192.168.x.x
+  User youruser
+  RemoteForward 31293 127.0.0.1:31293
+```
+
+**Step 3: Remote agent uses relay**
+
+The `audio_speak_relay` MCP tool auto-detects:
+1. `SCITEX_AUDIO_RELAY_URL` env var
+2. Localhost:31293 (SSH reverse tunnel)
+3. SSH_CLIENT IP (auto-detected from SSH session)
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SCITEX_AUDIO_PORT` | 31293 | Server/relay port |
+| `SCITEX_AUDIO_MODE` | auto | `local`, `remote`, or `auto` |
+| `SCITEX_AUDIO_RELAY_URL` | (auto) | Full relay URL |
+| `SCITEX_AUDIO_RELAY_HOST` | (none) | Relay host |
+| `SCITEX_AUDIO_RELAY_PORT` | 31293 | Relay port |
+
+### Server Transports
+
+| Transport | Command | Use Case |
+|-----------|---------|----------|
+| stdio | `scitex audio serve` | Claude Desktop (default) |
+| sse | `scitex audio serve -t sse --port 31293` | Remote MCP agents |
+| http | `scitex audio serve -t http --port 31293` | HTTP MCP clients |
+| relay | `scitex audio relay --port 31293` | Simple HTTP relay |
+
+### MCP Tools
 
 | Tool | Description |
 |------|-------------|
-| `speak` | Text to speech (supports `rate` param for speed) |
-| `generate_audio` | Save audio to file |
-| `list_backends` | Show available backends |
+| `audio_speak` | Text to speech (plays on server) |
+| `audio_speak_local` | TTS on server machine |
+| `audio_speak_relay` | TTS via relay (remote playback) |
+| `audio_list_backends` | Show available backends |
+| `audio_check_audio_status` | Check WSL audio connectivity |
+| `audio_announce_context` | Announce current directory and git branch |
 
 ## Backends
 
@@ -50,3 +127,7 @@ Add to `~/.claude.json`:
 | pyttsx3 | Free | No | `pip install pyttsx3` + `apt install espeak-ng` |
 | gtts | Free | Yes | `pip install gTTS` |
 | elevenlabs | Paid | Yes | `pip install elevenlabs` + API key |
+
+## Cross-Process Locking
+
+The relay server uses FIFO locking to ensure only one audio plays at a time across all Claude Code sessions. This prevents audio overlap when multiple agents are running.

scitex/audio/__init__.py

@@ -6,12 +6,12 @@
 """
 SciTeX Audio Module - Text-to-Speech with Multiple Backends
 
-Fallback order: pyttsx3 -> gtts -> elevenlabs
+Fallback order: elevenlabs -> gtts -> pyttsx3
 
 Backends:
-    - pyttsx3: System TTS (offline, free, uses espeak/SAPI5)
-    - gtts: Google TTS (free, requires internet)
     - elevenlabs: ElevenLabs (paid, high quality)
+    - gtts: Google TTS (free, requires internet)
+    - pyttsx3: System TTS (offline, free, uses espeak/SAPI5)
 
 Usage:
     import scitex
@@ -264,69 +264,20 @@ _default_tts: Optional[BaseTTS] = None
 _default_backend: Optional[str] = None
 
 
-def speak(
+def _speak_local(
     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,
     **kwargs,
 ) -> Optional[str]:
-    """Convert text to speech with automatic fallback.
-
-    Fallback order: pyttsx3 -> gtts -> elevenlabs
-
-    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).
-        **kwargs: Additional backend options.
-
-    Returns:
-        Path to audio file if output_path specified, else None.
-
-    Examples:
-        import scitex
-
-        # Simple (auto-selects with fallback)
-        scitex.audio.speak("Hello!")
-
-        # Faster speech (pyttsx3)
-        scitex.audio.speak("Hello", rate=200)
-
-        # Faster speech (gtts with pydub)
-        scitex.audio.speak("Hello", backend="gtts", speed=1.5)
-
-        # Specific backend (no fallback)
-        scitex.audio.speak("Hello", backend="pyttsx3", fallback=False)
-
-        # Different language (gTTS)
-        scitex.audio.speak("Bonjour", backend="gtts", voice="fr")
-
-        # Save to file
-        scitex.audio.speak("Test", output_path="/tmp/test.mp3")
-    """
+    """Local TTS playback (original implementation)."""
     global _default_tts, _default_backend
 
-    # Stop any previously running speech first
-    stop_speech()
-
-    # Pass rate to kwargs for pyttsx3
-    if rate is not None:
-        kwargs["rate"] = rate
-
-    # Pass speed to kwargs for gtts
-    if speed is not None:
-        kwargs["speed"] = speed
+    # 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:
@@ -364,7 +315,6 @@ def speak(
         return str(result) if result else None
     except Exception as e:
         if fallback:
-            # Try other backends
             result, used_backend, errors = _try_speak_with_fallback(
                 text=text,
                 voice=voice,
@@ -381,13 +331,130 @@ def speak(
         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,
+    )
+
+
 def start_mcp_server():
     """Start the MCP server for audio."""
-    import asyncio
-
     from .mcp_server import main
 
-    asyncio.run(main())
+    # main() is synchronous - calls mcp.run() directly
+    main()
 
 
 # EOF

scitex/audio/__main__.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/__main__.py
 # ----------------------------------------
@@ -14,8 +13,6 @@ Usage:
 """
 
 import argparse
-import asyncio
-import sys
 
 
 def main():
@@ -25,8 +22,9 @@ def main():
 
     # Global options
     parser.add_argument(
-        "--mcp", action="store_true",
-        help="Start MCP server (for Claude Code integration)"
+        "--mcp",
+        action="store_true",
+        help="Start MCP server (for Claude Code integration)",
     )
 
     subparsers = parser.add_subparsers(dest="command", help="Commands")
@@ -35,19 +33,14 @@ def main():
     speak_parser = subparsers.add_parser("speak", help="Quick text-to-speech")
     speak_parser.add_argument("text", help="Text to speak")
     speak_parser.add_argument(
-        "-b", "--backend",
+        "-b",
+        "--backend",
         choices=["pyttsx3", "gtts", "elevenlabs"],
-        help="TTS backend (auto-selects with fallback if not specified)"
-    )
-    speak_parser.add_argument(
-        "-v", "--voice", help="Voice name or language code"
-    )
-    speak_parser.add_argument(
-        "-o", "--output", help="Save to file"
-    )
-    speak_parser.add_argument(
-        "--no-play", action="store_true", help="Don't play audio"
+        help="TTS backend (auto-selects with fallback if not specified)",
     )
+    speak_parser.add_argument("-v", "--voice", help="Voice name or language code")
+    speak_parser.add_argument("-o", "--output", help="Save to file")
+    speak_parser.add_argument("--no-play", action="store_true", help="Don't play audio")
     speak_parser.add_argument(
         "--no-fallback", action="store_true", help="Disable fallback"
     )
@@ -58,9 +51,10 @@ def main():
     # List voices
     voices_parser = subparsers.add_parser("voices", help="List available voices")
     voices_parser.add_argument(
-        "-b", "--backend",
+        "-b",
+        "--backend",
         choices=["pyttsx3", "gtts", "elevenlabs"],
-        help="Backend to list voices for"
+        help="Backend to list voices for",
     )
 
     args = parser.parse_args()
@@ -68,7 +62,9 @@ def main():
     # MCP server mode
     if args.mcp:
         from .mcp_server import main as server_main
-        asyncio.run(server_main())
+
+        # server_main() is synchronous - calls mcp.run() directly
+        server_main()
         return
 
     if args.command == "speak":
@@ -84,7 +80,7 @@ def main():
         )
 
     elif args.command == "backends":
-        from . import available_backends, FALLBACK_ORDER
+        from . import FALLBACK_ORDER, available_backends
 
         backends = available_backends()
         print("Available TTS backends (in fallback order):")
@@ -99,7 +95,7 @@ def main():
             print(f"  {marker} {b}: {desc.get(b, '')} - {status}")
 
     elif args.command == "voices":
-        from . import get_tts, available_backends
+        from . import available_backends, get_tts
 
         backend = args.backend
         if not backend: