Installation Guide

Installation Guide — RailGrid AI

Total time from zip file to a live dashboard: about 20 to 25 minutes, and most of that is just waiting for pip and the notebook. Follow this in order and don't skip step 5, because step 5 is where almost everyone gets stuck.

Prerequisites

• Python 3.10 or newer. If you don't have it, grab it from python.org. On Windows, tick the "Add Python to PATH" checkbox during install — if you miss it, every command below will fail with "python is not recognized." Check with python --version.
• pip. Ships with Python. Confirm with pip --version.
• 2 GB free disk space for the packages, model files and generated figures.
• An internet connection on first run. The map tiles and Leaflet libraries load from CDN, so a fully offline machine will show you an empty grey map.
• Any code editor. VS Code is fine.

Step 1 — Get the code and the dataset

Extract the project folder you downloaded, or clone it:

git clone <your-repository-url> railgrid-ai
cd railgrid-ai

Now the dataset. Download india_railway_stations.csv from the Kaggle "Indian Railway Stations and Routing Network" dataset and drop it in the project root — the same folder as app.py. Not inside a subfolder. Root.

Step 2 — Create a virtual environment

This keeps the project's packages away from the rest of your system. Skipping it is the number one cause of ModuleNotFoundError later.

Windows

python -m venv venv
venv\Scripts\activate

macOS and Linux

python3 -m venv venv
source venv/bin/activate

You'll know it worked when (venv) appears at the start of your terminal prompt. If it isn't there, the environment isn't active and nothing you install will land in the right place.

Step 3 — Install the dependencies

pip install -r requirements.txt

Then the extras the training notebook needs:

pip install jupyter matplotlib seaborn scipy

This takes two or three minutes on a decent connection. Some pip warnings in yellow are normal. Red errors are not.

Step 4 — Train the models

jupyter notebook railgrid_ai_training.ipynb

Your browser opens the notebook. Run every cell from the top, in order — Cell menu, then Run All, or just hit Shift+Enter through all 56 of them. On a normal laptop this finishes in 3 to 6 minutes.

Watch for these four confirmations as it runs:

1. The cleaning step reports how many rows survived. You want 8,801.
2. The leakage check prints a crosstab of is_junction against route_count. Screenshot this one — it's report material.
3. Model A prints its accuracy and cross-validation scores, around 0.947.
4. The final cell lists every file it saved.

Three new folders appear when it's done: models/, figures/ and outputs/.

Step 5 — Put the generated folders where Flask expects them

Here's the thing — Flask looks for models/ and outputs/ sitting directly beside app.py. If you ran Jupyter from a different directory, they landed somewhere else and the app won't find them.

cp -r /path/to/notebook/models ./models
cp -r /path/to/notebook/outputs ./outputs

Verify these three paths exist before moving on:

app.py
models/metadata.json
outputs/stations_enriched.csv

Step 6 — Run the server

python app.py

Open http://127.0.0.1:5000 in your browser.

How to Verify It's Actually Working

Visit http://127.0.0.1:5000/api/health. A healthy install returns:

{"ready": true, "warnings": []}

If warnings has anything in it, read what it names — it'll tell you which .pkl file is missing.

Then do the real test. Go to the Live Prediction page and click somewhere on the map, say around Kolkata. You should get back a predicted zone with a probability chart, a junction likelihood, an expected route count, and distances to nearby stations. If that returns data, all three models loaded correctly and you're done.

Common Issues

What you see	What to do
A setup notice instead of the dashboard	outputs/stations_enriched.csv is missing. Go back to step 5.
Warnings in /api/health about .pkl files	The models/ folder isn't beside app.py. Copy it across.
ModuleNotFoundError	The virtual environment isn't active, or you installed packages before activating it. Reactivate and reinstall.
Blank grey map, but station points render	Tile server unreachable. Check your internet.
Route tracer says no corridor exists	Those two stations sit in different connected components. Try two mainland codes.
Corridor mesh takes forever to load	It's drawing up to 9,000 polylines. Lower the limit parameter in static/js/network.js.
Prediction endpoint throws an error	The zone classifier or label encoder didn't load. Scroll up in your terminal to the startup output — the reason is printed there.

Optional — Running It Beyond Your Laptop

For a demo on a college server or anything not local, put it behind a WSGI server:

pip install gunicorn
gunicorn -w 2 -b 0.0.0.0:8000 app:app

Stick to two workers. Each one loads its own copy of the models and the spatial index into memory, so four workers will eat four times the RAM for no real gain at demo traffic.