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

scitex/verify/_tracker.py

@@ -0,0 +1,330 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-02-01 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/verify/_tracker.py
+"""Session tracker for automatic verification."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+from ._db import get_db
+from ._hash import combine_hashes, hash_file
+
+
+class SessionTracker:
+    """
+    Track inputs/outputs during a session for verification.
+
+    Automatically records file hashes when files are loaded or saved
+    through stx.io, and stores them in the verification database.
+
+    Examples
+    --------
+    >>> tracker = SessionTracker("2025Y-11M-18D-09h12m03s_HmH5")
+    >>> tracker.record_input("data.csv")
+    >>> tracker.record_output("result.png")
+    >>> tracker.finalize()
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        script_path: Optional[str] = None,
+        parent_session: Optional[str] = None,
+    ):
+        """
+        Initialize a session tracker.
+
+        Parameters
+        ----------
+        session_id : str
+            Unique session identifier
+        script_path : str, optional
+            Path to the script being run
+        parent_session : str, optional
+            Parent session ID for chain tracking
+        """
+        self.session_id = session_id
+        self.script_path = script_path
+        self.parent_session = parent_session
+
+        self._inputs: Dict[str, str] = {}
+        self._outputs: Dict[str, str] = {}
+        self._script_hash: Optional[str] = None
+        self._finalized = False
+
+        self._db = get_db()
+
+        # Compute script hash if provided
+        if script_path and Path(script_path).exists():
+            self._script_hash = hash_file(script_path)
+
+        # Register run in database
+        self._db.add_run(
+            session_id=session_id,
+            script_path=script_path or "",
+            script_hash=self._script_hash,
+            parent_session=parent_session,
+        )
+
+    def record_input(
+        self,
+        path: Union[str, Path],
+        track: bool = True,
+    ) -> Optional[str]:
+        """
+        Record a file as an input.
+
+        Parameters
+        ----------
+        path : str or Path
+            Path to the input file
+        track : bool, optional
+            Whether to track this file (default: True)
+
+        Returns
+        -------
+        str or None
+            Hash of the file, or None if not tracked
+        """
+        if not track or self._finalized:
+            return None
+
+        path = Path(path)
+        if not path.exists():
+            return None
+
+        path_str = str(path.resolve())
+        if path_str not in self._inputs:
+            file_hash = hash_file(path)
+            self._inputs[path_str] = file_hash
+            self._db.add_file_hash(
+                session_id=self.session_id,
+                file_path=path_str,
+                hash_value=file_hash,
+                role="input",
+            )
+
+            # Auto-link parent: if this file was created by another session,
+            # set that session as our parent (first one found)
+            if self.parent_session is None:
+                producer_sessions = self._db.find_session_by_file(
+                    path_str, role="output"
+                )
+                if producer_sessions:
+                    self.parent_session = producer_sessions[0]
+                    self._db.set_parent(self.session_id, self.parent_session)
+
+        return self._inputs[path_str]
+
+    def record_output(
+        self,
+        path: Union[str, Path],
+        track: bool = True,
+    ) -> Optional[str]:
+        """
+        Record a file as an output.
+
+        Parameters
+        ----------
+        path : str or Path
+            Path to the output file
+        track : bool, optional
+            Whether to track this file (default: True)
+
+        Returns
+        -------
+        str or None
+            Hash of the file, or None if not tracked
+        """
+        if not track or self._finalized:
+            return None
+
+        path = Path(path)
+        if not path.exists():
+            return None
+
+        path_str = str(path.resolve())
+        file_hash = hash_file(path)
+        self._outputs[path_str] = file_hash
+        self._db.add_file_hash(
+            session_id=self.session_id,
+            file_path=path_str,
+            hash_value=file_hash,
+            role="output",
+        )
+
+        return file_hash
+
+    def record_inputs(
+        self,
+        paths: List[Union[str, Path]],
+        track: bool = True,
+    ) -> Dict[str, str]:
+        """Record multiple input files."""
+        result = {}
+        for path in paths:
+            h = self.record_input(path, track=track)
+            if h:
+                result[str(path)] = h
+        return result
+
+    def record_outputs(
+        self,
+        paths: List[Union[str, Path]],
+        track: bool = True,
+    ) -> Dict[str, str]:
+        """Record multiple output files."""
+        result = {}
+        for path in paths:
+            h = self.record_output(path, track=track)
+            if h:
+                result[str(path)] = h
+        return result
+
+    @property
+    def inputs(self) -> Dict[str, str]:
+        """Get all recorded inputs."""
+        return self._inputs.copy()
+
+    @property
+    def outputs(self) -> Dict[str, str]:
+        """Get all recorded outputs."""
+        return self._outputs.copy()
+
+    @property
+    def combined_hash(self) -> str:
+        """Get combined hash of all inputs, script, and outputs."""
+        all_hashes = {}
+        all_hashes.update({f"input:{k}": v for k, v in self._inputs.items()})
+        if self._script_hash:
+            all_hashes["script"] = self._script_hash
+        all_hashes.update({f"output:{k}": v for k, v in self._outputs.items()})
+        return combine_hashes(all_hashes)
+
+    def finalize(
+        self,
+        status: str = "success",
+        exit_code: int = 0,
+    ) -> Dict[str, Any]:
+        """
+        Finalize the session tracking.
+
+        Parameters
+        ----------
+        status : str, optional
+            Final status (success, failed, error)
+        exit_code : int, optional
+            Exit code of the script
+
+        Returns
+        -------
+        dict
+            Summary of the tracked session
+        """
+        if self._finalized:
+            return self.summary()
+
+        combined = self.combined_hash
+
+        self._db.finish_run(
+            session_id=self.session_id,
+            status=status,
+            exit_code=exit_code,
+            combined_hash=combined,
+        )
+
+        self._finalized = True
+
+        return self.summary()
+
+    def summary(self) -> Dict[str, Any]:
+        """Get summary of tracked files."""
+        return {
+            "session_id": self.session_id,
+            "script_path": self.script_path,
+            "script_hash": self._script_hash,
+            "parent_session": self.parent_session,
+            "inputs": self._inputs,
+            "outputs": self._outputs,
+            "combined_hash": self.combined_hash,
+            "finalized": self._finalized,
+        }
+
+
+# Global tracker for current session
+_CURRENT_TRACKER: Optional[SessionTracker] = None
+
+
+def get_tracker() -> Optional[SessionTracker]:
+    """Get the current session tracker."""
+    return _CURRENT_TRACKER
+
+
+def set_tracker(tracker: Optional[SessionTracker]) -> None:
+    """Set the current session tracker."""
+    global _CURRENT_TRACKER
+    _CURRENT_TRACKER = tracker
+
+
+def start_tracking(
+    session_id: str,
+    script_path: Optional[str] = None,
+    parent_session: Optional[str] = None,
+) -> SessionTracker:
+    """
+    Start tracking a new session.
+
+    Parameters
+    ----------
+    session_id : str
+        Unique session identifier
+    script_path : str, optional
+        Path to the script being run
+    parent_session : str, optional
+        Parent session ID for chain tracking
+
+    Returns
+    -------
+    SessionTracker
+        The new tracker instance
+    """
+    tracker = SessionTracker(
+        session_id=session_id,
+        script_path=script_path,
+        parent_session=parent_session,
+    )
+    set_tracker(tracker)
+    return tracker
+
+
+def stop_tracking(
+    status: str = "success",
+    exit_code: int = 0,
+) -> Optional[Dict[str, Any]]:
+    """
+    Stop tracking the current session.
+
+    Parameters
+    ----------
+    status : str, optional
+        Final status
+    exit_code : int, optional
+        Exit code
+
+    Returns
+    -------
+    dict or None
+        Summary of the tracked session, or None if no tracker
+    """
+    tracker = get_tracker()
+    if tracker is None:
+        return None
+
+    result = tracker.finalize(status=status, exit_code=exit_code)
+    set_tracker(None)
+    return result
+
+
+# EOF

scitex/verify/_visualize.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-02-01 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/verify/_visualize.py
+"""Visualization utilities for verification status.
+
+This module re-exports from the _viz subpackage for backward compatibility.
+
+Provides:
+- Terminal output with colored status icons
+- Mermaid DAG generation
+- Interactive HTML visualization
+- PNG/SVG export via scitex.diagram
+"""
+
+from ._viz import (
+    Colors,
+    VerificationLevel,
+    format_chain_verification,
+    format_list,
+    format_run_detailed,
+    format_run_verification,
+    format_status,
+    generate_html_dag,
+    generate_mermaid_dag,
+    generate_plotly_dag,
+    print_verification_summary,
+    render_dag,
+    render_plotly_dag,
+)
+
+__all__ = [
+    "Colors",
+    "VerificationLevel",
+    "format_run_verification",
+    "format_run_detailed",
+    "format_chain_verification",
+    "format_status",
+    "format_list",
+    "generate_mermaid_dag",
+    "generate_html_dag",
+    "generate_plotly_dag",
+    "render_dag",
+    "render_plotly_dag",
+    "print_verification_summary",
+]
+
+
+# EOF

scitex/verify/_viz/__init__.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-02-01 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/verify/_viz/__init__.py
+"""Visualization subpackage for verification status.
+
+Provides multiple visualization backends:
+- Terminal: Colored text output with status icons
+- Mermaid: Text-based diagrams for docs/GitHub
+- HTML: Interactive web visualization
+- Plotly: Interactive Python-based visualization (optional)
+"""
+
+from ._colors import Colors, VerificationLevel
+from ._format import (
+    format_chain_verification,
+    format_list,
+    format_run_detailed,
+    format_run_verification,
+    format_status,
+)
+from ._mermaid import generate_html_dag, generate_mermaid_dag, render_dag
+from ._utils import print_verification_summary
+
+# Optional Plotly support
+try:
+    from ._plotly import generate_plotly_dag, render_plotly_dag
+
+    _HAS_PLOTLY = True
+except ImportError:
+    _HAS_PLOTLY = False
+
+    def generate_plotly_dag(*args, **kwargs):
+        raise ImportError("plotly required: pip install plotly")
+
+    def render_plotly_dag(*args, **kwargs):
+        raise ImportError("plotly required: pip install plotly")
+
+
+__all__ = [
+    "Colors",
+    "VerificationLevel",
+    "format_run_verification",
+    "format_chain_verification",
+    "format_status",
+    "format_list",
+    "format_run_detailed",
+    "generate_mermaid_dag",
+    "generate_html_dag",
+    "render_dag",
+    "print_verification_summary",
+    "generate_plotly_dag",
+    "render_plotly_dag",
+]
+
+
+# EOF

scitex/verify/_viz/_colors.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-02-01 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/verify/_viz/_colors.py
+"""Color constants and status icons for verification visualization."""
+
+from __future__ import annotations
+
+from .._chain import VerificationStatus
+
+
+class Colors:
+    """ANSI color codes for terminal output."""
+
+    GREEN = "\033[92m"
+    RED = "\033[91m"
+    YELLOW = "\033[93m"
+    CYAN = "\033[96m"
+    GRAY = "\033[90m"
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+
+
+class VerificationLevel:
+    """Verification level for display badges."""
+
+    CACHE = "cache"  # verified-by-cache (fast hash comparison) - 🟢
+    SCRATCH = "scratch"  # verified-from-scratch (re-executed) - 🟢🟢
+
+
+def status_icon(
+    status: VerificationStatus,
+    level: str = VerificationLevel.CACHE,
+) -> str:
+    """
+    Get colored icon for verification status.
+
+    Parameters
+    ----------
+    status : VerificationStatus
+        The verification status
+    level : str
+        Verification level: 'cache' (🟢) or 'scratch' (🟢🟢)
+
+    Returns
+    -------
+    str
+        Colored status icon
+    """
+    if level == VerificationLevel.SCRATCH and status == VerificationStatus.VERIFIED:
+        return f"{Colors.GREEN}●●{Colors.RESET}"
+
+    icons = {
+        VerificationStatus.VERIFIED: f"{Colors.GREEN}●{Colors.RESET}",
+        VerificationStatus.MISMATCH: f"{Colors.RED}●{Colors.RESET}",
+        VerificationStatus.MISSING: f"{Colors.YELLOW}○{Colors.RESET}",
+        VerificationStatus.UNKNOWN: f"{Colors.CYAN}?{Colors.RESET}",
+    }
+    return icons.get(status, "?")
+
+
+def status_text(status: VerificationStatus) -> str:
+    """
+    Get colored text for verification status.
+
+    Parameters
+    ----------
+    status : VerificationStatus
+        The verification status
+
+    Returns
+    -------
+    str
+        Colored status text
+    """
+    texts = {
+        VerificationStatus.VERIFIED: f"{Colors.GREEN}verified{Colors.RESET}",
+        VerificationStatus.MISMATCH: f"{Colors.RED}mismatch{Colors.RESET}",
+        VerificationStatus.MISSING: f"{Colors.YELLOW}missing{Colors.RESET}",
+        VerificationStatus.UNKNOWN: f"{Colors.CYAN}unknown{Colors.RESET}",
+    }
+    return texts.get(status, "unknown")
+
+
+# EOF