README.md

---
title: Gale Shapely
emoji: 🏠
colorFrom: blue
colorTo: purple
sdk: streamlit
sdk_version: "1.30.0"
app_file: app.py
pinned: false
---

# 🏠 Roommate Allocation System — Python & Streamlit Edition

[![Python](https://img.shields.io/badge/Python-3.9+-3776AB?logo=python&logoColor=white)](https://python.org)
[![Streamlit](https://img.shields.io/badge/Streamlit-1.30+-FF4B4B?logo=streamlit&logoColor=white)](https://streamlit.io)
[![Algorithm](https://img.shields.io/badge/Algorithm-Gale--Shapley-6C63FF)](https://en.wikipedia.org/wiki/Gale%E2%80%93Shapley_algorithm)

A modern **Streamlit UI** for the Gale-Shapley Roommate Allocation algorithm.  
This version uses **Python** for the algorithm and **file-system storage** (JSON) instead of MySQL.

> 🔗 **For the original C + MySQL version**, see:  
> [https://github.com/Harshwardhan-Deshmukh03/Roommate-allocation-using-Gale-Shapley-Algorithm.git](https://github.com/Harshwardhan-Deshmukh03/Roommate-allocation-using-Gale-Shapley-Algorithm.git)

---

## ✨ Features

- **Stable Matching** via the Nobel Prize-winning Gale-Shapley algorithm
- **Two-Stage Allocation**: Roommate matching → CGPA-ranked room assignment
- **CSV Import**: Bulk-upload students & rooms via CSV files
- **File-System Storage**: No database needed — data stored as JSON
- **Interactive Charts**: Plotly visualizations of CGPA distributions
- **Premium UI**: Dark theme with glassmorphism, gradients, and animations

---

## 🚀 Quick Start

```bash
# 1. Create virtual environment
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS/Linux

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run the app
streamlit run app.py
```

---

## 📁 Project Structure

```
streamlit_gale_shapely/
├── app.py                  # Main Streamlit UI application
├── gale_shapley.py         # Gale-Shapley algorithm (Python port)
├── db.py                   # File-system database layer (JSON)
├── requirements.txt        # Python dependencies
├── .streamlit/
│   └── config.toml         # Streamlit theme configuration
├── data/
│   ├── students.json       # Student records (replaces MySQL 'main' table)
│   ├── rooms.json          # Room records (replaces MySQL 'RoomNum' table)
│   └── allocations.json    # Allocation results
└── sample_csv/
    ├── sample_students_10.csv   # 10 students (5 pairs)
    ├── sample_rooms_5.csv       # 5 rooms for 10 students
    ├── sample_students_26.csv   # 26 students (13 pairs)
    └── sample_rooms_13.csv      # 13 rooms for 26 students
```

---

## 📊 CSV Format

### Students CSV
| Column | Type | Description |
|--------|------|-------------|
| id | int | Unique student ID (0-indexed) |
| name | str | Student name |
| cgpa | float | CGPA (0.0–10.0) |
| pref_roommate | str | Space-separated preferred roommate IDs |
| pref_room | str | Space-separated preferred room IDs |

### Rooms CSV
| Column | Type | Description |
|--------|------|-------------|
| room_id | int | Unique room ID (0-indexed) |
| room_number | str | Room label (e.g., "A101") |

---

## 🧠 Algorithm

1. **Stage 1 — Roommate Matching**: Gale-Shapley pairs students into stable roommate matches.
2. **Stage 2 — Room Allocation**: Pairs ranked by max CGPA select rooms via Gale-Shapley.

Higher CGPA pairs get priority in room selection.