Upload 2 files

README.md

@@ -4,74 +4,75 @@ emoji: 🕳️
 colorFrom: yellow
 colorTo: red
 sdk: gradio
-sdk_version: 4.0.0
+sdk_version: 4.42.0
 app_file: app.py
 pinned: false
+license: mit
+tags:
+- xgboost
+- tabular-regression
+- civic-tech
+- pothole-detection
 ---
 
-# 🛣️ Pothole Severity Scoring Pipeline
+# Model Card for Pothole Severity Scoring
 
-Active ML pipeline for generating synthetic civic data and training an XGBoost-based regression model to predict pothole severity scores ($S \in [0,1]$).
+## Model Details
 
-## 🚀 Quick Start
+### Model Description
 
-1. **Install Dependencies**:
-   ```bash
-   pip install numpy pandas scikit-learn xgboost shap matplotlib joblib
-   ```
+This is an XGBoost Regressor model designed to predict the priority/severity score of civic infrastructure issues (specifically potholes). It evaluates multiple structural, environmental, and temporal features to output a severity score bounded between 0 and 1, assisting civic authorities in prioritizing repairs and resource allocation.
 
-2. **Run Pipeline**:
-   ```bash
-   python severity_model_pipeline.py
-   ```
+- **Developed by:** Civic AI System (Demo)
+- **Model type:** XGBoost Regressor
+- **License:** MIT
 
-## 🏗️ Project Structure
+## Uses
 
-| File | Description |
-| :--- | :--- |
-| `severity_model_pipeline.py` | Main end-to-end pipeline script. |
-| `synthetic_pothole_data.csv` | The generated dataset (10k samples). |
-| `severity_model.json` | Trained XGBoost model (Native JSON format). |
-| `feature_scaler.pkl` | MinMaxScaler for normalizing real-time features. |
-| `feature_list.json` | JSON list ensuring correct feature ordering during inference. |
-| `shap_bar_plot.png` | Global feature importance visualization. |
-| `shap_dot_plot.png` | Detailed SHAP summary plot showing feature impact. |
+### Direct Use
 
-## 📊 Feature Definitions
+The model natively ingests 10 engineered features characterizing a reported pothole and outputs:
+- A numeric severity score ($S \in [0,1]$).
+- A qualitative priority label ("Low", "Medium", "High").
 
-All features are normalized within the range `[0, 1]`:
+This is intended for sorting and prioritizing civil work dispatch queues.
 
-- **A**: Defect area ratio (size relative to image).
-- **D**: Defect density (fragmentation level).
-- **C**: Centrality (distance from road center).
-- **Q**: Detection confidence (CV confidence score).
-- **M**: Multi-user confirmation score (crowdsourced weight).
-- **T**: Temporal persistence (time since detection).
-- **R**: Traffic importance (Highway: 1.0, Main: 0.7, Local: 0.4).
-- **P**: Proximity to critical infrastructure (Hospitals, schools).
-- **F**: Recurrence frequency (historical patch failure).
-- **X**: Resolution failure score (reopen count).
+## Bias, Risks, and Limitations
 
-## 🧠 Model Logic
+The model heavily factors in proximity to critical infrastructure (`P`) and road hierarchy (`R`). While this effectively prioritizes areas like highways and hospitals, it may systematically delay repairs in neglected or local neighborhoods if those areas lack designated local "critical infrastructure". Disparate impact assessments should be run periodically to ensure equitable civic maintenance.
 
-- **Ground Truth Foundation**: 
-  $S_{base} = 0.28A + 0.10D + 0.14C + 0.04Q + 0.08M + 0.07T + 0.09R + 0.10P + 0.06F + 0.04X$
-- **Infrastructure Boost**: $K = 1 + 0.5P$
-- **Final Target**: $S = \min(1, S_{base} * K + \text{Gaussian Noise})$
+## Training Details
 
----
+### Training Data
+
+The model was trained on a synthetically generated dataset of `10,000` samples designed to mirror realistic distributions of civic reporting. Features include:
+- `A`: Defect area ratio
+- `D`: Defect density
+- `C`: Centrality (distance from center)
+- `Q`: Initial detection confidence
+- `M`: Multi-user confirmation score
+- `T`: Temporal persistence (days unresolved)
+- `R`: Traffic importance tier
+- `P`: Proximity to critical infrastructure
+- `F`: Recurrence frequency
+- `X`: Resolution failure count
+
+All features are min-max scaled `[0,1]`.
+
+### Training Procedure 
 
-## 🛠️ Inference Usage
+- **Algorithm:** XGBoost
+- **Objective:** `reg:squarederror`
+- **Trees:** 200
+- **Max Depth:** 5
+- **Learning Rate:** 0.05
 
-You can use the `predict_severity` function within `severity_model_pipeline.py` to get predictions:
+## Evaluation
 
-```python
-from severity_model_pipeline import predict_severity, load_inference_artefacts
+### Testing Data, Factors & Metrics
 
-# Load trained components
-model, scaler, features = load_inference_artefacts()
+Evaluated on a 20% holdout set (`N=2000`).
 
-# Predict
-result = predict_severity(my_data_dict, model, scaler, features)
-print(f"Severity: {result['score']} ({result['label']})")
-```
+- **RMSE:** 0.0312
+- **MAE:** 0.0247
+- **R² Score:** 0.8067

requirements.txt

@@ -3,4 +3,5 @@ pandas
 scikit-learn
 xgboost
 joblib
-gradio
+gradio>=4.42.0
+pyaudioop