foundry-mcp 0.8.22__py3-none-any.whl

foundry_mcp/dashboard/launcher.py

@@ -0,0 +1,300 @@
+"""Dashboard launcher with subprocess management.
+
+Manages the Streamlit server as a subprocess, allowing the dashboard to be
+started and stopped from the CLI or programmatically.
+
+Uses a PID file to track the dashboard process across CLI invocations.
+"""
+
+import logging
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Global process reference (for in-process use)
+_dashboard_process: Optional[subprocess.Popen] = None
+
+
+def _get_pid_file() -> Path:
+    """Get path to the dashboard PID file."""
+    pid_dir = Path.home() / ".foundry-mcp"
+    pid_dir.mkdir(parents=True, exist_ok=True)
+    return pid_dir / "dashboard.pid"
+
+
+def _save_pid(pid: int) -> None:
+    """Save PID to file."""
+    _get_pid_file().write_text(str(pid))
+
+
+def _load_pid() -> Optional[int]:
+    """Load PID from file, return None if not found or invalid."""
+    pid_file = _get_pid_file()
+    if not pid_file.exists():
+        return None
+    try:
+        return int(pid_file.read_text().strip())
+    except (ValueError, OSError):
+        return None
+
+
+def _clear_pid() -> None:
+    """Remove the PID file."""
+    pid_file = _get_pid_file()
+    if pid_file.exists():
+        pid_file.unlink()
+
+
+def _is_process_running(pid: int) -> bool:
+    """Check if a process with given PID is running."""
+    try:
+        os.kill(pid, 0)  # Signal 0 doesn't kill, just checks existence
+        return True
+    except (OSError, ProcessLookupError):
+        return False
+
+
+def launch_dashboard(
+    host: str = "127.0.0.1",
+    port: int = 8501,
+    open_browser: bool = True,
+) -> dict:
+    """Launch the Streamlit dashboard server.
+
+    Args:
+        host: Host to bind to (default: localhost only)
+        port: Port to run on (default: 8501)
+        open_browser: Whether to open browser automatically
+
+    Returns:
+        dict with:
+            - success: bool
+            - url: Dashboard URL
+            - pid: Process ID
+            - message: Status message
+    """
+    global _dashboard_process
+
+    # Check if already running
+    status = get_dashboard_status()
+    if status.get("running"):
+        return {
+            "success": True,
+            "url": f"http://{host}:{port}",
+            "pid": status["pid"],
+            "message": "Dashboard already running",
+        }
+
+    # Path to the main Streamlit app
+    app_path = Path(__file__).parent / "app.py"
+
+    if not app_path.exists():
+        return {
+            "success": False,
+            "message": f"Dashboard app not found at {app_path}",
+        }
+
+    # Build Streamlit command
+    cmd = [
+        sys.executable,
+        "-m",
+        "streamlit",
+        "run",
+        str(app_path),
+        "--server.port",
+        str(port),
+        "--server.address",
+        host,
+        "--browser.gatherUsageStats",
+        "false",
+        "--theme.base",
+        "dark",
+    ]
+
+    if not open_browser:
+        cmd.extend(["--server.headless", "true"])
+
+    # Environment with dashboard mode flag
+    env = {
+        **os.environ,
+        "FOUNDRY_MCP_DASHBOARD_MODE": "1",
+    }
+
+    # Pass config file path to dashboard subprocess so it can find error/metrics storage
+    # If FOUNDRY_MCP_CONFIG_FILE is already set, it will be inherited from os.environ
+    # Otherwise, find and pass the config file path explicitly
+    if "FOUNDRY_MCP_CONFIG_FILE" not in env:
+        for config_name in ["foundry-mcp.toml", ".foundry-mcp.toml"]:
+            config_path = Path(config_name).resolve()
+            if config_path.exists():
+                env["FOUNDRY_MCP_CONFIG_FILE"] = str(config_path)
+                logger.debug("Passing config file to dashboard: %s", config_path)
+                break
+
+    try:
+        # Start subprocess
+        _dashboard_process = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env=env,
+        )
+
+        # Brief wait to check for immediate failures
+        time.sleep(1)
+        poll = _dashboard_process.poll()
+        if poll is not None:
+            stderr = _dashboard_process.stderr.read().decode() if _dashboard_process.stderr else ""
+            return {
+                "success": False,
+                "message": f"Dashboard failed to start (exit code {poll}): {stderr}",
+            }
+
+        pid = _dashboard_process.pid
+        _save_pid(pid)
+        logger.info("Dashboard started at http://%s:%s (pid=%s)", host, port, pid)
+
+        return {
+            "success": True,
+            "url": f"http://{host}:{port}",
+            "pid": pid,
+            "message": "Dashboard started successfully",
+        }
+
+    except FileNotFoundError:
+        return {
+            "success": False,
+            "message": "Streamlit not installed. Install with: pip install foundry-mcp[dashboard]",
+        }
+    except Exception as e:
+        logger.exception("Failed to start dashboard")
+        return {
+            "success": False,
+            "message": f"Failed to start dashboard: {e}",
+        }
+
+
+def stop_dashboard() -> dict:
+    """Stop the running dashboard server.
+
+    Returns:
+        dict with:
+            - success: bool
+            - message: Status message
+    """
+    global _dashboard_process
+
+    # First check in-memory process reference
+    if _dashboard_process is not None:
+        try:
+            _dashboard_process.terminate()
+            _dashboard_process.wait(timeout=5)
+            pid = _dashboard_process.pid
+            _dashboard_process = None
+            _clear_pid()
+
+            logger.info("Dashboard stopped (pid=%s)", pid)
+
+            return {
+                "success": True,
+                "message": f"Dashboard stopped (pid={pid})",
+            }
+
+        except subprocess.TimeoutExpired:
+            _dashboard_process.kill()
+            _dashboard_process = None
+            _clear_pid()
+            return {
+                "success": True,
+                "message": "Dashboard killed (did not terminate gracefully)",
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "message": f"Failed to stop dashboard: {e}",
+            }
+
+    # Fall back to PID file (for cross-process stop)
+    pid = _load_pid()
+    if pid is None:
+        return {
+            "success": False,
+            "message": "No dashboard process to stop",
+        }
+
+    if not _is_process_running(pid):
+        _clear_pid()
+        return {
+            "success": False,
+            "message": f"Dashboard process (pid={pid}) not running, cleaned up stale PID file",
+        }
+
+    try:
+        os.kill(pid, signal.SIGTERM)
+
+        # Wait for process to terminate
+        for _ in range(50):  # 5 seconds total
+            time.sleep(0.1)
+            if not _is_process_running(pid):
+                break
+        else:
+            # Force kill if still running
+            os.kill(pid, signal.SIGKILL)
+
+        _clear_pid()
+        logger.info("Dashboard stopped (pid=%s)", pid)
+
+        return {
+            "success": True,
+            "message": f"Dashboard stopped (pid={pid})",
+        }
+
+    except ProcessLookupError:
+        _clear_pid()
+        return {
+            "success": True,
+            "message": f"Dashboard process (pid={pid}) already terminated",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "message": f"Failed to stop dashboard: {e}",
+        }
+
+
+def get_dashboard_status() -> dict:
+    """Check if dashboard is running.
+
+    Returns:
+        dict with:
+            - running: bool
+            - pid: Process ID (if running)
+            - exit_code: Exit code (if not running)
+    """
+    global _dashboard_process
+
+    # First check in-memory process reference
+    if _dashboard_process is not None:
+        poll = _dashboard_process.poll()
+        if poll is not None:
+            _clear_pid()
+            return {"running": False, "exit_code": poll}
+        return {"running": True, "pid": _dashboard_process.pid}
+
+    # Fall back to PID file (for cross-process status)
+    pid = _load_pid()
+    if pid is None:
+        return {"running": False}
+
+    if _is_process_running(pid):
+        return {"running": True, "pid": pid}
+
+    # Process not running but PID file exists - clean up
+    _clear_pid()
+    return {"running": False}

foundry_mcp/dashboard/views/__init__.py

@@ -0,0 +1,12 @@
+"""Dashboard view modules.
+
+Each view module provides a `render()` function that renders the page content.
+"""
+
+__all__ = [
+    "overview",
+    "errors",
+    "metrics",
+    "providers",
+    "sdd_workflow",
+]

foundry_mcp/dashboard/views/errors.py

@@ -0,0 +1,217 @@
+"""Errors page - filterable error list with patterns and details."""
+
+import streamlit as st
+
+from typing import Any
+
+from foundry_mcp.dashboard.components.filters import (
+    time_range_filter,
+    text_filter,
+    filter_row,
+)
+from foundry_mcp.dashboard.components.tables import (
+    error_table_config,
+    paginated_table,
+)
+from foundry_mcp.dashboard.components.charts import treemap_chart, pie_chart
+from foundry_mcp.dashboard.data.stores import (
+    get_errors,
+    get_error_stats,
+    get_error_patterns,
+    get_error_by_id,
+)
+
+# Try importing pandas
+pd: Any
+try:
+    import pandas as pd
+
+    PANDAS_AVAILABLE = True
+except ImportError:
+    PANDAS_AVAILABLE = False
+    pd = None
+
+
+def render():
+    """Render the Errors page."""
+    st.header("Errors")
+
+    # Check if error collection is enabled
+    stats = get_error_stats()
+    if not stats.get("enabled"):
+        st.warning(
+            "Error collection is disabled. Enable it in foundry-mcp.toml under [error_collection]"
+        )
+        return
+
+    # Filters
+    st.subheader("Filters")
+    cols = filter_row(4)
+
+    with cols[0]:
+        hours = time_range_filter(key="error_time_range", default="24h")
+    with cols[1]:
+        tool_filter = text_filter(
+            "Tool Name", key="error_tool", placeholder="e.g., spec"
+        )
+    with cols[2]:
+        code_filter = text_filter(
+            "Error Code", key="error_code", placeholder="e.g., VALIDATION_ERROR"
+        )
+    with cols[3]:
+        # Show stats - use total_errors from stats (single source of truth)
+        st.metric("Total Errors", stats.get("total_errors", 0))
+
+    st.divider()
+
+    # Get filtered errors
+    errors_df = get_errors(
+        tool_name=tool_filter if tool_filter else None,
+        error_code=code_filter if code_filter else None,
+        since_hours=hours,
+        limit=500,
+    )
+
+    # Main content tabs
+    tab1, tab2, tab3 = st.tabs(["Error List", "Patterns", "Analysis"])
+
+    with tab1:
+        st.subheader("Error List")
+        if errors_df is not None and not errors_df.empty:
+            # Show table with selection
+            st.caption(f"Showing {len(errors_df)} errors")
+
+            # Paginated table
+            paginated_table(
+                errors_df,
+                page_size=25,
+                key="errors_page",
+                columns=error_table_config(),
+            )
+
+            # Error detail expander
+            st.subheader("Error Details")
+            selected_id = st.text_input(
+                "Enter Error ID to view details",
+                key="error_detail_id",
+                placeholder="Click an error ID above and paste here",
+            )
+
+            if selected_id:
+                error = get_error_by_id(selected_id)
+                if error:
+                    with st.expander(f"Error: {selected_id}", expanded=True):
+                        col1, col2 = st.columns(2)
+                        with col1:
+                            st.markdown("**Tool:** " + error.get("tool_name", "N/A"))
+                            st.markdown("**Code:** " + error.get("error_code", "N/A"))
+                            st.markdown("**Type:** " + error.get("error_type", "N/A"))
+                            st.markdown(
+                                "**Time:** " + str(error.get("timestamp", "N/A"))
+                            )
+
+                        with col2:
+                            st.markdown(
+                                "**Fingerprint:** "
+                                + error.get("fingerprint", "N/A")[:20]
+                                + "..."
+                            )
+
+                        st.markdown("**Message:**")
+                        st.text(error.get("message", "No message"))
+
+                        if error.get("stack_trace"):
+                            st.markdown("**Stack Trace:**")
+                            st.code(error["stack_trace"], language="python")
+
+                        if error.get("context"):
+                            st.markdown("**Context:**")
+                            st.json(error["context"])
+                else:
+                    st.warning(f"Error {selected_id} not found")
+        else:
+            st.info("No errors found matching the filters")
+
+    with tab2:
+        st.subheader("Error Patterns")
+        patterns = get_error_patterns(min_count=2)
+
+        if patterns and PANDAS_AVAILABLE and pd is not None:
+            # Create DataFrame for visualization
+            patterns_df = pd.DataFrame(patterns)
+
+            # Treemap of patterns
+            if "tool_name" in patterns_df.columns and "count" in patterns_df.columns:
+                treemap_chart(
+                    patterns_df,
+                    path=["tool_name", "error_code"]
+                    if "error_code" in patterns_df.columns
+                    else ["tool_name"],
+                    values="count",
+                    title="Error Distribution by Tool",
+                    height=400,
+                )
+
+            # Pattern details table
+            st.subheader("Pattern Details")
+            st.dataframe(
+                patterns_df,
+                use_container_width=True,
+                hide_index=True,
+            )
+        else:
+            st.info("No recurring patterns detected (minimum 2 occurrences required)")
+
+    with tab3:
+        st.subheader("Error Analysis")
+
+        if errors_df is not None and not errors_df.empty and PANDAS_AVAILABLE:
+            col1, col2 = st.columns(2)
+
+            with col1:
+                # Errors by tool
+                if "tool_name" in errors_df.columns:
+                    tool_counts = errors_df["tool_name"].value_counts().reset_index()
+                    tool_counts.columns = ["tool_name", "count"]
+                    pie_chart(
+                        tool_counts,
+                        values="count",
+                        names="tool_name",
+                        title="Errors by Tool",
+                        height=300,
+                    )
+
+            with col2:
+                # Errors by code
+                if "error_code" in errors_df.columns:
+                    code_counts = errors_df["error_code"].value_counts().reset_index()
+                    code_counts.columns = ["error_code", "count"]
+                    pie_chart(
+                        code_counts,
+                        values="count",
+                        names="error_code",
+                        title="Errors by Code",
+                        height=300,
+                    )
+
+            # Export button
+            st.divider()
+            col1, col2 = st.columns(2)
+            with col1:
+                csv = errors_df.to_csv(index=False)
+                st.download_button(
+                    label="Download CSV",
+                    data=csv,
+                    file_name="errors_export.csv",
+                    mime="text/csv",
+                )
+            with col2:
+                json_data = errors_df.to_json(orient="records")
+                st.download_button(
+                    label="Download JSON",
+                    data=json_data,
+                    file_name="errors_export.json",
+                    mime="application/json",
+                )
+        else:
+            st.info("No error data available for analysis")

foundry_mcp/dashboard/views/metrics.py

@@ -0,0 +1,164 @@
+"""Metrics page - viewer with summaries."""
+
+import streamlit as st
+
+from foundry_mcp.dashboard.components.filters import time_range_filter
+from foundry_mcp.dashboard.components.cards import kpi_row
+from foundry_mcp.dashboard.data.stores import (
+    get_metrics_list,
+    get_metrics_timeseries,
+    get_metrics_summary,
+    get_top_tool_actions,
+)
+
+# Try importing pandas
+try:
+    import pandas as pd
+    PANDAS_AVAILABLE = True
+except ImportError:
+    PANDAS_AVAILABLE = False
+    pd = None
+
+
+def render():
+    """Render the Metrics page."""
+    st.header("Metrics")
+
+    # Get available metrics
+    metrics_list = get_metrics_list()
+
+    if not metrics_list:
+        st.warning("No metrics available. Metrics persistence may be disabled.")
+        st.info("Enable metrics persistence in foundry-mcp.toml under [metrics_persistence]")
+        return
+
+    # Metric selector and time range
+    col1, col2 = st.columns([2, 1])
+
+    with col1:
+        metric_names = [m.get("metric_name", "unknown") for m in metrics_list]
+        selected_metric = st.selectbox(
+            "Select Metric",
+            options=metric_names,
+            key="metrics_selector",
+        )
+
+    with col2:
+        hours = time_range_filter(key="metrics_time_range", default="24h")
+
+    st.divider()
+
+    if selected_metric:
+        # Get summary statistics
+        summary = get_metrics_summary(selected_metric, since_hours=hours)
+
+        # Summary cards
+        st.subheader("Summary Statistics")
+        if summary.get("enabled"):
+            # Handle None values (returned when no data exists)
+            min_val = summary.get("min") if summary.get("min") is not None else 0
+            max_val = summary.get("max") if summary.get("max") is not None else 0
+            avg_val = summary.get("avg") if summary.get("avg") is not None else 0
+            sum_val = summary.get("sum") if summary.get("sum") is not None else 0
+
+            kpi_row(
+                [
+                    {"label": "Count", "value": summary.get("count", 0)},
+                    {"label": "Min", "value": f"{min_val:.2f}"},
+                    {"label": "Max", "value": f"{max_val:.2f}"},
+                    {"label": "Average", "value": f"{avg_val:.2f}"},
+                    {"label": "Sum", "value": f"{sum_val:.2f}"},
+                ],
+                columns=5,
+            )
+        else:
+            st.info("Summary not available")
+
+        st.divider()
+
+        # Data table
+        st.subheader(f"Data: {selected_metric}")
+        timeseries_df = get_metrics_timeseries(selected_metric, since_hours=hours)
+
+        # Check if we have data, if not try longer time ranges
+        display_df = timeseries_df
+        time_range_note = None
+
+        if display_df is None or display_df.empty:
+            # Try progressively longer time ranges
+            for fallback_hours, label in [(168, "7 days"), (720, "30 days"), (8760, "1 year")]:
+                if fallback_hours > hours:
+                    display_df = get_metrics_timeseries(selected_metric, since_hours=fallback_hours)
+                    if display_df is not None and not display_df.empty:
+                        time_range_note = f"No data in selected range - showing last {label}"
+                        break
+
+        if display_df is not None and not display_df.empty:
+            if time_range_note:
+                st.caption(time_range_note)
+
+            st.dataframe(
+                display_df,
+                use_container_width=True,
+                hide_index=True,
+            )
+
+            # Export
+            col1, col2 = st.columns(2)
+            with col1:
+                csv = display_df.to_csv(index=False)
+                st.download_button(
+                    label="Download CSV",
+                    data=csv,
+                    file_name=f"{selected_metric}_export.csv",
+                    mime="text/csv",
+                )
+            with col2:
+                json_data = display_df.to_json(orient="records")
+                st.download_button(
+                    label="Download JSON",
+                    data=json_data,
+                    file_name=f"{selected_metric}_export.json",
+                    mime="application/json",
+                )
+        else:
+            st.info(f"No data available for {selected_metric}")
+
+    # Tool Action Breakdown
+    st.divider()
+    st.subheader("Top Tool Actions")
+    top_actions = get_top_tool_actions(since_hours=hours, top_n=10)
+
+    if top_actions:
+        col1, col2 = st.columns(2)
+        for i, item in enumerate(top_actions):
+            tool = item.get("tool", "unknown")
+            action = item.get("action", "")
+            count = int(item.get("count", 0))
+            display_name = f"{tool}.{action}" if action and action != "(no action)" else tool
+            target_col = col1 if i < 5 else col2
+            with target_col:
+                with st.container(border=True):
+                    st.markdown(f"**{display_name}**")
+                    st.caption(f"Invocations: {count:,}")
+    else:
+        st.info("No tool action data available for selected time range")
+
+    # Metrics catalog
+    st.divider()
+    st.subheader("Available Metrics")
+
+    if PANDAS_AVAILABLE:
+        metrics_df = pd.DataFrame(metrics_list)
+        st.dataframe(
+            metrics_df,
+            use_container_width=True,
+            hide_index=True,
+            column_config={
+                "metric_name": st.column_config.TextColumn("Metric", width="medium"),
+                "count": st.column_config.NumberColumn("Records", width="small"),
+            },
+        )
+    else:
+        for m in metrics_list:
+            st.text(f"- {m.get('metric_name', 'unknown')} ({m.get('count', 0)} records)")