navyadarisi/adaptive-ev-coordination

⚡ Adaptive EV Charging Coordination — OpenEnv Environment

   

A production-ready OpenEnv hackathon submission simulating shared EV charging station coordination — a real-world infrastructure scheduling problem where an AI agent must allocate limited resources under strict constraints.

🌍 Motivation

Urban EV charging infrastructure is increasingly strained during evening peak hours. Multiple vehicles compete for scarce charging ports and shared grid capacity, each with different battery states, charging rates, and departure urgencies. A naive first-come-first-served policy leads to poor outcomes — urgent vehicles miss deadlines, low-priority vehicles starve, and the grid risks overload.

This environment challenges an agent to act as an intelligent charging coordinator:

• —Allocate limited ports and grid power fairly
• —Respect high-priority emergency vehicles
• —Prevent starvation of lower-priority users
• —Optimize across sequential decisions (15-min timesteps)

📐 Observation Space

{
  "time_step": 3,
  "available_ports": 2,
  "grid_power_limit_kw": 40.0,
  "current_load_kw": 20.0,
  "vehicles": [
    {
      "id": "EV1",
      "battery": 30.0,
      "target": 80.0,
      "departure_in_steps": 5,
      "priority": "high",
      "status": "waiting"
    }
  ]
}

🎮 Action Space

{
  "action_type": "assign",
  "vehicle_id": "EV1",
  "power_kw": 11.0
}

🏆 Reward Logic

Reward is normalized to (0.0, 1.0) exclusive.

Positive Components

Penalties

Priority Weights

high   = 1.0
medium = 0.7
low    = 0.5

📋 Task Descriptions

Task 1 — basic_single_port (Easy)

Single port, two vehicles. EV1 (high priority, 20% battery) must charge before departing in 6 steps. EV2 is low priority with slack time. Agent learns to prioritize urgency.

Task 2 — dual_port_priority (Medium)

Two ports, three vehicles with conflicting priorities and deadlines. EV3 (medium priority) departs in 5 steps despite EV1 being high priority. Tests priority vs urgency trade-off.

Task 3 — grid_limit_power_split (Medium)

Three ports but grid capped at 30 kW. Four vehicles including two high-priority. Agent must split power carefully to charge all without overloading.

Task 4 — emergency_late_arrival (Hard)

An emergency EV (5% battery, high priority) arrives at step 6 with only 6 steps to charge. Agent must preempt existing allocations dynamically.

Task 5 — community_fairness_evening_peak (Hard)

Evening peak simulation: 5 community EVs, 2 ports, 40 kW grid. Tests fairness index optimization — agent must rotate charging to prevent starvation while meeting high-priority deadlines.

🚀 Setup & Installation

Requirements

• —Python 3.11+
• —Node.js 20+ (for frontend)

Quick Start (Backend)

pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 7860

API available at http://localhost:7860

Run Frontend (Dev)

cd frontend
npm install
npm run dev

Run Grader

python grade_tasks.py

Run Inference

export OPENAI_API_KEY=your_key
export API_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
export MODEL_NAME=gemini-2.0-flash

python inference.py

🐳 Docker Build & Run

# Build
docker build -t adaptive_ev_coordination .

# Run
docker run -p 7860:7860 \
  -e OPENAI_API_KEY=your_key \
  -e API_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/ \
  -e MODEL_NAME=gemini-2.0-flash \
  adaptive_ev_coordination

🤗 Hugging Face Deployment

This project is pre-configured as a Hugging Face Space container.

1. 1.Push this repo to a HuggingFace Space (Docker SDK)
2. 2.Set Secrets in Space settings:
3. 3.OPENAI_API_KEY
4. 4.API_BASE_URL
5. 5.MODEL_NAME
6. 6.Space will auto-deploy and expose GET / on port 7860

🌐 API Endpoints

📊 Baseline Scores

Scores from the deterministic heuristic policy (priority + urgency sorting):

All scores strictly in (0.0, 1.0).

✅ Pre-Submission Checklist

• —[x] GET / returns 200 OK
• —[x] POST /reset returns valid observation
• —[x] POST /step accepts action, returns step response
• —[x] openenv.yaml defines all 5 tasks with difficulty and goal
• —[x] python inference.py runs with [START], [STEP], [END] logs
• —[x] python grade_tasks.py returns scores in (0.0, 1.0)
• —[x] python -m py_compile app.py environment.py models.py graders.py inference.py passes
• —[x] docker build -t adaptive_ev_coordination . succeeds
• —[x] React dashboard functional

📁 Project Structure

adaptive_ev_coordination/
├── app.py              # FastAPI application
├── environment.py      # Core simulation engine
├── models.py           # Pydantic typed models
├── graders.py          # Deterministic task graders
├── grade_tasks.py      # Grading runner script
├── inference.py        # LLM inference script
├── openenv.yaml        # OpenEnv metadata
├── requirements.txt    # Python dependencies
├── Dockerfile          # Multi-stage Docker build
├── README.md           # This file
├── tasks/
│   ├── __init__.py
│   └── task_configs.py # 5 task scenario definitions
├── data/               # Reserved for datasets
└── frontend/
    ├── index.html
    ├── vite.config.js
    ├── package.json
    └── src/
        ├── main.jsx
        ├── App.jsx     # Main dashboard component
        └── index.css   # Styling

📄 License

MIT — Free for hackathon use.