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