plutoa386 commited on
Commit
e5330d0
Β·
1 Parent(s): 2226758

updated readme

Browse files
Files changed (1) hide show
  1. README.md +72 -0
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)