Upload README.md with huggingface_hub

README.md

@@ -1,206 +1,47 @@
-# Used Car Price Prediction Flask App
+---
+title: Nigerian Used Car Price Predictor
+emoji: 🚗
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+---
 
-A Flask web application that predicts used car prices using LightGBM and sentence embeddings.
+# Nigerian Used Car Price Predictor
 
-## Project Structure
-
-```
-project/
-│
-├── app.py                          # Main Flask application
-├── requirements.txt                # Python dependencies
-├── README.md                       # This file
-│
-├── templates/
-│   └── index.html                  # Main web interface
-│
-├── static/
-│   └── Car Images/                 # Background images
-│       ├── 1.png
-│       ├── 2.png
-│       ├── 3.png
-│       ├── 4.png
-│       └── 5.png
-│
-├── embeddings/
-│   ├── car_names_list.txt         # List of car names from training
-│   ├── car_name_embeddings.npy    # Pre-computed embeddings
-│   ├── categorical_features_map.pkl # Categorical encoding mapping
-│   └── all_mpnet_base_v2/         # Sentence transformer model
-│       ├── config.json
-│       ├── model.safetensors
-│       └── ...
-│
-└── model/
-    ├── lightgbm_used_car_model.pkl # Trained LightGBM model
-    ├── model_metrics.json          # Model performance metrics
-    └── model_parameters.json       # Model hyperparameters
-```
-
-## Setup Instructions
-
-### 1. Move Files to Correct Locations
-
-Since your `Car Images` folder is currently in the root, you need to move it to the `static` folder:
-
-```bash
-# Create static directory
-mkdir static
-
-# Move Car Images to static
-mv "Car Images" static/
-```
-
-### 2. Install Dependencies
-
-```bash
-# Create virtual environment (recommended)
-python -m venv venv
-
-# Activate virtual environment
-# On Windows:
-venv\Scripts\activate
-# On Mac/Linux:
-source venv/bin/activate
-
-# Install dependencies
-pip install -r requirements.txt
-```
-
-### 3. Run the Application
-
-```bash
-python app.py
-```
-
-The app will be available at: `http://localhost:5000`
-
-## How It Works
-
-### 1. **User Input**
-Users provide:
-- Car name/model (e.g., "Toyota Camry 2015")
-- Origin (Local/Foreign)
-- Transmission (Automatic/Manual)
-- Fuel Type (Petrol/Diesel/Hybrid/Electric)
-- Interior Color
-- Exterior Color
-
-### 2. **Feature Engineering**
-The app processes inputs through several steps:
-
-**a. Name Embeddings:**
-- Uses the pre-trained `all-mpnet-base-v2` sentence transformer
-- Converts car name into 768-dimensional embedding vector
-- Extracts specific dimensions used by the model (e.g., `name_emb_307`, `name_emb_741`)
-
-**b. Categorical Encoding:**
-- Applies one-hot encoding to categorical features
-- Uses the same encoding schema from training (saved in `categorical_features_map.pkl`)
-- Creates binary columns like `origin_local`, `interior_color_coffee brown`, etc.
-
-### 3. **Feature Selection**
-The model uses only 12 specific features:
-- 10 name embedding dimensions
-- 2 categorical features (origin_local, interior/exterior colors)
-
-### 4. **Prediction**
-- LightGBM model predicts the price
-- Result is formatted and displayed in Nigerian Naira (₦)
-
-## Model Features
-
-The trained model uses these 12 features:
-```python
-[
-    'name_emb_307', 'name_emb_741', 'origin_local', 'name_emb_559',
-    'name_emb_618', 'name_emb_207', 'name_emb_661', 'name_emb_766',
-    'name_emb_541', 'name_emb_518', 'interior_color_coffee brown',
-    'exterior_color_dark silver'
-]
-```
-
-## API Endpoints
-
-### `GET /`
-Returns the main HTML interface
-
-### `POST /predict`
-Predicts car price based on input features
-
-**Request Body:**
-```json
-{
-    "car_name": "Toyota Camry 2015",
-    "origin": "local",
-    "transmission": "automatic",
-    "fuel_type": "petrol",
-    "interior_color": "coffee brown",
-    "exterior_color": "dark silver"
-}
-```
-
-**Response:**
-```json
-{
-    "success": true,
-    "predicted_price": 4500000.0,
-    "formatted_price": "₦4,500,000.00"
-}
-```
-
-### `GET /health`
-Health check endpoint
+A machine learning web application that predicts used car prices in Nigeria using LightGBM and sentence embeddings.
 
 ## Features
 
-✅ **Dynamic Background:** Rotating car images every 5 seconds  
-✅ **Real-time Predictions:** Instant price estimates  
-✅ **Modern UI:** Glassmorphism design with smooth animations  
-✅ **Mobile Responsive:** Works on all devices  
-✅ **Error Handling:** Clear error messages for invalid inputs  
-✅ **Loading States:** Visual feedback during prediction  
-
-## Troubleshooting
-
-### Issue: "Model not found"
-**Solution:** Ensure all files are in the correct directories as shown in the project structure.
-
-### Issue: "Categorical encoding error"
-**Solution:** Make sure you're using the exact same categorical values as during training. Check the `categorical_features_map.pkl` for valid options.
-
-### Issue: "Import error for sentence_transformers"
-**Solution:** Reinstall with: `pip install sentence-transformers==2.2.2`
-
-### Issue: Background images not showing
-**Solution:** 
-1. Ensure images are in `static/Car Images/`
-2. Check file permissions
-3. Restart the Flask server
-
-## Production Deployment
-
-For production use with Gunicorn:
+- 🚗 Predict car prices based on multiple attributes
+- 🤖 Uses advanced sentence embeddings for car name processing
+- ⚡ Fast predictions with LightGBM model
+- 🎨 Modern, responsive UI with dynamic backgrounds
+- 💰 Prices displayed in Nigerian Naira (₦)
 
-```bash
-gunicorn -w 4 -b 0.0.0.0:5000 app:app
-```
+## How to Use
 
-## Model Performance
+1. Enter the car name/model (e.g., "Toyota Camry 2015")
+2. Select the origin (Local/Foreign)
+3. Choose transmission type
+4. Select fuel type
+5. Pick interior and exterior colors
+6. Click "Predict Price" to get instant estimate
 
-Check `model/model_metrics.json` for:
-- RMSE (Root Mean Squared Error)
-- MAPE (Mean Absolute Percentage Error)
-- R² Score
+## Tech Stack
 
-## Notes
+- **Backend:** Flask + Gunicorn
+- **ML Model:** LightGBM
+- **Embeddings:** Sentence Transformers (all-mpnet-base-v2)
+- **Frontend:** HTML, CSS, JavaScript
+- **Deployment:** Docker
 
-- The model was trained on Nigerian used car data
-- Prices are in Nigerian Naira (₦)
-- The sentence transformer uses 768-dimensional embeddings
-- Only 12 features are used for final predictions (selected via stepwise selection)
-- The app handles unseen categorical values by setting them to 0
+## Model Details
 
-## License
+The model uses:
+- 10 sentence embedding dimensions from car names
+- 2 categorical features (origin and color combinations)
+- Trained on Nigerian used car market data
 
-This project is for educational use.
+---