EcoLoop

EcoLoop is a hackathon-ready proof of concept for autonomous supervisory HVAC control. EnergyPlus simulates a five-zone office, OpenRouter chooses a bounded operating mode, and Python maps that mode to validated thermostat setpoints. The same building and weather are run twice so energy and comfort can be compared fairly.

The LLM is remote through OpenRouter. No Ollama installation or local model download is required.

1. Install Python 3.10 or newer.
2. Install EnergyPlus 26.1 at /Applications/EnergyPlus-26-1-0.
3. Open Terminal and run:

cd ~/Desktop/ecoloop
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cp .env.example .env

4. Open .env and add your OpenRouter API key:

OPENROUTER_API_KEY=your_key_here
OPENROUTER_MODEL=inclusionai/ling-3.0-flash:free

The project can run without an API key, but it will use the safe fallback controller instead of OpenRouter.

Each time you open a new Terminal window, run:

cd ~/Desktop/ecoloop
source .venv/bin/activate
python main.py

main.py automatically:

1. Prepares the EnergyPlus models.
2. Runs the baseline simulation.
3. Runs the controlled simulation.
4. Generates the energy and comfort comparison.
5. Starts the Streamlit dashboard.

Wait for both simulations to finish. When this message appears:

Dashboard: http://localhost:8501

open http://localhost:8501 in your browser. Keep the Terminal window open while using the dashboard. Press Ctrl+C in the Terminal to stop EcoLoop.

If valid simulation results already exist, use:

cd ~/Desktop/ecoloop
source .venv/bin/activate
python main.py --reuse-results

This rebuilds the comparison and starts the dashboard immediately.

# Run everything without starting the dashboard
python main.py --no-dashboard

# Run unit tests before the complete workflow
python main.py --run-tests

# Show every launcher option
python main.py --help

• Live EnergyPlus Python API sensor and actuator loop
• Five safe HVAC modes with deterministic failover
• OpenRouter JSON decision client with timeout handling
• MCP server for state, safe actions, IDF inspection, logs, and summaries
• Baseline/controlled CSVs and a comparison generator
• Streamlit/Plotly results dashboard
• Unit tests and assessment architecture notes

• macOS with EnergyPlus 26.1 installed at /Applications/EnergyPlus-26-1-0
• Python 3.10 or newer
• An OpenRouter API key (recommended, but optional)

The repository already contains:

• models/baseline.idf
• models/controlled.idf
• weather/chicago.epw

Never commit .env. To use another OpenRouter model, change only OPENROUTER_MODEL.

These commands are available for testing or troubleshooting:

python -m unittest discover -s tests
python src/test_api.py
python run_baseline.py
python run_controlled.py
python -m src.compare_results

During the controlled run, look for lines like:

CONTROL 07/15 09:00 mode=occupied_eco heat=21.0C cool=25.0C source=openrouter_tool

If OpenRouter is unavailable, source=fallback appears and the run safely continues. This behavior is deliberate and is logged in decisions.csv.

python -m streamlit run dashboard.py

The dashboard presents baseline and controlled energy, savings, occupied comfort compliance, cumulative electricity, temperatures, setpoints, and the decision audit trail.

Run the server over standard input/output:

python -m src.mcp_server

Tools:

• get_building_state
• apply_hvac_mode
• get_recent_simulation_errors
• inspect_idf
• get_simulation_summary

apply_hvac_mode validates and records a request. The live callback remains the sole owner of EnergyPlus actuators, avoiding unsafe cross-thread writes.

outputs/
├── baseline/simulation.csv
├── controlled/simulation.csv
├── controlled/decisions.csv
└── comparison.json

Energy is converted from EnergyPlus timestep joules to kWh. Comfort compliance is the percentage of occupied timesteps where the average zone temperature is between 20°C and 26°C.

1. Show the architecture in ARCHITECTURE.md.
2. Show .env with the key value hidden.
3. Run python run_controlled.py and point out sensor-driven decisions.
4. Open outputs/controlled/decisions.csv.
5. Run the dashboard and present actual energy and comfort results.
6. Demonstrate one MCP call using the MCP inspector of your choice.

Do not claim a saving until both simulations have completed and outputs/comparison.json has been generated.