feat: cal-drift alerting, recert reminder, scheduled monitor (v5.2 W3)

- evaluate_drift_alert + cal_drift_alert: classify a drift comparison as
  OK/WARN/ALERT against warn/alert dB thresholds (worst per-pol mean & max
  abs), and flag setup_group mismatch. Closes #4.
- gain_standard_recert_status + cal_drift_recert_check: gain-standard
  recertification status (ok/due/unknown) from cal date + recert interval +
  last recert. Closes #3.
- cal_drift_monitor: cron-friendly — compare the most-recent recorded run to
  a baseline and alert; intended to be scheduled. Closes #33.

Pure functions are unit-tested directly; the MCP tools never raise. +3 tools
(50 total); +8 tests; full suite 391 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: RFingAdam

plot_antenna/cal_drift.py

@@ -837,6 +837,93 @@ def compute_drift(baseline_run_id: str, current_run_id: str) -> DriftResult:
     )
 
 
+def evaluate_drift_alert(
+    result: "DriftResult", warn_db: float = 0.5, alert_db: float = 1.0
+) -> dict:
+    """Classify a DriftResult against warn/alert thresholds (issue #4).
+
+    Looks at the worst per-polarization mean drift and max absolute drift and
+    returns a level — "OK", "WARN", or "ALERT" — with the triggering reasons.
+    Pure function (no IO); thresholds default to the module's soft/hard outlier
+    levels.
+
+    Returns:
+        {level, worst_mean_abs_db, worst_max_abs_db, warn_db, alert_db, reasons}
+    """
+    stats = result.stats
+    worst_mean = max(abs(stats["H"]["mean"]), abs(stats["V"]["mean"]))
+    worst_max = max(stats["H"]["max_abs"], stats["V"]["max_abs"])
+    reasons = []
+    level = "OK"
+    if worst_max >= alert_db or worst_mean >= alert_db:
+        level = "ALERT"
+        reasons.append(f"drift >= alert threshold {alert_db} dB")
+    elif worst_max >= warn_db or worst_mean >= warn_db:
+        level = "WARN"
+        reasons.append(f"drift >= warn threshold {warn_db} dB")
+    # Setup-group mismatch is always worth flagging.
+    sg = result.consistency.get("setup_group")
+    if sg and isinstance(sg, (list, tuple)) and sg[0] == "mismatch":
+        if level == "OK":
+            level = "WARN"
+        reasons.append(f"setup_group mismatch ({sg[1]!r} vs {sg[2]!r})")
+    return {
+        "level": level,
+        "worst_mean_abs_db": round(worst_mean, 4),
+        "worst_max_abs_db": round(worst_max, 4),
+        "warn_db": warn_db,
+        "alert_db": alert_db,
+        "reasons": reasons,
+    }
+
+
+def gain_standard_recert_status(
+    cal_date: str, interval_months: int = 12, last_recert_date: Optional[str] = None
+) -> dict:
+    """Gain-standard recertification status for a cal run (issue #3).
+
+    Given the calibration date and the recert interval, report whether the
+    gain standard's certification was current as of the cal (relative to its
+    last recert). Pure date math. Dates are "YYYY-MM-DD".
+
+    Returns:
+        {status: "ok"|"due"|"unknown", months_since_recert, interval_months,
+         due_date, cal_date, last_recert_date}
+    """
+    from datetime import date
+
+    out = {
+        "status": "unknown",
+        "months_since_recert": None,
+        "interval_months": interval_months,
+        "due_date": None,
+        "cal_date": cal_date,
+        "last_recert_date": last_recert_date,
+    }
+    if not last_recert_date:
+        return out  # no recert reference -> unknown
+
+    def _parse(s):
+        return date.fromisoformat(s)
+
+    try:
+        cal = _parse(cal_date)
+        recert = _parse(last_recert_date)
+    except (ValueError, TypeError):
+        return out
+
+    months = (cal.year - recert.year) * 12 + (cal.month - recert.month)
+    # due date = recert + interval (approx by months)
+    due_year = recert.year + (recert.month - 1 + interval_months) // 12
+    due_month = (recert.month - 1 + interval_months) % 12 + 1
+    due_day = min(recert.day, 28)
+    due = date(due_year, due_month, due_day)
+    out["months_since_recert"] = months
+    out["due_date"] = due.isoformat()
+    out["status"] = "due" if cal > due else "ok"
+    return out
+
+
 # ──────────────────────────────────────────────────────────────────────────
 # Plotting + reporting
 # ──────────────────────────────────────────────────────────────────────────

rflect-mcp/tools/cal_drift_tools.py

@@ -151,6 +151,105 @@ def cal_drift_set_notes(run_id: str, notes: str) -> bool:
     return cal_drift.update_notes(run_id, notes)
 
 
+def cal_drift_alert(
+    baseline_run_id: str,
+    current_run_id: str,
+    warn_db: float = 0.5,
+    alert_db: float = 1.0,
+) -> Dict[str, Any]:
+    """Compare two cal runs and classify the drift as OK / WARN / ALERT (#4).
+
+    Computes the drift between baseline and current and applies warn/alert
+    thresholds to the worst per-polarization mean and max-absolute drift; also
+    flags a setup_group mismatch.
+
+    Args:
+        baseline_run_id, current_run_id: run_ids from cal_drift_list_runs.
+        warn_db: drift at/above this -> WARN (default 0.5 dB).
+        alert_db: drift at/above this -> ALERT (default 1.0 dB).
+
+    Returns:
+        Dict: level, worst_mean_abs_db, worst_max_abs_db, reasons, warn_db,
+        alert_db. On failure: {error}. Never raises.
+    """
+    try:
+        result = cal_drift.compute_drift(baseline_run_id, current_run_id)
+    except Exception as exc:
+        return {"error": f"cal_drift_alert failed: {exc}"}
+    out = cal_drift.evaluate_drift_alert(result, warn_db=warn_db, alert_db=alert_db)
+    out["baseline_run_id"] = baseline_run_id
+    out["current_run_id"] = current_run_id
+    return out
+
+
+def cal_drift_monitor(
+    baseline_run_id: str,
+    antenna: Optional[str] = None,
+    band: Optional[str] = None,
+    warn_db: float = 0.5,
+    alert_db: float = 1.0,
+) -> Dict[str, Any]:
+    """Compare the most-recent cal run to a baseline and alert (#33).
+
+    Cron-friendly: finds the latest recorded run (optionally filtered by
+    antenna/band), compares it to the baseline, and returns the drift alert.
+    Intended to be scheduled so chamber drift is caught automatically.
+
+    Args:
+        baseline_run_id: the reference run to compare against.
+        antenna, band: optional filters to select the latest run.
+        warn_db, alert_db: alert thresholds (dB).
+
+    Returns:
+        Dict: latest_run_id, plus the cal_drift_alert fields. On failure:
+        {error}. Never raises.
+    """
+    try:
+        df = cal_drift.list_runs(antenna=antenna, band=band)
+        if df is None or len(df) == 0:
+            return {"error": "no_recorded_runs", "warnings": ["nothing to monitor"]}
+        # Latest by date then time if present.
+        sort_cols = [c for c in ("date", "time") if c in df.columns]
+        latest = df.sort_values(sort_cols).iloc[-1] if sort_cols else df.iloc[-1]
+        latest_id = str(latest["run_id"])
+    except Exception as exc:
+        return {"error": f"cal_drift_monitor failed: {exc}"}
+    if latest_id == baseline_run_id:
+        return {
+            "latest_run_id": latest_id,
+            "level": "OK",
+            "reasons": ["latest run is the baseline; nothing newer to compare"],
+        }
+    out = cal_drift_alert(baseline_run_id, latest_id, warn_db=warn_db, alert_db=alert_db)
+    out["latest_run_id"] = latest_id
+    return out
+
+
+def cal_drift_recert_check(
+    cal_date: str,
+    interval_months: int = 12,
+    last_recert_date: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Gain-standard recertification status for a cal run (#3).
+
+    Reports whether the gain standard's certification was current as of the
+    cal date, given its last recert and the recert interval.
+
+    Args:
+        cal_date: calibration date "YYYY-MM-DD".
+        interval_months: recert validity interval (default 12).
+        last_recert_date: last recertification date "YYYY-MM-DD" (required for
+            a definite verdict; otherwise status is "unknown").
+
+    Returns:
+        Dict: status ("ok"|"due"|"unknown"), months_since_recert, due_date,
+        interval_months, cal_date, last_recert_date. Never raises.
+    """
+    return cal_drift.gain_standard_recert_status(
+        cal_date, interval_months=interval_months, last_recert_date=last_recert_date
+    )
+
+
 def register_cal_drift_tools(mcp):
     """Register calibration-drift tools with the MCP server."""
     mcp.tool()(cal_drift_ingest)
@@ -161,3 +260,6 @@ def register_cal_drift_tools(mcp):
     mcp.tool()(cal_drift_set_history_dir)
     mcp.tool()(cal_drift_set_setup_group)
     mcp.tool()(cal_drift_set_notes)
+    mcp.tool()(cal_drift_alert)
+    mcp.tool()(cal_drift_monitor)
+    mcp.tool()(cal_drift_recert_check)

tests/test_cal_drift_v52.py

@@ -0,0 +1,101 @@
+"""v5.2 cal-drift extensions: drift alert (#4), recert reminder (#3),
+monitor (#33)."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import pytest
+
+import matplotlib
+
+matplotlib.use("Agg")
+
+from plot_antenna.cal_drift import (
+    DriftResult,
+    evaluate_drift_alert,
+    gain_standard_recert_status,
+)
+
+
+def _dr(h_mean, h_max, v_mean=0.0, v_max=0.0, consistency=None):
+    return DriftResult(
+        deltas=None,
+        stats={
+            "H": {"mean": h_mean, "max_abs": h_max},
+            "V": {"mean": v_mean, "max_abs": v_max},
+        },
+        consistency=consistency or {},
+        missing_audit={},
+        baseline=None,
+        current=None,
+    )
+
+
+# ----------------------------- #4 drift alert -----------------------------
+
+
+def test_alert_levels():
+    assert evaluate_drift_alert(_dr(0.2, 0.3))["level"] == "OK"
+    assert evaluate_drift_alert(_dr(0.2, 0.7))["level"] == "WARN"  # max 0.7 >= 0.5
+    assert evaluate_drift_alert(_dr(0.2, 1.3))["level"] == "ALERT"  # max 1.3 >= 1.0
+    assert evaluate_drift_alert(_dr(1.2, 0.3))["level"] == "ALERT"  # mean 1.2 >= 1.0
+
+
+def test_alert_setup_group_mismatch_escalates_ok_to_warn():
+    out = evaluate_drift_alert(_dr(0.1, 0.2, consistency={"setup_group": ("mismatch", "a", "b")}))
+    assert out["level"] == "WARN"
+    assert any("setup_group mismatch" in r for r in out["reasons"])
+
+
+def test_alert_custom_thresholds():
+    # With a tighter warn threshold, a 0.3 dB drift trips WARN.
+    out = evaluate_drift_alert(_dr(0.0, 0.3), warn_db=0.2, alert_db=0.5)
+    assert out["level"] == "WARN"
+
+
+# ----------------------------- #3 recert reminder -----------------------------
+
+
+def test_recert_ok_within_interval():
+    out = gain_standard_recert_status(
+        "2026-03-01", interval_months=12, last_recert_date="2025-06-01"
+    )
+    assert out["status"] == "ok"
+    assert out["due_date"] == "2026-06-01"
+
+
+def test_recert_due_past_interval():
+    out = gain_standard_recert_status(
+        "2026-09-01", interval_months=12, last_recert_date="2025-06-01"
+    )
+    assert out["status"] == "due"
+
+
+def test_recert_unknown_without_reference():
+    assert gain_standard_recert_status("2026-03-01")["status"] == "unknown"
+
+
+def test_recert_bad_date_is_unknown():
+    assert gain_standard_recert_status("not-a-date", 12, "2025-06-01")["status"] == "unknown"
+
+
+# ----------------------------- #4/#33 MCP never-raise -----------------------------
+
+
+def test_mcp_alert_and_monitor_never_raise_on_missing_runs():
+    pytest.importorskip("mcp", reason="mcp package not installed")
+    sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(__file__)), "rflect-mcp"))
+    from mcp.server.fastmcp import FastMCP
+    from tools.cal_drift_tools import register_cal_drift_tools
+
+    mcp = FastMCP("cd-v52")
+    register_cal_drift_tools(mcp)
+    reg = mcp._tool_manager._tools
+
+    alert = reg["cal_drift_alert"].fn("nope-a", "nope-b")
+    assert isinstance(alert, dict) and "error" in alert
+
+    recert = reg["cal_drift_recert_check"].fn("2026-03-01", 12, "2025-06-01")
+    assert recert["status"] == "ok"