| --- |
| license: mit |
| language: |
| - en |
| tags: |
| - intent-classification |
| - mental-health |
| - transformer |
| - conversational-ai |
| pipeline_tag: text-classification |
| base_model: distilbert-base-uncased |
| --- |
| |
| # 🧠 Intent Classifier (MindPadi) |
|
|
| The `intent_classifier` is a transformer-based text classification model trained to detect **user intents** in a mental health support setting. It powers the MindPadi assistant's ability to route conversations to the appropriate modules—like emotional support, scheduling, reflection, or journal analysis—based on the user’s message. |
|
|
|
|
|
|
| ## 📝 Model Overview |
|
|
| - **Model Architecture:** DistilBERT (uncased) + classification head |
| - **Task:** Intent Classification |
| - **Classes:** Over 20 intent categories (e.g., `vent`, `gratitude`, `help_request`, `journal_analysis`) |
| - **Model Size:** ~66M parameters |
| - **Files:** |
| - `config.json` |
| - `pytorch_model.bin` or `model.safetensors` |
| - `tokenizer_config.json`, `vocab.txt`, `tokenizer.json` |
| - `checkpoint-*/` (optional training checkpoints) |
|
|
|
|
|
|
| ## ✅ Intended Use |
|
|
| ### ✔️ Use Cases |
| - Detecting user intent in MindPadi mental health conversations |
| - Enabling context-specific dialogue flows |
| - Assisting with journal entry triage and tagging |
| - Triggering therapy-related tools (e.g., emotion check-ins, PubMed summaries) |
|
|
| ### 🚫 Not Intended For |
| - Multilingual intent classification (English-only) |
| - Legal or medical diagnosis tasks |
| - Multi-label classification (currently single-label per input) |
|
|
|
|
|
|
| ## 💡 Example Intents Detected |
|
|
| | Intent | Description | |
| |--------------------|-------------------------------------------------------| |
| | `vent` | User expressing frustration or emotion freely | |
| | `help_request` | Seeking mental health support | |
| | `schedule_session` | Booking a therapy check-in | |
| | `gratitude` | Showing appreciation for support | |
| | `journal_analysis` | Submitting a journal entry for AI feedback | |
| | `reflection` | Talking about personal growth or setbacks | |
| | `not_sure` | Unsure or unclear message from user | |
|
|
|
|
|
|
| ## 🛠️ Training Details |
|
|
| - **Base Model:** `distilbert-base-uncased` |
| - **Dataset:** Curated and annotated conversations (`training/datasets/finetuned/intents/`) |
| - **Script:** `training/train_intent_classifier.py` |
| - **Preprocessing:** |
| - Text normalization (lowercasing, punctuation removal) |
| - Label encoding |
| - **Loss:** CrossEntropyLoss |
| - **Metrics:** Accuracy, F1-score |
| - **Tokenizer:** WordPiece (DistilBERT tokenizer) |
|
|
|
|
|
|
| ## 📊 Evaluation |
|
|
| | Metric | Score | |
| |-----------|-------------| |
| | Accuracy | 91.3% | |
| | F1-score | 89.8% | |
| | Recall@3 | 97.1% | |
| | Precision | 88.4% | |
|
|
| Evaluation performed on a held-out validation split of MindPadi intent dataset. |
|
|
|
|
|
|
| ## 🔍 Example Usage |
|
|
| ```python |
| from transformers import AutoTokenizer, AutoModelForSequenceClassification |
| import torch |
| |
| model = AutoModelForSequenceClassification.from_pretrained("mindpadi/intent_classifier") |
| tokenizer = AutoTokenizer.from_pretrained("mindpadi/intent_classifier") |
| |
| text = "I’m struggling with my emotions today" |
| inputs = tokenizer(text, return_tensors="pt") |
| outputs = model(**inputs) |
| |
| predicted_class = torch.argmax(outputs.logits, dim=1).item() |
| print("Predicted intent ID:", predicted_class) |
| ```` |
|
|
| To map `intent ID → label`, load your label encoder from: |
|
|
| ```python |
| from joblib import load |
| label_encoder = load("intent_encoder/label_encoder.joblib") |
| print("Predicted intent:", label_encoder.inverse_transform([predicted_class])[0]) |
| ``` |
|
|
|
|
| ## 🔌 Inference Endpoint Example |
|
|
| ```python |
| import requests |
| |
| API_URL = "https://api-inference.huggingface.co/models/mindpadi/intent_classifier" |
| headers = {"Authorization": f"Bearer <your-api-token>"} |
| payload = {"inputs": "Can I book a mental health session?"} |
| |
| response = requests.post(API_URL, headers=headers, json=payload) |
| print(response.json()) |
| ``` |
|
|
|
|
|
|
| ## ⚠️ Limitations |
|
|
| * Not robust to long-form texts (>256 tokens); truncate or summarize input. |
| * May confuse overlapping intents like `vent` and `help_request` |
| * False positives possible in vague or sarcastic inputs |
| * Requires pairing with fallback model (`intent_fallback`) for reliability |
|
|
|
|
|
|
| ## 🔐 Ethical Considerations |
|
|
| * This model is for **supportive routing**, not clinical diagnosis |
| * Use with user consent and proper data privacy safeguards |
| * Intent predictions should not override human judgment in sensitive contexts |
|
|
|
|
|
|
| ## 📂 Integration Points |
|
|
| | Location | Functionality | |
| | ---------------------------------- | --------------------------------------------- | |
| | `app/chatbot/intent_classifier.py` | Main classifier logic | |
| | `app/chatbot/intent_router.py` | Routes based on predicted intent | |
| | `app/utils/embedding_search.py` | Uses `intent_encoder` for similarity fallback | |
| | `data/processed_intents.json` | Annotated intent samples | |
|
|
|
|
|
|
| ## 📜 License |
|
|
| MIT License – freely available for commercial and non-commercial use. |
|
|
|
|
| ## 📬 Contact |
|
|
| * **Team:** MindPadi AI Developers |
| * **Profile:** [https://huggingface.co/mindpadi](https://huggingface.co/mindpadi) |
| * **Email:** \[[you@example.com](mailto:you@example.com)] |
|
|
| *Last updated: May 2025* |
