Update readme

README.md

@@ -1,79 +1,58 @@
----
-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
-  - scikit-learn
-datasets:
-  - synthetic-electricity-data
-metrics:
-  - mse
-  - rmse
-  - mae
-  - r2
-library_name: scikit-learn
----
-
-# ⚡ 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
+# 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
 
 ## 🏗️ Project Structure
 
 ```
+lin-re-model/
 ├── src/
-│   ├── app.py              # Main Gradio application
-│   ├── model.py            # ML model implementation
-│   └── data_generator.py   # Synthetic data generation
+│   ├── __init__.py
+│   ├── data_generator.py      # Synthetic data generation
+│   ├── model.py              # ML model training and prediction
+│   └── app.py                # Gradio web interface
 ├── tests/
-│   ├── 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
+│   ├── __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
 ```
 
-## 🧪 Usage
+## 🚀 Quick Start
+
+### Prerequisites
 
-### Local Development
+- Python 3.8 or higher
+- pip (Python package installer)
 
-1. **Clone the repository**:
+### Installation
+
+1. **Clone the repository** (if not already done):
 
    ```bash
-   git clone https://github.com/YOUR_USERNAME/electricity-consumption-predictor.git
-   cd electricity-consumption-predictor
+   git clone <repository-url>
+   cd lin-re-model
    ```
 
 2. **Install dependencies**:
@@ -85,67 +64,235 @@ A machine learning application that predicts daily electricity consumption based
 3. **Run the application**:
 
    ```bash
-   python app.py
+   python src/app.py
    ```
 
-4. **Run tests**:
-   ```bash
-   pytest tests/
-   ```
+4. **Open your browser** and navigate to `http://localhost:7860`
 
-### Hugging Face Spaces
+## 🧪 Testing
 
-The app is automatically deployed on Hugging Face Spaces. Simply visit the live demo link above to use the application.
+This project includes comprehensive tests to ensure code quality and functionality. The test suite covers:
 
-## 📈 How It Works
+- **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
 
-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
+### Running Tests
 
-## 🎯 Model Features
+#### Option 1: Using the test runner script
 
-- **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
+```bash
+# Run all tests with coverage
+python run_tests.py
 
-## 📊 Example Predictions
+# Run only unit tests
+python run_tests.py unit
 
-| 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              |
+# Run only integration tests
+python run_tests.py integration
+```
 
-## 🔧 Configuration
+#### Option 2: Using pytest directly
 
-The model can be customized by modifying parameters in `src/model.py`:
+```bash
+# Run all tests
+pytest
 
-- Training data size
-- Feature weights
-- Model hyperparameters
+# Run with verbose output
+pytest -v
 
-## 🧪 Testing
+# 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!
+```
 
-Run the test suite to ensure everything works correctly:
+## 📊 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
+
+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
+
+### Step 2: Make Predictions
+
+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
+
+### Step 3: Understand the Model
+
+1. Navigate to the "Model Information" tab
+2. Click "Show Model Information"
+3. Review feature coefficients and model interpretation
+
+## 🔧 Development
+
+### Adding New Tests
+
+To add new tests:
+
+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
+
+### Test Best Practices
+
+- **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)
+
+### Running Tests in Development
+
+During development, you can run tests in different ways:
 
 ```bash
-# Run all tests
-pytest tests/
+# Quick test run (no coverage)
+pytest -x  # Stop on first failure
 
-# Run with coverage
-pytest tests/ --cov=src
+# Run tests in parallel (if pytest-xdist installed)
+pytest -n auto
 
-# Run specific test file
-pytest tests/test_model.py
+# Run tests with detailed output
+pytest -v -s
+
+# Run tests and watch for changes
+pytest-watch  # Requires pytest-watch package
 ```
 
-## 📝 License
+## 🚀 Deployment
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+### Local Deployment
+
+```bash
+python src/app.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
+
+### 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
 
 ## 🤝 Contributing
 
@@ -153,16 +300,15 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 2. Create a feature branch
 3. Make your changes
 4. Add tests for new functionality
-5. Submit a pull request
+5. Ensure all tests pass
+6. Submit a pull request
 
-## 📞 Support
+## 📄 License
 
-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
+This project is licensed under the MIT License - see the LICENSE file for details.
 
----
+## 🙏 Acknowledgments
 
-**Built with ❤️ using Gradio and scikit-learn**
+- Gradio team for the excellent web interface framework
+- Scikit-learn team for the machine learning library
+- The MLOps community for best practices and guidance