Hugging Face's logo

Spaces:
Ziad9022
/
Mentallico-API-v2
Sleeping

App Files Community
Mentallico-API-v2 / README.md
Ziad9022's picture
Ziad9022
Update README.md
8b9df28 verified
preview code
|
Raw
History Blame Contribute Delete
9.24 kB
metadata 
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)=∑i=14wi⋅Pi(c)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.