Spaces:
Sleeping
Sleeping
| title: Mentallico AI v2.0 | |
| emoji: 🧠 | |
| colorFrom: blue | |
| colorTo: indigo | |
| sdk: docker | |
| pinned: false | |
| # Mentallico AI v2.0 - Comprehensive Architectural & Technical Thesis | |
| ## 1. Executive Summary & Problem Statement | |
| The global healthcare infrastructure faces a severe shortage of psychiatric professionals, leading to delayed diagnoses and unmonitored mental health crises. **Mentallico AI v2.0** is engineered to bridge this critical gap. It is an advanced, AI-powered psychiatric diagnostic backend designed for seamless integration into digital clinics, telehealth platforms, and Virtual Reality (VR) environments. | |
| **Why AI?** Traditional rule-based chatbots (using decision trees) fail to capture the nuanced, often chaotic nature of human emotional expression. Mentallico utilizes a robust Machine Learning pipeline to understand contextual semantics, tone, and clinical indicators. | |
| **The Core Philosophy:** "Medical Safety First." The system is strictly programmed to prevent premature diagnoses, requiring sufficient conversational context, and features an unyielding crisis intervention protocol for high-risk situations. | |
| --- | |
| ## 2. Data Engineering & Preprocessing Pipeline | |
| Machine Learning models are only as good as the data they are trained on. Psychiatric texts are inherently complex and often suffer from severe class imbalance. | |
| ### 2.1. What We Did (Implementation Details) | |
| We aggregated a massive corpus of unstructured text derived from 12 distinct, high-quality mental health datasets (including `Suicide_Detection`, `dreaddit`, `counsel_chat`, and `depression_dataset_reddit`). | |
| We developed a custom `data_loader.py` script that cleans the text (removing URLs, special characters, and stop words), drops null values, and standardizes the labels into six core clinical categories: *Normal, Depression, Suicide, Anxiety/Stress, PTSD, and Bipolar*. | |
| ### 2.2. Architectural Rationale (Why "Smart Balancing"?) | |
| Mental health datasets are notoriously skewed (e.g., 26,000 "Normal" records vs. only 62 "Bipolar" records). Training a model on this raw distribution would result in a heavily biased AI that ignores minority diseases. | |
| Instead of using basic SMOTE (which struggles with text semantics), we implemented a **Custom Smart Balancing Pipeline**: | |
| * **Target:** Exactly 15,500 samples distributed mathematically to reflect clinical importance. | |
| * **Oversampling:** Synthetically amplifying critical minority classes (Bipolar: 1500, PTSD: 2500) through textual augmentation. | |
| * **Undersampling:** Randomly reducing majority classes (Normal/Depression: 3000 each) to prevent model overfitting. | |
| --- | |
| ## 3. The Multi-Model Machine Learning Ensemble | |
| Relying on a single classification model in the medical field poses a massive architectural risk (Single Point of Failure). Mentallico mitigates this by implementing a weighted voting ensemble consisting of four distinct AI models. | |
| ### 3.1. What We Did | |
| We fine-tuned two primary Transformer-based models over 5 Epochs using PyTorch, and integrated two additional pre-trained zero-shot models. The orchestrator computes the final diagnostic probability using a weighted mathematical sum: | |
| $$P(c) = \sum_{i=1}^{4} w_i \cdot P_i(c)$$ | |
| Where $P(c)$ is the final probability for clinical class $c$, $w_i$ is the assigned weight, and $P_i(c)$ is the independent probability. | |
| ### 3.2. Architectural Rationale (Why these specific models?) | |
| 1. **Mental-BERT (`mental-bert-base-uncased` - Weight: 35%):** * *Why?* Standard BERT is trained on Wikipedia. Mental-BERT is pre-trained specifically on medical and psychological forums. It understands clinical terminology out-of-the-box. We fine-tuned it to achieve a **77.0% F1-Score**. | |
| 2. **DistilRoBERTa (`distilroberta-base` - Weight: 25%):** * *Why?* RoBERTa removes BERT's next-sentence prediction and trains on larger datasets, making it structurally superior for understanding long, complex patient sentences. It achieved an **89.0% F1-Score**. | |
| 3. **Dsuram Clinical (`dsuram/...` - Weight: 25%):** * *Why?* To prevent our fine-tuned models from living in an "echo chamber." This zero-shot pre-trained clinical classifier adds an objective external validation layer. | |
| 4. **Emotion DistilRoBERTa (`j-hartmann/...` - Weight: 15%):** * *Why?* Patients often express emotions (fear, sadness) rather than symptoms. This model maps raw emotional states directly to psychiatric categories, enhancing the system's empathetic accuracy. | |
| --- | |
| ## 4. Advanced RAG Engine & LLM Orchestration | |
| Mentallico employs **Google Gemini 1.5 Pro** augmented by a ChromaDB vector database to ensure responses are grounded in actual medical science, eliminating the risk of AI "hallucinations." | |
| ### 4.1. What We Did (The Knowledge Base Integration) | |
| We ingested world-renowned psychiatric textbooks and clinical guidelines into the `medical_docs` directory. Using `langchain` and `sentence-transformers`, these documents were chunked and vectorized into `ChromaDB`. | |
| **Key References Ingested:** | |
| * *Diagnostic and Statistical Manual of Mental Disorders, Fifth Edition (DSM-5)* - The global standard for psychiatric diagnosis. | |
| * *Kaplan and Sadock's Synopsis of Psychiatry* - For comprehensive clinical overviews. | |
| * *Cognitive Behavior Therapy: Basics and Beyond (by Judith S. Beck)* - To provide the LLM with scientifically backed therapy techniques. | |
| ### 4.2. Architectural Rationale (Why RAG and Gemini?) | |
| * *Why Gemini 1.5 Pro?* It possesses a massive context window and exceptional clinical reasoning capabilities, allowing it to act as a human-level physician proxy. | |
| * *Why RAG?* Without RAG, an LLM might generate dangerous or unverified medical advice. By querying the DSM-5 and CBT manuals stored in ChromaDB, the model's responses are mathematically forced to align with established medical literature. | |
| * *The LLM Override Protocol:* If a patient exhibits symptoms of Schizophrenia or OCD (which are outside our 6 core ML classes), Gemini has the systemic authority to override the ML ensemble and output a custom, accurate diagnosis based on the ingested DSM-5 criteria. | |
| --- | |
| ## 5. Clinical Safety & The Diagnostic State Machine | |
| The most critical engineering achievement in Mentallico is the `conversation_manager.py`, acting as a medical firewall. | |
| ### 5.1. What We Did (The Safety Gates) | |
| We programmed a state machine (`DIAGNOSIS_CONFIG`) that locks the diagnosis until strict thresholds are met: | |
| 1. **Interaction Volume:** Minimum of **3 messages**. | |
| 2. **Linguistic Data:** Minimum of **30 words**. | |
| 3. **Algorithmic Confidence:** Ensemble's final probability must be **$\ge$ 75%**. | |
| 4. **Temporal Consistency:** At least 66% of the last 3 ML predictions must match. | |
| ### 5.2. Architectural Rationale (Why these rules?) | |
| * *Why Delay Diagnosis?* If a user says "I am sad today," a naive AI might instantly diagnose Depression. Our gates ensure the system collects enough longitudinal data (Consistency) and depth (Word Count) before generating a medical report. | |
| * *Why The High-Risk Override?* If the ensemble detects the **Suicide** class at *any* point (even in the first message), the system immediately bypasses all safety gates. It is an ethical and medical obligation to prioritize life-saving intervention (outputting emergency hotlines) over diagnostic data collection. | |
| --- | |
| ## 6. Real-Time Audio Processing Pipeline (Speech-to-Text) | |
| To support immersive VR therapy sessions and ensure accessibility for users unable to type, we implemented a dual-layered audio pipeline. | |
| ### 6.1. What We Did | |
| We created an endpoint (`/api/v2/session/{id}/audio`) that accepts `.wav` uploads. We integrated the **Groq API** (`whisper-large-v3`) as the primary transcription engine, with a local OpenAI Whisper (`ffmpeg` powered) fallback mechanism. | |
| ### 6.2. Architectural Rationale | |
| * *Why Groq Whisper?* Groq utilizes LPUs (Language Processing Units) rather than traditional GPUs, providing near-instantaneous audio transcription. This ultra-low latency is strictly required to maintain the illusion of a real-time, human-to-human conversation in a VR environment. | |
| * *Why a Local Fallback?* Cloud APIs are subject to rate limits and network outages. Implementing a local fallback ensures that the application has zero downtime and can always process patient input, maintaining absolute reliability. | |
| --- | |
| ## 7. Cloud Deployment & API Architecture | |
| The entire Mentallico ecosystem is designed as a stateless, highly scalable microservice. | |
| ### 7.1. What We Did & Why We Did It | |
| * **Deployment Medium:** Dockerized and deployed on **Hugging Face Spaces**. | |
| * *Why?* Docker ensures that the system runs identically across all environments (eliminating "it works on my machine" issues). Hugging Face provides an excellent infrastructure specifically optimized for heavy Machine Learning models. | |
| * **Framework:** Built on **FastAPI** with `Uvicorn`. | |
| * *Why?* FastAPI is asynchronous by design, meaning it can handle multiple patient requests simultaneously without blocking the server, which is essential for a production-level healthcare API. | |
| * **Security:** Cryptographic keys (Gemini, Groq, HF Token) are isolated using cloud environment secrets, adhering strictly to zero-trust security principles and protecting patient data integrity. |