Add Kaggle-trained BRFSS risk model and production deployment path.

Train on CDC diabetes indicators with CV, tuning, and calibration; load artifacts in the API/UI; add AWS App Runner Terraform and Kaggle automation scripts.

Author: adit24dhaya

.env.example

@@ -3,3 +3,4 @@ API_TOKEN=dev-token-change-me
 REQUIRE_API_TOKEN=false
 REQUEST_TIMEOUT_SECONDS=25
 LOG_DIR=./logs
+MODEL_ARTIFACT_PATH=./artifacts/risk_model.joblib

.gitignore

@@ -5,3 +5,5 @@ __pycache__/
 logs/
 .coverage
 data/chroma/
+artifacts/*.joblib
+artifacts/*.log

README.md

@@ -6,7 +6,8 @@ An autonomous AI system that analyzes patient data, estimates health risk, expla
 
 This project combines:
 
-- A machine learning risk model (`LogisticRegression`) for baseline probability estimation
+- A machine learning risk model for baseline probability estimation
+- A Kaggle-trained production model path using the CDC Diabetes Health Indicators dataset
 - An orchestrator agent that coordinates specialized agents
 - LLM-powered explanation and recommendation generation
 - Retrieval-augmented context from a local medical knowledge base
@@ -33,7 +34,9 @@ Detailed diagram: [`docs/architecture.md`](docs/architecture.md)
 
 ## Key Features
 
-- **Risk prediction** from patient vitals and demographic inputs
+- **Risk prediction** from patient vitals, demographics, lifestyle, and access inputs
+- **Production training pipeline** for CDC BRFSS diabetes indicators on Kaggle
+- **Persisted model artifact loading** with local CSV fallback for development
 - **Internal BMI computation** from height and weight
 - **Risk classification** into Low / Medium / High
 - **SHAP explainability** to show feature impact on risk
@@ -49,10 +52,12 @@ Detailed diagram: [`docs/architecture.md`](docs/architecture.md)
 
 - **Language**: Python 3.10+
 - **ML**: scikit-learn, pandas, shap
+- **Training**: Kaggle, persisted `joblib` artifacts, model card + metrics JSON
 - **LLM**: OpenAI API
 - **Memory/Vector Store**: ChromaDB
 - **Backend API**: FastAPI, Uvicorn
 - **Frontend**: Streamlit
+- **Deployment**: Docker, AWS App Runner, ECR, Terraform
 
 ## Project Structure
 
@@ -63,12 +68,22 @@ healthcare-agent-system/
 │   ├── explainer.py
 │   ├── recommender.py
 │   └── retriever.py
+├── artifacts/
+│   └── risk_model.joblib
 ├── api/
 │   └── app.py
 ├── data/
 │   ├── patients.csv
 │   ├── medical_knowledge.jsonl
 │   └── chroma/
+├── docs/
+│   ├── aws_deployment.md
+│   └── kaggle_training.md
+├── infra/
+│   └── aws/apprunner/
+├── kaggle/
+│   ├── kaggle_train.py
+│   └── kernel-metadata.json
 ├── memory/
 │   └── store.py
 ├── models/
@@ -87,11 +102,11 @@ healthcare-agent-system/
 
 ## How the System Works
 
-1. User provides patient attributes (`age`, `height_cm`, `weight_kg`, `blood_pressure`, optional `glucose`)
+1. User provides patient attributes (`age`, `height_cm`, `weight_kg`, `bp`, optional `glucose`, and optional BRFSS-style health indicators)
 2. System computes BMI internally (`kg / m^2`)
 3. Risk model predicts probability of elevated risk
 4. Risk classifier maps probability -> `Low` / `Medium` / `High`
-5. SHAP computes feature contribution scores
+5. Feature explainer computes SHAP or local sensitivity contribution scores
 6. Retrieval agent fetches relevant medical context
 7. Memory agent retrieves similar historical cases and stores new case
 8. Explanation and recommendation agents generate human-friendly outputs
@@ -127,10 +142,45 @@ Create a `.env` file (or export directly):
 
 ```bash
 export OPENAI_API_KEY="your_api_key_here"
+export MODEL_ARTIFACT_PATH="./artifacts/risk_model.joblib"
 ```
 
 > The explanation/recommendation agents require a valid OpenAI key.
 
+If `MODEL_ARTIFACT_PATH` points to a trained Kaggle artifact, the app loads it at
+startup. If the artifact is missing, the app falls back to `data/patients.csv`.
+
+## Train The Production Model On Kaggle
+
+Training runs on Kaggle against the CDC Diabetes Health Indicators dataset
+(`alexteboul/diabetes-health-indicators-dataset`). Your machine only uploads the script
+and downloads the trained artifact.
+
+```bash
+chmod +x scripts/kaggle_run.sh
+./scripts/kaggle_run.sh
+```
+
+Kernel: `aditya2402/healthcare-ai-diabetes-risk-training`  
+Script: [`kaggle/kaggle_train.py`](kaggle/kaggle_train.py)
+
+See [`docs/kaggle_training.md`](docs/kaggle_training.md) and [`kaggle/README.md`](kaggle/README.md).
+
+## Deploy To AWS
+
+The API deploys as a Dockerized FastAPI service on AWS App Runner with ECR and Terraform.
+
+```bash
+cd infra/aws/apprunner
+terraform init
+terraform apply -target=aws_ecr_repository.api
+terraform apply -var "api_token=replace-with-a-strong-token"
+```
+
+After the first targeted apply creates ECR, build and push the Docker image from the
+repo root, then run the full apply. See [`docs/aws_deployment.md`](docs/aws_deployment.md) and
+[`infra/aws/apprunner/README.md`](infra/aws/apprunner/README.md).
+
 ## Run the Project
 
 ### Run CLI demo
@@ -177,7 +227,7 @@ Typical `/predict` response includes:
 
 - Risk probability + risk label
 - Calculated BMI
-- SHAP feature impacts
+- Feature impact scores
 - Retrieved medical context
 - Similar past cases
 - Explanation text
@@ -213,7 +263,7 @@ Each record includes timestamp, request ID, normalized patient summary, risk res
   "age": 45,
   "height_cm": 175,
   "weight_kg": 78,
-  "blood_pressure": 130,
+  "bp": 130,
   "glucose": 165
 }
 ```
@@ -227,10 +277,10 @@ Always consult qualified healthcare professionals for real medical advice.
 
 ## Current Limitations
 
-- Model training data is currently small/synthetic
+- Kaggle artifact must be trained/downloaded before production deployment
 - Recommendations are generated by LLM and may require strict clinical guardrails
 - No full production security/compliance pipeline yet (PHI/HIPAA hardening)
-- Evaluation and fairness benchmarking should be expanded
+- Fairness, calibration, and drift monitoring should be expanded
 
 ## Roadmap
 
@@ -244,11 +294,10 @@ Always consult qualified healthcare professionals for real medical advice.
 
 ### Planned (Phase 3+)
 
-- Better datasets and stronger model validation
+- Fairness reports, calibration plots, and drift monitoring
 - Safety guardrails and escalation logic
 - Automated tests and CI pipeline
 - Better observability and decision tracing
-- Containerized deployment (Docker)
 - Feedback loops for continuous learning
 
 ### Implemented in Phase 3
@@ -274,6 +323,14 @@ Always consult qualified healthcare professionals for real medical advice.
 - Added local pre-commit hooks for code quality
 - Added Dependabot automation for pip and GitHub Actions updates
 
+### Implemented in Phase 5
+
+- Added Kaggle training workflow for the CDC Diabetes Health Indicators dataset
+- Added persisted `joblib` artifact loading with local fallback
+- Expanded API/UI inputs for BRFSS-style health indicators
+- Added production training script with model comparison and metrics output
+- Added AWS App Runner Terraform deployment stack
+
 ## Security Notes
 
 See [`docs/security.md`](docs/security.md) for PII handling guidance, retention policy, and hardening recommendations.

agents/orchestrator.py

@@ -72,4 +72,5 @@ def run(self, patient_data):
             "safety": safety,
             "explanation": explanation,
             "recommendation": recommendation,
+            "model": self.model.artifact_metadata,
         }

api/app.py

@@ -26,6 +26,24 @@ class PatientRequest(BaseModel):
     bmi: Optional[float] = Field(None, ge=0, le=80)
     bp: int = Field(..., ge=0, le=260)
     glucose: Optional[float] = Field(None, ge=0, le=500)
+    high_chol: Optional[bool] = None
+    chol_check: Optional[bool] = None
+    smoker: Optional[bool] = None
+    stroke: Optional[bool] = None
+    heart_disease_or_attack: Optional[bool] = None
+    phys_activity: Optional[bool] = None
+    fruits: Optional[bool] = None
+    veggies: Optional[bool] = None
+    heavy_alcohol_consump: Optional[bool] = None
+    any_healthcare: Optional[bool] = None
+    no_doc_bc_cost: Optional[bool] = None
+    general_health: Optional[int] = Field(None, ge=1, le=5)
+    mental_health_days: Optional[int] = Field(None, ge=0, le=30)
+    physical_health_days: Optional[int] = Field(None, ge=0, le=30)
+    diff_walk: Optional[bool] = None
+    sex: Optional[str] = Field(None, pattern="^(female|male|0|1|F|M|f|m)$")
+    education: Optional[int] = Field(None, ge=1, le=6)
+    income: Optional[int] = Field(None, ge=1, le=8)
 
 
 class ChatRequest(BaseModel):

artifacts/.gitkeep

@@ -0,0 +1 @@
+

artifacts/metrics.json

@@ -0,0 +1,149 @@
+{
+  "schema_version": 2,
+  "trained_at": "2026-05-18T04:25:44.982333+00:00",
+  "dataset_slug": "alexteboul/diabetes-health-indicators-dataset",
+  "dataset_path": "/kaggle/input/datasets/alexteboul/diabetes-health-indicators-dataset/diabetes_binary_health_indicators_BRFSS2015.csv",
+  "target": "Diabetes_binary",
+  "rows_total": 253680,
+  "rows_train": 202944,
+  "rows_test": 50736,
+  "feature_names": [
+    "HighBP",
+    "HighChol",
+    "CholCheck",
+    "BMI",
+    "Smoker",
+    "Stroke",
+    "HeartDiseaseorAttack",
+    "PhysActivity",
+    "Fruits",
+    "Veggies",
+    "HvyAlcoholConsump",
+    "AnyHealthcare",
+    "NoDocbcCost",
+    "GenHlth",
+    "MentHlth",
+    "PhysHlth",
+    "DiffWalk",
+    "Sex",
+    "Age",
+    "Education",
+    "Income"
+  ],
+  "selected_model": "hist_gradient_boosting",
+  "selection_method": "5-fold_cv_then_holdout_test",
+  "calibration": "isotonic_cv3",
+  "tuned_models": [
+    "hist_gradient_boosting",
+    "lightgbm"
+  ],
+  "lightgbm_available": true,
+  "metrics": {
+    "logistic_regression": {
+      "cv_roc_auc_mean": 0.8233,
+      "cv_roc_auc_std": 0.00144,
+      "roc_auc": 0.8196,
+      "average_precision": 0.39165,
+      "brier_score": 0.09928,
+      "accuracy_at_0_5": 0.86239,
+      "precision_at_0_5": 0.53234,
+      "recall_at_0_5": 0.10129,
+      "f1_at_0_5": 0.17019,
+      "selected_threshold": 0.22077,
+      "accuracy": 0.78506,
+      "precision": 0.35327,
+      "recall": 0.65327,
+      "f1": 0.45857,
+      "confusion_matrix": {
+        "true_negative": 35213,
+        "false_positive": 8454,
+        "false_negative": 2451,
+        "true_positive": 4618
+      }
+    },
+    "hist_gradient_boosting": {
+      "cv_roc_auc_mean": 0.83059,
+      "cv_roc_auc_std": 0.00232,
+      "best_params": {
+        "min_samples_leaf": 40,
+        "max_iter": 350,
+        "max_depth": null,
+        "learning_rate": 0.05,
+        "l2_regularization": 0.1
+      },
+      "cv_roc_auc_tune": 0.83034,
+      "roc_auc": 0.82698,
+      "average_precision": 0.42299,
+      "brier_score": 0.09739,
+      "accuracy_at_0_5": 0.86536,
+      "precision_at_0_5": 0.56503,
+      "recall_at_0_5": 0.14627,
+      "f1_at_0_5": 0.23239,
+      "selected_threshold": 0.22379,
+      "accuracy": 0.80075,
+      "precision": 0.37302,
+      "recall": 0.63163,
+      "f1": 0.46904,
+      "confusion_matrix": {
+        "true_negative": 36162,
+        "false_positive": 7505,
+        "false_negative": 2604,
+        "true_positive": 4465
+      }
+    },
+    "random_forest": {
+      "cv_roc_auc_mean": 0.82118,
+      "cv_roc_auc_std": 0.00215,
+      "roc_auc": 0.82434,
+      "average_precision": 0.41728,
+      "brier_score": 0.09791,
+      "accuracy_at_0_5": 0.86509,
+      "precision_at_0_5": 0.56154,
+      "recall_at_0_5": 0.14457,
+      "f1_at_0_5": 0.22995,
+      "selected_threshold": 0.23549,
+      "accuracy": 0.80527,
+      "precision": 0.3767,
+      "recall": 0.60744,
+      "f1": 0.46502,
+      "confusion_matrix": {
+        "true_negative": 36562,
+        "false_positive": 7105,
+        "false_negative": 2775,
+        "true_positive": 4294
+      }
+    },
+    "lightgbm": {
+      "cv_roc_auc_mean": 0.82868,
+      "cv_roc_auc_std": 0.00235,
+      "best_params": {
+        "subsample": 0.8,
+        "num_leaves": 31,
+        "n_estimators": 200,
+        "min_child_samples": 40,
+        "learning_rate": 0.03,
+        "colsample_bytree": 1.0
+      },
+      "cv_roc_auc_tune": 0.83017,
+      "roc_auc": 0.8269,
+      "average_precision": 0.42152,
+      "brier_score": 0.09745,
+      "accuracy_at_0_5": 0.86528,
+      "precision_at_0_5": 0.5627,
+      "recall_at_0_5": 0.14854,
+      "f1_at_0_5": 0.23503,
+      "selected_threshold": 0.23289,
+      "accuracy": 0.80487,
+      "precision": 0.37788,
+      "recall": 0.61961,
+      "f1": 0.46945,
+      "confusion_matrix": {
+        "true_negative": 36456,
+        "false_positive": 7211,
+        "false_negative": 2689,
+        "true_positive": 4380
+      }
+    }
+  },
+  "sklearn_version": "1.6.1"
+}