Running the Application

You can run the application either using Docker (recommended) or by manually setting up a Python environment.

---

🐳 Option 1: Run via Docker (Recommended)

To build and run the application using Docker, follow these steps:

1. Build the Docker image

This command installs all dependencies and prepares the image:

docker build -t gdm_music_image .

⚠️ Note During the image build, some scripts—such as data_downloader.py and download_models_configs_logs.py—attempt to download external resources (datasets and pretrained models) from Google Drive using gdown. These downloads may fail intermittently due to:

• Google Drive quota limits
• Virus scan warnings for large files (e.g., .pt models)
• Public link restrictions or permission issues

---

Workaround: Manual File Download

If the build fails with an error like gdown.exceptions.FileURLRetrievalError:

1. Look at the failing file’s Google Drive link, printed in the build log.

2. Open the link in your browser and click "Download anyway" if prompted.

3. Determine where to place the file by checking the relevant script:

   • If the failure happened during data_downloader.py, inspect: rec_sys/data_preparation/data_downloader.py Check the FOLDERS_TO_DOWNLOAD dictionary to find the expected local directory (e.g., rec_sys/data/msd_db_table/).
   • If the failure happened during download_models_configs_logs.py, check: rec_sys/download_models_configs_logs.py Use the FOLDERS_TO_DOWNLOAD mapping to find the destination path (e.g., rec_sys/dl_models/VAE/RecVAE/).

4. After manually placing the file in the correct folder, rebuild the image:

docker build --no-cache -t gdm_music_image .

Tip: If you're unsure about the exact filename or folder structure, you can temporarily comment out the RUN command in the Dockerfile, run the script manually, and inspect the expected directory layout.

2. Run the container and expose it on port 5000

docker run --rm -p 5000:5000 gdm_music_image

3. Open the app

Visit http://localhost:5000 in your browser.

---

🐍 Option 2: Run without Docker

If you prefer to run the application directly on your machine without Docker:

1. Set up a Python 3.11 virtual environment in the root directory of the project

python3.11 -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

2. Install dependencies

pip install --upgrade pip
pip install -r requirements.txt

3. Download required datasets, models, and configs

The following commands must be executed before running the app. They will:

• Download database tables for CAMRa and MovieLens datasets.
• Download pre-trained model weights and configuration files.
• Place them in the appropriate folders expected by the system.

python rec_sys/data_preparation/data_downloader.py --only msd_db_table
python rec_sys/data_preparation/data_downloader.py --only mvl_db_table
python rec_sys/download_models_configs_logs.py

⚠️ Important: These scripts must be run prior to launching the app. The system expects model files their configs and dataset tables to be located in specific directories under rec_sys/ in order to run and work as expected.

4. Run the application

python run.py

5. Open the app

Visit http://localhost:5000 in your browser.

---

Repository Overview

This repository contains the full implementation of a web-based Group Recommender System (GRS) platform, along with pre-trained models, datasets, evaluation scripts, and unit tests.

📁 app/

Main application package that powers the backend of the web platform.

• api_routes.py, ui_routes.py, socket_events.py – API endpoints, frontend routing logic, and real-time WebSocket communication.

• models.py – SQLAlchemy ORM models defining the database schema.

• config.py, constants.py – Application-level configuration and shared constants.

• recommenders/ – Wrapper modules and utility loaders for serving trained models.

  • BetaVAE.py, RecVAE.py, SANSA.py – Registered production-ready recommenders.
  • utils/ – Utilities for loading models and configurations (load_cached_vae_model, load_sansa_matrix, etc.).

📁 rec_sys/

Research, evaluation and ready state subpackage for experimentation, offline analysis and keeping clean model implementations for the framework to use.

• baseline_models/ – Traditional single-user recommenders: ALS, BPR, KNN (Jupyter notebooks).
• dl_models/ – Deep learning models such as AGREE, BetaVAE, RecVAE.
• ord_models/ – Ordinal and fairness-oriented models (e.g., EP-FuzzDA, SANSA).
• OfflineGroupEvaluation/ – Evaluation notebooks and scripts for conducting model evaluations on artificial groups and compare them.
• data_preparation/ – Scripts for downloading (raw and preprocessed) datasets (MovieLens, CAMRa, MSD) and preprocessing into model-ready formats.
• download_models_configs_logs.py – Downloads trained models and configuration files from Google Drive.

📁 static/ and 📁 templates/

Frontend code built with Tailwind CSS and vanilla JavaScript.

• static/js/ – JavaScript logic for room creation, chat, join flow, timers, and voting interaction.
• templates/ – HTML templates rendered by Flask: login, signup, chat, room setup, etc.

📁 test/

Unit tests covering authentication, room creation, and session flow.

• Use pytest to validate functionality inside or outside the Docker container.
• See the Unit Testing section below.

🐳 Docker

• Dockerfile – Defines the complete environment for running the app, downloading data/models, and launching the platform.
• run.py – Entrypoint for launching the web application inside Docker.

---

Running the Unit Tests Inside Docker

To run the unit tests inside the Docker container (after building the image), use the following command:

docker run --rm gdm_music_image pytest -v

To run a specific test file, for example test_room_creation.py, use:

docker run --rm gdm_music_image pytest tests/test_room_creation.py -v

This will execute the tests using the container’s installed environment and dependencies.

---

Machine and Environment Requirements

To ensure smooth operation in both development and production settings, the following specifications are recommended:

• Operating System: Linux (Ubuntu/Debian) or Windows 10+
• Memory: Minimum 28 GB RAM (recommended for model loading and evaluation)
• Disk Space: At least 32 GB available storage for datasets, models, and logs
• GPU (Optional): CUDA-compatible NVIDIA GPU for faster inference
• Internet Access: Required during Docker build for downloading models via gdown
• Python Version: Python 3.11 (handled by the container)

---

⚠️ Initial Delay on First-Time Model Use

When a group session begins and the recommendation engine is triggered for the first time using a particular model, users may notice that chat messages appear delayed for a few seconds. This happens because:

• The backend is loading a deep learning model (e.g., VAE-based) or huge matrix (SANSA) into memory for the first time.
• Model loading involves disk I/O, memory caching, and sometimes deserialization of large files (e.g., .pt PyTorch weights).
• During this short period, the application remains functional, but the DOM may feel unresponsive due to concurrent rendering tasks or WebSocket handling delays.

✅ Once the model is cached, subsequent sessions using the same model will load instantly and behave smoothly.

---

🧠 Production Tip: Preload Models to Avoid First-Time Delay

To eliminate this delay in production deployments, you can preload commonly used models during application startup. This ensures that:

• The first user interaction isn't affected by model caching time.
• WebSocket communication and UI responsiveness remain consistent.

For example, add the following warm-up logic to your application entrypoint (app/__init__.py):

from app.recommenders.utils.utils import load_cached_vae_model
from rec_sys.dl_models.VAE.RecVAE.recvae import RecVAE

# Preload common RecVAE model

load_cached_vae_model(
    model_path="rec_sys/dl_models/VAE/RecVAE/out_rec_msd/best_recvae_msd_model.pt",
    config_path="rec_sys/dl_models/VAE/RecVAE/out_rec_msd/recvae_msd_config.json",
    model_class=RecVAE
)

This is especially recommended if you're deploying with Docker and want consistent performance across rooms.

---

📚 Further Documentation

For a more detailed explanation of the system architecture, model implementations, evaluation methodology, and design decisions, please refer to the corresponding Bachelor's Thesis:

Papyan, Artur Group decision making in group recommender systems Supervised by RNDr. Patrik Dokoupil Charles University, 2025

Link to the thesis: https://dspace.cuni.cz/handle/20.500.11956/202363

The thesis provides in-depth coverage of both user-facing and developer-facing aspects of the platform, including:

• Architecture overview
• Framework features and functionalities
• Recommendation model registration and execution logic
• Offline evaluation pipeline
• Dataset preprocessing workflows

---