diagnostics-framework 0.1.0__py3-none-any.whl

diagnostics_framework/__init__.py

@@ -0,0 +1,8 @@
+__version__ = "0.1.0"
+
+from diagnostics_framework.registry import register_system, register_test, register_plot, register_report, registry
+from diagnostics_framework.models import DiagnosticResult, DiagnosticStatus, DiagnosticSummary
+from diagnostics_framework.runner import run_diagnostics, generate_plot, generate_report
+
+# Auto-discover and register all system plugins
+import diagnostics_framework.systems  # noqa: F401

diagnostics_framework/app.py

@@ -0,0 +1,185 @@
+import io
+import json
+
+import pandas as pd
+import streamlit as st
+
+# Import systems to trigger decorator registration
+import diagnostics_framework.systems  # noqa: F401
+
+from diagnostics_framework.models import DiagnosticStatus
+from diagnostics_framework.registry import registry
+from diagnostics_framework.runner import run_diagnostics, generate_plot, generate_report
+
+
+STATUS_COLORS = {
+    DiagnosticStatus.PASS: "#28a745",
+    DiagnosticStatus.FAIL: "#dc3545",
+    DiagnosticStatus.WARNING: "#ffc107",
+    DiagnosticStatus.ERROR: "#6c757d",
+}
+
+STATUS_ICONS = {
+    DiagnosticStatus.PASS: "PASS",
+    DiagnosticStatus.FAIL: "FAIL",
+    DiagnosticStatus.WARNING: "WARN",
+    DiagnosticStatus.ERROR: "ERR",
+}
+
+
+def load_data(uploaded_file) -> pd.DataFrame | dict | None:
+    """Attempt to load an uploaded file as a DataFrame or dict."""
+    if uploaded_file is None:
+        return None
+
+    name = uploaded_file.name.lower()
+    try:
+        if name.endswith(".csv"):
+            return pd.read_csv(uploaded_file)
+        elif name.endswith(".json"):
+            content = json.load(uploaded_file)
+            if isinstance(content, list) and all(isinstance(r, dict) for r in content):
+                return pd.DataFrame(content)
+            return content
+        elif name.endswith((".xls", ".xlsx")):
+            return pd.read_excel(uploaded_file)
+        elif name.endswith(".parquet"):
+            return pd.read_parquet(io.BytesIO(uploaded_file.read()))
+        else:
+            return uploaded_file.read().decode("utf-8", errors="replace")
+    except Exception as e:
+        st.error(f"Failed to load file: {e}")
+        return None
+
+
+def render_results(summary):
+    """Render diagnostic results as a styled table."""
+    st.subheader("Diagnostic Results")
+
+    cols = st.columns(4)
+    cols[0].metric("Total", len(summary.results))
+    cols[1].metric("Pass", summary.pass_count)
+    cols[2].metric("Fail", summary.fail_count)
+    cols[3].metric("Warn / Error", summary.warning_count + summary.error_count)
+
+    for result in summary.results:
+        color = STATUS_COLORS[result.status]
+        icon = STATUS_ICONS[result.status]
+        with st.container():
+            st.markdown(
+                f"<div style='border-left: 4px solid {color}; padding: 8px 12px; margin: 4px 0;'>"
+                f"<strong>[{icon}]</strong> <strong>{result.test_name}</strong><br/>"
+                f"{result.message}"
+                f"</div>",
+                unsafe_allow_html=True,
+            )
+            if result.details:
+                with st.expander("Details"):
+                    st.json(result.details)
+
+
+def render_plots(system_name, data):
+    """Render plot buttons and display generated plots."""
+    st.subheader("Plots")
+    plots = registry.get_plots(system_name)
+    if not plots:
+        st.info("No plots registered for this system.")
+        return
+
+    for plot_info in plots:
+        with st.expander(f"{plot_info.name} — {plot_info.description}"):
+            try:
+                fig = generate_plot(system_name, plot_info.name, data)
+                st.pyplot(fig)
+            except Exception as e:
+                st.error(f"Error generating plot: {e}")
+
+
+def render_reports(system_name, data):
+    """Render report buttons and display generated reports."""
+    st.subheader("Reports")
+    reports = registry.get_reports(system_name)
+    if not reports:
+        st.info("No reports registered for this system.")
+        return
+
+    for report_info in reports:
+        with st.expander(f"{report_info.name} — {report_info.description}"):
+            try:
+                report_text = generate_report(system_name, report_info.name, data)
+                st.markdown(report_text)
+            except Exception as e:
+                st.error(f"Error generating report: {e}")
+
+
+def main():
+    st.set_page_config(page_title="Diagnostics Dashboard", layout="wide")
+    st.title("Diagnostics Dashboard")
+
+    # --- Sidebar ---
+    with st.sidebar:
+        st.header("Configuration")
+
+        systems = registry.get_systems()
+        if not systems:
+            st.warning("No systems registered. Add a system module to diagnostics_framework/systems/.")
+            return
+
+        system_names = list(systems.keys())
+        selected = st.selectbox(
+            "Select System",
+            system_names,
+            format_func=lambda s: f"{s} — {systems[s].description}" if systems[s].description else s,
+        )
+
+        st.markdown("---")
+        st.subheader("Upload Data")
+        uploaded_file = st.file_uploader(
+            "Choose a file",
+            type=["csv", "json", "xlsx", "xls", "parquet", "txt"],
+        )
+
+        run_button = st.button("Run Diagnostics", type="primary", use_container_width=True)
+
+    # --- Main area ---
+    if uploaded_file is not None:
+        data = load_data(uploaded_file)
+        if data is None:
+            return
+
+        if isinstance(data, pd.DataFrame):
+            with st.expander("Preview uploaded data"):
+                st.dataframe(data.head(50))
+
+        if run_button:
+            with st.spinner("Running diagnostics..."):
+                summary = run_diagnostics(selected, data)
+            st.session_state["last_summary"] = summary
+            st.session_state["last_data"] = data
+            st.session_state["last_system"] = selected
+
+        if "last_summary" in st.session_state and st.session_state.get("last_system") == selected:
+            tab_results, tab_plots, tab_reports = st.tabs(["Results", "Plots", "Reports"])
+            with tab_results:
+                render_results(st.session_state["last_summary"])
+            with tab_plots:
+                render_plots(selected, st.session_state.get("last_data", data))
+            with tab_reports:
+                render_reports(selected, st.session_state.get("last_data", data))
+    else:
+        st.info("Upload a data file in the sidebar and click **Run Diagnostics** to begin.")
+
+        # Show registered info for the selected system
+        if "selected" not in dir():
+            return
+        st.markdown(f"### System: {selected}")
+        tests = registry.get_tests(selected)
+        plots = registry.get_plots(selected)
+        reports = registry.get_reports(selected)
+        st.markdown(f"- **{len(tests)}** diagnostic test(s) registered")
+        st.markdown(f"- **{len(plots)}** plot(s) registered")
+        st.markdown(f"- **{len(reports)}** report(s) registered")
+
+
+if __name__ == "__main__":
+    main()

diagnostics_framework/models.py

@@ -0,0 +1,71 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Callable
+
+
+class DiagnosticStatus(Enum):
+    PASS = "pass"
+    FAIL = "fail"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+@dataclass
+class DiagnosticResult:
+    test_name: str
+    status: DiagnosticStatus
+    message: str
+    details: dict[str, Any] = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+@dataclass
+class SystemInfo:
+    name: str
+    description: str = ""
+    version: str = "0.1.0"
+
+
+@dataclass
+class TestInfo:
+    name: str
+    description: str
+    fn: Callable
+
+
+@dataclass
+class PlotInfo:
+    name: str
+    description: str
+    fn: Callable
+
+
+@dataclass
+class ReportInfo:
+    name: str
+    description: str
+    fn: Callable
+
+
+@dataclass
+class DiagnosticSummary:
+    system_name: str
+    results: list[DiagnosticResult]
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    @property
+    def pass_count(self) -> int:
+        return sum(1 for r in self.results if r.status == DiagnosticStatus.PASS)
+
+    @property
+    def fail_count(self) -> int:
+        return sum(1 for r in self.results if r.status == DiagnosticStatus.FAIL)
+
+    @property
+    def warning_count(self) -> int:
+        return sum(1 for r in self.results if r.status == DiagnosticStatus.WARNING)
+
+    @property
+    def error_count(self) -> int:
+        return sum(1 for r in self.results if r.status == DiagnosticStatus.ERROR)

diagnostics_framework/registry.py

@@ -0,0 +1,79 @@
+from diagnostics_framework.models import SystemInfo, TestInfo, PlotInfo, ReportInfo
+
+
+class DiagnosticsRegistry:
+    """Singleton registry for systems, tests, plots, and reports."""
+
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._systems = {}
+            cls._instance._tests = {}
+            cls._instance._plots = {}
+            cls._instance._reports = {}
+        return cls._instance
+
+    def add_system(self, name: str, description: str = "", version: str = "0.1.0"):
+        self._systems[name] = SystemInfo(name=name, description=description, version=version)
+        self._tests.setdefault(name, [])
+        self._plots.setdefault(name, [])
+        self._reports.setdefault(name, [])
+
+    def add_test(self, system: str, test_info: TestInfo):
+        self._tests.setdefault(system, []).append(test_info)
+
+    def add_plot(self, system: str, plot_info: PlotInfo):
+        self._plots.setdefault(system, []).append(plot_info)
+
+    def add_report(self, system: str, report_info: ReportInfo):
+        self._reports.setdefault(system, []).append(report_info)
+
+    def get_systems(self) -> dict[str, SystemInfo]:
+        return dict(self._systems)
+
+    def get_tests(self, system: str) -> list[TestInfo]:
+        return list(self._tests.get(system, []))
+
+    def get_plots(self, system: str) -> list[PlotInfo]:
+        return list(self._plots.get(system, []))
+
+    def get_reports(self, system: str) -> list[ReportInfo]:
+        return list(self._reports.get(system, []))
+
+
+# Module-level singleton
+registry = DiagnosticsRegistry()
+
+
+def register_system(name: str, description: str = "", version: str = "0.1.0"):
+    """Decorator that registers a system. Apply to any function or class (it's returned unchanged)."""
+    def decorator(obj):
+        registry.add_system(name, description, version)
+        return obj
+    return decorator
+
+
+def register_test(system: str, name: str, description: str = ""):
+    """Decorator that registers a diagnostic test function for a system."""
+    def decorator(fn):
+        registry.add_test(system, TestInfo(name=name, description=description, fn=fn))
+        return fn
+    return decorator
+
+
+def register_plot(system: str, name: str, description: str = ""):
+    """Decorator that registers a plot function for a system."""
+    def decorator(fn):
+        registry.add_plot(system, PlotInfo(name=name, description=description, fn=fn))
+        return fn
+    return decorator
+
+
+def register_report(system: str, name: str, description: str = ""):
+    """Decorator that registers a report function for a system."""
+    def decorator(fn):
+        registry.add_report(system, ReportInfo(name=name, description=description, fn=fn))
+        return fn
+    return decorator

diagnostics_framework/runner.py

@@ -0,0 +1,57 @@
+import traceback
+from datetime import datetime
+from typing import Any
+
+import matplotlib.figure
+
+from diagnostics_framework.models import DiagnosticResult, DiagnosticStatus, DiagnosticSummary
+from diagnostics_framework.registry import registry
+
+
+def run_diagnostics(system_name: str, data: Any) -> DiagnosticSummary:
+    """Run all registered diagnostic tests for a system against the provided data."""
+    tests = registry.get_tests(system_name)
+    results = []
+
+    for test_info in tests:
+        try:
+            result = test_info.fn(data)
+            if isinstance(result, DiagnosticResult):
+                results.append(result)
+            else:
+                results.append(DiagnosticResult(
+                    test_name=test_info.name,
+                    status=DiagnosticStatus.ERROR,
+                    message=f"Test '{test_info.name}' did not return a DiagnosticResult.",
+                ))
+        except Exception as e:
+            results.append(DiagnosticResult(
+                test_name=test_info.name,
+                status=DiagnosticStatus.ERROR,
+                message=f"Test raised an exception: {e}",
+                details={"traceback": traceback.format_exc()},
+            ))
+
+    return DiagnosticSummary(
+        system_name=system_name,
+        results=results,
+        timestamp=datetime.now(),
+    )
+
+
+def generate_plot(system_name: str, plot_name: str, data: Any) -> matplotlib.figure.Figure:
+    """Generate a plot by name for a system. Returns a matplotlib Figure."""
+    plots = registry.get_plots(system_name)
+    for plot_info in plots:
+        if plot_info.name == plot_name:
+            return plot_info.fn(data)
+    raise ValueError(f"Plot '{plot_name}' not found for system '{system_name}'.")
+
+
+def generate_report(system_name: str, report_name: str, data: Any) -> str:
+    """Generate a report by name for a system. Returns a string (plain text or markdown)."""
+    reports = registry.get_reports(system_name)
+    for report_info in reports:
+        if report_info.name == report_name:
+            return report_info.fn(data)
+    raise ValueError(f"Report '{report_name}' not found for system '{system_name}'.")

diagnostics_framework/systems/__init__.py

@@ -0,0 +1,9 @@
+"""Auto-discover and import all system modules so their decorators register on import."""
+import importlib
+import pkgutil
+from pathlib import Path
+
+_package_dir = Path(__file__).parent
+
+for _finder, _name, _ispkg in pkgutil.iter_modules([str(_package_dir)]):
+    importlib.import_module(f"{__name__}.{_name}")

diagnostics_framework/systems/generic_example.py

@@ -0,0 +1,201 @@
+"""
+Generic Example System
+======================
+A template system demonstrating the diagnostics framework plugin pattern.
+Copy this file and modify it to create diagnostics for your own system.
+"""
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import seaborn as sns
+
+from diagnostics_framework.models import DiagnosticResult, DiagnosticStatus
+from diagnostics_framework.registry import register_system, register_test, register_plot, register_report
+
+SYSTEM_NAME = "generic_example"
+
+
+@register_system(SYSTEM_NAME, description="Generic example system for tabular data", version="0.1.0")
+class GenericExampleSystem:
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Diagnostic Tests
+# ---------------------------------------------------------------------------
+
+@register_test(SYSTEM_NAME, name="check_not_empty", description="Verify the data is not empty")
+def check_not_empty(data) -> DiagnosticResult:
+    if isinstance(data, pd.DataFrame):
+        is_empty = data.empty
+        size = len(data)
+    elif isinstance(data, (list, dict)):
+        is_empty = len(data) == 0
+        size = len(data)
+    else:
+        is_empty = data is None
+        size = 0 if data is None else 1
+
+    if is_empty:
+        return DiagnosticResult(
+            test_name="check_not_empty",
+            status=DiagnosticStatus.FAIL,
+            message="Data is empty.",
+        )
+    return DiagnosticResult(
+        test_name="check_not_empty",
+        status=DiagnosticStatus.PASS,
+        message=f"Data has {size} records.",
+        details={"record_count": size},
+    )
+
+
+@register_test(SYSTEM_NAME, name="check_no_nulls", description="Check for null or missing values")
+def check_no_nulls(data) -> DiagnosticResult:
+    if not isinstance(data, pd.DataFrame):
+        return DiagnosticResult(
+            test_name="check_no_nulls",
+            status=DiagnosticStatus.WARNING,
+            message="Null check only supported for DataFrame input. Skipped.",
+        )
+
+    null_counts = data.isnull().sum()
+    total_nulls = int(null_counts.sum())
+    cols_with_nulls = {col: int(count) for col, count in null_counts.items() if count > 0}
+
+    if total_nulls == 0:
+        return DiagnosticResult(
+            test_name="check_no_nulls",
+            status=DiagnosticStatus.PASS,
+            message="No null values found.",
+        )
+
+    return DiagnosticResult(
+        test_name="check_no_nulls",
+        status=DiagnosticStatus.WARNING if total_nulls < len(data) else DiagnosticStatus.FAIL,
+        message=f"Found {total_nulls} null value(s) across {len(cols_with_nulls)} column(s).",
+        details={"columns_with_nulls": cols_with_nulls},
+    )
+
+
+@register_test(SYSTEM_NAME, name="check_numeric_ranges", description="Validate numeric columns have finite values")
+def check_numeric_ranges(data) -> DiagnosticResult:
+    if not isinstance(data, pd.DataFrame):
+        return DiagnosticResult(
+            test_name="check_numeric_ranges",
+            status=DiagnosticStatus.WARNING,
+            message="Range check only supported for DataFrame input. Skipped.",
+        )
+
+    numeric_cols = data.select_dtypes(include="number").columns.tolist()
+    if not numeric_cols:
+        return DiagnosticResult(
+            test_name="check_numeric_ranges",
+            status=DiagnosticStatus.WARNING,
+            message="No numeric columns found to check.",
+        )
+
+    issues = {}
+    for col in numeric_cols:
+        inf_count = int(np.isinf(data[col].dropna()).sum())
+        if inf_count > 0:
+            issues[col] = {"infinite_values": inf_count}
+
+    if issues:
+        return DiagnosticResult(
+            test_name="check_numeric_ranges",
+            status=DiagnosticStatus.FAIL,
+            message=f"Found infinite values in {len(issues)} column(s).",
+            details={"columns_with_issues": issues},
+        )
+
+    return DiagnosticResult(
+        test_name="check_numeric_ranges",
+        status=DiagnosticStatus.PASS,
+        message=f"All {len(numeric_cols)} numeric column(s) have finite values.",
+        details={"numeric_columns": numeric_cols},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Plots
+# ---------------------------------------------------------------------------
+
+@register_plot(SYSTEM_NAME, name="data_overview", description="Overview histogram of numeric columns")
+def data_overview_plot(data) -> plt.Figure:
+    if not isinstance(data, pd.DataFrame):
+        fig, ax = plt.subplots()
+        ax.text(0.5, 0.5, "Plot requires DataFrame input", ha="center", va="center")
+        return fig
+
+    numeric_cols = data.select_dtypes(include="number").columns.tolist()
+    if not numeric_cols:
+        fig, ax = plt.subplots()
+        ax.text(0.5, 0.5, "No numeric columns to plot", ha="center", va="center")
+        return fig
+
+    n_cols = len(numeric_cols)
+    fig, axes = plt.subplots(1, n_cols, figsize=(4 * n_cols, 4), squeeze=False)
+    for i, col in enumerate(numeric_cols):
+        axes[0][i].hist(data[col].dropna(), bins=20, edgecolor="black", alpha=0.7)
+        axes[0][i].set_title(col)
+        axes[0][i].set_xlabel("Value")
+        axes[0][i].set_ylabel("Count")
+    fig.suptitle("Numeric Column Distributions", fontsize=14)
+    fig.tight_layout()
+    return fig
+
+
+@register_plot(SYSTEM_NAME, name="null_heatmap", description="Heatmap showing location of null values")
+def null_heatmap(data) -> plt.Figure:
+    if not isinstance(data, pd.DataFrame):
+        fig, ax = plt.subplots()
+        ax.text(0.5, 0.5, "Plot requires DataFrame input", ha="center", va="center")
+        return fig
+
+    fig, ax = plt.subplots(figsize=(max(6, len(data.columns)), max(4, len(data) * 0.05)))
+    sns.heatmap(data.isnull().astype(int), cbar=False, cmap="YlOrRd", ax=ax, yticklabels=False)
+    ax.set_title("Null Values (yellow = present, red = null)")
+    fig.tight_layout()
+    return fig
+
+
+# ---------------------------------------------------------------------------
+# Reports
+# ---------------------------------------------------------------------------
+
+@register_report(SYSTEM_NAME, name="summary_report", description="Text summary of the dataset")
+def summary_report(data) -> str:
+    if not isinstance(data, pd.DataFrame):
+        return f"Data type: {type(data).__name__}\nCannot generate detailed summary for non-DataFrame data."
+
+    lines = [
+        "# Data Summary Report",
+        "",
+        f"**Rows:** {len(data)}",
+        f"**Columns:** {len(data.columns)}",
+        "",
+        "## Column Types",
+    ]
+    for col in data.columns:
+        lines.append(f"- **{col}**: {data[col].dtype}")
+
+    lines.append("")
+    lines.append("## Null Counts")
+    null_counts = data.isnull().sum()
+    for col, count in null_counts.items():
+        if count > 0:
+            lines.append(f"- **{col}**: {count} nulls ({count / len(data) * 100:.1f}%)")
+    if null_counts.sum() == 0:
+        lines.append("- No null values found.")
+
+    numeric_cols = data.select_dtypes(include="number")
+    if not numeric_cols.empty:
+        lines.append("")
+        lines.append("## Numeric Summary")
+        for col in numeric_cols.columns:
+            series = numeric_cols[col].dropna()
+            lines.append(f"- **{col}**: min={series.min():.4g}, max={series.max():.4g}, "
+                         f"mean={series.mean():.4g}, std={series.std():.4g}")
+
+    return "\n".join(lines)

diagnostics_framework/systems/sensor_monitoring.py

@@ -0,0 +1,321 @@
+"""
+Sensor Monitoring System
+========================
+Diagnostics for IoT/environmental sensor data with time series,
+battery health, and anomaly detection checks.
+"""
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import seaborn as sns
+
+from diagnostics_framework.models import DiagnosticResult, DiagnosticStatus
+from diagnostics_framework.registry import register_system, register_test, register_plot, register_report
+
+SYSTEM_NAME = "sensor_monitoring"
+
+
+@register_system(SYSTEM_NAME, description="IoT sensor monitoring diagnostics", version="0.1.0")
+class SensorMonitoringSystem:
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Diagnostic Tests
+# ---------------------------------------------------------------------------
+
+@register_test(SYSTEM_NAME, name="check_not_empty", description="Verify sensor data is not empty")
+def check_not_empty(data) -> DiagnosticResult:
+    if not isinstance(data, pd.DataFrame) or data.empty:
+        return DiagnosticResult(
+            test_name="check_not_empty",
+            status=DiagnosticStatus.FAIL,
+            message="No data found.",
+        )
+    return DiagnosticResult(
+        test_name="check_not_empty",
+        status=DiagnosticStatus.PASS,
+        message=f"Dataset has {len(data)} rows and {len(data.columns)} columns.",
+        details={"rows": len(data), "columns": list(data.columns)},
+    )
+
+
+@register_test(SYSTEM_NAME, name="check_missing_readings", description="Check for missing sensor readings")
+def check_missing_readings(data) -> DiagnosticResult:
+    if not isinstance(data, pd.DataFrame):
+        return DiagnosticResult(test_name="check_missing_readings", status=DiagnosticStatus.WARNING, message="Skipped: not a DataFrame.")
+
+    null_counts = data.isnull().sum()
+    total_nulls = int(null_counts.sum())
+    total_cells = int(data.size)
+    pct = total_nulls / total_cells * 100 if total_cells > 0 else 0
+    cols_with_nulls = {col: int(c) for col, c in null_counts.items() if c > 0}
+
+    if total_nulls == 0:
+        return DiagnosticResult(test_name="check_missing_readings", status=DiagnosticStatus.PASS, message="No missing readings.")
+
+    status = DiagnosticStatus.WARNING if pct < 5 else DiagnosticStatus.FAIL
+    return DiagnosticResult(
+        test_name="check_missing_readings",
+        status=status,
+        message=f"{total_nulls} missing values ({pct:.1f}% of all cells) across {len(cols_with_nulls)} column(s).",
+        details={"missing_by_column": cols_with_nulls, "total_missing": total_nulls, "percent_missing": round(pct, 2)},
+    )
+
+
+@register_test(SYSTEM_NAME, name="check_battery_health", description="Flag sensors with low battery levels")
+def check_battery_health(data) -> DiagnosticResult:
+    if not isinstance(data, pd.DataFrame) or "battery_level" not in data.columns:
+        return DiagnosticResult(test_name="check_battery_health", status=DiagnosticStatus.WARNING, message="No battery_level column found.")
+
+    low_threshold = 20.0
+    critical_threshold = 10.0
+    battery = data[["sensor_id", "battery_level"]].dropna() if "sensor_id" in data.columns else data[["battery_level"]].dropna()
+
+    if "sensor_id" in data.columns:
+        latest = battery.groupby("sensor_id")["battery_level"].last()
+        critical = latest[latest < critical_threshold].to_dict()
+        low = latest[(latest >= critical_threshold) & (latest < low_threshold)].to_dict()
+    else:
+        last_val = float(battery["battery_level"].iloc[-1])
+        critical = {"unknown": last_val} if last_val < critical_threshold else {}
+        low = {"unknown": last_val} if critical_threshold <= last_val < low_threshold else {}
+
+    if critical:
+        return DiagnosticResult(
+            test_name="check_battery_health",
+            status=DiagnosticStatus.FAIL,
+            message=f"{len(critical)} sensor(s) at CRITICAL battery level (<{critical_threshold}%).",
+            details={"critical_sensors": critical, "low_sensors": low},
+        )
+    if low:
+        return DiagnosticResult(
+            test_name="check_battery_health",
+            status=DiagnosticStatus.WARNING,
+            message=f"{len(low)} sensor(s) with low battery (<{low_threshold}%).",
+            details={"low_sensors": low},
+        )
+    return DiagnosticResult(
+        test_name="check_battery_health",
+        status=DiagnosticStatus.PASS,
+        message="All sensors have healthy battery levels.",
+    )
+
+
+@register_test(SYSTEM_NAME, name="check_temperature_range", description="Validate temperature readings are within expected range")
+def check_temperature_range(data) -> DiagnosticResult:
+    if not isinstance(data, pd.DataFrame) or "temperature" not in data.columns:
+        return DiagnosticResult(test_name="check_temperature_range", status=DiagnosticStatus.WARNING, message="No temperature column found.")
+
+    temp = data["temperature"].dropna()
+    min_expected, max_expected = -10.0, 50.0
+    out_of_range = temp[(temp < min_expected) | (temp > max_expected)]
+
+    if len(out_of_range) > 0:
+        return DiagnosticResult(
+            test_name="check_temperature_range",
+            status=DiagnosticStatus.FAIL,
+            message=f"{len(out_of_range)} readings outside expected range [{min_expected}, {max_expected}].",
+            details={"out_of_range_count": len(out_of_range), "min_observed": float(temp.min()), "max_observed": float(temp.max())},
+        )
+    return DiagnosticResult(
+        test_name="check_temperature_range",
+        status=DiagnosticStatus.PASS,
+        message=f"All {len(temp)} temperature readings within [{min_expected}, {max_expected}]. Range: {temp.min():.1f} to {temp.max():.1f}.",
+        details={"min": float(temp.min()), "max": float(temp.max()), "mean": float(temp.mean())},
+    )
+
+
+@register_test(SYSTEM_NAME, name="check_sensor_status", description="Check for sensors in warning or critical status")
+def check_sensor_status(data) -> DiagnosticResult:
+    if not isinstance(data, pd.DataFrame) or "status" not in data.columns:
+        return DiagnosticResult(test_name="check_sensor_status", status=DiagnosticStatus.WARNING, message="No status column found.")
+
+    status_counts = data["status"].value_counts().to_dict()
+    critical_count = status_counts.get("critical", 0)
+    warning_count = status_counts.get("warning", 0)
+
+    if critical_count > 0:
+        return DiagnosticResult(
+            test_name="check_sensor_status",
+            status=DiagnosticStatus.FAIL,
+            message=f"{critical_count} readings in 'critical' status, {warning_count} in 'warning'.",
+            details={"status_breakdown": status_counts},
+        )
+    if warning_count > 0:
+        return DiagnosticResult(
+            test_name="check_sensor_status",
+            status=DiagnosticStatus.WARNING,
+            message=f"{warning_count} readings in 'warning' status.",
+            details={"status_breakdown": status_counts},
+        )
+    return DiagnosticResult(
+        test_name="check_sensor_status",
+        status=DiagnosticStatus.PASS,
+        message="All sensors reporting normal status.",
+        details={"status_breakdown": status_counts},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Plots
+# ---------------------------------------------------------------------------
+
+@register_plot(SYSTEM_NAME, name="temperature_timeseries", description="Temperature over time per sensor")
+def temperature_timeseries(data) -> plt.Figure:
+    if not isinstance(data, pd.DataFrame) or "temperature" not in data.columns:
+        fig, ax = plt.subplots()
+        ax.text(0.5, 0.5, "Requires 'temperature' column", ha="center", va="center")
+        return fig
+
+    fig, ax = plt.subplots(figsize=(12, 5))
+    if "sensor_id" in data.columns and "timestamp" in data.columns:
+        for sensor_id, group in data.groupby("sensor_id"):
+            ts = pd.to_datetime(group["timestamp"], errors="coerce")
+            ax.plot(ts, group["temperature"], marker="o", markersize=3, label=sensor_id)
+        ax.legend(title="Sensor")
+        ax.set_xlabel("Time")
+    else:
+        ax.plot(data.index, data["temperature"], marker="o", markersize=3)
+        ax.set_xlabel("Index")
+    ax.set_ylabel("Temperature")
+    ax.set_title("Temperature Over Time")
+    ax.grid(True, alpha=0.3)
+    fig.autofmt_xdate()
+    fig.tight_layout()
+    return fig
+
+
+@register_plot(SYSTEM_NAME, name="battery_levels", description="Battery level per sensor over time")
+def battery_levels(data) -> plt.Figure:
+    if not isinstance(data, pd.DataFrame) or "battery_level" not in data.columns:
+        fig, ax = plt.subplots()
+        ax.text(0.5, 0.5, "Requires 'battery_level' column", ha="center", va="center")
+        return fig
+
+    fig, ax = plt.subplots(figsize=(12, 5))
+    if "sensor_id" in data.columns and "timestamp" in data.columns:
+        for sensor_id, group in data.groupby("sensor_id"):
+            ts = pd.to_datetime(group["timestamp"], errors="coerce")
+            ax.plot(ts, group["battery_level"], marker="o", markersize=3, label=sensor_id)
+        ax.legend(title="Sensor")
+        ax.set_xlabel("Time")
+    else:
+        ax.plot(data.index, data["battery_level"], marker="o", markersize=3)
+        ax.set_xlabel("Index")
+
+    ax.axhline(y=20, color="orange", linestyle="--", alpha=0.7, label="Low threshold (20%)")
+    ax.axhline(y=10, color="red", linestyle="--", alpha=0.7, label="Critical threshold (10%)")
+    ax.set_ylabel("Battery Level (%)")
+    ax.set_title("Battery Level Over Time")
+    ax.legend(title="Sensor")
+    ax.grid(True, alpha=0.3)
+    fig.autofmt_xdate()
+    fig.tight_layout()
+    return fig
+
+
+@register_plot(SYSTEM_NAME, name="correlation_heatmap", description="Correlation matrix of numeric columns")
+def correlation_heatmap(data) -> plt.Figure:
+    if not isinstance(data, pd.DataFrame):
+        fig, ax = plt.subplots()
+        ax.text(0.5, 0.5, "Requires DataFrame input", ha="center", va="center")
+        return fig
+
+    numeric = data.select_dtypes(include="number")
+    if numeric.empty:
+        fig, ax = plt.subplots()
+        ax.text(0.5, 0.5, "No numeric columns", ha="center", va="center")
+        return fig
+
+    fig, ax = plt.subplots(figsize=(8, 6))
+    corr = numeric.corr()
+    sns.heatmap(corr, annot=True, fmt=".2f", cmap="RdBu_r", center=0, ax=ax, square=True)
+    ax.set_title("Correlation Matrix")
+    fig.tight_layout()
+    return fig
+
+
+@register_plot(SYSTEM_NAME, name="sensor_status_breakdown", description="Pie chart of sensor status counts")
+def sensor_status_breakdown(data) -> plt.Figure:
+    if not isinstance(data, pd.DataFrame) or "status" not in data.columns:
+        fig, ax = plt.subplots()
+        ax.text(0.5, 0.5, "Requires 'status' column", ha="center", va="center")
+        return fig
+
+    status_counts = data["status"].value_counts()
+    colors = {"active": "#28a745", "warning": "#ffc107", "critical": "#dc3545", "inactive": "#6c757d"}
+    pie_colors = [colors.get(s, "#999999") for s in status_counts.index]
+
+    fig, ax = plt.subplots(figsize=(6, 6))
+    ax.pie(status_counts.values, labels=status_counts.index, autopct="%1.0f%%", colors=pie_colors, startangle=90)
+    ax.set_title("Sensor Status Breakdown")
+    fig.tight_layout()
+    return fig
+
+
+# ---------------------------------------------------------------------------
+# Reports
+# ---------------------------------------------------------------------------
+
+@register_report(SYSTEM_NAME, name="sensor_health_report", description="Full health report across all sensors")
+def sensor_health_report(data) -> str:
+    if not isinstance(data, pd.DataFrame):
+        return "Report requires DataFrame input."
+
+    lines = ["# Sensor Health Report", ""]
+
+    lines.append(f"**Total readings:** {len(data)}")
+    if "sensor_id" in data.columns:
+        sensors = data["sensor_id"].nunique()
+        lines.append(f"**Unique sensors:** {sensors}")
+        lines.append(f"**Sensors:** {', '.join(sorted(data['sensor_id'].unique()))}")
+    lines.append("")
+
+    # Missing data
+    null_counts = data.isnull().sum()
+    total_nulls = int(null_counts.sum())
+    lines.append("## Data Completeness")
+    if total_nulls == 0:
+        lines.append("All readings complete — no missing values.")
+    else:
+        lines.append(f"**{total_nulls} missing values** detected:")
+        for col, count in null_counts.items():
+            if count > 0:
+                lines.append(f"- {col}: {count} missing ({count / len(data) * 100:.1f}%)")
+    lines.append("")
+
+    # Battery
+    if "battery_level" in data.columns and "sensor_id" in data.columns:
+        lines.append("## Battery Status")
+        latest_battery = data.groupby("sensor_id")["battery_level"].last()
+        for sensor_id, level in latest_battery.items():
+            if pd.isna(level):
+                emoji = "unknown"
+            elif level < 10:
+                emoji = "CRITICAL"
+            elif level < 20:
+                emoji = "LOW"
+            else:
+                emoji = "OK"
+            display_level = f"{level:.1f}%" if not pd.isna(level) else "N/A"
+            lines.append(f"- **{sensor_id}**: {display_level} [{emoji}]")
+        lines.append("")
+
+    # Temperature
+    if "temperature" in data.columns:
+        temp = data["temperature"].dropna()
+        lines.append("## Temperature Summary")
+        lines.append(f"- Min: {temp.min():.1f}")
+        lines.append(f"- Max: {temp.max():.1f}")
+        lines.append(f"- Mean: {temp.mean():.1f}")
+        lines.append(f"- Std Dev: {temp.std():.1f}")
+        lines.append("")
+
+    # Status
+    if "status" in data.columns:
+        lines.append("## Status Summary")
+        for status, count in data["status"].value_counts().items():
+            lines.append(f"- **{status}**: {count} readings ({count / len(data) * 100:.0f}%)")
+
+    return "\n".join(lines)

diagnostics_framework-0.1.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: diagnostics-framework
+Version: 0.1.0
+Summary: A pluggable diagnostics framework for running system-specific tests, plots, and reports.
+Author: Pam Painter
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pampainter/diagnostics-framework
+Project-URL: Repository, https://github.com/pampainter/diagnostics-framework
+Project-URL: Issues, https://github.com/pampainter/diagnostics-framework/issues
+Keywords: diagnostics,testing,dashboard,streamlit,data-quality,monitoring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: streamlit>=1.30
+Requires-Dist: pandas>=2.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: seaborn>=0.13
+Dynamic: license-file
+
+# Diagnostics Framework
+
+A pluggable Python framework for running diagnostic tests, generating plots, and viewing reports for any system — all from a Streamlit dashboard.
+
+## Overview
+
+The framework uses a **plugin architecture**: each "system" is a self-contained module that registers its own diagnostic tests, plots, and reports using simple decorators. Adding a new system is as easy as dropping a new Python file into the `systems/` folder.
+
+**Built-in example systems:**
+
+| System | Description |
+|--------|-------------|
+| `generic_example` | Basic tabular data checks (nulls, ranges, emptiness) |
+| `sensor_monitoring` | IoT sensor diagnostics with battery health, temperature validation, and status tracking |
+
+## Quick Start
+
+### Install
+
+```bash
+# Create a virtual environment (Python 3.10+ required)
+python -m venv .venv
+source .venv/bin/activate
+
+# Install in editable mode
+pip install -e .
+```
+
+### Run the Dashboard
+
+```bash
+streamlit run diagnostics_framework/app.py
+```
+
+Open http://localhost:8501, select a system, upload a data file, and click **Run Diagnostics**.
+
+A sample dataset is included at `sample_data.csv` for testing the `sensor_monitoring` system.
+
+## Project Structure
+
+```
+diagnostics_framework/
+├── models.py           # Dataclasses: DiagnosticResult, DiagnosticStatus, etc.
+├── registry.py         # Singleton registry + decorator API
+├── runner.py           # Test execution engine with error isolation
+├── app.py              # Streamlit dashboard
+└── systems/
+    ├── __init__.py             # Auto-discovers all system modules
+    ├── generic_example.py      # Example: generic tabular data checks
+    └── sensor_monitoring.py    # Example: IoT sensor diagnostics
+```
+
+## Adding a New System
+
+Create a new file in `diagnostics_framework/systems/` — it will be auto-discovered on import.
+
+```python
+# diagnostics_framework/systems/my_system.py
+from diagnostics_framework import (
+    register_system, register_test, register_plot, register_report,
+    DiagnosticResult, DiagnosticStatus,
+)
+
+SYSTEM_NAME = "my_system"
+
+@register_system(SYSTEM_NAME, description="My custom system")
+class MySystem:
+    pass
+
+@register_test(SYSTEM_NAME, name="my_check", description="Validates something important")
+def my_check(data):
+    # Your test logic here
+    return DiagnosticResult(
+        test_name="my_check",
+        status=DiagnosticStatus.PASS,
+        message="Everything looks good.",
+    )
+
+@register_plot(SYSTEM_NAME, name="my_plot", description="Visualizes the data")
+def my_plot(data):
+    import matplotlib.pyplot as plt
+    fig, ax = plt.subplots()
+    # Your plotting logic here
+    return fig
+
+@register_report(SYSTEM_NAME, name="my_report", description="Summary of findings")
+def my_report(data):
+    return "# My Report\n\nEverything is fine."
+```
+
+That's it — the new system will appear in the dashboard dropdown automatically.
+
+## Decorator API
+
+| Decorator | Purpose |
+|-----------|---------|
+| `@register_system(name, description, version)` | Register a new system |
+| `@register_test(system, name, description)` | Add a diagnostic test |
+| `@register_plot(system, name, description)` | Add a plot generator |
+| `@register_report(system, name, description)` | Add a report generator |
+
+## Diagnostic Result Statuses
+
+| Status | Meaning |
+|--------|---------|
+| `PASS` | Test passed successfully |
+| `FAIL` | Test found a problem |
+| `WARNING` | Test found something worth noting |
+| `ERROR` | Test itself crashed (caught automatically by the runner) |
+
+## Programmatic Usage
+
+You can also use the framework without the dashboard:
+
+```python
+import pandas as pd
+from diagnostics_framework import run_diagnostics
+
+data = pd.read_csv("sample_data.csv")
+summary = run_diagnostics("sensor_monitoring", data)
+
+for result in summary.results:
+    print(f"[{result.status.value}] {result.test_name}: {result.message}")
+```
+
+## Dependencies
+
+- Python >= 3.10
+- streamlit
+- pandas
+- matplotlib
+- seaborn

diagnostics_framework-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+diagnostics_framework/__init__.py,sha256=un66MjUaL-8GUU9ZaXAykQpiRhdH16Bn3dqyBEy4qMc,423
+diagnostics_framework/app.py,sha256=L6rF7plmMKBruA1lcCZAFI-pQZG-WVPtVz_gEyYk3hk,6486
+diagnostics_framework/models.py,sha256=2Q1Fwc-UXloiCp2MR3Nyhfx66N-yWMB7DzDFk50KCRc,1484
+diagnostics_framework/registry.py,sha256=Mefbvr6IeTzkiLl8oC22a5T7TrGQdpgeNqrDhcyPNAQ,2810
+diagnostics_framework/runner.py,sha256=4D1l50Q2MY3BN9HkuUc2Ux6JprcOXpgqutru3sisUqY,2165
+diagnostics_framework/systems/__init__.py,sha256=zly8KsotoHLrSMC-FOiX8sUtETP2JhxXvp-PS08MoUY,310
+diagnostics_framework/systems/generic_example.py,sha256=QQGdJ-UvsAm4S1Ru0ip6aJWQQuMRGjmyhVOQ1eCXolg,7415
+diagnostics_framework/systems/sensor_monitoring.py,sha256=7pXFnnpWoEMjuev-jICxUMMHVOLlq45CQpii38OV-_c,13819
+diagnostics_framework-0.1.0.dist-info/licenses/LICENSE,sha256=L2eX4LNu6Jo0kOKdN-x_a5IZ_AXtAgrKE-jmVXvAj3A,1068
+diagnostics_framework-0.1.0.dist-info/METADATA,sha256=f9Z7AXAqg_g-9Y9NWlqtH5aRw2lTdkBGLfnh4xgrx9Q,5286
+diagnostics_framework-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+diagnostics_framework-0.1.0.dist-info/entry_points.txt,sha256=OeeBCFxEsxcuQCPWlAKehfyBEXWwtwIpgxBH6ofyk_A,63
+diagnostics_framework-0.1.0.dist-info/top_level.txt,sha256=kymk6vfk_5DwR815dhrFqL6V3PjBvcHQJEbsCxh9Vfg,22
+diagnostics_framework-0.1.0.dist-info/RECORD,,

diagnostics_framework-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

diagnostics_framework-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+diagnostics = diagnostics_framework.app:main

diagnostics_framework-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pam Painter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

diagnostics_framework-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+diagnostics_framework