Merge pull request #2 from Khanz9664/monitoring_module

feat(monitoring): Integrate Production-Grade Clinical Monitoring & Visual Documentation Suite

Author: Khanz9664

.coverage

@@ -119,19 +119,22 @@ uvicorn api.main:app --host 0.0.0.0 --port 8000
 - **The Safety & Trust Framework**: Implements ACC/AHA guideline overrides and out-of-distribution (OOD) monitoring.
 - **The Optimization Engine**: Calculates the "Least Effort Path" to risk reduction using clinical cost-weights.
 - **The Explainability Engine**: Powered by SHAP and LIME for local feature-level contributions and model reasoning.
+- **Modern Infrastructure**: Fully integrated **FastAPI Lifespan** management and hardened monitoring (variance guards).
 
 ---
 
 | Metric | Score | Professional Interpretation |
 | :--- | :--- | :--- |
-| **Model Version** | **XGB-O.1.2** | Optuna-optimized gradient boosted legacy engine. |
-| **Clinical Accuracy** | **90.16%** | Production-grade stability via robust preprocessing. |
-| **ROC-AUC Score** | **0.9524** | Exceptional ability to distinguish risk from health. |
-| **PR-AUC Score** | **0.9272** | High precision-recall balance for clinical flagging. |
-| **Recall (Sens.)** | **92.86%** | Minimized false negatives for patient safety. |
-| **F1 Score** | **0.8966** | Robust harmonic mean of precision and recall. |
+| **Model Version** | **v2.4.0** | Professional gradient boosted clinical engine. |
+| **Clinical Accuracy** | **88.52%** | Production-grade stability via robust preprocessing. |
+| **ROC-AUC Score** | **0.9621** | Exceptional ability to distinguish risk from health. |
+| **PR-AUC Score** | **0.9553** | High precision-recall balance for clinical flagging. |
+| **Recall (Sens.)** | **92.86%** | Maximized sensitivity for patient safety (Min FN). |
+| **F1 Score** | **0.8814** | Robust harmonic mean of precision and recall. |
+| **Test Coverage** | **63%** | Comprehensive unit testing across core clinical logic. |
+| **Clinical Tests** | **40** | Total verified clinical scenarios and edge cases. |
 | **Safety Engine** | **Active** | Standard-of-care guardrails for critical vitals. |
-| **Auditability** | **Enabled** | Full request tracing and model state hashing. |
+| **Auditability** | **Enabled** | Full request tracing (Lifespan) and state hashing. |
 
 ---
 

README.md

@@ -3,6 +3,7 @@
 import logging
 from fastapi import FastAPI, HTTPException, Request
 from fastapi.responses import JSONResponse
+from contextlib import asynccontextmanager
 from pydantic import BaseModel, Field
 import pandas as pd
 import joblib
@@ -11,27 +12,20 @@
 import uvicorn
 from src.models.predict import HeartDiseasePredictor
 from src.utils.logger import setup_logger
+from src.monitoring.logger import MonitoringLogger
+from src.monitoring.engine import MonitoringEngine
+from src.utils.version_utils import get_model_version
+from fastapi import BackgroundTasks
 
 # Initialize Production-Grade Logger
 logger = setup_logger("API-ENGINE")
 
-app = FastAPI(
-    title="CardioSense AI Inference Gateway",
-    description="Production-grade clinical API for real-time risk assessment with traceability and audit logging.",
-    version="2.1.0"
-)
-
-# Configuration & Loaders
-MODEL_PATH = "models/heart_disease_model.joblib"
-PREPROCESSOR_PATH = "models/preprocessor.joblib"
-METADATA_PATH = "models/model_metadata.json"
-
-predictor = None
-metadata = None
-model_version = "Unknown"
-
-@app.on_event("startup")
-def startup_event():
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Lifespan context manager for initializing clinical model artifacts
+    and cleaning up resources on shutdown.
+    """
     global predictor, metadata, model_version
     logger.info("Initializing Clinical Intelligence System...")
 
@@ -46,10 +40,34 @@ def startup_event():
         try:
             with open(METADATA_PATH, 'r') as f:
                 metadata = json.load(f)
-                model_version = metadata.get("version", "1.0.0")
+                model_version = metadata.get("version", "2.4.0")
+                app.version = model_version # Sync FastAPI version if metadata updated
             logger.info(f"Clinical metadata loaded. Active Model Version: {model_version}")
         except Exception as e:
             logger.error(f"Startup Warning: Could not parse metadata. {e}")
+            
+    yield
+    # Cleanup logic (if needed) can go here
+    logger.info("Shutting down Clinical Intelligence System...")
+
+app = FastAPI(
+    title="CardioSense AI: Clinical Decision Support API",
+    description="Medical-grade cardiovascular risk stratification engine with integrated ACC/AHA safety guardrails and multi-modal explainability.",
+    version=get_model_version(),
+    lifespan=lifespan
+)
+
+# Configuration & Loaders
+MODEL_PATH = "models/heart_disease_model.joblib"
+PREPROCESSOR_PATH = "models/preprocessor.joblib"
+METADATA_PATH = "models/model_metadata.json"
+
+predictor = None
+metadata = None
+model_version = "Unknown"
+mon_logger = MonitoringLogger()
+mon_engine = MonitoringEngine()
+
 
 # --- PRODUCTION MIDDLEWARE ---
 
@@ -129,11 +147,11 @@ def health_check():
     }
 
 @app.post("/predict")
-def predict_risk(request: Request, data: PatientData):
+def predict_risk(request: Request, data: PatientData, background_tasks: BackgroundTasks):
     """
-    Executes real-time clinical risk prediction.
+    Executes real-time clinical risk prediction with background monitoring.
     """
-    request_id = request.headers.get("X-Request-ID", "N/A")
+    request_id = request.headers.get("X-Request-ID", str(uuid.uuid4()))
 
     if not predictor:
         logger.warning(f"REQ [{request_id}] | Inference attempted while model is offline.")
@@ -142,16 +160,49 @@ def predict_risk(request: Request, data: PatientData):
     input_df = pd.DataFrame([data.dict()])
     prediction, probability = predictor.predict(input_df)
 
+    prob_val = round(float(probability[0][1]), 4)
     result = {
         "prediction": int(prediction[0]),
-        "risk_probability": round(float(probability[0][1]), 4),
+        "risk_probability": prob_val,
         "status": "Positive (High Risk)" if prediction[0] == 1 else "Negative (Low Risk)",
         "model_version": model_version,
         "request_id": request_id
     }
 
-    logger.info(f"REQ [{request_id}] | Inference Successful | Result: {result['status']} ({result['risk_probability']})")
+    # Async Persistence for Drift Monitoring
+    background_tasks.add_task(
+        mon_logger.log_prediction, 
+        request_id, input_df, prediction[0], prob_val, model_version
+    )
+    
+    logger.info(f"REQ [{request_id}] | Inference Successful | Result: {result['status']}")
     return result
 
+@app.post("/feedback/{request_id}")
+def submit_feedback(request_id: str, actual_outcome: int):
+    """
+    Clinician endpoint to submit ground truth outcome (0: Healthy, 1: Disease) 
+    for Concept Drift monitoring.
+    """
+    try:
+        mon_logger.log_feedback(request_id, actual_outcome)
+        return {"status": "Feedback recorded", "request_id": request_id}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.get("/monitoring/status")
+def get_monitoring_status():
+    """
+    Returns a high-level summary of data and concept drift.
+    """
+    drift_stats = mon_engine.run_drift_analysis(window_size=100)
+    perf_stats = mon_engine.run_performance_audit()
+    
+    return {
+        "drift": drift_stats,
+        "performance": perf_stats,
+        "timestamp": time.time()
+    }
+
 if __name__ == "__main__":
     uvicorn.run(app, host="0.0.0.0", port=8000)