Installation Guide

Before You Start

Get these sorted first. It takes five minutes and saves you an hour of confusion later.

• Python 3.10 or newer. Grab it from python.org. Not 2.7, not 3.8. During installation on Windows, tick the box that says "Add Python to PATH" — people miss this constantly and then wonder why the terminal doesn't recognise the python command.
• A code editor. VS Code or PyCharm, either is fine.
• The three model files we sent you: tfidf_vectorizer.pkl, classifier.pkl and metadata.json. Keep them handy, you'll need them at step 4.

Check your Python version by opening a terminal and typing python --version. If it prints something starting with 3.10 or higher, you're good.

Step by Step Setup

1. Extract the project and open a terminal inside the folder. On Windows, the easiest way is to open the folder, hold Shift, right-click on empty space and choose "Open in Terminal" or "Open PowerShell window here." You should be in the folder that contains manage.py.

2. Create a virtual environment. Run python -m venv venv. Then activate it — venv\Scripts\activate on Windows, or source venv/bin/activate on macOS and Linux. When it works, you'll see (venv) at the start of your terminal line. If you don't see that, activation failed and everything after this will install to the wrong place.

3. Install the dependencies. Run pip install -r requirements.txt. This pulls in Django, Django REST Framework, scikit-learn and the libraries that read .docx and .pdf files. It'll take a minute or two. Let it finish.

4. Drop the model files into place. Copy tfidf_vectorizer.pkl, classifier.pkl and metadata.json into the folder detector/ml/artifacts/. Exactly that folder. This is the single most common thing people get wrong, so double-check the path before moving on.

5. Set up your environment file. Copy .env.example to .env — copy .env.example .env on Windows, cp .env.example .env on macOS and Linux. Open the new .env file and put any long random string as your SECRET_KEY. For local development, leave DEBUG as True.

6. Create the database tables. Run python manage.py migrate. This builds the SQLite database with the Scan, ScanSentence, ApiKey and BatchJob tables.

7. Verify the model loaded. Run python manage.py check_model. This is your safety net — it loads the artifacts and runs a sample prediction. If it prints a successful result, the ML side is working and any later problem is a Django problem, not a model problem.

8. Seed some demo data. Run python manage.py seed_demo_data. Optional, but do it anyway. You get 40 sample scans and a demo API key, which means your dashboard has actual charts instead of empty boxes when you present.

9. Create an admin account. Run python manage.py createsuperuser and follow the prompts. Note down whatever password you set. Yes, people forget it.

10. Start the server. Run python manage.py runserver and open http://127.0.0.1:8000/ in your browser.

When Something Breaks

"ModuleNotFoundError" when you run manage.py. Your virtual environment isn't active. Look at your terminal — no (venv) at the front means you skipped or lost activation. Activate it again and re-run the install command.

An error the moment you click Analyze. The model artifacts aren't in detector/ml/artifacts/, or one of the three files is missing. Run python manage.py check_model and it'll tell you exactly which file it couldn't find.

"Text too short" instead of a result. That's not a bug. The model needs at least 50 words to give a reliable verdict, so short paragraphs get rejected on purpose. Paste a full paragraph or two and it'll work. You can change the threshold with MIN_TEXT_WORDS in .env if you really want to, but shorter input means worse predictions.

Port 8000 already in use. Something else is running there, often a leftover server from an earlier attempt. Run python manage.py runserver 8001 and use that port instead.

How To Tell It's Actually Working

Open the home page and paste in two or three paragraphs of text — grab something from a news site, or ask ChatGPT to write you a short essay if you want to test the other direction. Hit analyze. Within a couple of seconds you should get a verdict, a confidence percentage, and a result page where individual sentences are highlighted.

Then check three more things. Visit /dashboard/ and confirm the charts render. Open /admin/ and log in with the superuser you made. Finally, hit the health endpoint from your terminal with curl http://127.0.0.1:8000/api/v1/health/ — no API key needed for that one.

All four working? You're done. Go rehearse your viva.