main.py and README.md final touches

Dockerfile

@@ -19,8 +19,7 @@ COPY requirements.txt requirements-dev.txt ./
 
 # Install dependencies
 RUN pip install --no-cache-dir --upgrade pip \
-    && pip install --no-cache-dir -r requirements.txt \
-    && pip install --no-cache-dir -r requirements-dev.txt
+    && pip install --no-cache-dir -r requirements.txt
 
 # Copy the entire repo
 COPY . .

README.md

@@ -9,81 +9,121 @@ pinned: false
 license: mit
 ---
 
-# Under Construction
-
-Building a production-ready ML inference service with post-deployment drift detection, governance, and alerting, demonstrating real MLOps practices rather than offline modeling.
-
-py -3.9 -m venv .venv
-
-.venv\Scripts\activate
-
-python -m pip install --upgrade pip
-
-pip install -r requirements.txt
-
-uvicorn app.main:app --reload
-
-# Repo Structure
-
-ml-inference-drift-service/
-Dockerfile
-LICENSE
-README.md
-requirements-dev.txt
-requirements.txt
-app/
-    main.py
-    api/
-        background_drift.py
-        dashboard_data.py
-        routes.py
-        schemas.py
-        traffic_daemon.py
-    core/
-        config.py
-        logging.py
-        templates.py
-    inference/
-        predictor.py
-    monitoring/
-        data_loader.py
-        drift.py
-        governance.py
-    static/
-        styles.css
-    templates/
-        dashboard.html
-    utils/
-        alerts.py
-data/
-    processed/
-        credit_default_clean.csv
-        current_data.csv
-    production/
-        predictions_log.csv
-    raw/
-        credit_default.csv
-database/
-logs/
-models/
-    v1/
-        features.json
-        reference_data.csv
-    v2/
-reports/
-    evidently/
-        drift_report.html
-        drift_report.json
-scripts/
-    prepare_data.py
-    simulate_inference.py
-    train.py
-tests/
-    conftest.py
-    integration/
-        test_api.py
-        test_governance.json
-        test_governance.py
-        test_run_drift.py
-    unit/
-        test_schemas.py
+# ML Inference Service with Drift Detection
+
+## Overview
+
+This project is an end-to-end machine learning inference service with post-deployment drift detection and monitoring. It exposes a REST API for model predictions, continuously monitors data for drift using a rolling window, and provides a dashboard to visualize recent predictions and drift metrics.
+
+The system is designed to be deployed locally via Docker or on Hugging Face Spaces, with minimal dependencies and a simple front-end dashboard.
+
+## Repository Structure
+
+```
+ML Inference Service with Drift Detection/
+├─ app/
+│  ├─ api/                   # FastAPI routes, background tasks, and drift logic
+│  ├─ inference/             # Model wrapper and predictor logic
+│  ├─ monitoring/            # Drift checks, governance, and data loaders
+│  ├─ templates/             # HTML templates for dashboard
+│  ├─ utils/                 # Utility scripts like validators and alert senders
+│  ├─ core/                  # Configurations, constants
+│  └─ main.py                # FastAPI entry point with lifespan tasks
+├─ data/
+│  ├─ processed/             # Input CSVs for predictions
+│  ├─ production/            # Predictions log CSV
+├─ models/                   # Model artifacts and reference datasets
+├─ reports/                  # Drift and dashboard JSON/HTML outputs
+│  └─ evidently/             # Drift report JSON
+├─ tests/                    # Unit and integration tests
+├─ Dockerfile                # Container configuration
+├─ requirements.txt          # Python dependencies
+└─ README.md
+```
+
+## Installation (Local / venv)
+
+1. Clone the repository:
+
+   ```bash
+   git clone <repo_url>
+   cd ML Inference Service with Drift Detection
+   ```
+2. Create a virtual environment and activate it:
+
+   ```bash
+   py 3.9 -m venv .venv
+   source .venv/bin/activate  # Linux/macOS
+   .\.venv\Scripts\activate   # Windows
+   ```
+3. Install dependencies:
+
+   ```bash
+   python -m pip install --upgrade pip
+
+   pip install -r requirements-dev.txt
+   ```
+
+## Running the API Locally
+
+1. Start the FastAPI server:
+
+   ```bash
+   uvicorn app.main:app --reload
+   ```
+2. Open the dashboard:
+
+   * Localhost: [http://127.0.0.1:8000/](http://127.0.0.1:8000/)
+3. Predictions can be submitted via the API `/predict` endpoint (multipart CSV upload).
+
+## Testing
+
+1. Run all tests with pytest:
+
+   ```bash
+   pytest -v
+   ```
+2. Integration tests cover API endpoints, predictions, schema validation, and governance alerts.
+
+## How It Works (Logic Layers)
+
+1. **API Layer**: FastAPI routes handle `/predict`, `/dashboard`, `/health`, and `/run-drift`. Predictions are appended to `data/production/predictions_log.csv`.
+2. **Inference Layer**: `Predictor` wraps the model, loads features from `FEATURES_PATH`, and performs batch predictions.
+3. **Background Drift Loop**: Continuously monitors recent predictions (rolling window up to 5,000 rows), runs feature-level drift checks, and writes results to `reports/evidently/drift_report.json`.
+4. **Governance**: Checks metrics like PSI, F1, and regression accuracy against thresholds and logs alerts. Sends notifications via email or Slack (if configured).
+5. **Dashboard**: Reads `drift_report.json` and displays recent predictions and drift metrics via Plotly charts.
+
+## Technology Stack
+
+* Python 3.9
+* FastAPI
+* Pandas / NumPy
+* Joblib (for model serialization)
+* Evidently (drift detection)
+* Plotly (frontend charts)
+* SQLite (optional, currently unused)
+* Docker (for containerized deployment)
+* Hugging Face Spaces (optional deployment)
+
+## Recommendations / Important Notes
+
+* **CSV Rolling Window**: `MAX_DRIFT_ROWS` limits the predictions log to 5,000 rows. Older rows are removed to prevent oversized files.
+* **Email Alerts**: SMTP server must be configured; otherwise, alert sending will fail gracefully.
+* **HF Spaces**: The dashboard runs at `/` endpoint by default for compatibility.
+* **Database**: `database/app.db` is currently unused and can be removed if desired.
+* **UI File Upload**: The legacy CSV upload field in the dashboard can be removed if batch uploads are not needed.
+
+## References / Docs
+
+* [FastAPI Documentation](https://fastapi.tiangolo.com/)
+* [Evidently AI](https://evidentlyai.com/)
+* [Plotly Charts](https://plotly.com/javascript/)
+
+## Contact / Author
+
+* Darkray Accel
+* GitHub: [https://github.com/LeonardoMdSACode](https://github.com/LeonardoMdSACode)
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for details.

app/api/routes.py

@@ -97,6 +97,6 @@ async def predict_file(background_tasks: BackgroundTasks, file: UploadFile = Fil
 def health():
     return {"status": "ok"}
 
-@router.get("/dashboard")
+@router.get("/")
 def dashboard(request: Request):
     return templates.TemplateResponse("dashboard.html", {"request": request})

app/main.py

@@ -132,7 +132,6 @@ from contextlib import asynccontextmanager
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    init_db()
     tasks = [
         asyncio.create_task(traffic_loop()),
         asyncio.create_task(drift_loop(10))

data/production/predictions_log.csv

@@ -60,3 +60,35 @@ credit_limit,age,pay_delay_sep,pay_delay_aug,bill_amt_sep,bill_amt_aug,pay_amt_s
 200000.0,42,2,0,60000.0,58000.0,10000.0,9000.0,,0,0.4295814923706167,Low,v1,2026-01-15 16:25:09.547744+00:00
 50000.0,35,0,-1,12000.0,11000.0,3000.0,2500.0,,0,0.20681478861472152,Low,v1,2026-01-15 16:28:31.134432+00:00
 200000.0,42,2,0,60000.0,58000.0,10000.0,9000.0,,0,0.4295814923706167,Low,v1,2026-01-15 16:28:31.134432+00:00
+20000.0,33,0,0,20276.0,20134.0,1326.0,1326.0,0,0,0.24103223300443963,Low,v1,2026-01-15 16:34:59.730603+00:00
+80000.0,36,1,2,74328.0,75515.0,3000.0,0.0,1,0,0.41621943737111305,Low,v1,2026-01-15 16:35:02.719871+00:00
+170000.0,34,-1,-1,2435.0,0.0,0.0,0.0,0,0,0.11781894939497005,Low,v1,2026-01-15 16:35:02.719871+00:00
+200000.0,27,0,0,185143.0,188678.0,7000.0,7512.0,0,0,0.1469885132838565,Low,v1,2026-01-15 16:35:02.719871+00:00
+50000.0,37,5,4,19859.0,19268.0,0.0,0.0,0,1,0.9285871468011194,High,v1,2026-01-15 16:35:02.719871+00:00
+150000.0,29,-1,2,2599.0,1530.0,0.0,390.0,0,0,0.1753792670431056,Low,v1,2026-01-15 16:35:09.038969+00:00
+300000.0,26,0,0,293880.0,242669.0,11128.0,47009.0,0,0,0.06550496865854624,Low,v1,2026-01-15 16:35:14.486395+00:00
+500000.0,32,0,0,422713.0,406204.0,15000.0,16000.0,0,0,0.06593387266081487,Low,v1,2026-01-15 16:35:14.486395+00:00
+10000.0,43,0,0,4834.0,1803.0,1038.0,1054.0,1,0,0.2643145792109844,Low,v1,2026-01-15 16:35:14.486395+00:00
+50000.0,29,0,0,39124.0,40474.0,2000.0,1700.0,0,0,0.2225164441301266,Low,v1,2026-01-15 16:35:14.486395+00:00
+250000.0,31,-1,0,377399.0,78416.0,10045.0,3194.0,0,0,0.01920239774479085,Low,v1,2026-01-15 16:35:14.486395+00:00
+20000.0,38,0,0,16465.0,18470.0,3000.0,1473.0,0,0,0.248346177111492,Low,v1,2026-01-15 16:35:20.908878+00:00
+400000.0,48,0,0,112789.0,115910.0,5000.0,6624.0,0,0,0.16522251285591869,Low,v1,2026-01-15 16:35:29.336088+00:00
+50000.0,24,-1,-1,1572.0,1572.0,1572.0,1572.0,0,0,0.11850361149255435,Low,v1,2026-01-15 16:35:29.336088+00:00
+110000.0,29,0,0,107336.0,107195.0,5320.0,7845.0,0,0,0.17930034502932266,Low,v1,2026-01-15 16:35:32.875958+00:00
+360000.0,50,-1,-1,1858.0,0.0,0.0,0.0,0,0,0.11367438414700433,Low,v1,2026-01-15 16:35:32.875958+00:00
+290000.0,26,0,0,291861.0,254619.0,9596.0,7700.0,0,0,0.09692545030438433,Low,v1,2026-01-15 16:35:32.875958+00:00
+80000.0,43,0,0,78374.0,80472.0,4000.0,4000.0,0,0,0.22216256487741134,Low,v1,2026-01-15 16:35:32.875958+00:00
+50000.0,35,0,-1,12000.0,11000.0,3000.0,2500.0,,0,0.20681478861472152,Low,v1,2026-01-15 16:39:25.200768+00:00
+200000.0,42,2,0,60000.0,58000.0,10000.0,9000.0,,0,0.4295814923706167,Low,v1,2026-01-15 16:39:25.200768+00:00
+500000.0,26,0,0,16162.0,18581.0,3000.0,1335.0,0,0,0.15298331771846604,Low,v1,2026-01-15 16:39:41.490774+00:00
+260000.0,29,2,0,19006.0,19113.0,6005.0,1525.0,1,0,0.4303606392434953,Low,v1,2026-01-15 16:39:41.490774+00:00
+60000.0,33,-1,0,14932.0,12840.0,5000.0,10390.0,0,0,0.12818843100695615,Low,v1,2026-01-15 16:39:41.490774+00:00
+170000.0,54,-1,-1,186.0,116.0,116.0,0.0,0,0,0.14040673151255778,Low,v1,2026-01-15 16:39:49.465272+00:00
+200000.0,29,-1,-1,3655.0,3036.0,3084.0,3475.0,0,0,0.10386777515897552,Low,v1,2026-01-15 16:39:49.465272+00:00
+310000.0,53,-2,-2,1126.0,2603.0,2635.0,0.0,0,0,0.059470708342318636,Low,v1,2026-01-15 16:39:49.465272+00:00
+320000.0,29,-2,-2,5118.0,3743.0,6783.0,8063.0,0,0,0.041545173334793836,Low,v1,2026-01-15 16:39:56.188731+00:00
+50000.0,44,0,0,43828.0,40684.0,1947.0,1829.0,0,0,0.24317333333089378,Low,v1,2026-01-15 16:39:56.188731+00:00
+280000.0,36,-2,-2,2874.0,2874.0,2888.0,2888.0,0,0,0.050791529010223366,Low,v1,2026-01-15 16:39:56.188731+00:00
+280000.0,36,-2,-2,198.0,1979.0,1979.0,500.0,0,0,0.05293378034616363,Low,v1,2026-01-15 16:39:56.188731+00:00
+60000.0,40,0,0,28738.0,30216.0,4000.0,1010.0,1,0,0.23867262599538985,Low,v1,2026-01-15 16:39:56.188731+00:00
+400000.0,29,0,0,5074.0,4097.0,1097.0,3716.0,0,0,0.17183267351342854,Low,v1,2026-01-15 16:40:01.268559+00:00

reports/evidently/drift_report.json

@@ -1,5 +1,5 @@
 {
-  "n_rows": 57,
+  "n_rows": 87,
   "results": [
     {
       "row": 0,
@@ -342,44 +342,224 @@
       "prediction": "No Default",
       "probability": 0.2165,
       "risk_level": "Low"
+    },
+    {
+      "row": 57,
+      "prediction": "No Default",
+      "probability": 0.2068,
+      "risk_level": "Low"
+    },
+    {
+      "row": 58,
+      "prediction": "No Default",
+      "probability": 0.4296,
+      "risk_level": "Low"
+    },
+    {
+      "row": 59,
+      "prediction": "No Default",
+      "probability": 0.2068,
+      "risk_level": "Low"
+    },
+    {
+      "row": 60,
+      "prediction": "No Default",
+      "probability": 0.4296,
+      "risk_level": "Low"
+    },
+    {
+      "row": 61,
+      "prediction": "No Default",
+      "probability": 0.241,
+      "risk_level": "Low"
+    },
+    {
+      "row": 62,
+      "prediction": "No Default",
+      "probability": 0.4162,
+      "risk_level": "Low"
+    },
+    {
+      "row": 63,
+      "prediction": "No Default",
+      "probability": 0.1178,
+      "risk_level": "Low"
+    },
+    {
+      "row": 64,
+      "prediction": "No Default",
+      "probability": 0.147,
+      "risk_level": "Low"
+    },
+    {
+      "row": 65,
+      "prediction": "Default",
+      "probability": 0.9286,
+      "risk_level": "High"
+    },
+    {
+      "row": 66,
+      "prediction": "No Default",
+      "probability": 0.1754,
+      "risk_level": "Low"
+    },
+    {
+      "row": 67,
+      "prediction": "No Default",
+      "probability": 0.0655,
+      "risk_level": "Low"
+    },
+    {
+      "row": 68,
+      "prediction": "No Default",
+      "probability": 0.0659,
+      "risk_level": "Low"
+    },
+    {
+      "row": 69,
+      "prediction": "No Default",
+      "probability": 0.2643,
+      "risk_level": "Low"
+    },
+    {
+      "row": 70,
+      "prediction": "No Default",
+      "probability": 0.2225,
+      "risk_level": "Low"
+    },
+    {
+      "row": 71,
+      "prediction": "No Default",
+      "probability": 0.0192,
+      "risk_level": "Low"
+    },
+    {
+      "row": 72,
+      "prediction": "No Default",
+      "probability": 0.2483,
+      "risk_level": "Low"
+    },
+    {
+      "row": 73,
+      "prediction": "No Default",
+      "probability": 0.1652,
+      "risk_level": "Low"
+    },
+    {
+      "row": 74,
+      "prediction": "No Default",
+      "probability": 0.1185,
+      "risk_level": "Low"
+    },
+    {
+      "row": 75,
+      "prediction": "No Default",
+      "probability": 0.1793,
+      "risk_level": "Low"
+    },
+    {
+      "row": 76,
+      "prediction": "No Default",
+      "probability": 0.1137,
+      "risk_level": "Low"
+    },
+    {
+      "row": 77,
+      "prediction": "No Default",
+      "probability": 0.0969,
+      "risk_level": "Low"
+    },
+    {
+      "row": 78,
+      "prediction": "No Default",
+      "probability": 0.2222,
+      "risk_level": "Low"
+    },
+    {
+      "row": 79,
+      "prediction": "No Default",
+      "probability": 0.2068,
+      "risk_level": "Low"
+    },
+    {
+      "row": 80,
+      "prediction": "No Default",
+      "probability": 0.4296,
+      "risk_level": "Low"
+    },
+    {
+      "row": 81,
+      "prediction": "No Default",
+      "probability": 0.153,
+      "risk_level": "Low"
+    },
+    {
+      "row": 82,
+      "prediction": "No Default",
+      "probability": 0.4304,
+      "risk_level": "Low"
+    },
+    {
+      "row": 83,
+      "prediction": "No Default",
+      "probability": 0.1282,
+      "risk_level": "Low"
+    },
+    {
+      "row": 84,
+      "prediction": "No Default",
+      "probability": 0.1404,
+      "risk_level": "Low"
+    },
+    {
+      "row": 85,
+      "prediction": "No Default",
+      "probability": 0.1039,
+      "risk_level": "Low"
+    },
+    {
+      "row": 86,
+      "prediction": "No Default",
+      "probability": 0.0595,
+      "risk_level": "Low"
     }
   ],
   "drift": [
     {
       "column": "dataset",
-      "score": 0.875
+      "score": 0.75
     },
     {
       "column": "age",
-      "score": 0.23371009362458137
+      "score": 0.15611149622024934
     },
     {
       "column": "bill_amt_aug",
-      "score": 0.15297297061013115
+      "score": 0.12250072824204197
     },
     {
       "column": "bill_amt_sep",
-      "score": 0.15343706502680868
+      "score": 0.18763213901625655
     },
     {
       "column": "credit_limit",
-      "score": 0.31403434449489975
+      "score": 0.1713948991364952
     },
     {
       "column": "pay_amt_aug",
-      "score": 0.11849030297054779
+      "score": 0.08246967085476054
     },
     {
       "column": "pay_amt_sep",
-      "score": 0.12469609378058553
+      "score": 0.11861811820004925
     },
     {
       "column": "pay_delay_aug",
-      "score": 0.2553718164587327
+      "score": 0.21519799744256923
     },
     {
       "column": "pay_delay_sep",
-      "score": 0.07397843471719741
+      "score": 0.07734517509505544
     }
   ]
 }