README.md

metadata

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 — 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 — 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 placed in data/

Installation

pip install -r requirements.txt

Train the model

python -m ml.export_model

Launch the Gradio demo

python app.py

Launch the FastAPI + Postgres stack

docker-compose up --build
# API docs at http://localhost:8080/docs