Prepare Hugging Face Spaces deployment

.dockerignore

@@ -0,0 +1,21 @@
+.git
+.env
+.venv
+.hf_cache
+__pycache__
+*.pyc
+*.pyo
+*.log
+
+data
+checkpoints
+runs
+docs
+
+src/models/saved_lang_model.pkl
+src/models/saved_emotion_model
+src/models/saved_*
+
+notebooks/.ipynb_checkpoints
+notebooks/data
+notebooks/reports

.env.example

@@ -1,5 +1,9 @@
 GROQ_API_KEY=your_groq_api_key_here
 
+LANGUAGE_MODEL_REPO_ID=your_hf_username/language-detector-model
+LANGUAGE_MODEL_FILENAME=saved_lang_model.pkl
+EMOTION_MODEL_ID=your_hf_username/emotion-detector-model
+
 QDRANT_URL=https://your-cluster-url.qdrant.tech
 QDRANT_API_KEY=your_qdrant_api_key_here
 QDRANT_COLLECTION=mental_health_rag

DEPLOYMENT.md

@@ -0,0 +1,87 @@
+# Hugging Face Spaces Deployment
+
+This project is prepared for deployment as a Hugging Face Docker Space.
+
+## 1. Login Locally
+
+Run:
+
+```powershell
+.\.venv\Scripts\hf.exe auth login
+```
+
+Use a Hugging Face token with write access.
+
+## 2. Upload Model Artifacts
+
+Create two Hugging Face model repositories:
+
+```text
+your_username/mental-health-language-detector
+your_username/mental-health-emotion-detector
+```
+
+Upload:
+
+- `src/models/saved_lang_model.pkl` to the language model repository.
+- All files inside `src/models/saved_emotion_model/` to the emotion model repository.
+
+The emotion model folder should contain:
+
+```text
+config.json
+model.safetensors
+tokenizer.json
+tokenizer_config.json
+```
+
+## 3. Create The Space
+
+Create a Hugging Face Space:
+
+```text
+SDK: Docker
+Visibility: Public or Private
+App port: 7860
+```
+
+## 4. Add Space Secrets
+
+In the Space settings, add:
+
+```text
+GROQ_API_KEY
+QDRANT_URL
+QDRANT_API_KEY
+QDRANT_COLLECTION
+LANGUAGE_MODEL_REPO_ID
+LANGUAGE_MODEL_FILENAME
+EMOTION_MODEL_ID
+```
+
+Recommended values:
+
+```text
+LANGUAGE_MODEL_FILENAME=saved_lang_model.pkl
+QDRANT_COLLECTION=mental_health_rag
+EMBEDDING_MODEL_NAME=intfloat/multilingual-e5-base
+EMBEDDING_BATCH_SIZE=2
+TORCH_NUM_THREADS=1
+```
+
+## 5. Push To The Space Repo
+
+After the Space is created, add it as a Git remote:
+
+```powershell
+git remote add space https://huggingface.co/spaces/your_username/your_space_name
+git push space main
+```
+
+The Dockerfile starts the production app with:
+
+```text
+uvicorn src.api_app:app --host 0.0.0.0 --port 7860
+```
+
+Open the Space URL after the build finishes.

Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PIP_NO_CACHE_DIR=1
+ENV TOKENIZERS_PARALLELISM=false
+ENV TORCH_NUM_THREADS=1
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --upgrade pip \
+    && pip install -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "src.api_app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -164,6 +164,9 @@ Create a local `.env` file from `.env.example`:
 
 ```text
 GROQ_API_KEY=your_groq_api_key_here
+LANGUAGE_MODEL_REPO_ID=your_hf_username/language-detector-model
+LANGUAGE_MODEL_FILENAME=saved_lang_model.pkl
+EMOTION_MODEL_ID=your_hf_username/emotion-detector-model
 QDRANT_URL=https://your-cluster-url.qdrant.tech
 QDRANT_API_KEY=your_qdrant_api_key_here
 QDRANT_COLLECTION=mental_health_rag
@@ -221,11 +224,37 @@ These reports make the project easier to review, debug, and present.
 
 ## Deployment Notes
 
-The current app runs locally through FastAPI and can be prepared for Hugging Face Spaces. For deployment:
+The current app runs locally through FastAPI and is prepared for a Hugging Face Docker Space.
 
-- Store API keys as platform secrets, not in code.
-- Keep trained model artifacts outside Git or upload them to a model host.
-- Rebuild or connect to the Qdrant collection during setup.
+See `DEPLOYMENT.md` for the full Hugging Face Spaces checklist.
+
+Recommended Hugging Face Space setup:
+
+1. Create a new Space with `Docker` as the SDK.
+2. Push this repository content to the Space repository.
+3. Add the required secrets in the Space settings:
+
+```text
+GROQ_API_KEY
+QDRANT_URL
+QDRANT_API_KEY
+QDRANT_COLLECTION
+LANGUAGE_MODEL_REPO_ID
+LANGUAGE_MODEL_FILENAME
+EMOTION_MODEL_ID
+```
+
+The Dockerfile runs:
+
+```text
+uvicorn src.api_app:app --host 0.0.0.0 --port 7860
+```
+
+Model artifact policy:
+
+- Upload `saved_lang_model.pkl` to a Hugging Face model repository and set `LANGUAGE_MODEL_REPO_ID`.
+- Upload the trained `saved_emotion_model/` files to another Hugging Face model repository and set `EMOTION_MODEL_ID`.
+- Keep API keys, model secrets, local data, and local caches outside Git.
 - Keep the production UI at `/` and the developer UI at `/developer`.
 
 ## Safety Note

requirements.txt

@@ -3,6 +3,7 @@ scikit-learn==1.9.0
 joblib==1.5.3
 gradio==6.18.0
 datasets==5.0.0
+huggingface_hub
 transformers
 torch
 accelerate

src/models/emotion_classifier.py

@@ -10,6 +10,7 @@ from typing import Any
 
 PROJECT_ROOT = Path(__file__).resolve().parents[2]
 DEFAULT_MODEL_DIR = PROJECT_ROOT / "src" / "models" / "saved_emotion_model"
+DEFAULT_HF_MODEL_ID = ""
 
 
 def _load_transformer_stack() -> tuple[Any, Any, Any]:
@@ -33,29 +34,38 @@ class EmotionClassifier:
         model_dir: str | Path | None = None,
     ) -> None:
         self.model_dir = Path(model_dir or os.getenv("EMOTION_MODEL_DIR", DEFAULT_MODEL_DIR))
-        self.active_model_source = str(self.model_dir)
+        self.model_id = os.getenv("EMOTION_MODEL_ID", DEFAULT_HF_MODEL_ID).strip()
+        self.active_model_source = str(self.model_dir if self.model_dir.exists() else self.model_id)
         self.torch = None
         self.tokenizer = None
         self.model = None
         self.id2label: dict[int, str] = {}
 
     def load_model(self) -> None:
-        if not self.model_dir.exists():
+        model_source = self._resolve_model_source()
+        if not model_source:
             raise FileNotFoundError(
-                f"Emotion model not found at {self.model_dir}. "
-                "Train it first with notebooks/module_2_emotion_training.ipynb."
+                "Emotion model is not available. Train Module 2 locally, or set "
+                "EMOTION_MODEL_ID to a Hugging Face model repository."
             )
 
         torch, model_cls, tokenizer_cls = _load_transformer_stack()
         self.torch = torch
-        self.tokenizer = tokenizer_cls.from_pretrained(self.model_dir)
-        self.model = model_cls.from_pretrained(self.model_dir)
+        self.tokenizer = tokenizer_cls.from_pretrained(model_source)
+        self.model = model_cls.from_pretrained(model_source)
         self.model.eval()
-        self.active_model_source = str(self.model_dir)
+        self.active_model_source = str(model_source)
 
         config_labels = self.model.config.id2label
         self.id2label = {int(key): value for key, value in config_labels.items()}
 
+    def _resolve_model_source(self) -> str | Path | None:
+        if self.model_dir.exists():
+            return self.model_dir
+        if self.model_id:
+            return self.model_id
+        return None
+
     def _score_text(self, text: str) -> dict[str, Any]:
         if self.model is None or self.tokenizer is None or self.torch is None:
             self.load_model()

src/models/language_classifier.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 import argparse
 import json
+import os
 import sys
 from pathlib import Path
 from typing import Any
@@ -17,6 +18,7 @@ DATA_DIR = PROJECT_ROOT / "data"
 MODEL_DIR = PROJECT_ROOT / "src" / "models"
 REPORTS_DIR = PROJECT_ROOT / "reports" / "module_1_language_detection"
 DEFAULT_MODEL_PATH = MODEL_DIR / "saved_lang_model.pkl"
+DEFAULT_HF_MODEL_FILENAME = "saved_lang_model.pkl"
 
 LANGUAGE_NAMES = {
     "ar": "Arabic",
@@ -47,10 +49,10 @@ class LanguageDetector:
 
     def __init__(
         self,
-        model_path: str | Path = DEFAULT_MODEL_PATH,
+        model_path: str | Path | None = None,
         confidence_threshold: float = 0.65,
     ) -> None:
-        self.model_path = Path(model_path)
+        self.model_path = Path(model_path or os.getenv("LANGUAGE_MODEL_PATH", DEFAULT_MODEL_PATH))
         self.confidence_threshold = confidence_threshold
         self.pipeline = self._build_pipeline()
 
@@ -191,11 +193,29 @@ class LanguageDetector:
         print(f"Saved evaluation reports to {REPORTS_DIR}")
 
     def load_model(self) -> None:
-        if not self.model_path.exists():
+        model_path = self._resolve_model_path()
+        if not model_path.exists():
             raise FileNotFoundError(
-                f"Model not found at {self.model_path}. Run training first."
+                "Language model is not available. Train Module 1 locally, or set "
+                "LANGUAGE_MODEL_REPO_ID to a Hugging Face model repository."
             )
-        self.pipeline = joblib.load(self.model_path)
+        self.pipeline = joblib.load(model_path)
+
+    def _resolve_model_path(self) -> Path:
+        if self.model_path.exists():
+            return self.model_path
+
+        repo_id = os.getenv("LANGUAGE_MODEL_REPO_ID")
+        if not repo_id:
+            return self.model_path
+
+        filename = os.getenv("LANGUAGE_MODEL_FILENAME", DEFAULT_HF_MODEL_FILENAME)
+        try:
+            from huggingface_hub import hf_hub_download
+        except ImportError as exc:
+            raise ImportError("Install huggingface_hub to load the language model from Hugging Face Hub.") from exc
+
+        return Path(hf_hub_download(repo_id=repo_id, filename=filename))
 
     def predict(self, text: str) -> str:
         return self.predict_with_confidence(text)["language_code"]
@@ -249,7 +269,7 @@ if __name__ == "__main__":
     sample_texts = [
         "I feel anxious and need someone to talk to.",
         "أنا أشعر بالقلق وأحتاج إلى المساعدة.",
-        "Je me sens stresse aujourd'hui.",
+        "Je me sens stressé aujourd'hui.",
     ]
 
     print("\nSample predictions:")