# ecowatt-predictor-ai

**Repository Path**: wavef/ecowatt-predictor-ai

## Basic Information

- **Project Name**: ecowatt-predictor-ai
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-02
- **Last Updated**: 2025-12-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EcoWatt Predictor AI

EcoWatt Predictor AI is a professional frontend application designed to forecast industrial and commercial electricity usage. It leverages Generative AI (Google Gemini or Local LLMs) to analyze historical power data, predict future consumption trends, and propose energy-saving strategies based on industry-standard formulas.

## Features

*   **Real-time Visualization**: Interactive dashboards showing historical data (Red), baseline predictions (Blue), and optimized usage (Green).
*   **AI-Powered Forecasting**: Uses LLMs to understand context and generate explainable forecasts.
*   **Dual AI Modes**:
    *   **Online Mode**: Integrates with Google Gemini 2.5 Flash for high-speed, reasoning-based predictions.
    *   **Local Mode**: Connects to local inference servers (e.g., Ollama, vLLM) via OpenAI-compatible APIs for privacy-first deployments.
*   **Scenario Simulation**: Built-in mock data generator for testing and demonstration.
*   **External Data Integration**: Support for fetching JSON data from custom endpoints.
*   **Strategy Optimization**: Applies specific industrial energy-saving formulas (Peak Shifting, Voltage Optimization, HVAC Control).
*   **Responsive Dark Theme**: Modern, accessible UI built with Tailwind CSS.
*   **Bilingual Support**: Instant switching between English and Chinese.

## How to Use

1.  **Select Region**: Choose the target facility (Industrial Zone, Commercial Complex, or Data Center).
2.  **Configure Data Source**:
    *   Enable **"Sim Data"** for random generation.
    *   Disable simulation and enter a **Data Source URL** to fetch real JSON data.
3.  **Set Parameters**:
    *   **History Range**: 12h, 24h, 48h, or 7 Days.
    *   **Prediction Horizon**: Slider to set future prediction hours (1-24h).
4.  **Choose Strategy**: Select an energy-saving formula (e.g., Peak Shifting).
5.  **Run Analysis**: Click **"Run AI Analysis"**.
    *   **Online Mode**: Requires a valid `API_KEY` in the environment.
    *   **Local Mode**: Click the CPU icon, then the Settings icon to configure your Local AI Base URL (e.g., `http://localhost:11434/v1`) and Model Name (e.g., `llama3`).

## Standards & Formulas

The application uses standard formulas derived from energy management systems (EMS) and industrial best practices.

### 1. Peak Shifting & Valley Filling
*   **Concept**: Reduces demand charges by shifting consumption from peak tariff hours to off-peak hours.
*   **Standard**: Based on **Load Factor** improvement principles.
*   **Implementation**:
    *   Identifies peak hours (typically 09:00-12:00, 18:00-21:00).
    *   Applies a load reduction factor (e.g., 15%) during peaks.
    *   Simulates load increase during valley hours (charging phase).

### 2. Voltage Optimization (CVO)
*   **Concept**: Conservation Voltage Reduction (CVR) / CVO.
*   **Standard**: ANSI C84.1 (Voltage Ratings for Electric Power Systems).
*   **Implementation**: Simulates the effect of lowering supply voltage to the lower limit of the allowable bandwidth (e.g., -4%).
*   **Source**: IEEE estimates that for constant impedance loads, a 1% voltage reduction yields roughly 1% energy savings (CVR factor of 1.0).

### 3. Smart HVAC Control
*   **Concept**: Model Predictive Control (MPC) for HVAC systems.
*   **Standard**: ASHRAE Guideline 36 (High-Performance Sequences of Operation for HVAC Systems).
*   **Implementation**: Adjusts setpoints based on predicted weather and occupancy, reducing load typically by 10-15% during operational hours.

---

## AI Model Training Guide for Energy Forecasting

To transition from general-purpose LLM inference to a specialized predictive model, you can train or fine-tune a model specifically for Time-Series Forecasting.

### 1. Data Requirements

**Type of Data**:
Structured Time-Series Data (Tabular).

**Required Fields**:
*   `timestamp`: ISO 8601 format (e.g., `2023-10-27T14:00:00Z`).
*   `power_consumption`: Float, unit kW (Target Variable).

**Recommended Covariates (Features)**:
*   `temperature`: Ambient temperature (°C).
*   `humidity`: Relative humidity (%).
*   `is_holiday`: Boolean (0/1).
*   `day_of_week`: Integer (0-6).
*   `hour_of_day`: Integer (0-23).
*   `operational_status`: Boolean (Factory Active / Shutdown).

### 2. Data Volume

*   **Minimum**: 1 year of hourly data (approx. 8,760 data points) to capture all four seasons and daily/weekly periodicities.
*   **Recommended**: 3+ years of historical data to capture long-term trends and anomalies.
*   **Resolution**: Hourly (1H) is standard; 15-minute intervals are better for peak load analysis.

### 3. Training Tools & Libraries

**For Statistical/Machine Learning (High Accuracy)**:
*   **XGBoost / LightGBM**: Industry standard for tabular time-series competitions.
*   **Prophet (Meta)**: Good for strong seasonal effects.
*   **AutoGluon / H2O.ai**: AutoML tools that automate feature engineering and model selection.

**For Deep Learning (Complex Patterns)**:
*   **PyTorch / TensorFlow**:
    *   **LSTM (Long Short-Term Memory)**: Classic RNN architecture for sequences.
    *   **TFT (Temporal Fusion Transformer)**: State-of-the-art for interpretable multi-horizon forecasting.
    *   **N-BEATS**: Pure deep learning architecture for univariate time series.

### 4. Training Environment & Deployment

**Setup**:
1.  **Environment**: Python 3.9+ with Anaconda or Docker.
2.  **Hardware**: NVIDIA GPU (e.g., T4, A100) recommended for Transformer-based models; CPU suffices for XGBoost.

**Workflow**:
1.  **Data Cleaning**: Handle missing values (imputation) and remove outliers.
2.  **Feature Engineering**: Create lag features (usage 24h ago), rolling averages (7-day mean).
3.  **Training**: Split data into Train (80%), Validation (10%), Test (10%).
4.  **Evaluation Metric**: MAPE (Mean Absolute Percentage Error) or RMSE (Root Mean Square Error).

**Deployment**:
*   **Format**: Export model as `.pkl` (Scikit-learn/XGBoost) or `.onnx` / `.pt` (Deep Learning).
*   **Serving**: Wrap the model in a FastAPI or Flask container.
*   **Integration**: The EcoWatt frontend "External Data Source" or "Local AI" mode can point to this inference API.