Imported from Farhanahmad-kust/energy-forecast-advisor (AGENTS.md). Install upstream with npx skills add Farhanahmad-kust/energy-forecast-advisor. Copyright stays with the author.

Agent Build Contract: Smart Energy Forecast and Anomaly Advisor

Read this file completely before modifying this project. Keep all work inside this folder unless a root-level documentation change is necessary.

Product goal

Build a deployable Streamlit application with manual and CSV-upload modes. It forecasts the next 10-minute appliance-energy value, converts forecasts to estimated cost using a user-provided tariff, visualizes expected use, and flags observations that are unusually high relative to model residuals. Scope claims to a prototype for sensor-equipped buildings similar to the source house.

Source data

• Canonical source: UCI Machine Learning Repository, Appliances Energy Prediction, ID 374.
• DOI: https://doi.org/10.24432/C5VC8G
• Expected raw CSV: data/raw/energydata_complete.csv.
• Preserve the downloaded archive and add data/raw/SOURCE.md containing URL, retrieval date, licence, filenames, sizes, and SHA-256 hashes.
• Never edit raw data in place.

Forecast contract

• Target: appliance energy use in Wh for the next 10-minute interval.
• Inputs: timestamp, current/recent appliance use, available indoor temperature/humidity sensors, and outdoor weather fields.
• Manual mode may use a documented reduced feature set only if validation shows acceptable degradation.
• Batch mode must validate the uploaded schema and display actionable errors.
• Anomaly flags are residual-based operational indicators, not proof of a faulty appliance.

Leakage and split rules

• Parse and sort time before all feature engineering.
• Drop rv1 and rv2, which are random variables intentionally included by the dataset authors.
• Shift the target to the next interval before generating splits.
• Lag and rolling features must use past observations only; rolling windows must be shifted before aggregation.
• Use chronological train/validation/test periods or walk-forward evaluation. Never randomly split time rows.
• Fit imputers, scalers, model parameters, anomaly thresholds, and any reduced-feature selection using training/validation periods only.

Modeling plan

1. Baselines: last observed value, same interval previous day, and training-only rolling seasonal average.
2. Candidate/final model: HistGradientBoosting Regressor on calendar, sensor, weather, lag, and rolling features.
3. Consider a log target only when validation residuals and inverse-transform behavior justify it.
4. Define high-use anomaly thresholds from validation residuals, preferably conditional on forecast scale or time-of-day if warranted.

Required evaluation

• Timestamp completeness, duplicates, sensor ranges, missingness, and target distribution.
• MAE, RMSE, R-squared, and sMAPE or another zero-safe relative metric.
• Baseline-versus-model comparison.
• Residual plots and error slices by hour, weekday, and consumption band.
• Walk-forward stability and peak-demand error.
• Prediction interval or empirical uncertainty coverage.
• Inference latency/model size.
• Limitations must cover single-building training data, 4.5-month collection period, sensor compatibility, weather dependence, and concept drift.

Expected implementation files

• src/download_data.py — reproducible UCI acquisition and hash verification.
• src/preprocess.py — timestamp/schema cleaning and chronological splits.
• src/features.py — leakage-safe calendar, lag, rolling, and reduced/manual features.
• src/train.py — baselines, final training, tuning, anomaly threshold, and serialization.
• src/evaluate.py — metrics, figures, slices, uncertainty, and report generation.
• src/inference.py — manual/batch validation, forecasts, cost conversion, and anomaly results.
• app.py — Streamlit manual and CSV-upload interface.
• requirements.txt, requirements-dev.txt, and tests/.

Artifact contract

Save the complete inference pipeline, expected upload schema/example, anomaly configuration, and models/model_metadata.json. Metadata must record source hash, forecast horizon, split dates, feature timing, metrics, baselines, uncertainty method, model version, and limitations. The app must not retrain.

Definition of done

• Download, preprocessing, training, evaluation, tests, batch example, and Streamlit launch work from documented commands.
• Tests prove lag/rolling features never use current or future target values.
• Held-out chronological evaluation beats or honestly reports failure to beat meaningful baselines.
• Manual and CSV modes validate inputs and provide forecast, cost estimate, uncertainty, and careful anomaly wording.
• README includes setup, data attribution, methodology, results, limitations, and deployment instructions.