Spaces:
Sleeping
Sleeping
File size: 3,160 Bytes
e5bb0bb ae6339f 88d8679 e5bb0bb ae6339f 92f6762 e5bb0bb 88d8679 e5bb0bb fb4b0b6 f4f5e62 fb4b0b6 f4f5e62 fb4b0b6 f4f5e62 fb4b0b6 f4f5e62 fb4b0b6 f4f5e62 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 | ---
title: Housing Price API
emoji: 💻
colorFrom: purple
colorTo: red
sdk: gradio
sdk_version: 6.20.0
python_version: "3.12"
app_file: app.py
pinned: false
license: mit
short_description: Production ML API for housing price prediction
---
# 🏠 House Price Predictor
A production-ready ML system that predicts residential house sale prices using a stacking ensemble trained on the [Kaggle Housing Prices dataset](https://www.kaggle.com/c/house-prices-advanced-regression-techniques) — **Top 16 / 4,000+ participants**.
**Stack:** scikit-learn · CatBoost · FastAPI · PostgreSQL · Docker · Gradio · Hugging Face Spaces
---
## Model
A stacking ensemble of three base learners with an SGDRegressor meta-model:
| Model | Role |
|---|---|
| GradientBoostingRegressor | Base learner |
| CatBoostRegressor | Base learner |
| KernelRidge (RBF) | Base learner |
| SGDRegressor | Meta-model |
Eight features are engineered at inference time: `TotalSF`, `TotalQualSF`, `Age`, `TimeSinceRemod`, `InteriorQualityScore`, `TotalBaths`, `HasPorchDeck`, `TotalPorchDeckSF`.
### Performance (80/20 hold-out split)
| Model | RMSLE | MAE | MAPE | R² |
|---|---|---|---|---|
| Baseline (predict mean price) | 0.397 | $55,453 | 32.6% | -0.00 |
| GradientBoostingRegressor | 0.118 | $13,027 | 8.0% | 0.912 |
| CatBoostRegressor | 0.116 | $12,793 | 7.9% | 0.914 |
| KernelRidge (RBF) | 0.124 | $13,667 | 8.4% | 0.902 |
| **Stacking Ensemble** | **0.117** | **$12,997** | **7.9%** | **0.914** |
*Regenerate via `python -m ml.export_model` — see `ml/artifacts/metrics.json` for raw values.*
**Interpretation:** on a market with a median sale price of $163,000, the model's typical prediction is off by about **8%** (~$13,000) — a ~24x reduction in error versus guessing the mean price for every house. CatBoost alone is marginally more accurate on raw MAE than the stack; stacking wins narrowly on MAPE/R² and is kept as the deployed model for robustness across the three learners' different error profiles rather than for a large accuracy gain.
---
## Deployments
This repo ships two separate deployment paths built on the same trained artifacts (`ml/artifacts/`):
| Path | Entry point | Stack | Use case |
|---|---|---|---|
| **Live demo** | `app.py` | Gradio, no DB | Deployed on [HF Spaces](https://huggingface.co/spaces/Ezio2001/Housing_Price_API) — `app_file` in this README's frontmatter |
| **Local API stack** | `app/main.py` | FastAPI + PostgreSQL | Run via `docker-compose up`; persists every prediction to Postgres (`/predict`, `/predictions`) |
The Gradio demo is what's publicly live. The FastAPI/Postgres stack is the production-style API for local/self-hosted use.
## Run Locally
### Prerequisites
- Python 3.10+
- `train.csv` from [Kaggle](https://www.kaggle.com/c/house-prices-advanced-regression-techniques/data) placed in `data/`
### Installation
```bash
pip install -r requirements.txt
```
### Train the model
```bash
python -m ml.export_model
```
### Launch the Gradio demo
```bash
python app.py
```
### Launch the FastAPI + Postgres stack
```bash
docker-compose up --build
# API docs at http://localhost:8080/docs
```
|