scitex 2.14.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

@@ -27,6 +27,8 @@ 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
@@ -46,75 +48,77 @@ Add to `~/.claude/mcp.json`:
 }
 ```
 
-### Remote Audio (SSH tunnel)
+### Remote Audio (HTTP Relay)
 
-Enable remote agents to play audio on local speakers.
+Enable remote agents to play audio on local speakers using a simple HTTP relay.
 
 **Architecture:**
 ```
 ┌─────────────────────────┐              ┌─────────────────────────┐
 │  Remote (e.g., NAS)     │              │  Local (WSL/Windows)    │
 │                         │              │                         │
-│  Claude Agent ──────────┼─ SSH ───────▶│  scitex audio serve     │
-│  connects to            │ RemoteForward│  -t sse --port 8084     │
-│  localhost:8084         │              │         │               │
-│                         │              │         ▼               │
+│  Claude Agent uses      │              │  scitex audio relay     │
+│  audio_speak_relay ─────┼─ SSH ───────▶│  --port 31293           │
+│                         │ Reverse      │         │               │
+│  localhost:31293        │ Tunnel       │         ▼               │
 │                         │              │     🔊 Speakers         │
 └─────────────────────────┘              └─────────────────────────┘
 ```
 
-**Step 1: Local machine - Start audio server**
+**Step 1: Local machine - Start relay server**
 ```bash
-scitex audio serve -t sse --port 8084
+scitex audio relay --port 31293
 ```
 
-**Step 2: SSH config - Add RemoteForward**
+**Step 2: SSH with reverse tunnel**
+```bash
+ssh -R 31293:localhost:31293 remote-server
+```
 
-In `~/.ssh/config` (on local machine):
+Or add to `~/.ssh/config`:
 ```
 Host nas
   HostName 192.168.x.x
   User youruser
-  RemoteForward 8084 127.0.0.1:8084  # Audio: remote -> local speakers
+  RemoteForward 31293 127.0.0.1:31293
 ```
 
-**Step 3: Remote machine - MCP config**
+**Step 3: Remote agent uses relay**
 
-On remote machine, add to `~/.claude/mcp.json`:
-```json
-{
-  "mcpServers": {
-    "scitex-audio-remote": {
-      "type": "sse",
-      "url": "http://localhost:8084/sse"
-    }
-  }
-}
-```
+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)
 
-**Step 4: Connect via SSH**
-```bash
-ssh nas  # RemoteForward creates tunnel automatically
-```
+### Environment Variables
 
-Now Claude agents on the remote machine can use `mcp__scitex-audio-remote__speak` to play audio on your local speakers.
+| 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 8084` | Remote agents via SSH |
-| http | `scitex audio serve -t http --port 8084` | HTTP clients |
+| 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 |
 
-### Tools
+### MCP Tools
 
 | Tool | Description |
 |------|-------------|
-| `speak` | Text to speech (supports `rate`, `speed` params) |
-| `list_backends` | Show available backends |
-| `check_audio_status` | Check WSL audio connectivity |
-| `announce_context` | Announce current directory and git branch |
+| `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
 
@@ -126,4 +130,4 @@ Now Claude agents on the remote machine can use `mcp__scitex-audio-remote__speak
 
 ## Cross-Process Locking
 
-The MCP 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.
+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
@@ -145,8 +145,8 @@ __all__ = [
     "FALLBACK_ORDER",
 ]
 
-# Fallback order: pyttsx3 (offline/free) -> gtts (free) -> elevenlabs (paid)
-FALLBACK_ORDER = ["pyttsx3", "gtts", "elevenlabs"]
+# Fallback order: elevenlabs (best quality) -> gtts (free) -> pyttsx3 (offline)
+FALLBACK_ORDER = ["elevenlabs", "gtts", "pyttsx3"]
 
 
 def available_backends() -> List[str]:
@@ -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,6 +331,124 @@ 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."""
     from .mcp_server import main