Installation Guide

Before You Start

You need Python installed. Version 3.9 or newer — grab it from python.org, and on Windows make sure you tick the "Add Python to PATH" checkbox during install. People miss that box every single time and then wonder why the terminal says python is not recognised.

You also want a code editor. VS Code is fine. Notepad is not.

That's it. No database to set up, no API keys to register for, no Node, no Docker.

Step 1: Open a terminal inside the project folder

Extract the zip somewhere sensible like Desktop or D drive. Avoid folder names with spaces or Hindi characters, it saves pain later. Then right-click inside the folder and open Terminal, or open Command Prompt and cd into it.

Step 2: Create a virtual environment

Run this:

python -m venv venv

Then activate it. On Windows:

venv\Scripts\activate

On macOS or Linux:

source venv/bin/activate

You'll know it worked when (venv) shows up at the start of your terminal line.

Step 3: Install the dependencies

pip install -r requirements.txt

This pulls in Flask, scikit-learn, pandas and numpy. Takes a minute or two depending on your internet. Let it finish fully.

Step 4: Run it

python app.py

The terminal will print something like "Running on http://127.0.0.1:5000". Ctrl-click that link or paste it into Chrome.

Step 5: Check that it's actually working

Three quick checks. Open /health and confirm you get a healthy response. Then go to the search page and type "AESTHINT" — autocomplete should start filling in course names. Pick one, hit search, and you should land on a results page with a matched course, a similarity chart and a ranked table of recommendations with scores.

If all three work, you're done. Go look at the Analytics page too, it's the part examiners tend to notice.

When Things Break

"venv\Scripts\activate is not recognised" or a PowerShell execution policy error. PowerShell blocks scripts by default on some Windows setups. Either use Command Prompt instead of PowerShell, or run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass in that PowerShell window and try activating again.

An error while loading kmeans_model.pkl or scaler.pkl. This is almost always a scikit-learn version mismatch — the pickles were saved with the version pinned in requirements.txt. Make sure you installed inside the activated virtual environment and didn't skip the requirements step. If it persists, uninstall scikit-learn and reinstall the exact version listed in requirements.txt.

Port 5000 already in use. Common on newer Macs, where AirPlay Receiver grabs port 5000. Turn AirPlay Receiver off in System Settings, or change the port in the last line of app.py to 5050 and open 127.0.0.1:5050 instead.

Page loads but no recommendations come back. Check that the models/ folder actually has all six files in it. If your extraction tool skipped X_scaled.npy because of its size, re-extract the zip.

Presenting It

Start the app five minutes before your demo, not thirty seconds before. Keep a Postman tab open with GET /recommend?course=AESTHINT%2013&top_n=5 ready to fire — showing the raw JSON alongside the UI makes the whole thing look a lot more serious than clicking around a webpage.