diagnostics-framework 0.1.0__tar.gz

diagnostics_framework-0.1.0/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/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+include sample_data.csv

diagnostics_framework-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,132 @@
+# 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/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-0.1.0/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-0.1.0/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-0.1.0/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