scitex 2.16.2__py3-none-any.whl → 2.17.3__py3-none-any.whl

scitex/_mcp_tools/verify.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-02-01 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/_mcp_tools/verify.py
+"""Verify module tools for FastMCP unified server."""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+
+def _json(data: dict) -> str:
+    return json.dumps(data, indent=2, default=str)
+
+
+def register_verify_tools(mcp) -> None:
+    """Register verify tools with FastMCP server."""
+
+    @mcp.tool()
+    async def verify_list(
+        limit: int = 50,
+        status_filter: Optional[str] = None,
+    ) -> str:
+        """[verify] List all tracked runs with verification status.
+
+        Parameters
+        ----------
+        limit : int, optional
+            Maximum number of runs to return (default: 50)
+        status_filter : str, optional
+            Filter by status: 'success', 'failed', 'running', or None for all
+
+        Returns
+        -------
+        str
+            JSON with list of runs and their verification status
+        """
+        from scitex.verify import get_db, verify_run
+
+        db = get_db()
+        runs = db.list_runs(status=status_filter, limit=limit)
+
+        results = []
+        for run in runs:
+            verification = verify_run(run["session_id"])
+            results.append(
+                {
+                    "session_id": run["session_id"],
+                    "script_path": run.get("script_path"),
+                    "db_status": run.get("status"),
+                    "verification_status": verification.status.value,
+                    "is_verified": verification.is_verified,
+                    "started_at": run.get("started_at"),
+                    "finished_at": run.get("finished_at"),
+                }
+            )
+
+        return _json(
+            {
+                "count": len(results),
+                "runs": results,
+            }
+        )
+
+    @mcp.tool()
+    async def verify_run(
+        session_or_path: str,
+    ) -> str:
+        """[verify] Verify a specific session run by checking all file hashes.
+
+        Parameters
+        ----------
+        session_or_path : str
+            Session ID (e.g., '2025Y-11M-18D-09h12m03s_HmH5') or
+            path to a file to find its associated session
+
+        Returns
+        -------
+        str
+            JSON with verification results including file-level details
+        """
+        from pathlib import Path
+
+        from scitex.verify import get_db
+        from scitex.verify import verify_run as do_verify_run
+
+        db = get_db()
+
+        # Check if it's a file path
+        path = Path(session_or_path)
+        if path.exists():
+            sessions = db.find_session_by_file(str(path.resolve()), role="output")
+            if not sessions:
+                sessions = db.find_session_by_file(str(path.resolve()), role="input")
+
+            if not sessions:
+                return _json(
+                    {
+                        "error": f"No session found for file: {session_or_path}",
+                        "session_id": None,
+                    }
+                )
+            session_id = sessions[0]
+        else:
+            session_id = session_or_path
+
+        verification = do_verify_run(session_id)
+
+        return _json(
+            {
+                "session_id": verification.session_id,
+                "script_path": verification.script_path,
+                "status": verification.status.value,
+                "is_verified": verification.is_verified,
+                "combined_hash_expected": verification.combined_hash_expected,
+                "files": [
+                    {
+                        "path": f.path,
+                        "role": f.role,
+                        "status": f.status.value,
+                        "expected_hash": f.expected_hash,
+                        "current_hash": f.current_hash,
+                        "is_verified": f.is_verified,
+                    }
+                    for f in verification.files
+                ],
+                "mismatched_count": len(verification.mismatched_files),
+                "missing_count": len(verification.missing_files),
+            }
+        )
+
+    @mcp.tool()
+    async def verify_chain(
+        target_file: str,
+    ) -> str:
+        """[verify] Verify the dependency chain for a target file.
+
+        Traces back through all sessions that contributed to producing
+        the target file and verifies each one.
+
+        Parameters
+        ----------
+        target_file : str
+            Path to the target file to trace
+
+        Returns
+        -------
+        str
+            JSON with chain verification results
+        """
+        from pathlib import Path
+
+        from scitex.verify import verify_chain as do_verify_chain
+
+        path = Path(target_file)
+        if not path.exists():
+            return _json(
+                {
+                    "error": f"File not found: {target_file}",
+                    "target_file": target_file,
+                }
+            )
+
+        chain = do_verify_chain(str(path.resolve()))
+
+        return _json(
+            {
+                "target_file": chain.target_file,
+                "status": chain.status.value,
+                "is_verified": chain.is_verified,
+                "chain_length": len(chain.runs),
+                "failed_runs_count": len(chain.failed_runs),
+                "runs": [
+                    {
+                        "session_id": r.session_id,
+                        "script_path": r.script_path,
+                        "status": r.status.value,
+                        "is_verified": r.is_verified,
+                        "mismatched_files": [f.path for f in r.mismatched_files],
+                        "missing_files": [f.path for f in r.missing_files],
+                    }
+                    for r in chain.runs
+                ],
+            }
+        )
+
+    @mcp.tool()
+    async def verify_status() -> str:
+        """[verify] Show verification status summary (like git status).
+
+        Returns
+        -------
+        str
+            JSON with counts of verified, mismatched, and missing runs
+        """
+        from scitex.verify import get_status
+
+        status = get_status()
+        return _json(status)
+
+    @mcp.tool()
+    async def verify_stats() -> str:
+        """[verify] Show verification database statistics.
+
+        Returns
+        -------
+        str
+            JSON with database statistics
+        """
+        from scitex.verify import get_db
+
+        db = get_db()
+        stats = db.stats()
+        return _json(stats)
+
+    @mcp.tool()
+    async def verify_mermaid(
+        session_id: Optional[str] = None,
+        target_file: Optional[str] = None,
+    ) -> str:
+        """[verify] Generate Mermaid diagram for verification DAG.
+
+        Parameters
+        ----------
+        session_id : str, optional
+            Start from this session
+        target_file : str, optional
+            Start from session that produced this file
+
+        Returns
+        -------
+        str
+            Mermaid diagram code
+        """
+        from pathlib import Path
+
+        from scitex.verify import generate_mermaid_dag
+
+        if target_file:
+            target_file = str(Path(target_file).resolve())
+
+        mermaid_code = generate_mermaid_dag(
+            session_id=session_id,
+            target_file=target_file,
+        )
+
+        return _json(
+            {
+                "mermaid": mermaid_code,
+                "session_id": session_id,
+                "target_file": target_file,
+            }
+        )
+
+
+# EOF

scitex/audio/_audio_check.py

@@ -7,9 +7,75 @@ before attempting to play audio.
 
 from __future__ import annotations
 
+import os
+import shutil
 import subprocess
 
-__all__ = ["check_local_audio_available"]
+__all__ = ["check_local_audio_available", "check_wsl_windows_audio_available"]
+
+
+def check_wsl_windows_audio_available() -> dict:
+    """Check if WSL Windows audio playback is available.
+
+    In WSL, audio can be played via PowerShell's System.Media.SoundPlayer
+    even when PulseAudio is unavailable or SUSPENDED.
+
+    Returns
+    -------
+        dict with keys:
+        - available: bool - True if Windows playback via PowerShell is possible
+        - reason: str - Human-readable explanation
+    """
+    if not os.path.exists("/mnt/c/Windows"):
+        return {"available": False, "reason": "Not running in WSL"}
+
+    if not shutil.which("powershell.exe"):
+        return {"available": False, "reason": "powershell.exe not found in PATH"}
+
+    return {
+        "available": True,
+        "reason": "WSL Windows playback available via PowerShell",
+    }
+
+
+def _try_wsl_fallback(
+    state: str, reason: str, pulseaudio_state: str | None = None
+) -> dict:
+    """Try WSL Windows fallback, return appropriate result dict."""
+    wsl_check = check_wsl_windows_audio_available()
+    if wsl_check["available"]:
+        result = {
+            "available": True,
+            "state": "WSL_WINDOWS",
+            "reason": wsl_check["reason"],
+            "fallback": "windows_powershell",
+        }
+        if pulseaudio_state:
+            result["pulseaudio_state"] = pulseaudio_state
+        return result
+    return {"available": False, "state": state, "reason": reason}
+
+
+def _parse_pulseaudio_state(output: str) -> dict:
+    """Parse PulseAudio sink state from pactl output."""
+    for line in output.strip().split("\n"):
+        parts = line.split("\t")
+        if len(parts) >= 5:
+            state = parts[4]
+            if state == "SUSPENDED":
+                return _try_wsl_fallback(
+                    "SUSPENDED",
+                    "Audio sink SUSPENDED (no active output device)",
+                    pulseaudio_state="SUSPENDED",
+                )
+            if state in ("RUNNING", "IDLE"):
+                return {
+                    "available": True,
+                    "state": state,
+                    "reason": f"Audio sink is {state}",
+                }
+
+    return _try_wsl_fallback("UNKNOWN", "Could not determine sink state")
 
 
 def check_local_audio_available() -> dict:
@@ -18,11 +84,15 @@ def check_local_audio_available() -> dict:
     Checks PulseAudio sink state to determine if audio can actually be heard.
     On NAS or headless servers, the sink is typically SUSPENDED.
 
-    Returns:
+    In WSL environments, also checks for Windows playback fallback via PowerShell.
+
+    Returns
+    -------
         dict with keys:
         - available: bool - True if local audio output is likely to work
         - state: str - 'RUNNING', 'IDLE', 'SUSPENDED', 'NO_SINK', etc.
         - reason: str - Human-readable explanation
+        - fallback: str (optional) - Fallback method if primary unavailable
     """
     try:
         result = subprocess.run(
@@ -32,45 +102,22 @@ def check_local_audio_available() -> dict:
             timeout=5,
         )
         if result.returncode != 0:
-            return {
-                "available": False,
-                "state": "NO_PACTL",
-                "reason": "PulseAudio not available",
-            }
+            return _try_wsl_fallback("NO_PACTL", "PulseAudio not available")
 
         if not result.stdout.strip():
-            return {
-                "available": False,
-                "state": "NO_SINK",
-                "reason": "No audio sinks found",
-            }
+            return _try_wsl_fallback("NO_SINK", "No audio sinks found")
 
-        # Parse sink state (format: id\tname\tmodule\tformat\tstate)
-        for line in result.stdout.strip().split("\n"):
-            parts = line.split("\t")
-            if len(parts) >= 5:
-                state = parts[4]
-                if state == "SUSPENDED":
-                    return {
-                        "available": False,
-                        "state": "SUSPENDED",
-                        "reason": "Audio sink SUSPENDED (no active output device)",
-                    }
-                elif state in ("RUNNING", "IDLE"):
-                    return {
-                        "available": True,
-                        "state": state,
-                        "reason": f"Audio sink is {state}",
-                    }
-
-        return {
-            "available": False,
-            "state": "UNKNOWN",
-            "reason": "Could not determine sink state",
-        }
+        return _parse_pulseaudio_state(result.stdout)
 
     except FileNotFoundError:
-        # No pactl - might be macOS or minimal system, assume available
+        wsl_check = check_wsl_windows_audio_available()
+        if wsl_check["available"]:
+            return {
+                "available": True,
+                "state": "WSL_WINDOWS",
+                "reason": wsl_check["reason"],
+                "fallback": "windows_powershell",
+            }
         return {
             "available": True,
             "state": "NO_PACTL",
@@ -83,11 +130,7 @@ def check_local_audio_available() -> dict:
             "reason": "PulseAudio query timed out",
         }
     except Exception as e:
-        return {
-            "available": False,
-            "state": "ERROR",
-            "reason": str(e),
-        }
+        return {"available": False, "state": "ERROR", "reason": str(e)}
 
 
 # EOF

scitex/cli/capture.py

@@ -406,32 +406,55 @@ def doctor():
 
 
 @mcp.command("list-tools")
-def list_tools():
-    """
-    List available MCP tools
-
-    \b
-    Example:
-      scitex capture mcp list-tools
-    """
+@click.option("-v", "--verbose", count=True, help="-v params, -vv returns")
+def list_tools(verbose):
+    """List available MCP tools for capture."""
     click.secho("Capture MCP Tools", fg="cyan", bold=True)
     click.echo()
+    # (name, desc, params, returns)
     tools = [
-        ("capture_capture_screenshot", "Capture screenshot"),
-        ("capture_capture_window", "Capture specific window"),
-        ("capture_start_monitoring", "Start continuous capture"),
-        ("capture_stop_monitoring", "Stop monitoring"),
-        ("capture_get_monitoring_status", "Get monitoring status"),
-        ("capture_analyze_screenshot", "Analyze screenshot for errors"),
-        ("capture_list_recent_screenshots", "List recent screenshots"),
-        ("capture_clear_cache", "Clear screenshot cache"),
-        ("capture_create_gif", "Create animated GIF"),
-        ("capture_list_sessions", "List monitoring sessions"),
-        ("capture_get_info", "Get monitor/window info"),
-        ("capture_list_windows", "List visible windows"),
+        (
+            "capture_screenshot",
+            "Capture screenshot",
+            "output_path=None, monitor=0",
+            "str",
+        ),
+        (
+            "capture_window",
+            "Capture specific window",
+            "window_id: str, output=None",
+            "str",
+        ),
+        (
+            "start_monitoring",
+            "Start continuous capture",
+            "interval=5.0, monitor=0",
+            "str",
+        ),
+        ("stop_monitoring", "Stop monitoring", "session_id=None", "str"),
+        ("get_monitoring_status", "Get monitoring status", "", "JSON"),
+        (
+            "analyze_screenshot",
+            "Analyze screenshot for errors",
+            "image_path: str",
+            "JSON",
+        ),
+        ("list_recent_screenshots", "List recent screenshots", "limit=10", "JSON"),
+        ("clear_cache", "Clear screenshot cache", "older_than_hours=24", "JSON"),
+        ("create_gif", "Create animated GIF", "session_id: str, output=None", "str"),
+        ("list_sessions", "List monitoring sessions", "", "JSON"),
+        ("get_info", "Get monitor/window info", "", "JSON"),
+        ("list_windows", "List visible windows", "", "JSON"),
     ]
-    for name, desc in tools:
-        click.echo(f"  {name}: {desc}")
+    for name, desc, params, returns in tools:
+        click.secho(f"  capture_{name}", fg="green", bold=True, nl=False)
+        click.echo(f": {desc}")
+        if verbose >= 1 and params:
+            click.echo(f"    params: {params}")
+        if verbose >= 2:
+            click.echo(f"    returns: {returns}")
+        if verbose >= 1:
+            click.echo()
 
 
 @capture.command("list-python-apis")