README.md

---
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
```