Add YAML metadata to README.md and create app.py entry point for HF Spaces

README.md

@@ -1,58 +1,77 @@
-# Daily Household Electricity Consumption Predictor
-
-A web-based application designed to help Nigerian households estimate their daily electricity usage in Kilowatt-hours (kWh). This project serves as a practical learning vehicle for Machine Learning Operations (MLOps), covering the full lifecycle from data preparation and model training to deployment, monitoring, and continuous improvement.
-
-## 🎯 Project Goals
-
-### Business Goals
-
-- **Empower Households**: Provide users with a simple, accessible tool to understand and predict their daily electricity consumption
-- **Promote Energy Awareness**: Help users identify factors influencing their electricity usage, encouraging more efficient energy habits
-- **Inform Budgeting**: Enable users to better estimate their electricity bills, reducing financial surprises
-- **Foundational MLOps Learning**: Serve as a concrete project to apply and understand core MLOps principles
-
-### Machine Learning & Technical Goals
-
-- **Accurate Prediction**: Develop a regression model capable of predicting daily kWh consumption with acceptable accuracy
-- **User-Friendly Interface**: Create an intuitive web interface that allows easy input of features and clear display of predictions
-- **Deployable Application**: Build a self-contained application that can be deployed to a public platform
-- **MLOps Readiness**: Design the application with modularity and best practices that facilitate future MLOps implementation
+---
+title: 'Electricity Consumption Predictor'
+emoji: '⚡'
+colorFrom: 'blue'
+colorTo: 'purple'
+sdk: 'gradio'
+sdk_version: '3.40.1'
+app_file: 'app.py'
+pinned: false
+license: 'mit'
+tags:
+  - machine-learning
+  - regression
+  - electricity
+  - consumption
+  - prediction
+  - gradio
+datasets:
+  - synthetic-electricity-data
+metrics:
+  - mse
+  - rmse
+  - mae
+  - r2
+---
+
+# ⚡ Electricity Consumption Predictor
+
+A machine learning application that predicts daily electricity consumption based on various factors like temperature, day of the week, and special events.
+
+## 🚀 Live Demo
+
+[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/surahj/electricity-consumption-predictor)
+
+## 📊 Features
+
+- **Temperature-based predictions**: Considers how temperature affects electricity usage
+- **Day of week analysis**: Accounts for different consumption patterns on weekdays vs weekends
+- **Special events**: Factors in holidays and major events
+- **Interactive interface**: User-friendly Gradio web interface
+- **Model insights**: Detailed explanation of prediction factors
+
+## 🛠️ Technology Stack
+
+- **Machine Learning**: scikit-learn (Linear Regression)
+- **Data Processing**: pandas, numpy
+- **Web Interface**: Gradio
+- **Model Persistence**: joblib
 
 ## 🏗️ Project Structure
 
 ```
-lin-re-model/
 ├── src/
-│   ├── __init__.py
-│   ├── data_generator.py      # Synthetic data generation
-│   ├── model.py              # ML model training and prediction
-│   └── app.py                # Gradio web interface
+│   ├── app.py              # Main Gradio application
+│   ├── model.py            # ML model implementation
+│   └── data_generator.py   # Synthetic data generation
 ├── tests/
-│   ├── __init__.py
-│   ├── test_data_generator.py # Data generator tests
-│   ├── test_model.py         # Model tests
-│   ├── test_app.py           # Application tests
-│   └── test_integration.py   # Integration tests
-├── requirements.txt          # Python dependencies
-├── pytest.ini              # Pytest configuration
-├── run_tests.py            # Test runner script
-└── README.md               # This file
+│   ├── test_model.py       # Model unit tests
+│   ├── test_app.py         # App unit tests
+│   └── test_integration.py # Integration tests
+├── app.py                  # Hugging Face Spaces entry point
+├── requirements.txt        # Python dependencies
+└── README.md              # This file
 ```
 
-## 🚀 Quick Start
-
-### Prerequisites
+## 🧪 Usage
 
-- Python 3.8 or higher
-- pip (Python package installer)
+### Local Development
 
-### Installation
-
-1. **Clone the repository** (if not already done):
+1. **Clone the repository**:
 
    ```bash
-   git clone <repository-url>
-   cd lin-re-model
+   git clone https://github.com/YOUR_USERNAME/electricity-consumption-predictor.git
+   cd electricity-consumption-predictor
    ```
 
 2. **Install dependencies**:
@@ -64,235 +83,67 @@ lin-re-model/
 3. **Run the application**:
 
    ```bash
-   python src/app.py
+   python app.py
    ```
 
-4. **Open your browser** and navigate to `http://localhost:7860`
-
-## 🧪 Testing
-
-This project includes comprehensive tests to ensure code quality and functionality. The test suite covers:
-
-- **Unit Tests**: Individual component testing
-- **Integration Tests**: End-to-end workflow testing
-- **Data Quality Tests**: Validation of synthetic data generation
-- **Model Performance Tests**: Verification of model accuracy and consistency
-
-### Running Tests
-
-#### Option 1: Using the test runner script
-
-```bash
-# Run all tests with coverage
-python run_tests.py
-
-# Run only unit tests
-python run_tests.py unit
-
-# Run only integration tests
-python run_tests.py integration
-```
-
-#### Option 2: Using pytest directly
-
-```bash
-# Run all tests
-pytest
-
-# Run with verbose output
-pytest -v
-
-# Run with coverage report
-pytest --cov=src --cov-report=html
-
-# Run specific test file
-pytest tests/test_model.py
-
-# Run specific test class
-pytest tests/test_model.py::TestElectricityConsumptionModel
-
-# Run specific test method
-pytest tests/test_model.py::TestElectricityConsumptionModel::test_train_model
-```
-
-### Test Coverage
-
-The test suite provides comprehensive coverage including:
-
-- **Data Generator Tests**:
-
-  - Data generation with different parameters
-  - Data splitting functionality
-  - Data persistence (save/load)
-  - Data quality validation
-  - Reproducibility checks
-
-- **Model Tests**:
-
-  - Model initialization and training
-  - Feature preparation and validation
-  - Prediction functionality
-  - Model evaluation metrics
-  - Model persistence (save/load)
-  - Error handling
-
-- **Application Tests**:
-
-  - Web interface functionality
-  - User interaction flows
-  - Error handling in UI
-  - State management
-
-- **Integration Tests**:
-  - Complete workflow testing
-  - End-to-end functionality
-  - Performance consistency
-  - Data quality across components
-
-### Expected Test Results
-
-When all tests pass, you should see output similar to:
-
-```
-🧪 Running Daily Household Electricity Consumption Predictor Tests
-======================================================================
-============================= test session starts ==============================
-platform linux -- Python 3.8.x, pytest-7.4.0, pluggy-1.0.0
-rootdir: /path/to/lin-re-model
-plugins: cov-4.1.0
-collected 45 tests
-
-tests/test_app.py ...................                              [ 42%]
-tests/test_data_generator.py ...................                  [ 78%]
-tests/test_integration.py ..........                              [100%]
-
----------- coverage: platform linux, python 3.8.x-final-0 -----------
-Name                           Stmts   Miss  Cover   Missing
-------------------------------------------------------------
-src/__init__.py                    1      0   100%
-src/app.py                       180      5    97%   180-185
-src/data_generator.py             95      2    98%   95-97
-src/model.py                     180      8    96%   180-188
-------------------------------------------------------------
-TOTAL                           456     15    97%
-
-============================== 45 passed in 5.23s ==============================
-
-✅ All tests passed!
-```
-
-## 📊 Model Features
-
-The electricity consumption prediction model uses the following features:
-
-1. **Average Daily Temperature** (°C): Numerical input (15-35°C range)
-2. **Day of the Week**: Categorical input (Monday through Sunday)
-3. **Major Event**: Boolean input (Holiday, Power Outage, etc.)
-
-### Model Algorithm
-
-- **Algorithm**: Linear Regression
-- **Preprocessing**: StandardScaler for numerical features, OneHotEncoder for categorical features
-- **Evaluation Metrics**: MSE, RMSE, MAE, R²
-
-## 🎮 Using the Application
-
-### Step 1: Generate Data & Train Model
+4. **Run tests**:
+   ```bash
+   pytest tests/
+   ```
 
-1. Navigate to the "Data Generation & Training" tab
-2. Adjust parameters as desired:
-   - Number of Data Points (100-5000)
-   - Noise Level (0.01-0.5)
-   - Training/Validation/Test Set Proportions
-3. Click "Generate Data & Train Model"
-4. Review the training metrics and evaluation results
+### Hugging Face Spaces
 
-### Step 2: Make Predictions
+The app is automatically deployed on Hugging Face Spaces. Simply visit the live demo link above to use the application.
 
-1. Navigate to the "Prediction" tab
-2. Enter your parameters:
-   - Average Daily Temperature (15-35°C)
-   - Day of the Week
-   - Major Event (checkbox)
-3. Click "Predict Consumption"
-4. View your estimated daily electricity consumption
+## 📈 How It Works
 
-### Step 3: Understand the Model
+1. **Data Generation**: Creates synthetic electricity consumption data with realistic patterns
+2. **Model Training**: Trains a linear regression model on historical data
+3. **Feature Engineering**: Extracts relevant features (temperature, day of week, events)
+4. **Prediction**: Uses the trained model to predict consumption for new scenarios
+5. **Interpretation**: Provides detailed breakdown of prediction factors
 
-1. Navigate to the "Model Information" tab
-2. Click "Show Model Information"
-3. Review feature coefficients and model interpretation
+## 🎯 Model Features
 
-## 🔧 Development
+- **Temperature Effect**: Higher temperatures increase AC usage
+- **Day of Week**: Weekends typically have different consumption patterns
+- **Base Consumption**: Minimum daily electricity usage
+- **Event Impact**: Special events can significantly affect consumption
 
-### Adding New Tests
+## 📊 Example Predictions
 
-To add new tests:
+| Temperature | Day       | Event   | Predicted Consumption |
+| ----------- | --------- | ------- | --------------------- |
+| 25°C        | Monday    | None    | 16.5 kWh              |
+| 35°C        | Saturday  | Holiday | 22.3 kWh              |
+| 15°C        | Wednesday | None    | 14.1 kWh              |
 
-1. **Unit Tests**: Add to appropriate test file in `tests/`
-2. **Integration Tests**: Add to `tests/test_integration.py`
-3. **Follow naming convention**: `test_<functionality>`
-4. **Use descriptive docstrings**: Explain what the test validates
+## 🔧 Configuration
 
-### Test Best Practices
+The model can be customized by modifying parameters in `src/model.py`:
 
-- **Isolation**: Each test should be independent
-- **Descriptive names**: Test names should clearly indicate what they test
-- **Assertions**: Use specific assertions with meaningful messages
-- **Coverage**: Aim for high test coverage (>95%)
-- **Performance**: Tests should run quickly (<10 seconds total)
+- Training data size
+- Feature weights
+- Model hyperparameters
 
-### Running Tests in Development
+## 🧪 Testing
 
-During development, you can run tests in different ways:
+Run the test suite to ensure everything works correctly:
 
 ```bash
-# Quick test run (no coverage)
-pytest -x  # Stop on first failure
-
-# Run tests in parallel (if pytest-xdist installed)
-pytest -n auto
-
-# Run tests with detailed output
-pytest -v -s
-
-# Run tests and watch for changes
-pytest-watch  # Requires pytest-watch package
-```
-
-## 🚀 Deployment
+# Run all tests
+pytest tests/
 
-### Local Deployment
+# Run with coverage
+pytest tests/ --cov=src
 
-```bash
-python src/app.py
+# Run specific test file
+pytest tests/test_model.py
 ```
 
-### Hugging Face Spaces Deployment
-
-1. Create a new Space on Hugging Face
-2. Upload the project files
-3. Configure the Space to run `python src/app.py`
-4. The application will be available at your Space URL
-
-## 📈 Future Enhancements
-
-### MLOps Features (Future Phases)
-
-- **Data Versioning**: Implement DVC for data version control
-- **Experiment Tracking**: Integrate MLflow or Weights & Biases
-- **Model Registry**: Use MLflow Model Registry for model lifecycle management
-- **Containerization**: Create Dockerfile for reproducible environments
-- **CI/CD**: Set up GitHub Actions for automated testing and deployment
-- **Model Monitoring**: Implement monitoring for data drift and performance degradation
-- **Continuous Training**: Define triggers for automated retraining
+## 📝 License
 
-### Model Improvements
-
-- **Feature Engineering**: Add more complex features (historical averages, time of day, etc.)
-- **Advanced Models**: Experiment with Random Forest, Gradient Boosting, etc.
-- **Hyperparameter Tuning**: Implement automated hyperparameter optimization
-- **Ensemble Methods**: Combine multiple models for better predictions
+This project is licensed under the MIT License - see the LICENSE file for details.
 
 ## 🤝 Contributing
 
@@ -300,15 +151,16 @@ python src/app.py
 2. Create a feature branch
 3. Make your changes
 4. Add tests for new functionality
-5. Ensure all tests pass
-6. Submit a pull request
+5. Submit a pull request
 
-## 📄 License
+## 📞 Support
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+If you encounter any issues or have questions:
+
+- Open an issue on GitHub
+- Check the Hugging Face Spaces discussion
+- Review the test files for usage examples
 
-## 🙏 Acknowledgments
+---
 
-- Gradio team for the excellent web interface framework
-- Scikit-learn team for the machine learning library
-- The MLOps community for best practices and guidance
+**Built with ❤️ using Gradio and scikit-learn**