Update tools/plot_generator.py

tools/plot_generator.py

@@ -1,9 +1,17 @@
 # tools/plot_generator.py
+# ------------------------------------------------------------
+# Creates an interactive line‑and‑marker trend chart for any
+# (date_col, value_col) pair and saves a hi‑res PNG copy.
+
 import os
 import tempfile
+from typing import Tuple, Union
+
 import pandas as pd
 import plotly.graph_objects as go
-from typing import Tuple, Union
+
+# Alias for typing — every helper returns a go.Figure
+Plot = go.Figure
 
 
 def plot_metric_tool(
@@ -11,41 +19,42 @@ def plot_metric_tool(
     date_col: str,
     value_col: str,
     output_dir: str = "/tmp",
-    title: str = None,
+    title: str | None = None,
     line_width: int = 2,
-    marker_size: int = 6
-) -> Union[Tuple[go.Figure, str], str]:
+    marker_size: int = 6,
+) -> Union[Tuple[Plot, str], str]:
     """
-    Load CSV or Excel file, parse a time series metric, and return an interactive Plotly Figure
-    plus a high-res PNG file path for static embedding.
+    Build a (date, metric) trend chart.
 
-    Returns:
-      - (fig, img_path) on success
-      - error string starting with '❌' on failure
+    Returns
+    -------
+    (fig, png_path)  on success
+    error string     on failure (string starts with '❌')
     """
-    # Load data
+    # ── 1. Load CSV or Excel ──────────────────────────────────
     ext = os.path.splitext(file_path)[1].lower()
     try:
-        df = pd.read_excel(file_path) if ext in ('.xls', '.xlsx') else pd.read_csv(file_path)
+        df = (
+            pd.read_excel(file_path)
+            if ext in (".xls", ".xlsx")
+            else pd.read_csv(file_path)
+        )
     except Exception as exc:
         return f"❌ Failed to load file: {exc}"
 
-    # Validate columns
+    # ── 2. Validate columns ───────────────────────────────────
     missing = [c for c in (date_col, value_col) if c not in df.columns]
     if missing:
         return f"❌ Missing column(s): {', '.join(missing)}"
 
-    # Parse and clean
-    try:
-        df[date_col] = pd.to_datetime(df[date_col], errors='coerce')
-    except Exception:
-        return f"❌ Could not parse '{date_col}' as dates."
-    df[value_col] = pd.to_numeric(df[value_col], errors='coerce')
+    # ── 3. Parse & clean ──────────────────────────────────────
+    df[date_col] = pd.to_datetime(df[date_col], errors="coerce")
+    df[value_col] = pd.to_numeric(df[value_col], errors="coerce")
     df = df.dropna(subset=[date_col, value_col])
     if df.empty:
-        return f"❌ No valid data after cleaning '{date_col}'/'{value_col}'"
+        return f"❌ No valid data after cleaning '{date_col}' / '{value_col}'."
 
-    # Aggregate duplicates and sort
+    # Aggregate duplicate timestamps, sort by date
     df = (
         df[[date_col, value_col]]
         .groupby(date_col, as_index=True)
@@ -53,35 +62,35 @@ def plot_metric_tool(
         .sort_index()
     )
 
-    # Build figure
+    # ── 4. Build Plotly figure ────────────────────────────────
     fig = go.Figure(
-        data=[
-            go.Scatter(
-                x=df.index,
-                y=df[value_col],
-                mode='lines+markers',
-                line=dict(width=line_width),
-                marker=dict(size=marker_size),
-                name=value_col,
-            )
-        ]
+        go.Scatter(
+            x=df.index,
+            y=df[value_col],
+            mode="lines+markers",
+            line=dict(width=line_width),
+            marker=dict(size=marker_size),
+            name=value_col,
+        )
     )
     fig.update_layout(
         title=title or f"{value_col} Trend",
         xaxis_title=date_col,
         yaxis_title=value_col,
-        template='plotly_dark',
-        hovermode='x unified'
+        template="plotly_dark",
+        hovermode="x unified",
     )
 
-    # Save PNG
+    # ── 5. Save static PNG copy ───────────────────────────────
     os.makedirs(output_dir, exist_ok=True)
-    tmp = tempfile.NamedTemporaryFile(suffix='.png', prefix='trend_', dir=output_dir, delete=False)
-    img_path = tmp.name
+    tmp = tempfile.NamedTemporaryFile(
+        prefix="trend_", suffix=".png", dir=output_dir, delete=False
+    )
+    png_path = tmp.name
     tmp.close()
     try:
-        fig.write_image(img_path, scale=2)
+        fig.write_image(png_path, scale=2)
     except Exception as exc:
         return f"❌ Failed saving image: {exc}"
 
-    return fig, img_path
+    return fig, png_path