Installation Guide

Setup Guide — From Zip File to Working App

Roughly 15 to 20 minutes if your internet is behaving. Follow it in order and don't skip the virtual environment step, because that's where most of the "it worked on my friend's laptop" problems come from.

Prerequisites

• Python 3.9 to 3.11. Tested on 3.10.11, so grab that one from python.org if you're installing fresh. Not 2.7, and not 3.13 either — TensorFlow tends to lag behind the newest release.
• pip, which ships with Python. Check it with pip --version.
• Around 2 GB of free disk space for dependencies and models. TensorFlow alone is a chunky download.
• Git is optional. Only needed if you're cloning instead of using the downloaded folder.
• No GPU. None required at any point.

On Windows, when the Python installer opens, tick the "Add Python to PATH" checkbox at the bottom of the first screen. Miss it and every command below throws "python is not recognized."

Step 1 — Open the project folder in a terminal

Extract the downloaded zip somewhere sensible, then open Command Prompt or Terminal and move into it:

cd path/to/project

Run dir on Windows or ls on macOS and Linux. You should see app.py, requirements.txt and the src folder listed. If you don't, you're one folder too high — go one level deeper.

Step 2 — Create and activate a virtual environment

python -m venv venv

Then activate it. macOS or Linux:

source venv/bin/activate

Windows Command Prompt:

venv\Scripts\activate

Windows PowerShell:

venv\Scripts\Activate.ps1

Your prompt should now start with (venv). That little tag is your confirmation that packages will install into the project instead of messing up your system Python.

PowerShell users sometimes get a script execution error here. Run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass in the same window and try again.

Step 3 — Install the dependencies

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

This pulls in Flask, NumPy, Pandas, scikit-learn, spaCy, textdescriptives, TensorFlow, matplotlib, seaborn, SHAP and joblib. It takes a few minutes and prints a wall of text. That's normal. Go make chai.

Step 4 — Download the spaCy English model

python -m spacy download en_core_web_sm

About 12 MB. The project needs it for tokenisation, POS tagging and dependency parsing, and the app will crash without it. Do not skip this one.

Step 5 — Put the dataset in place

Copy the CSV into the data folder so the path looks like this:

project/data/ai_vs_human_text_2026.csv

The file needs these columns: text_id, label, source_model, domain, text_content, topic_hint, word_count, avg_sentence_length, generation_method. The label column holds either human or ai.

Step 6 — Train the models

Two ways to do this. If your guide wants to watch the process, use the notebook:

jupyter notebook train_notebook.ipynb

Run the cells top to bottom. You get inline plots and a comparison table at the end, which looks good during a review.

If you just want it done, use the command line:

python -m src.train

Either way it loads the dataset, builds a balanced sample, extracts 32 features per text, trains all three models, prints the metrics table, and writes everything to models/ and outputs/. Expect 5 to 15 minutes for around 1,332 texts. Feature extraction is the slow part and it'll look frozen for a while. It isn't.

Step 7 — Start the web app

python app.py

Open your browser to http://127.0.0.1:5001. The landing page loads with the hero section and stats bar. Click Analyse Text Now, or just go straight to /analyse.

How to Check It's Actually Working

1. Paste in two or three paragraphs of something you wrote yourself. The verdict should lean human, and most sentences should be green.
2. Now paste a chatbot answer of similar length. The verdict should flip and you should see red sentences.
3. Scroll down to the top 5 features panel. If you see feature names like sentence length standard deviation or type-token ratio with contribution values next to them, SHAP is running correctly.
4. Open the outputs/ folder. If confusion_matrices.png, roc_curves.png, calibration_diagram.png and the three SHAP plots are all sitting there, training completed properly and your report screenshots are ready.

Common Problems and Quick Fixes

• ModuleNotFoundError: textdescriptives — your venv probably isn't activated. Check for (venv) in the prompt, then run pip install textdescriptives.
• OSError: [E050] Can't find model 'en_core_web_sm' — you skipped Step 4. Run python -m spacy download en_core_web_sm with the venv active.
• No CSV found in data/ — the file is either named differently or sitting in the wrong folder. It has to be inside project/data/.
• Port 5001 already in use — change the port number on the last line of app.py to 5002 or 8000 and rerun.
• SHAP waterfall plot error — older SHAP versions break on this plot type. Run pip install --upgrade shap and make sure you're on 0.45 or newer.
• TensorFlow prints oneDNN and AVX warnings on startup — those are informational, not errors. Ignore them completely.

Still stuck after all that? Message the CodeAj team with a screenshot of the full error and we'll sort it out.