How swetha-arul/ai-mental-health-monitoring-system works
1. This repository is a single Python-based, multi-agent inference system for mental health risk estimation. It does not expose separate services or microservices; instead, simulate.py acts as the top-level orchestrator and user-facing entry point.
2. The presentation layer is a Gradio interface in simulate.py. It collects two distinct input streams: free-form text from the user and wearable/physiological metrics. The UI is meant for real-time simulation rather than batch processing.
3. The first analysis boundary is the text_agent/ package. text_agent/main.py runs a local fine-tuned DistilBERT sentiment/emotion classifier using the bundled Hugging Face model assets under text_agent/sentiment-analysis-model/. Its output is a text label plus confidence, representing emotional state from journal-like or social text.
4. The second analysis boundary is the wearable_agent/ package. wearable_agent/main.py loads serialized preprocessing and classification artifacts: stress_model_xgb.pkl, scaler.pkl, and label_encoder.pkl. This agent predicts stress level from numeric health/activity features such as heart rate, sleep, steps, and calories.
5. The wearable pipeline is explicitly model-driven but has a safety boundary: the README notes rule-based fallback behavior if model files are unavailable. That means the agent can degrade gracefully instead of failing hard when the serialized artifacts cannot be loaded.
6. The fusion_agent/ package is the decision layer. It combines the text agent and wearable agent outputs with a weighted fusion strategy, defaulting to 60% text and 40% wearable. This layer is responsible for transforming two modality-specific predictions into a single mental health risk score.
7. The fusion layer also owns the user-facing interpretation logic. It maps the combined score into one of four risk bands: Low, Mild, Moderate, or High, and generates contextual warnings, advice, and supportive messages. In architecture terms, this is the boundary between raw ML predictions and human-readable guidance.
8. Data flow is strictly downstream: user input enters the Gradio UI, then splits into two independent inference paths, and finally converges in the fusion agent. There is no evidence of a shared feature store, external database, or online training loop in the repo.
9. The system includes longitudinal logging via JSONL in the fusion layer. The README references results_log.jsonl, which indicates append-only record keeping for previous assessments and supports simple audit/history tracking without a database.
10. The repository is fully self-contained for inference because the model artifacts are stored locally in the repo tree. The only runtime dependency outside the codebase is the Python environment defined by requirements.txt, with Gradio for UI and ML libraries for transformer and XGBoost-based inference.
11. Operationally, the key architectural distinction is modality separation: unstructured text and structured wearable metrics are processed by different models, then merged late. That separation is what makes the diagram useful: two specialized analyzers feeding one fusion-and-explanation layer, all behind a single interactive front end.
12. The project’s output is advisory, not diagnostic. The disclaimer matters architecturally because it frames the system as decision support and messaging, not a clinical workflow or medical-record system.
Main entry points: wearable_agent/main.py Wearable agent · fusion_agent/main.py Fusion engine · text_agent/main.py Text agent · simulate.py Simulation UI
Components 12
Interactive front end
Single Gradio entry point for real-time simulation and input collection.
- Simulation UI · Top-level entry point that collects text and wearable inputs for live simulation.
simulate.py - Text stream · User journal-like or social text provided to the simulation.
- Wearable stream · Heart rate, sleep, steps, calories, and related physiological/activity metrics.
Text analysis
Unstructured text is classified separately from wearable data.
- Text agent · Runs the local sentiment/emotion classifier on incoming text.
text_agent/main.py - Model assets · Bundled tokenizer and fine-tuned DistilBERT assets used by the text agent.
text_agent/sentiment-analysis-model - Text label · Predicted emotional state label with confidence from the text path.
Wearable analysis
Structured physiological features are scored by a model-driven pipeline with fallback behavior.
- Wearable agent · Loads preprocessing and classification artifacts to estimate stress from structured metrics.
wearable_agent/main.py - Model artifacts · Stored scaler, label encoder, and stress classifier used for wearable inference.
- Fallback rules · Rule-based behavior used when serialized wearable artifacts cannot be loaded.
Fusion and output
Late fusion combines modality outputs and turns them into user-facing guidance.
- Fusion engine · Combines text and wearable predictions using the repository’s weighted fusion strategy.
fusion_agent/main.py - Risk band · Maps the fused score into Low, Mild, Moderate, or High risk.
- Guidance log · Produces supportive warnings and appends assessment history in JSONL-style longitudinal records.
Connections 14
- Simulation UI → Text stream: collects · The interface gathers free-form text from the user.
- Simulation UI → Wearable stream: collects · The interface gathers wearable and physiological metrics.
- Text stream → Text agent: sent to · Text input flows into the text analysis boundary.
- Wearable stream → Wearable agent: sent to · Structured health metrics flow into the wearable analysis boundary.
- Text agent → Model assets: loads · The text agent uses the bundled Hugging Face model assets.
- Text agent → Text label: emits · Outputs a text emotion label and confidence.
- Wearable agent → Model artifacts: loads · The wearable agent uses serialized scaler, encoder, and classifier artifacts.
- Wearable agent → Fallback rules: degrades to · If model files are unavailable, rule-based fallback behavior is used.
- Wearable agent → Fusion engine: emits · Outputs a wearable stress prediction for fusion.
- Text label → Fusion engine: contributes · Text modality prediction is weighted into the final score.
- Wearable agent → Fusion engine: contributes · Wearable modality prediction is weighted into the final score.
- Fusion engine → Risk band: maps to · The fused score is translated into one of four risk levels.
- Risk band → Guidance log: drives · Risk level determines warnings, advice, and assessment logging.
- Fusion engine → Guidance log: records · Assessment outputs can be appended as longitudinal JSONL history.