# mario-pv/predictive-hvac-optimization-model architecture

> Architecture diagram of the GitHub repository mario-pv/predictive-hvac-optimization-model, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mario-pv/predictive-hvac-optimization-model
- Repository: https://github.com/mario-pv/predictive-hvac-optimization-model

## Overview

This repository is a Python decision-support pipeline for predicting building heating and cooling loads and turning predictions into HVAC recommendations. The main workflow fetches and preprocesses the UCI energy-efficiency data, saves a CSV, trains and evaluates a multi-output Random Forest, then generates actions from a test sample. A separate script cross-validates and tunes the model. The README also describes live weather integration, but the sampled implementation does not show it; that capability is therefore shown as documented but unverified.

Main entry points: [`preprocess.py`](https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/preprocess.py) (Preprocessing), [`preprocessed_energy_efficiency.csv`](https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/preprocessed_energy_efficiency.csv) (Prepared CSV), [`train_and_evaluate.py`](https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/train_and_evaluate.py) (Training Pipeline), [`optimize_model.py`](https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/optimize_model.py) (Model Tuning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data Preparation"]
  node_preprocess["Preprocessing<br/>[preprocess.py]"]
  node_prepared["Prepared CSV"]
end

subgraph group_model["Modeling"]
  node_training["Training Pipeline"]
  node_iaq["Synthetic IAQ Features"]
  node_forest["Random Forest"]
  node_evaluation["Model Evaluation"]
  node_optimization["Model Tuning<br/>[optimize_model.py]"]
end

subgraph group_decision["HVAC Decisions"]
  node_actions["HVAC Directives"]
  node_recommendations["Actionable Recommendations"]
end

subgraph group_integrations["External Data"]
  node_uci[("UCI Dataset")]
  node_weather["Weather API"]
end

node_operator(("Operator"))

node_operator -->|"runs preprocessing"| node_preprocess
node_preprocess -->|"fetches dataset"| node_uci
node_preprocess -->|"writes CSV"| node_prepared
node_prepared -->|"loads data"| node_training
node_training -->|"adds CO2 feature"| node_iaq
node_iaq -->|"trains model"| node_forest
node_forest -->|"scores predictions"| node_evaluation
node_training -->|"calls directives"| node_actions
node_actions -->|"returns actions"| node_recommendations
node_operator -->|"runs tuning"| node_optimization
node_prepared -->|"loads data"| node_optimization
node_optimization -->|"tunes parameters"| node_forest
node_weather -.->|"provides live data"| node_preprocess

click node_preprocess "https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/preprocess.py"
click node_prepared "https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/preprocessed_energy_efficiency.csv"
click node_training "https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/train_and_evaluate.py"
click node_iaq "https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/train_and_evaluate.py"
click node_forest "https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/train_and_evaluate.py"
click node_evaluation "https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/train_and_evaluate.py"
click node_optimization "https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/optimize_model.py"
click node_actions "https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/inference_actions.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_preprocess,node_prepared toneBlue
class node_training,node_iaq,node_forest,node_evaluation,node_optimization toneAmber
class node_actions,node_recommendations toneMint
class node_uci,node_weather toneRose
class node_operator toneIndigo
```

## Components

### Data Preparation

- [Preprocessing](https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/preprocess.py): `preprocess.py`
- [Prepared CSV](https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/preprocessed_energy_efficiency.csv): `preprocessed_energy_efficiency.csv`

### Modeling

- [Training Pipeline](https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/train_and_evaluate.py): `train_and_evaluate.py`
- [Synthetic IAQ Features](https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/train_and_evaluate.py): `train_and_evaluate.py`
- [Random Forest](https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/train_and_evaluate.py): `train_and_evaluate.py`
- [Model Evaluation](https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/train_and_evaluate.py): `train_and_evaluate.py`
- [Model Tuning](https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/optimize_model.py): `optimize_model.py`

### HVAC Decisions

- [HVAC Directives](https://github.com/mario-pv/predictive-hvac-optimization-model/blob/main/inference_actions.py): `inference_actions.py`
- **Actionable Recommendations**

### External Data

- **UCI Dataset**
- **Weather API**

### Other components

- **Operator**

## Connections

- Operator → Preprocessing: runs preprocessing (evidence: `preprocess.py`)
- Preprocessing → UCI Dataset: fetches dataset (evidence: `preprocess.py`)
- Preprocessing → Prepared CSV: writes CSV (evidence: `preprocess.py`)
- Prepared CSV → Training Pipeline: loads data (evidence: `train_and_evaluate.py`)
- Training Pipeline → Synthetic IAQ Features: adds CO2 feature (evidence: `train_and_evaluate.py`)
- Synthetic IAQ Features → Random Forest: trains model (evidence: `train_and_evaluate.py`)
- Random Forest → Model Evaluation: scores predictions (evidence: `train_and_evaluate.py`)
- Training Pipeline → HVAC Directives: calls directives (evidence: `train_and_evaluate.py`)
- HVAC Directives → Actionable Recommendations: returns actions (evidence: `inference_actions.py`)
- Operator → Model Tuning: runs tuning (evidence: `optimize_model.py`)
- Prepared CSV → Model Tuning: loads data (evidence: `optimize_model.py`)
- Model Tuning → Random Forest: tunes parameters (evidence: `optimize_model.py`)
- Weather API → Preprocessing: provides live data (evidence: `README.md`)
