--- 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)