Installation Guide

Before You Start

Make sure Python is installed. Open a terminal and type python --version. If you see 3.10 or higher, you're set. If you see 2.7 or a "command not found" error, grab the latest 3.10 or newer installer from python.org — and on Windows, tick the "Add Python to PATH" checkbox during install, because skipping that box is responsible for roughly half the setup problems students run into.

You'll also want a free Groq API key. Go to console.groq.com, sign up, open the API Keys section, create a key, and keep that tab open. You'll paste it in a minute. Chat and Marks-Aware Answers need it. Upload, the PYQ Analyzer and the Model Paper Generator run fine without one.

Around 1 GB of free disk space and a working internet connection for the first run. That's the full list.

Step-by-Step Setup

Step 1 — Open a terminal inside the project folder

Extract the downloaded zip somewhere sensible, not inside Downloads. On Windows, open the extracted folder, type cmd in the address bar and press Enter. On macOS or Linux, right-click the folder and choose the open-in-terminal option. You should be sitting in the folder that contains manage.py.

Step 2 — Create and activate a virtual environment

Run this first:

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. If it doesn't show up, the activation failed and everything after this will install into the wrong place — fix it before moving on.

Step 3 — Install the dependencies

pip install -r requirements.txt

Go make chai. This pulls in Django, Django REST Framework, ChromaDB, sentence-transformers, PyMuPDF, scikit-learn and ReportLab, and sentence-transformers drags in PyTorch behind it, so on a slow connection this can take five to ten minutes. That's normal.

Step 4 — Set up your .env file

Copy the example file. On Windows: copy .env.example .env. On macOS or Linux: cp .env.example .env.

Open the new .env in any text editor and fill it in:

DJANGO_SECRET_KEY= — type any long random string of letters and numbers, it just needs to be unpredictable.
DJANGO_DEBUG=True — leave this as it is while developing.
GROQ_API_KEY= — paste the key from that Groq tab you left open.
GROQ_MODEL=openai/gpt-oss-120b — leave as is unless you hit the model error below.
EMBEDDING_MODEL_NAME=all-MiniLM-L6-v2 — don't change this one.

Save and close.

Step 5 — Create the database tables

python manage.py migrate

This builds the SQLite database with tables for Subject, Document, Chunk, Question and Cluster. Optionally run python manage.py createsuperuser too, which gives you a login for the Django admin at /admin/ — useful during a demo when you want to show your examiner the raw data behind the charts.

Step 6 — Load the sample data

python manage.py load_sample_data

This one takes a couple of minutes on first run, because it's downloading the embedding model and then generating and ingesting real PDFs for two subjects across five years. You end up with Operating Systems and Database Management Systems, each with three units of notes and PYQ papers from 2021 through 2025. Re-running it later is always safe — it wipes and rebuilds only those two subjects and leaves anything you added yourself alone.

Step 7 — Start the server

python manage.py runserver

Open http://127.0.0.1:8000/ in your browser. Keep the terminal window open — closing it kills the server.

Common Issues and Fixes

"'python' is not recognized as an internal or external command"

Python isn't on your PATH. Easiest fix is to re-run the Python installer, choose Modify, and make sure the PATH option is ticked. Then close your terminal completely and open a fresh one — an already-open terminal won't pick up the change.

The first question you ask takes forever

That's the one-time embedding model download, around 90 MB from Hugging Face. It happens once, gets cached, and every run after that is fast and fully offline. If it seems stuck, check your internet rather than restarting.

"model does not exist or you do not have access to it"

Groq retires and renames models fairly often, so the default in .env may have gone stale. List the models your key can currently reach:

python -c "from groq import Groq; import os; from dotenv import load_dotenv; load_dotenv(); [print(m.id) for m in Groq(api_key=os.environ['GROQ_API_KEY']).models.list().data]"

Pick a text chat model from that list — skip anything with whisper, tts or prompt-guard in the name, those handle audio and safety filtering, not text generation. Put the chosen name into GROQ_MODEL in your .env, then stop the server with Ctrl+C and start it again. Environment variables load at startup, so a restart is mandatory here.

"No extractable text found in this PDF"

Your PDF is a scanned image with no text layer. OCR isn't part of this project. Run the file through a free OCR converter first, then upload the result.

How to Check It's Actually Working

1. Go to /pyq/ and pick Operating Systems. You should see a bar chart of the top recurring topics and a stacked chart of questions per unit. If both charts render with data, your ingestion, embedding and clustering pipeline is fully working.
2. Go to /paper/, pick a subject, and generate a paper. Sections A, B and C should fill with actual questions. Hit Download PDF and confirm the file opens.
3. Go to /chat/, pick Operating Systems, and ask something your notes definitely cover, like a question about deadlock. You should get an answer with page numbers attached.
4. Now ask something completely unrelated in the same subject — anything about cricket works. You should get "Not found in your notes." If you get a real answer instead, your Groq key or your retrieval threshold needs checking, because that refusal is the behaviour your examiner will care about most.