File size: 4,223 Bytes
34bc468
a7555f1
 
 
 
34bc468
 
 
 
 
e5330d0
 
77d41ea
4897642
e5330d0
 
 
4897642
 
e5330d0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4897642
 
e5330d0
 
 
 
 
 
 
 
 
 
 
4897642
e5330d0
4897642
e5330d0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4897642
 
 
 
 
e5330d0
 
 
4897642
77d41ea
3066110
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
---
title: NMS AI DEV
emoji: πŸ€–
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
---

# 🧠 NMS Dementia Risk Assessment API  
**AI Backend for the NMS Mobile App & NMS Web Platform**  
**3rd Year Uni Project**

This repository contains the **agentic AI backend** powering dementia risk assessment and personalized news delivery for the NMS ecosystem. Built on [**CrewAI**](https://crewai.com), it provides scalable, explainable, and audience-aware intelligence for patients, caregivers, and clinicians.

This is my contribution to the NMS group project.

---

## βœ… Core Capabilities

### 1. **Dementia Risk Prediction**
- **Audio-Based Assessment**: Analyzes speech patterns (MFCCs, prosody, articulation) from patient-recorded audio to predict dementia risk.
- **Lifestyle-Based Assessment**: Evaluates 16+ clinical and behavioral factors (e.g., sleep, diet, cardiovascular health, education) for holistic risk profiling.
- **SHAP-Powered Explainability (XAI)**: Every prediction includes:
  - Top contributing features (e.g., *"↓ SleepQuality (3/5) β†’ ↑ risk (+0.18)"*)
  - Plain-language, actionable insights for patients and clinicians.

### 2. **Personalized News Curation**
- **Patient-Focused News**: Scrapes trusted caregiving/dementia advocacy sites (e.g., `caregiving.org`, `alz.org`) and generates **empathetic, jargon-free summaries**.
- **Clinician-Focused News**: Retrieves and summarizes peer-reviewed research and policy updates (e.g., from open-access sources), emphasizing **clinical relevance and evidence**.

---

## πŸ€– Agent Architecture (CrewAI)

The system uses **4 specialized agents**, each with dedicated tools and LLMs:

| Agent | Role | LLM | Tools |
|-------|------|-----|-------|
| `Risk Calculator (Audio)` | Runs XGBoost model + SHAP on speech features | `gpt-oss-120b` | `calculate_dementia_risk_audio`, `explain_dementia_risk_audio` |
| `Risk Calculator (Lifestyle)` | Runs XGBoost model + SHAP on lifestyle data | `gpt-oss-120b` | `calculate_dementia_risk_lifestyle`, `explain_dementia_risk_lifestyle` |
| `Patient News Agent` | Fetches, scrapes, and summarizes news for patients/caregivers | `Qwen3-4B-Thinking-2507` | `gather_news_patient` |
| `Doctor News Agent` | Fetches, scrapes, and summarizes research for clinicians | `Qwen3-4B-Thinking-2507` | `gather_news_doctor` |

> πŸ”‘ **Why agents?**  
> - Separation of concerns (prediction vs. information retrieval)  
> - Independent scaling & debugging  
> - Audience-tailored language (no technical terms for patients; evidence-first for doctors)

---

## πŸ› οΈ Key Technologies

- **Machine Learning**: XGBoost (v3.0.5) for high-accuracy binary classification  
- **XAI (Explainable AI)**: SHAP TreeExplainer for model-agnostic, global + local interpretability  
- **Web Scraping**: `requests` + `BeautifulSoup4` (with fallbacks for dynamic sites)  
- **LLM Orchestration**: LiteLLM + Hugging Face Inference API (`Qwen/Qwen3-4B-Thinking-2507`, `openai/gpt-oss-120b`)  
- **Data Pipeline**: Firebase (Firestore for lifestyle, Storage for audio/transcripts)  
- **Deployment**: Hugging Face Spaces (Gradio frontend + CrewAI backend)

---

## πŸ“‘ API Endpoints (via Gradio)

| Endpoint | Input | Output |
|---------|-------|--------|
| `/assess_risk` | `{ "docID": "umWSG...", "mode": "audio"\|\"lifestyle" }` | Risk level, confidence, SHAP explanations |
| `/get_news` | `{ "mode": "patientnews"\|\"doctornews", "count": 5 }` | List of `{title, summary, url}` articles |

---

## πŸ” Ethical & Technical Notes

- All predictions undergo **SHAP-based validation** to ensure model fairness and transparency.
- No personally identifiable information (PII) leaves Firebase β€” all processing is anonymized.


## ‼️ Disclaimer
 - **This README was generated by AI**
 - The webscraping is mid

---

> πŸ’‘ **Developed by** [plutoa386](https://huggingface.co/plutoa386)  
> 🌐 **Live Demo**: [Hugging Face Space](https://huggingface.co/spaces/plutoa386/nms-ai-dev)  
> πŸ“¦ **Models**: `modelAudiov8_ML.json`, `modelLifestyleV3_ML.json` (XGBoost + SHAP-compatible)  
> πŸ‘Ύ **Old Messy Model Training Repo**: [GitHub](https://github.com/Malekfahad/NMS_Project/tree/NMS-AI)