Harvydoshi/rlmetaenergy
0
⚡ Energy Grid Balancer — OpenEnv
A real-world renewable energy grid management environment for AI agent training and evaluation. Built for the OpenEnv Hackathon by Meta & Hugging Face.
   
🌍 Problem Statement
Modern power grids are increasingly dependent on solar and wind — both inherently intermittent. Unlike traditional power plants, these sources cannot be switched on demand. Every 10 minutes an AI agent must decide:
- Charge battery — store surplus renewable energy for later
- Sell to grid — export surplus at market price for revenue
- Curtail power — safely dump excess to protect equipment
- Hold — let battery auto-discharge to cover demand shortfall
The goal: minimise cost and wasted energy while keeping grid frequency stable.
🔌 Observation Space (24 dimensions)
Grid frequency is modelled via a swing-equation approximation — frequency deviates from 50 Hz based on real-time power imbalance, giving the agent a physical stability signal.
🎮 Action Space
{
"action_type": "charge_battery | sell_to_grid | curtail_power | hold",
"magnitude": 0.0
}📊 Reward Function (shaped, −2 to +2 per step)
reward = stability_reward # 0 to +0.4 — frequency within ±0.2 Hz
+ economic_reward # proportional to avoided import cost
+ curtailment_penalty # −kWh wasted × task multiplier × 0.05
+ frequency_penalty # cascade penalty beyond ±0.2 Hz
+ battery_efficiency # +0.1 (SoC 30–80 %), −0.15 (outside)
+ action_reward # context-specific bonus/penaltyPartial-progress signals appear every step so the agent can learn from the stability axis before it has mastered cost minimisation.
🎯 Tasks
easy — Sunny Day Balancing
medium — Mixed Renewables District
hard — Storm Resilience Challenge
🏆 Grading (deterministic, 0.0–1.0)
🚀 Hackathon Workflow (exact commands)
Step 1 — Install the CLI
pip install "openenv-core>=0.2.1"
# or from source:
pip install "git+https://github.com/meta-pytorch/OpenEnv.git"Step 2 — Scaffold (already done — this repo IS the scaffold)
# If starting fresh:
openenv init energy_grid_balancerStep 3 — Build (local test)
git clone https://huggingface.co/spaces/YOUR_USERNAME/energy-grid-balancer
cd energy-grid-balancer⚠️ Python Setup (Mac/Linux users)
If python points to Python 2 on your system, use:
alias python=python3
alias pip=pip3OR (recommended — isolated environment):
python3 -m venv .venv
source .venv/bin/activate🔧 Setup environment
cp .env.example .env # fill in your API key▶️ Run locally
# Run with OpenEnv
openenv serve # starts FastAPI on :8000
# OR run with Docker
docker build -t energy-grid-balancer .
docker run -p 7860:7860 --env-file .env energy-grid-balancerStep 4 — Test locally
# Validate the environment structure
openenv validate --verbose
# Run the baseline inference script
export API_BASE_URL=https://api.openai.com/v1
export MODEL_NAME=gpt-4o-mini
export HF_TOKEN=sk-...
export ENV_BASE_URL=http://localhost:7860
python inference.pyExpected output:
⚡ ENERGY GRID BALANCER — BASELINE INFERENCE
easy [████████████████████░░░░] 0.9700
medium [████████████████░░░░░░░░] 0.8329
hard [██████████████░░░░░░░░░░] 0.7474
AVERAGE : 0.8501Step 5 — Deploy to HuggingFace Spaces
openenv push --repo-id YOUR_USERNAME/energy-grid-balancer
# or manually:
git push # HF Space auto-builds from DockerfileStep 6 — Submit
Paste your Space URL: https://YOUR_USERNAME-energy-grid-balancer.hf.space
🤖 Using the Client
# HTTP client (no openenv-core needed)
import requests
BASE = "https://YOUR_USERNAME-energy-grid-balancer.hf.space"
r = requests.post(f"{BASE}/reset", json={"task_id": "medium"})
sid = r.json()["session_id"]
obs = r.json()["observation"]
done = False
while not done:
action = {"action_type": "charge_battery", "magnitude": 0.7}
r = requests.post(f"{BASE}/step", json={"session_id": sid, "action": action})
obs = r.json()["observation"]
done = r.json()["done"]
score = requests.post(f"{BASE}/grade", json={"session_id": sid}).json()["score"]
print(f"Score: {score:.3f}")# Typed WebSocket client (openenv-core installed)
from client import EnergyGridEnv
from models import GridAction
with EnergyGridEnv.from_hub("YOUR_USERNAME/energy-grid-balancer").sync() as env:
obs = env.reset(task_id="medium")
while not obs.done:
action = GridAction(action_type="charge_battery", magnitude=0.8)
obs = env.step(action)
result = env.grade()
print(f"Score: {result['score']:.3f}")📡 API Endpoints
🔬 Physical Models
📁 Project Structure
energy-grid-balancer/ ← openenv init output
├── __init__.py
├── models.py ← GridAction, GridObservation, GridState (Pydantic)
├── client.py ← EnergyGridEnv typed WebSocket client
├── inference.py ← Baseline LLM agent (OpenAI client)
├── openenv.yaml ← OpenEnv metadata
├── pyproject.toml ← uv-compatible dependency manifest
├── Dockerfile ← multi-stage, openenv-base compatible
├── .env.example ← credentials template
├── .gitignore
├── README.md
├── server/
│ ├── __init__.py
│ ├── app.py ← FastAPI + WebSocket server (create_app)
│ ├── energy_grid_environment.py ← core simulation (extends Environment)
│ └── requirements.txt
└── static/
└── index.html ← interactive dashboard🔐 Environment Variables
🧪 Tests
pip install pytest pytest-asyncio
python -m pytest tests/ -v📜 Baseline Scores
Achieved with gpt-4o-mini via OpenAI API:
Built for the OpenEnv Challenge — Real-world AI agent environment for renewable energy grid management