# Virtual Power Plant (DER) Orchestration Platform

An enterprise-grade, multi-agent AI Virtual Power Plant (VPP) software simulator, MCP server, and interactive web dashboard.

Coordinates distributed energy resources (DERs)—including rooftop solar PV, residential and commercial batteries, EV chargers, smart HVAC thermostats, and flexible household loads—into a single controllable virtual resource capable of delivering grid support (+10 MW demand response, peak shaving, solar surplus absorption) and participating in capacity markets.

---

## Architecture Stack

```
                       ┌──────────────────────────────────────────────┐
                       │   Streamlit + Plotly Visual Dashboard UI     │
                       │             (frontend/app.py)                │
                       └──────────────┬────────────────┬──────────────┘
                                      │                │
                             REST API │                │ WebSockets
                      (port 8000)     │                │ (/ws/telemetry)
                       ┌──────────────▼────────────────▼──────────────┐
                       │          FastAPI Backend Application         │
                       │              (vpp/api/main.py)               │
                       └──────────────────────┬───────────────────────┘
                                              │
                       ┌──────────────────────▼───────────────────────┐
                       │     LangGraph Multi-Agent Workflow           │
                       │    (Supervisor, Forecast, Dispatch, etc.)    │
                       └──────────────────────┬───────────────────────┘
                                              │ MCP Tools
                       ┌──────────────────────▼───────────────────────┐
                       │  MCP Server & Deterministic Gatekeeper       │
                       └──────────────────────┬───────────────────────┘
                                              │ Validated Dispatches
                       ┌──────────────────────▼───────────────────────┐
                       │  Deterministic Physics Engine & Simulator    │
                       └──────────────────────────────────────────────┘
```

---

## Features

1. **Deterministic Physics Engine**: Exact time-step ($\Delta t$) physics for Battery SOC kinetics, 1-zone thermal RC building HVAC dynamics, EV schedules, solar irradiance curves, and non-sheddable critical loads.
2. **SciPy Convex Optimizer**: Bounded Linear Program solver (`scipy.optimize.linprog(method='highs')`) solving target grid support MW while minimizing degradation and comfort costs.
3. **Deterministic Safety Gatekeeper**: Centralized validator enforcing non-negotiable physical constraints. Unsafe requests are rejected with structured error payloads leaving simulation state 100% untouched.
4. **FastMCP Server**: Custom MCP server exposing 11 Read/Observation tools and 6 Action/Control tools backed by Pydantic v2 schemas.
5. **LangGraph Multi-Agent Workflows**: Stateful graph orchestrating Supervisor, Forecasting, Dispatch, Market, and Conflict-Resolution agents with max step loop bounds and real-time execution tracing.
6. **FastAPI Backend & WebSockets**: REST endpoints and 1 Hz live WebSocket telemetry streaming.
7. **Streamlit & Plotly Dashboard**: Interactive dashboard featuring 8 tabs (VPP Overview, Live Grid Response, DER Fleet, Agent Execution Trace, MCP Tool Activity, Safety Monitor, Scenario Runner, Market & Metrics).

---

## Quick Start (Fresh Clone)

### 1. Clone Repository & Setup Virtual Environment
```bash
git clone https://github.com/Venkat-Padimi/VPP-orchestration-agent.git
cd VPP-orchestration-agent

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On Linux/macOS:
source .venv/bin/activate
```

### 2. Install Dependencies
```bash
pip install -r requirements.txt
```

### 3. Run Test Suite
```bash
python -m pytest
```

### 4. Run CLI Demonstrations
- **Phase 1 Physics & Optimizer CLI**:
  ```bash
  python -m vpp.run_simulation
  ```
- **Phase 3 Multi-Agent Orchestration CLI**:
  ```bash
  python -m vpp.run_agent_demo
  ```

---

## Launch Commands for Web Dashboard & Servers

### 1. Launch FastAPI Backend (Port 8000)
```bash
python -m uvicorn vpp.api.main:app --host 127.0.0.1 --port 8000
```
- Health Check: `http://127.0.0.1:8000/health`
- OpenAPI Docs: `http://127.0.0.1:8000/docs`

### 2. Launch Streamlit Dashboard (Port 8501)
```bash
streamlit run frontend/app.py
```
- Dashboard URL: `http://localhost:8501`

### 3. Launch Custom VPP MCP Server
```bash
python -m vpp.mcp_server.server
```

---

## Antigravity MCP Client Integration

Add the following to `mcp_config.json`:
```json
{
  "mcpServers": {
    "vpp-orchestrator": {
      "command": "python",
      "args": ["-m", "vpp.mcp_server.server"],
      "env": { "PYTHONPATH": "." }
    }
  }
}
```