Depression Detector Backend

A FastAPI backend for inference from speech, text, or both modalities. The project exposes a trained audio model and a trained text model through a small HTTP API and combines their probabilities for a weighted multimodal prediction.

Important: This is a research/demo inference service, not a medical diagnostic tool. A prediction must not be used as a diagnosis or as a substitute for assessment by a qualified mental-health professional. If someone may be in immediate danger, contact local emergency services or a crisis service.

What Is Included

• Audio inference in audio_depression/
  • Loads a serialized model, scalers, and feature selector.
  • Converts non-WAV audio through pydub/FFmpeg when needed.
  • Extracts acoustic and prosodic statistics with librosa.
• Text inference in text_depression/
  • Cleans transcript-like text.
  • Applies a serialized TF-IDF vectorizer, feature selector, scaler, and classifier.
  • Returns simple interpretable word and sentiment counts in addition to the model result.
• FastAPI application in app.py
  • Provides health, model-status, information, audio, text, and fusion endpoints.
• Testing examples in data for testing/
  • Five depressed and five not-depressed text samples.
  • Five depressed and five not-depressed WAV samples.

This checkout contains inference code only. The training notebooks are not present in the working tree, and no serialized model artifacts are included. The service cannot produce predictions until the required artifacts are copied into the model directories described below.

Project Layout

.
├── app.py
├── requirements.txt
├── .env                         # configuration reference; not loaded by app.py
├── audio_depression/
│   ├── config.py                # audio paths and feature-extraction limits
│   ├── feature_extraction.py    # librosa feature extraction
│   ├── predict.py               # audio artifact loading and prediction
│   └── utils.py                 # dataset/statistics helpers
├── text_depression/
│   ├── text_config.py            # text paths and training-related settings
│   └── text_predict.py           # text cleaning, artifact loading, prediction
└── data for testing/
    ├── depressed/
    └── not depressedd/           # existing directory name

The .gitignore excludes .pkl and .csv files, so model artifacts and label files are intentionally not expected to be committed.

Requirements

• Python 3.10+ is recommended.
• FFmpeg is required for MP3, FLAC, OGG, and WEBM conversion. WAV input can be used without conversion.
• Python packages are listed in requirements.txt, including FastAPI, python-multipart, NumPy, pandas, joblib, scikit-learn, XGBoost, librosa, soundfile, and pydub.

Install the Python dependencies in a virtual environment:

python -m venv .venv
source .venv/bin/activate       # Linux/macOS
# .venv\Scripts\activate      # Windows PowerShell
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Install FFmpeg using the package manager for your operating system if you need non-WAV uploads. Verify it is available with:

ffmpeg -version

Model Artifacts

Place artifacts exported from compatible training runs in these directories:

audio_depression/models/
├── best_audio_model.pkl
├── scaler_initial.pkl
├── scaler_final.pkl       # feature_scaler.pkl is accepted as a legacy name
└── feature_selector.pkl

text_depression/models/
├── best_text_model.pkl
├── text_vectorizer.pkl
├── text_scaler.pkl
└── feature_selector.pkl

The files in each group must come from the same training run. The loaders cache artifacts after the first successful load. Restart the server after replacing a model so the cache is refreshed.

The text configuration contains Windows paths for the original external training dataset and labels, but the inference endpoint does not read those paths. The current API only needs the four serialized text artifacts above.

Run the API

Start from the repository root so the relative model-status checks in app.py resolve consistently:

python app.py

The server listens on http://localhost:8000 and exposes interactive documentation at:

• http://localhost:8000/docs (Swagger UI)
• http://localhost:8000/redoc (ReDoc)

Equivalent command:

uvicorn app:app --host 0.0.0.0 --port 8000

The .env file records API_HOST, API_PORT, reload, model paths, and CORS values, but the application does not load it. These values therefore do not change runtime behavior unless an external process loads or uses them.

Endpoints

Health check

curl http://localhost:8000/

Returns status, audio_model, and text_model. The boolean values only indicate whether the expected model files exist at the paths checked by the application; they do not validate that artifacts can be loaded successfully.

Model status and API information

curl http://localhost:8000/models/status
curl http://localhost:8000/info

/models/status also reports each model path and file size. /info lists the supported formats and routes.

Text prediction

The JSON text must contain at least 10 non-whitespace characters before cleaning:

curl -X POST http://localhost:8000/predict/text \
  -H 'Content-Type: application/json' \
  -d '{"text":"I have felt tired, sad, and hopeless for several days."}'

The response contains:

• prediction: 1 for Depressed, 0 for Not Depressed.
• label, probability, and confidence.
• linguistic_features: word count, sentence count, average word length, positive/negative keyword counts, and sentiment ratio.
• message: a risk-oriented message based on the predicted label and confidence.

Cleaning removes timestamp-like numbers, standalone numbers, some confidence fragments, unsupported characters, and repeated whitespace before inference.

Audio prediction

The upload extension must be .wav, .mp3, .flac, .ogg, or .webm:

curl -X POST http://localhost:8000/predict/audio \
  -F 'audio=@"data for testing/depressed/sample 1.wav"'

Audio is loaded at 16 kHz, trimmed for silence, and capped at 180 seconds. The extractor summarizes MFCC, chroma, mel-spectrogram, spectral contrast, tonnetz, pitch, RMS energy, zero-crossing, spectral centroid/rolloff/bandwidth, pauses, onset strength, and duration-related values. The returned result includes both original and analyzed duration.

Non-WAV files are converted to mono 16 kHz WAV before extraction. If FFmpeg is unavailable, upload WAV or install FFmpeg.

Multimodal fusion

Fusion requires both an audio upload and a transcript of at least 10 non-whitespace characters:

curl -X POST http://localhost:8000/predict/fusion \
  -F 'audio=@"data for testing/depressed/sample 1.wav"' \
  -F 'text=I have felt tired, sad, and hopeless for several days.' \
  -F 'fusion_method=weighted_average'

The implemented fusion method is weighted_average:

ensemble depressed probability = 0.60 * text depressed probability
                                + 0.40 * audio depressed probability

The result includes the ensemble output and the individual audio and text predictions. Although some endpoint descriptions mention simple_average, max_confidence, and voting, the current implementation accepts only weighted_average.

Bundled Test Data

The sample data is organized by its intended class label:

Directory	Text samples	WAV samples	WAV format
data for testing/depressed/	5	5	Mono, 16-bit PCM, 16 kHz
data for testing/not depressedd/	5	5	Mono, 16-bit PCM, 16 kHz

The text files are transcript-like samples with no consistent newline requirement. File naming is inconsistent in places, and not depressedd is the existing directory name; do not rename it in scripts that reference these examples without updating those paths.

These files are useful for manual endpoint smoke tests only. The repository does not include an automated evaluation command, ground-truth metrics, or a guarantee that the samples match the training distribution.

Direct Python Usage

After installing dependencies and placing artifacts, the prediction modules can also be called directly:

python audio_depression/predict.py "data for testing/depressed/sample 1.wav"
python text_depression/text_predict.py "I feel sad and tired today but I am seeking help."

The audio predictor accepts a file path, bytes, or a BytesIO object. The text predictor accepts a string. Both return a dictionary and raise an informative FileNotFoundError when required artifacts are absent.

Operational Notes

• CORS is currently configured with allow_origins=["*"] and all methods/headers enabled. Restrict this before exposing the service publicly.
• Uploaded audio is written to a temporary file and removed in a finally block after inference.
• The API returns HTTP 400 for invalid extensions or short text, HTTP 422 for some input/analysis errors, and HTTP 500 for missing artifacts or server-side failures.
• Confidence is the largest class probability; it is not a clinical certainty or calibrated risk score.
• The root health check uses relative paths, while the prediction modules resolve paths from their package directories. Run from the project root or make these path conventions consistent before deploying.

Current Validation

The Python modules compile successfully with:

python -m compileall -q app.py audio_depression text_depression

Prediction execution requires the model artifacts listed above, which are not included in this checkout.