README.md

metadata

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

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

---

✨ 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

# 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.