README.md

FairFare

A UK train travel expert system chatbot that helps you find cheap tickets, check journey details, and explore delay predictions.

Requirements

• Python 3.10+
• A Google Gemini API key for the chatbot
• National Rail Open Data credentials for live ticket prices

Setup

1. Create a virtual environment

   python -m venv venv

   Activate it:

   • Windows: venv\Scripts\activate

2. Install dependencies

   pip install -r requirements.txt
   pip install google-genai

3. Configure environment variables

   Create a .env file in the project root:

   GEMINI_API_KEY=your_gemini_api_key
   NATIONAL_RAIL_USERNAME=your_username
   NATIONAL_RAIL_PASSWORD=your_password

4. Optional: station list

   Place StationNameAndCode.csv in data/ for the full UK station list.

Run the app

From the project root (with the virtual environment active):

python main.py

Open http://localhost:3000 in your browser to use the chatbot.

The SQLite database (database/train.db) is created automatically on first run.

Optional: train delay models

Delay prediction needs historical data and trained model files (not committed to git).

1. Add service detail CSVs under data/service_details/ (see utils/preprocess_data.py for expected filenames).

2. Build the cleaned dataset and train a model:

   python utils/preprocess_data.py
   python models/randomforest.py

   Other models: python models/mlp.py, python models/k-nearest.py

3. Load journey duration stats into the database:

   python models/data_loader.py

Project layout

Path	Purpose
main.py	HTTP server and chatbot entry point
chatbot/	Conversation flow and validation
frontend/	Web UI (HTML/CSS)
services/	Tickets, delays, LLM, journey history
database/	SQLite setup and station data
models/	ML training scripts and saved models
tests/	Manual / integration test scripts