Crime IQ - Karachi Crime Analysis ML Model

Machine Learning-Powered Crime Predictive Analysis Platform

---

---

📋 Table of Contents

• About The Project
• 📸 Screenshots
• ⭐ Repository Visitors
• ✨ Features
• 🛠️ Tech Stack
• 🚀 Getting Started
  • Prerequisites
  • Installation
  • Running the Application
• 📁 Project Structure
• 📖 API Documentation
• 🗺️ Available Nodes
• 🔐 Security Notes
• 🤝 Contributing
• 📄 License
• 👥 Team
• ❤️ Made with Love

---

About The Project

CrimeIQ is an end-to-end crime analytics and prediction platform developed to assist researchers, law enforcement agencies, and public safety analysts in understanding crime trends within Karachi, Pakistan.

Using historical crime records combined with synthetic demographic information of suspects, the platform trains machine learning models to classify and predict the most probable crime category based on situational and demographic inputs.

💡 Live Demo: CrimeIQ - Analysis & Prediction Portal (Live Website)

🧠 Model Performance & Selection

We compared three different machine learning models using the complete ML lifecycle (data cleaning, scaling, handling class imbalances, and splitting):

1. Random Forest Classifier (Best Performing): Achieved ~97.8% Accuracy and ~95.6% Precision. Excellent for modeling complex boundaries.
2. Decision Tree Classifier: Achieved ~95.2% Accuracy. Highly explainable, but slightly more prone to variance.
3. Logistic Regression: Achieved ~70.4% Accuracy. Serving as our baseline linear classifier.

---

📸 Screenshots

Website Snapshots

---

⭐ Repository Visitors

Keep track of the number of analysts, developers, and researchers visiting and cloning this repository:

Thank you for visiting! If you find this project useful, please consider giving it a ⭐

---

✨ Features

• 🤖 Interactive Prediction Engine: Input parameters like Karachi Area, suspect age, suspect gender, educational levels, and motives to test model predictions in real-time.
• 📈 Rich Analytics Dashboard: View metrics cards, prediction histories, risk scoring indexes, and categorical predictions distribution.
• 📰 Live Karachi Crime News: Interacts with the Currents API proxy to pull the latest headlines and articles concerning regional security.
• 💎 Glassmorphic User Interface: Sleek, modern styling with dark mode gradients, interactive animations (via AOS), and responsive CSS grids.
• 🔐 User Access flows: Included interactive Login and Sign Up interfaces for user account simulation.

---

🛠️ Tech Stack

Our platform is engineered using modern web technologies and a robust Python data stack:

Frontend

Backend

Libraries & Frameworks

Machine Learning Models & Algorithms

---

🚀 Getting Started

Follow these steps to set up and run CrimeIQ locally on your system.

Prerequisites

Ensure you have the following installed:

• Python 3.8+
• Git

Installation

1. Clone the Repository:

   git clone https://github.com/Blue-Rangoon/Karachi-Crime-Analysis-ML-Model.git
   cd Karachi-Crime-Analysis-ML-Model

2. Set Up a Virtual Environment (Optional but recommended):

   python -m venv venv
   # On Windows:
   venv\Scripts\activate
   # On macOS/Linux:
   source venv/bin/activate

3. Install Dependencies:

   pip install -r requirements.txt

4. Environment Configuration: Create a .env file in the root directory and add your Currents API Key to enable the live news module:

   CURRENTS_KEY=your_api_key_here

Running the Application

Start the Flask development server:

python app.py

Note

On the first run, app.py detects if the large Random Forest model (crime_model.joblib, ~354MB) is missing. It will automatically download the pre-trained model file from Google Drive using gdown. This might take a couple of minutes depending on your internet connection.

Once loaded, access the application in your browser at: http://127.0.0.1:5000

---

📁 Project Structure

Here is the structural overview of the repository:

Karachi-Crime-Analysis-ML-Model/
├── dataset/
│   └── karachi_crime.csv        # Local dataset
├── scripts/
│   ├── index.js                 # Authentication & UI controls
│   └── dashboard.js             # Prediction logic & charts visualization
├── styles/
│   ├── index.css                # Base styling & landing page design
│   └── dashboard.css            # Dashboard layouts & card component designs
├── app.py                       # Main Flask web API routing & server
├── train_model.py               # Comprehensive training notebook conversion
├── train_and_save_model.py      # Core data preparation & model generation script
├── vercel.json                  # Deployment serverless configuration
├── requirements.txt             # Required Python libraries list
├── LICENSE                      # MIT License file
├── index.html                   # Login & Landing page structure
└── dashboard.html               # Main analytics layout structure

---

📖 API Documentation

1. Get Categorical Feature Encodings

• Route: /api/features
• Method: GET
• Description: Returns lists of encoded categorical labels accepted by models. Used to populate select inputs on frontend dynamically.
• Success Response (200 OK):

  {
    "Karachi Area": ["Gulshan-e-Iqbal", "Saddar", "Clifton", "Korangi", "..."],
    "Suspect_Gender": ["Male", "Female", "Unknown"],
    "Crime_Motive": ["Financial Gain", "Personal Enmity", "Drug Addiction", "..."]
  }

2. Predict Crime Category

• Route: /api/predict
• Method: POST
• Headers: Content-Type: application/json
• Payload:

  {
    "Model": "Random Forest",
    "Month": "January",
    "Karachi Area": "Saddar",
    "Crime Count": 1.0,
    "Suspect_Age": "21-30",
    "Suspect_Gender": "Male",
    "Occupation": "Unemployed",
    "Education_Level": "Undergraduate",
    "Crime_Motive": "Financial Gain"
  }

• Success Response (200 OK):

  {
    "prediction": "ROBBERY",
    "confidence": 98.4,
    "risk_score": 98,
    "risk_level": "High",
    "top_predictions": [
      {"category": "ROBBERY", "probability": 0.984},
      {"category": "THEFT", "probability": 0.016}
    ],
    "model_name": "Random Forest",
    "accuracy": 0.978,
    "precision": 0.956
  }

3. Retrieve Crime News

• Route: /api/news
• Method: GET
• Description: Contacts Currents API and returns the top 10 articles matching keywords "Karachi crime".

---

🗺️ Available Nodes

Below is the collection of interactive interfaces and routes accessible within the system:

• 🏠 / (index.html): The landing page containing feature breakdowns, pricing metrics, project details, and auth modal triggers (Login / Sign Up).
• 📊 /dashboard.html: The main user hub containing live crime analytics charts, predictions entry forms, risk indicators, and real-time news feeds.
• ⚙️ /api/features: Fetches categories metadata.
• 🔮 /api/predict: Sends configuration variables to models to retrieve predictions.
• 📰 /api/news: News proxy endpoint.

---

🔐 Security Notes

• API Keys: Ensure your CURRENTS_KEY token is stored in the .env file. Never commit .env configurations to public repositories.
• CORS Handling: app.py implements CORS headers globally using @app.after_request to permit requests across developer sub-environments. Be sure to narrow this configuration down for strict production environments.
• Robust Model Fallbacks: If a categorical input value is sent that was not present during model encoder fitting, the backend safe-handles it by substituting Unknown or selecting the default fallback category.

---

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

Distributed under the AGPL-3.0 License. See LICENSE for more information.

---

👥 Team

Sadia Shoaib Lead Developer

Saad Ali Rizvi Frontend Developer

Laiba Idrees Backend Engineer

Syed Anas Hasan Integration & Technical Specialist

Alishba Batool Research & Documentation

---

❤️ Made with Love

Built with passion by Student Development Team

© 2026 CrimeIQ - Karachi Crime Analysis & Prediction Portal. All rights reserved.