updated readme
Browse files
README.md
CHANGED
|
@@ -8,3 +8,75 @@ sdk_version: 5.49.1
|
|
| 8 |
app_file: app.py
|
| 9 |
pinned: false
|
| 10 |
---
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8 |
app_file: app.py
|
| 9 |
pinned: false
|
| 10 |
---
|
| 11 |
+
|
| 12 |
+
# π§ NMS Dementia Risk Assessment API
|
| 13 |
+
**AI Backend for the NMS Mobile App & Web Platform**
|
| 14 |
+
|
| 15 |
+
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.
|
| 16 |
+
|
| 17 |
+
---
|
| 18 |
+
|
| 19 |
+
## β
Core Capabilities
|
| 20 |
+
|
| 21 |
+
### 1. **Dementia Risk Prediction**
|
| 22 |
+
- **Audio-Based Assessment**: Analyzes speech patterns (MFCCs, prosody, articulation) from patient-recorded audio to predict dementia risk.
|
| 23 |
+
- **Lifestyle-Based Assessment**: Evaluates 16+ clinical and behavioral factors (e.g., sleep, diet, cardiovascular health, education) for holistic risk profiling.
|
| 24 |
+
- **SHAP-Powered Explainability (XAI)**: Every prediction includes:
|
| 25 |
+
- Top contributing features (e.g., *"β SleepQuality (3/5) β β risk (+0.18)"*)
|
| 26 |
+
- Plain-language, actionable insights for patients and clinicians.
|
| 27 |
+
|
| 28 |
+
### 2. **Personalized News Curation**
|
| 29 |
+
- **Patient-Focused News**: Scrapes trusted caregiving/dementia advocacy sites (e.g., `caregiving.org`, `alz.org`) and generates **empathetic, jargon-free summaries**.
|
| 30 |
+
- **Clinician-Focused News**: Retrieves and summarizes peer-reviewed research and policy updates (e.g., from open-access sources), emphasizing **clinical relevance and evidence**.
|
| 31 |
+
|
| 32 |
+
---
|
| 33 |
+
|
| 34 |
+
## π€ Agent Architecture (CrewAI)
|
| 35 |
+
|
| 36 |
+
The system uses **4 specialized agents**, each with dedicated tools and LLMs:
|
| 37 |
+
|
| 38 |
+
| Agent | Role | LLM | Tools |
|
| 39 |
+
|-------|------|-----|-------|
|
| 40 |
+
| `Risk Calculator (Audio)` | Runs XGBoost model + SHAP on speech features | `gpt-oss-120b` | `calculate_dementia_risk_audio`, `explain_dementia_risk_audio` |
|
| 41 |
+
| `Risk Calculator (Lifestyle)` | Runs XGBoost model + SHAP on lifestyle data | `gpt-oss-120b` | `calculate_dementia_risk_lifestyle`, `explain_dementia_risk_lifestyle` |
|
| 42 |
+
| `Patient News Agent` | Fetches, scrapes, and summarizes news for patients/caregivers | `Llama-3.1-8B-Instruct` | `gather_news_patient` |
|
| 43 |
+
| `Doctor News Agent` | Fetches, scrapes, and summarizes research for clinicians | `Llama-3.1-8B-Instruct` | `gather_news_doctor` |
|
| 44 |
+
|
| 45 |
+
> π **Why agents?**
|
| 46 |
+
> - Separation of concerns (prediction vs. information retrieval)
|
| 47 |
+
> - Independent scaling & debugging
|
| 48 |
+
> - Audience-tailored language (no technical terms for patients; evidence-first for doctors)
|
| 49 |
+
|
| 50 |
+
---
|
| 51 |
+
|
| 52 |
+
## π οΈ Key Technologies
|
| 53 |
+
|
| 54 |
+
- **Machine Learning**: XGBoost (v3.0.5) for high-accuracy binary classification
|
| 55 |
+
- **Explainability**: SHAP TreeExplainer for model-agnostic, global + local interpretability
|
| 56 |
+
- **Web Scraping**: `requests` + `BeautifulSoup4` (with fallbacks for dynamic sites)
|
| 57 |
+
- **LLM Orchestration**: LiteLLM + Hugging Face Inference API (`meta-llama/Llama-3.1-8B-Instruct`, `openai/gpt-oss-120b`)
|
| 58 |
+
- **Data Pipeline**: Firebase (Firestore for lifestyle, Storage for audio/transcripts)
|
| 59 |
+
- **Deployment**: Hugging Face Spaces (Gradio frontend + CrewAI backend)
|
| 60 |
+
|
| 61 |
+
---
|
| 62 |
+
|
| 63 |
+
## π‘ API Endpoints (via Gradio)
|
| 64 |
+
|
| 65 |
+
| Endpoint | Input | Output |
|
| 66 |
+
|---------|-------|--------|
|
| 67 |
+
| `/assess_risk` | `{ "docID": "umWSG...", "mode": "audio"\|\"lifestyle" }` | Risk level, confidence, SHAP explanations |
|
| 68 |
+
| `/get_news` | `{ "mode": "patientnews"\|\"doctornews", "count": 5 }` | List of `{title, summary, url}` articles |
|
| 69 |
+
|
| 70 |
+
---
|
| 71 |
+
|
| 72 |
+
## π Ethical & Technical Notes
|
| 73 |
+
|
| 74 |
+
- All predictions undergo **SHAP-based validation** to ensure model fairness and transparency.
|
| 75 |
+
- News scraping respects `robots.txt` and uses rate-limiting; open-access/Europe PMC sources prioritized.
|
| 76 |
+
- No personally identifiable information (PII) leaves Firebase β all processing is anonymized.
|
| 77 |
+
|
| 78 |
+
---
|
| 79 |
+
|
| 80 |
+
> π‘ **Developed by** [plutoa386](https://huggingface.co/plutoa386)
|
| 81 |
+
> π **Live Demo**: [Hugging Face Space](https://huggingface.co/spaces/plutoa386/nms-dementia-api)
|
| 82 |
+
> π¦ **Models**: `modelAudiov8_ML.json`, `modelLifestyleV3_ML.json` (XGBoost + SHAP-compatible)
|