NMS_AI / README.md
plutoa386's picture
fix
7860dc0
|
Raw History Blame Contribute Delete
4.21 kB
---
title: NMS AI
emoji: 🧠
colorFrom: red
colorTo: pink
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)
> πŸ“¦ **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)