# meftah416/llm-energyplus architecture

> Architecture diagram of the GitHub repository meftah416/llm-energyplus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/meftah416/llm-energyplus
- Repository: https://github.com/meftah416/llm-energyplus

## Overview

##### Project type and purpose
- This repository is an ML pipeline / open-source tool for fine-tuning a large language model (LLM) to assist with interactive energy model development (EnergyPlus, IDF file generation, parametrics, etc.).
- The README confirms that the focus is on preparing datasets, prompt-engineering scripts, notebooks, and ultimately fine-tuning an LLM, with datasets hosted on Hugging Face.

##### File structure
Top-level files & directories:
- BuildingSurface.ipynb, BuildingSurface.py, fraction_geom_data.py, etc. – core scripts and notebooks processing building geometry and surfaces
- material_prompt.py, construction_prompt.py, full_idf_prompt.py, eplusPrompt.txt, etc. – prompt-engineering modules
- datasets/ – raw text docs of EnergyPlus I/O groups, plus helper notebooks (rag_example.ipynb, parametric_prompt.py)
- eplus_idf/ – sample .idf files used for testing or as examples
- web/ – web-scraping scripts to gather external data
- results/ – output IDFs and weather files
- train_test.py & trial models/ – code for training, evaluation, and dependency specification
- .gitignore, README.md – configuration and documentation

Patterns & components:
- Modular data ingestion → data preprocessing → prompt assembly → LLM fine-tuning → evaluation
- Notebooks (Jupyter) for interactive exploration
- Python scripts for batch processing and automation
- External integration: Hugging Face (datasets & model hosting), EnergyPlus (simulation engine)

##### README for additional insights
- States “all necessary python codes, datasets…to finetune an LLM model for human interactive energy model development”
- Points to Hugging Face for dataset storage

a. Main components:
1. Data Storage
– datasets/InputOutput text docs
– building-type prototypes
– eplus_idf examples
2. Data Ingestion & Preprocessing
– pdf_to_dataset.ipynb, importjson.py, web_scrap.py
– fraction_geom_data.py, parametric_prompt.py
3. Prompt Engineering
– material_prompt.py, construction_prompt.py, full_idf_prompt.py, eplusPrompt.txt
– IDF_prompt.txt, EnergyPlusEssentials.txt
4. LLM Fine-tuning & Training
– train_test.py
– trial models/context_increase01.py & requirements.txt
5. Evaluation & Results
– BuildingSurface.ipynb, datasets/ollamaRAG.ipynb, rag_example.ipynb
– results/*.idf, results/*.epw

6. External Services
– Hugging Face (dataset & model storage)
– EnergyPlus (simulation engine called via Python)

b. Relationships & interactions:
- Ingestion feeds Preprocessing modules → outputs cleaned training samples
- Samples + Prompt-Engineering feed into Fine-tuning
- Fine-tuned model pulled/pushed from Hugging Face
- Evaluation modules query the fine-tuned model → generate IDFs → EnergyPlus runs simulations → results stored
- Web-scraping may feed additional raw data into Data Storage

c. Architectural patterns & principles:
– Modular pipeline pattern (clear staging: ingest → transform → train → evaluate)
– Separation of concerns: notebooks for exploration vs. scripts for automation
– Extensibility: new prompt scripts or data sources can attach to the pipeline

d. Key technologies & libraries:
– Python 3.x, Jupyter Notebooks
– Hugging Face Datasets & Transformers
– EnergyPlus (via API or command-line calls)
– Standard data-processing libs (pandas, NumPy)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Storage Layer
    subgraph "Data Storage"
        direction TB
        RawData["Raw Datasets"]:::storage
        Prototypes["Building-Type Prototypes"]:::storage
        ExampleIDFs["Example IDFs"]:::storage
    end

    %% Ingestion & Preprocessing Layer
    subgraph "Ingestion & Preprocessing"
        direction TB
        pdfNode["pdf_to_dataset.ipynb"]:::processing
        importJSON["importjson.py"]:::processing
        webScrapPy["web_scrap.py"]:::processing
        webScrapNb["web_scrap.ipynb"]:::processing
        fraction["fraction_geom_data.py"]:::processing
        paramPrompt["parametric_prompt.py"]:::processing
    end

    %% Prompt Engineering Layer
    subgraph "Prompt Engineering"
        direction TB
        material["material_prompt.py"]:::prompt
        construction["construction_prompt.py"]:::prompt
        fullIDF["full_idf_prompt.py"]:::prompt
        subgraph "Prompt Templates"
            direction TB
            eplusPrompt["eplusPrompt.txt"]:::prompt
            idfTxt["IDF_prompt.txt"]:::prompt
            epEssentials["EnergyPlusEssentials.txt"]:::prompt
            mainPrompt["MainPrompt.txt"]:::prompt
            mcPrompt["MaterialConstructionPrompt.txt"]:::prompt
        end
    end

    %% Fine-tuning & Training Layer
    subgraph "LLM Fine-tuning & Training"
        direction TB
        trainTest["train_test.py"]:::training
        context01["context_increase01.py"]:::training
        reqs["requirements.txt"]:::training
    end

    %% Evaluation & Results Layer
    subgraph "Evaluation & Results"
        direction TB
        BS_nb["BuildingSurface.ipynb"]:::evaluation
        BS_py["BuildingSurface.py"]:::evaluation
        ollama["ollamaRAG.ipynb"]:::evaluation
        ragNb["rag_example.ipynb"]:::evaluation
        simOutputs["Simulation Outputs (.idf, .epw)"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        HF["Hugging Face"]:::external
        EP["EnergyPlus"]:::external
    end

    %% Connections
    RawData --> pdfNode
    Prototypes --> importJSON
    ExampleIDFs --> webScrapPy
    webScrapPy --> webScrapNb
    importJSON --> fraction
    fraction --> paramPrompt
    pdfNode --> paramPrompt

    paramPrompt --> material
    material --> fullIDF
    construction --> fullIDF
    eplusPrompt --> fullIDF
    idfTxt --> fullIDF
    epEssentials --> fullIDF
    mainPrompt --> fullIDF
    mcPrompt --> fullIDF

    fullIDF --> trainTest
    trainTest --> context01
    context01 --> reqs

    trainTest --> HF
    HF --> trainTest

    context01 --> BS_nb
    BS_nb --> EP
    BS_py --> EP
    ollama --> simOutputs
    ragNb --> simOutputs
    EP --> simOutputs

    %% Click Events
    click RawData "https://github.com/meftah416/llm-energyplus/tree/main/datasets/"
    click Prototypes "https://github.com/meftah416/llm-energyplus/tree/main/building-type/"
    click ExampleIDFs "https://github.com/meftah416/llm-energyplus/tree/main/eplus_idf/"
    click pdfNode "https://github.com/meftah416/llm-energyplus/blob/main/pdf_to_dataset.ipynb"
    click importJSON "https://github.com/meftah416/llm-energyplus/blob/main/importjson.py"
    click webScrapPy "https://github.com/meftah416/llm-energyplus/blob/main/web/web_scrap.py"
    click webScrapNb "https://github.com/meftah416/llm-energyplus/blob/main/web/web_scrap.ipynb"
    click fraction "https://github.com/meftah416/llm-energyplus/blob/main/fraction_geom_data.py"
    click paramPrompt "https://github.com/meftah416/llm-energyplus/blob/main/datasets/parametric_prompt.py"
    click material "https://github.com/meftah416/llm-energyplus/blob/main/material_prompt.py"
    click construction "https://github.com/meftah416/llm-energyplus/blob/main/construction_prompt.py"
    click fullIDF "https://github.com/meftah416/llm-energyplus/blob/main/full_idf_prompt.py"
    click eplusPrompt "https://github.com/meftah416/llm-energyplus/blob/main/eplusPrompt.txt"
    click idfTxt "https://github.com/meftah416/llm-energyplus/blob/main/IDF_prompt.txt"
    click epEssentials "https://github.com/meftah416/llm-energyplus/blob/main/EnergyPlusEssentials.txt"
    click mainPrompt "https://github.com/meftah416/llm-energyplus/blob/main/MainPrompt.txt"
    click mcPrompt "https://github.com/meftah416/llm-energyplus/blob/main/MaterialConstructionPrompt.txt"
    click trainTest "https://github.com/meftah416/llm-energyplus/blob/main/train_test.py"
    click context01 "https://github.com/meftah416/llm-energyplus/blob/main/trial models/context_increase01.py"
    click reqs "https://github.com/meftah416/llm-energyplus/blob/main/trial models/requirements.txt"
    click BS_nb "https://github.com/meftah416/llm-energyplus/blob/main/BuildingSurface.ipynb"
    click BS_py "https://github.com/meftah416/llm-energyplus/blob/main/BuildingSurface.py"
    click ollama "https://github.com/meftah416/llm-energyplus/blob/main/datasets/ollamaRAG.ipynb"
    click ragNb "https://github.com/meftah416/llm-energyplus/blob/main/datasets/rag_example.ipynb"

    %% Styles
    classDef storage fill:#f9f,stroke:#333,stroke-width:1px;
    classDef processing fill:#bbf,stroke:#333,stroke-width:1px;
    classDef prompt fill:#bfb,stroke:#333,stroke-width:1px;
    classDef training fill:#fbf,stroke:#333,stroke-width:1px;
    classDef evaluation fill:#ffb,stroke:#333,stroke-width:1px;
    classDef external fill:#efe,stroke:#333,stroke-width:1px;
```
