Cleaning up a few commits. Deals with #260 in the right way.

Author: mikegros

pyproject.toml

@@ -23,9 +23,9 @@ dependencies = [
     "arxiv>=2.2.0,<3.0",
     "beautifulsoup4>=4.13.4,<5.0",
     "randomname>=0.2.1,<0.3",
-    "pandas>=2.3.1,<3.0",
     "pillow>=11.3.0,<12.0",
-    "pymupdf>=1.26.0,<2.0",
+    "pymupdf>=1.28.0,<2.0",
+    "pymupdf4llm>=0.3.4,<1.0",
     "rich>=13.9.4,<14.0",
     "ddgs>=9.5.5",
     "typer>=0.16.1",
@@ -48,8 +48,6 @@ dependencies = [
     "fastmcp~=3.0",
     "pyyaml>=6.0.3",
     "justext>=3.0.2",
-    "matplotlib>=3.10.6",
-    "scipy>=1.16.2,<2.0.0",
 ]
 classifiers = [
     "Operating System :: OS Independent",
@@ -101,6 +99,11 @@ image = [
 mp = [
     "mp-api>=0.45.8,<0.45.13",
 ]
+metric_plots = [
+    "matplotlib>=3.10.6",
+    "pandas>=2.3.1,<3.0",
+    "scipy>=1.16.2,<2.0.0",
+]
 
 [build-system]
 requires = ["setuptools>=74.1,<80", "setuptools-git-versioning>=2.0,<3"]

src/ursa/observability/metrics_charts.py

@@ -1,16 +1,8 @@
 # charts.py
 from __future__ import annotations
 
-from typing import Any
-
-import matplotlib
-
-matplotlib.use("Agg")  # safe for headless environments
 import datetime as _dt
-
-import matplotlib.pyplot as plt
-import numpy as np
-from scipy.stats import gaussian_kde  # type: ignore
+from typing import Any
 
 # Layout spec for compact charts (fractions of figure size)
 _LAYOUT = dict(
@@ -22,6 +14,45 @@
 )
 
 
+def _optional_dependency_error(package: str, *, utility: str) -> ImportError:
+    return ImportError(
+        f"{utility} requires the optional dependency '{package}'. "
+        f"Install it to use this observability chart utility "
+        f"(for example: pip install {package})."
+    )
+
+
+def _require_pyplot():
+    try:
+        import matplotlib
+
+        matplotlib.use("Agg")  # safe for headless environments
+        import matplotlib.pyplot as plt
+    except ImportError as exc:
+        raise _optional_dependency_error(
+            "matplotlib", utility="Metrics chart generation"
+        ) from exc
+    return plt
+
+
+def _require_numpy():
+    try:
+        import numpy as np
+    except ImportError as exc:
+        raise _optional_dependency_error(
+            "numpy", utility="Metrics chart generation"
+        ) from exc
+    return np
+
+
+def _optional_gaussian_kde():
+    try:
+        from scipy.stats import gaussian_kde  # type: ignore
+    except ImportError:
+        return None
+    return gaussian_kde
+
+
 def compute_llm_wall_seconds(payload: dict) -> float:
     evs = payload.get("llm_events") or []
     intervals = []
@@ -193,6 +224,7 @@ def plot_time_breakdown(
     min_label_pct: float = 1.0,
     context: dict[str, Any] | None = None,  # NEW
 ) -> str:
+    plt = _require_pyplot()
     labels = [k for k, _ in parts]
     values = [v for _, v in parts]
     overall = sum(values) or 1.0
@@ -251,7 +283,7 @@ def plot_time_breakdown(
             fig.text(
                 0.5,
                 0.06,
-                f"{started} \u2192 {ended}",
+                f"{started} → {ended}",
                 ha="center",
                 va="center",
                 fontsize="x-small",
@@ -304,7 +336,7 @@ def _fmt(pct):
         fig.text(
             0.5,
             0.06,
-            f"{started} \u2192 {ended}",
+            f"{started} → {ended}",
             ha="center",
             va="center",
             fontsize="x-small",
@@ -328,6 +360,7 @@ def plot_lollipop_time(
     exclude_zero: bool = True,
     context: dict[str, Any] | None = None,  # NEW
 ) -> str:
+    plt = _require_pyplot()
     data = [(k, v) for (k, v) in parts if (v > 0 if exclude_zero else True)]
     data.sort(key=lambda kv: kv[1])
     labels = [k for k, _ in data]
@@ -418,7 +451,7 @@ def plot_lollipop_time(
         fig.text(
             0.5,
             _LAYOUT["footer2_y"],
-            f"{started} \u2192 {ended}",
+            f"{started} → {ended}",
             ha="center",
             va="center",
             fontsize="x-small",
@@ -498,6 +531,7 @@ def plot_token_totals_bar(
     """
     Horizontal bar chart of token totals by category.
     """
+    plt = _require_pyplot()
 
     order = [
         "input_tokens",
@@ -563,7 +597,7 @@ def plot_token_totals_bar(
         fig.text(
             0.5,
             _LAYOUT["footer2_y"],
-            f"{started} \u2192 {ended}",
+            f"{started} → {ended}",
             ha="center",
             va="center",
             fontsize="x-small",
@@ -587,9 +621,12 @@ def plot_token_kde(
 ) -> str:
     """
     Overlay KDEs for input/output/reasoning/cached/total tokens.
-    - Uses scipy.stats.gaussian_kde if available; falls back to a Gaussian-smoothed histogram.
+    - Uses scipy.stats.gaussian_kde if available; falls back to a simple NumPy Gaussian KDE.
     - No seaborn.
     """
+    plt = _require_pyplot()
+    np = _require_numpy()
+    gaussian_kde = _optional_gaussian_kde()
 
     # categories & pretty labels (skip empty series automatically)
     order = [
@@ -633,10 +670,22 @@ def plot_token_kde(
     x_max = max(1.0, all_max * 1.05)
     x = np.linspace(x_min, x_max, 600)
 
-    # Try scipy KDE; else fallback to simple Gaussian smoothing of hist density
-    def _kde(arr: np.ndarray) -> np.ndarray:
-        kde = gaussian_kde(arr, bw_method=bandwidth)
-        return kde.evaluate(x)
+    # Try scipy KDE; else fallback to simple NumPy Gaussian KDE.
+    def _kde(arr):
+        if gaussian_kde is not None:
+            kde = gaussian_kde(arr, bw_method=bandwidth)
+            return kde.evaluate(x)
+        std = float(np.std(arr)) or max(1.0, x_max - x_min) / 50.0
+        bw = (
+            float(bandwidth)
+            if bandwidth
+            else 1.06 * std * (arr.size ** (-1 / 5))
+        )
+        bw = max(bw, 1e-9)
+        diffs = (x[:, None] - arr[None, :]) / bw
+        return np.exp(-0.5 * diffs * diffs).sum(axis=1) / (
+            arr.size * bw * np.sqrt(2 * np.pi)
+        )
 
     # Plot
     fig = plt.figure(figsize=(8, 2.8))
@@ -687,7 +736,7 @@ def _kde(arr: np.ndarray) -> np.ndarray:
         fig.text(
             0.5,
             _LAYOUT["footer2_y"],
-            f"{started} \u2192 {ended}",
+            f"{started} → {ended}",
             ha="center",
             va="center",
             fontsize="x-small",
@@ -708,8 +757,8 @@ def plot_token_rates_bar(
     context: dict | None = None,
     categories: list[str] | None = None,
 ) -> str:
-    import matplotlib.pyplot as plt
-    import numpy as np
+    plt = _require_pyplot()
+    np = _require_numpy()
 
     cats = categories or [
         "input_tokens",
@@ -753,7 +802,7 @@ def _rate(x: int, denom: float) -> float:
             s
             for s in [
                 f"run_id: {run_id_short}" if run_id_short else "",
-                f"{started} \u2192 {ended}" if (started or ended) else "",
+                f"{started} → {ended}" if (started or ended) else "",
             ]
             if s
         )
@@ -855,7 +904,7 @@ def plot_tokens_bar_by_model(
     title: str = "LLM Token Totals by Category — by model",
     context: dict | None = None,
 ) -> str:
-    import matplotlib.pyplot as plt
+    plt = _require_pyplot()
 
     cats = [
         "input_tokens",
@@ -926,8 +975,8 @@ def plot_token_rates_by_model(
     title: str = "Tokens per second — by model",
     context: dict | None = None,
 ) -> str:
-    import matplotlib.pyplot as plt
-    import numpy as np
+    plt = _require_pyplot()
+    np = _require_numpy()
 
     cats = [
         "input_tokens",
@@ -1051,8 +1100,8 @@ def plot_tokens_by_agent_stacked(
     title: str = "LLM Token Totals by Agent (thread)",
     footer_lines: list[str] | None = None,
 ) -> str:
-    import matplotlib.pyplot as plt
-    import numpy as np
+    plt = _require_pyplot()
+    np = _require_numpy()
 
     cats = [
         "input_tokens",
@@ -1165,8 +1214,8 @@ def plot_tps_by_agent_grouped(
     title: str = "Tokens per second by Agent (thread)",
     footer_lines: list[str] | None = None,
 ) -> str:
-    import matplotlib.pyplot as plt
-    import numpy as np
+    plt = _require_pyplot()
+    np = _require_numpy()
 
     cats = [
         "input_tokens",

src/ursa/observability/metrics_session.py

@@ -4,17 +4,13 @@
 import json
 import os
 import re
+from collections import defaultdict
 from dataclasses import dataclass
 from datetime import datetime, timezone
+from typing import TYPE_CHECKING
 
-import matplotlib
-
-matplotlib.use("Agg")
-from collections import defaultdict
-
-import matplotlib.dates as mdates
-import matplotlib.pyplot as plt
-import pandas as pd
+if TYPE_CHECKING:
+    import pandas as pd
 
 from ursa.observability.metrics_charts import (
     compute_attribution,
@@ -24,6 +20,48 @@
 from ursa.observability.metrics_io import load_metrics
 
 
+def _optional_dependency_error(package: str, *, utility: str) -> ImportError:
+    return ImportError(
+        f"{utility} requires the optional dependency '{package}'. "
+        f"Install it to use this observability metrics utility "
+        f"(for example: pip install {package})."
+    )
+
+
+def _require_matplotlib():
+    try:
+        import matplotlib
+
+        matplotlib.use("Agg")
+        import matplotlib.dates as mdates
+        import matplotlib.pyplot as plt
+    except ImportError as exc:
+        raise _optional_dependency_error(
+            "matplotlib", utility="Metrics session chart generation"
+        ) from exc
+    return plt, mdates
+
+
+def _require_pandas():
+    try:
+        import pandas as pd
+    except ImportError as exc:
+        raise _optional_dependency_error(
+            "pandas", utility="Metrics session DataFrame/CSV export"
+        ) from exc
+    return pd
+
+
+def _require_plotly_express():
+    try:
+        import plotly.express as px
+    except ImportError as exc:
+        raise _optional_dependency_error(
+            "plotly", utility="Interactive metrics session timeline"
+        ) from exc
+    return px
+
+
 def _dt(x: str) -> datetime:
     return datetime.fromisoformat(str(x).replace("Z", "+00:00"))
 
@@ -153,6 +191,7 @@ def plot_thread_timeline(
       • Exact bounds: xlim is precisely first start → last end
       • Legend outside bars: compact legend drawn above the axes
     """
+    plt, mdates = _require_matplotlib()
     if not runs:
         raise ValueError("No runs provided for timeline")
 
@@ -303,6 +342,7 @@ def plot_thread_timeline(
 
 
 def runs_to_dataframe(runs: list[RunRecord]) -> pd.DataFrame:
+    pd = _require_pandas()
     rows = [
         {
             "thread_id": r.thread_id,
@@ -326,7 +366,7 @@ def plot_thread_timeline_interactive(
     *,
     group_by: str = "agent",  # "agent" (few lanes) or "run" (one lane per run)
 ) -> str:
-    import plotly.express as px
+    px = _require_plotly_express()
 
     if not runs:
         raise ValueError("No runs provided")