first commit

.gitignore

@@ -0,0 +1,42 @@
+# Python cache
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Packaging/build outputs
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Test and coverage artifacts
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Notebook checkpoints
+.ipynb_checkpoints/
+
+# OS/editor files
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# Project artifacts
+artifacts/
+openenv_smartgrid_marketsim.egg-info/
+
+# Local logs and temp files
+*.log
+*.tmp
+*.swp

Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY pyproject.toml /app/
+COPY smartgrid_mas /app/smartgrid_mas
+COPY training /app/training
+COPY main.py /app/main.py
+COPY openenv.yaml /app/openenv.yaml
+
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir .
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:7860/health', timeout=3)"
+
+CMD ["python", "main.py"]

README.md

@@ -0,0 +1,96 @@
+# OpenEnv Smart Grid MarketSim
+
+A new OpenEnv-compatible project for a hybrid hackathon narrative:
+- Theme 1: Multi-agent interactions
+- Theme 2: Long-horizon planning
+- Theme 3.1: Professional world modeling
+
+## Core idea
+
+The simulator is intentionally multi-layered:
+1. Agents submit strategic market bids.
+2. A market-clearing engine computes tentative allocations and prices.
+3. A Load Dispatching Unit (LDU) enforces physical feasibility.
+4. Grid dynamics evolve with volatility and shock events.
+5. Reward is computed from physically delivered outcomes.
+
+This creates tension between strategy and reality, which is the main differentiator.
+
+## What is implemented in this first slice
+
+- Multi-agent bid object with supply/demand bids.
+- Market clearing with matched quantities and clearing price.
+- Stackelberg-style leader price signal that reshapes bid books before clearing.
+- LDU feasibility corrections:
+  - power balance accounting
+  - EV storage constraints
+  - transmission/storage losses
+  - infeasibility correction logs
+- Long-horizon episode flow with shock event support.
+- Personality-aware strategy behavior (greedy, risk-averse, balanced, opportunistic).
+- Per-agent private view metrics in step/event outputs for richer multi-actor analysis.
+- Reward decomposition including infeasibility and blackout penalties.
+- REST API:
+  - GET /health
+  - POST /reset
+  - POST /step
+  - GET /state
+  - GET /events
+  - GET /info
+  - POST /run-inference
+- Baseline metric generation script with reward plot output.
+
+## Quickstart
+
+### Local run
+
+```powershell
+pip install -e .
+python main.py
+```
+
+Server starts on port 7860.
+
+If you also want the OpenEnv framework package locally:
+
+```powershell
+pip install -e .[openenv]
+```
+
+### Baseline metrics and plot
+
+```powershell
+python -m smartgrid_mas.train_baseline --episodes 30 --outdir artifacts
+```
+
+Outputs:
+- artifacts/baseline_metrics.csv
+- artifacts/reward_comparison.png
+
+Alternative (after editable install):
+
+```powershell
+train-baseline --episodes 30 --outdir artifacts
+```
+
+### Inference policy modes
+
+The `/run-inference` endpoint supports:
+- `random`
+- `heuristic`
+- `adaptive` (Stackelberg-aware)
+
+You can also pass `personality` such as `balanced`, `risk_averse`, or `opportunistic`.
+
+### Docker
+
+```powershell
+docker build -t openenv-smartgrid-marketsim .
+docker run -p 7860:7860 openenv-smartgrid-marketsim
+```
+
+## Next implementation milestones
+
+1. Add interactive 3D frontend scene synchronized to /events stream.
+2. Add Unsloth or HF TRL Colab training notebook with real policy updates.
+3. Add full judging artifact checklist in README (HF Space link, mini-blog/video, plots).

main.py

@@ -0,0 +1,140 @@
+import os
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+from smartgrid_mas.engine.policies import (
+    adaptive_stackelberg_action,
+    heuristic_joint_action,
+    random_joint_action,
+)
+from smartgrid_mas.env import SmartGridMarketEnv
+from smartgrid_mas.models import JointAction, ResetRequest, StepRequest
+
+
+app = FastAPI(
+    title="OpenEnv Smart Grid MarketSim",
+    description="Multi-agent market simulator with LDU physical feasibility layer.",
+    version="0.1.0",
+)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+env = SmartGridMarketEnv()
+
+
+class InferenceRequest(BaseModel):
+    policy: str = "heuristic"
+    personality: str = "balanced"
+    task_id: str = "default"
+    seed: Optional[int] = 42
+
+
+@app.get("/")
+def root():
+    return {
+        "name": "OpenEnv Smart Grid MarketSim",
+        "status": "ready",
+        "docs": "/docs",
+        "health": "/health",
+    }
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "openenv-smartgrid-marketsim"}
+
+
+@app.post("/reset")
+def reset(request: ResetRequest):
+    try:
+        return env.reset(task_id=request.task_id, seed=request.seed)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@app.post("/step")
+def step(request: StepRequest, session_id: Optional[str] = Query(default=None)):
+    try:
+        return env.step(action=request.action, session_id=session_id)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@app.get("/state")
+def state(session_id: Optional[str] = Query(default=None)):
+    try:
+        return env.state(session_id=session_id)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@app.get("/events")
+def events(session_id: Optional[str] = Query(default=None)):
+    try:
+        return env.events(session_id=session_id)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@app.get("/info")
+def info():
+    return env.get_schema()
+
+
+@app.post("/run-inference")
+def run_inference(request: InferenceRequest):
+    reset_resp = env.reset(task_id=request.task_id, seed=request.seed)
+    sid = reset_resp.session_id
+    obs = reset_resp.observation
+
+    rng = __import__("random").Random(request.seed)
+    trajectory = []
+    while True:
+        if request.policy == "random":
+            action = random_joint_action(obs, rng)
+        elif request.policy == "adaptive":
+            action = adaptive_stackelberg_action(obs, personality=request.personality)
+        else:
+            action = heuristic_joint_action(obs, personality=request.personality)
+
+        result = env.step(action=action, session_id=sid)
+        trajectory.append(
+            {
+                "step": len(trajectory) + 1,
+                "action": action.model_dump(),
+                "reward": result.reward.model_dump(),
+                "info": result.info,
+            }
+        )
+        obs = result.observation
+        if result.done:
+            break
+
+    avg_reward = sum(t["reward"]["score"] for t in trajectory) / max(1, len(trajectory))
+    return {
+        "success": True,
+        "policy": request.policy,
+        "personality": request.personality,
+        "steps": len(trajectory),
+        "average_reward": round(avg_reward, 4),
+        "trajectory": trajectory,
+    }
+
+
+def main() -> None:
+    import uvicorn
+
+    port = int(os.getenv("PORT", "7860"))
+    uvicorn.run(app, host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    main()

openenv.yaml

@@ -0,0 +1,87 @@
+name: openenv-smartgrid-marketsim
+version: "0.1.0"
+description: >
+  Multi-agent smart-grid market simulation where strategic bids are cleared by a market
+  and then corrected by a load dispatching unit to enforce physical feasibility.
+
+tags:
+  - openenv
+  - multi-agent
+  - market
+  - smart-grid
+  - long-horizon
+
+tasks:
+  - id: default
+    display_name: Strategic Bidding With Physical Dispatch
+    difficulty: medium
+    max_steps: 24
+    description: >
+      Agents bid into a market, then LDU enforces grid feasibility. Reward is based on
+      physically delivered outcomes under volatility and shock events.
+    success_threshold: 0.62
+
+action_space:
+  type: object
+  fields:
+    bids:
+      type: array
+      description: List of supply and demand bids from multiple agents
+    ev_charge_mwh:
+      type: float
+      min: 0.0
+    ev_discharge_mwh:
+      type: float
+      min: 0.0
+
+observation_space:
+  type: object
+  fields:
+    demand_mwh:
+      type: float
+    renewable_availability_mwh:
+      type: float
+    peaker_capacity_mwh:
+      type: float
+    ev_storage_mwh:
+      type: float
+    last_clearing_price:
+      type: float
+    shock_active:
+      type: bool
+
+reward:
+  type: object
+  fields:
+    score:
+      type: float
+      range: [0.0, 1.0]
+    demand_satisfaction_score:
+      type: float
+    cost_efficiency_score:
+      type: float
+    renewable_utilization_score:
+      type: float
+    stability_score:
+      type: float
+    infeasibility_penalty:
+      type: float
+    blackout_penalty:
+      type: float
+
+environment:
+  api: REST
+  framework: FastAPI
+  base_url: http://localhost:7860
+  endpoints:
+    - GET /health
+    - POST /reset
+    - POST /step
+    - GET /state
+    - GET /events
+    - GET /info
+    - POST /run-inference
+
+docker:
+  image: openenv-smartgrid-marketsim
+  port: 7860

pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "openenv-smartgrid-marketsim"
+version = "0.1.0"
+description = "Multi-agent smart-grid market simulator with LDU feasibility layer"
+requires-python = ">=3.10"
+dependencies = [
+  "fastapi>=0.115.5,<1",
+  "uvicorn>=0.32.1,<1",
+  "pydantic>=2.10.3,<3",
+  "pyyaml>=6.0.2,<7",
+  "matplotlib>=3.9.2,<4",
+]
+
+[project.optional-dependencies]
+openenv = [
+  "openenv-core>=0.2.0",
+]
+
+[project.scripts]
+server = "main:main"
+train-baseline = "smartgrid_mas.train_baseline:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["smartgrid_mas*"]

smartgrid_mas/__init__.py

@@ -0,0 +1,25 @@
+from smartgrid_mas.env import SmartGridMarketEnv
+from smartgrid_mas.models import (
+    AgentBid,
+    JointAction,
+    MarketObservation,
+    MarketReward,
+    ResetRequest,
+    ResetResponse,
+    StepRequest,
+    StepResponse,
+    StateResponse,
+)
+
+__all__ = [
+    "SmartGridMarketEnv",
+    "AgentBid",
+    "JointAction",
+    "MarketObservation",
+    "MarketReward",
+    "ResetRequest",
+    "ResetResponse",
+    "StepRequest",
+    "StepResponse",
+    "StateResponse",
+]

smartgrid_mas/engine/__init__.py

@@ -0,0 +1 @@
+"""Core engine modules for market clearing, physical dispatch, reward, and dynamics."""

smartgrid_mas/engine/dynamics.py

@@ -0,0 +1,41 @@
+import random
+from typing import Dict, Tuple
+
+from smartgrid_mas.tasks import TaskConfig
+
+
+def evolve_grid(
+    demand_mwh: float,
+    renewable_mwh: float,
+    base_price_usd_per_mwh: float,
+    step: int,
+    task: TaskConfig,
+    rng: random.Random,
+) -> Tuple[float, float, float, Dict]:
+    shock_active = step == task.shock_step
+
+    demand_noise = rng.gauss(0.0, task.demand_volatility)
+    renewable_noise = rng.gauss(0.0, task.renewable_volatility)
+
+    next_demand = demand_mwh + task.demand_trend_mwh + demand_noise
+    next_renewable = renewable_mwh + task.renewable_trend_mwh + renewable_noise
+
+    if shock_active:
+        next_renewable = max(0.0, next_renewable - task.shock_renewable_drop)
+
+    next_demand = max(20.0, next_demand)
+    next_renewable = max(0.0, next_renewable)
+
+    implied_price = base_price_usd_per_mwh * (1.0 + max(0.0, (next_demand - next_renewable) / 300.0))
+    next_price = max(5.0, implied_price)
+
+    return (
+        round(next_demand, 3),
+        round(next_renewable, 3),
+        round(next_price, 3),
+        {
+            "shock_active": shock_active,
+            "demand_noise": round(demand_noise, 3),
+            "renewable_noise": round(renewable_noise, 3),
+        },
+    )

smartgrid_mas/engine/ldu.py

@@ -0,0 +1,67 @@
+from typing import Dict, Tuple
+
+
+def enforce_dispatch(
+    market_result: Dict,
+    demand_mwh: float,
+    renewable_available_mwh: float,
+    peaker_capacity_mwh: float,
+    ev_storage_mwh: float,
+    ev_storage_capacity_mwh: float,
+    ev_charge_mwh: float,
+    ev_discharge_mwh: float,
+) -> Tuple[Dict, float]:
+    corrections = []
+
+    if ev_charge_mwh > 0 and ev_discharge_mwh > 0:
+        ev_discharge_mwh = 0.0
+        corrections.append("Simultaneous EV charge and discharge corrected by LDU")
+
+    max_charge = max(0.0, ev_storage_capacity_mwh - ev_storage_mwh)
+    max_discharge = max(0.0, ev_storage_mwh)
+
+    if ev_charge_mwh > max_charge:
+        corrections.append("EV charge exceeded storage headroom")
+        ev_charge_mwh = max_charge
+
+    if ev_discharge_mwh > max_discharge:
+        corrections.append("EV discharge exceeded storage state-of-charge")
+        ev_discharge_mwh = max_discharge
+
+    dispatch_from_market = market_result.get("cleared_mwh", 0.0)
+
+    renewable_dispatch = min(renewable_available_mwh, dispatch_from_market)
+    residual = max(0.0, dispatch_from_market - renewable_dispatch)
+    peaker_dispatch = min(peaker_capacity_mwh, residual)
+
+    if residual > peaker_capacity_mwh:
+        corrections.append("Market-cleared supply exceeded physical generation capacity")
+
+    gross_supply = renewable_dispatch + peaker_dispatch + ev_discharge_mwh
+
+    transmission_loss = 0.03 * gross_supply
+    storage_loss = 0.08 * ev_charge_mwh
+
+    delivered_supply = max(0.0, gross_supply - transmission_loss)
+    unmet_demand = max(0.0, demand_mwh - delivered_supply)
+    oversupply = max(0.0, delivered_supply - demand_mwh)
+
+    next_ev_storage = ev_storage_mwh + ev_charge_mwh - ev_discharge_mwh - storage_loss
+    next_ev_storage = max(0.0, min(ev_storage_capacity_mwh, next_ev_storage))
+
+    dispatch = {
+        "renewable_dispatch_mwh": round(renewable_dispatch, 3),
+        "peaker_dispatch_mwh": round(peaker_dispatch, 3),
+        "ev_charge_mwh": round(ev_charge_mwh, 3),
+        "ev_discharge_mwh": round(ev_discharge_mwh, 3),
+        "transmission_loss_mwh": round(transmission_loss, 3),
+        "storage_loss_mwh": round(storage_loss, 3),
+        "delivered_supply_mwh": round(delivered_supply, 3),
+        "unmet_demand_mwh": round(unmet_demand, 3),
+        "oversupply_mwh": round(oversupply, 3),
+        "next_ev_storage_mwh": round(next_ev_storage, 3),
+        "corrections": corrections,
+        "correction_count": len(corrections),
+    }
+
+    return dispatch, next_ev_storage

smartgrid_mas/engine/market.py

@@ -0,0 +1,102 @@
+from typing import Dict, List
+
+from smartgrid_mas.models import AgentBid
+
+
+def _apply_leader_signal(bids: List[AgentBid], leader_price_signal: float) -> Dict:
+    adjusted = []
+    adjusted_count = 0
+
+    for bid in bids:
+        price = float(bid.price_usd_per_mwh)
+        if bid.bid_type == "supply":
+            floor = 0.8 * leader_price_signal
+            if bid.role == "peaker_plant":
+                floor = 0.95 * leader_price_signal
+            new_price = max(price, floor)
+        else:
+            cap = 1.8 * leader_price_signal
+            floor = 0.9 * leader_price_signal
+            new_price = min(max(price, floor), cap)
+
+        if abs(new_price - price) > 1e-9:
+            adjusted_count += 1
+
+        adjusted.append(
+            {
+                "agent_id": bid.agent_id,
+                "role": bid.role,
+                "bid_type": bid.bid_type,
+                "quantity_mwh": float(bid.quantity_mwh),
+                "price_usd_per_mwh": float(new_price),
+                "raw_price_usd_per_mwh": float(price),
+            }
+        )
+
+    return {
+        "bids": adjusted,
+        "adjusted_count": adjusted_count,
+    }
+
+
+def clear_market(bids: List[AgentBid], leader_price_signal: float) -> Dict:
+    leader_adjusted = _apply_leader_signal(bids, leader_price_signal)
+    priced_bids = leader_adjusted["bids"]
+
+    supply = [
+        b for b in priced_bids if b["bid_type"] == "supply" and b["quantity_mwh"] > 0
+    ]
+    demand = [
+        b for b in priced_bids if b["bid_type"] == "demand" and b["quantity_mwh"] > 0
+    ]
+
+    supply_sorted = sorted(supply, key=lambda x: x["price_usd_per_mwh"])
+    demand_sorted = sorted(demand, key=lambda x: x["price_usd_per_mwh"], reverse=True)
+
+    i = 0
+    j = 0
+    cleared_qty = 0.0
+    matched = []
+    clearing_price = 0.0
+
+    while i < len(supply_sorted) and j < len(demand_sorted):
+        s = supply_sorted[i]
+        d = demand_sorted[j]
+        if s["price_usd_per_mwh"] > d["price_usd_per_mwh"]:
+            break
+
+        qty = min(s["quantity_mwh"], d["quantity_mwh"])
+        if qty <= 0:
+            break
+
+        cleared_qty += qty
+        clearing_price = (s["price_usd_per_mwh"] + d["price_usd_per_mwh"]) / 2.0
+        matched.append(
+            {
+                "supply_agent": s["agent_id"],
+                "demand_agent": d["agent_id"],
+                "quantity_mwh": round(qty, 3),
+                "price_usd_per_mwh": round(clearing_price, 3),
+            }
+        )
+
+        s["quantity_mwh"] -= qty
+        d["quantity_mwh"] -= qty
+        if s["quantity_mwh"] <= 1e-6:
+            i += 1
+        if d["quantity_mwh"] <= 1e-6:
+            j += 1
+
+    total_supply_offered = sum(float(b.quantity_mwh) for b in bids if b.bid_type == "supply")
+    total_demand_bid = sum(float(b.quantity_mwh) for b in bids if b.bid_type == "demand")
+
+    return {
+        "cleared_mwh": round(cleared_qty, 3),
+        "clearing_price": round(clearing_price, 3),
+        "total_supply_offered": round(total_supply_offered, 3),
+        "total_demand_bid": round(total_demand_bid, 3),
+        "leader_price_signal": round(leader_price_signal, 3),
+        "leader_adjusted_bids": leader_adjusted["adjusted_count"],
+        "post_signal_book": priced_bids,
+        "matches": matched,
+    }

smartgrid_mas/engine/policies.py

@@ -0,0 +1,137 @@
+import random
+
+from smartgrid_mas.models import AgentBid, JointAction, MarketObservation
+
+
+def random_joint_action(obs: MarketObservation, rng: random.Random) -> JointAction:
+    bids = [
+        AgentBid(
+            agent_id="renewable_1",
+            role="renewable_prosumer",
+            bid_type="supply",
+            quantity_mwh=max(0.0, rng.uniform(10.0, obs.renewable_availability_mwh)),
+            price_usd_per_mwh=rng.uniform(10.0, 40.0),
+        ),
+        AgentBid(
+            agent_id="peaker_1",
+            role="peaker_plant",
+            bid_type="supply",
+            quantity_mwh=rng.uniform(5.0, obs.peaker_capacity_mwh),
+            price_usd_per_mwh=rng.uniform(35.0, 80.0),
+        ),
+        AgentBid(
+            agent_id="industrial_1",
+            role="industrial_load",
+            bid_type="demand",
+            quantity_mwh=rng.uniform(0.6 * obs.demand_mwh, 1.1 * obs.demand_mwh),
+            price_usd_per_mwh=rng.uniform(30.0, 95.0),
+        ),
+    ]
+    return JointAction(
+        bids=bids,
+        ev_charge_mwh=rng.uniform(0.0, 8.0),
+        ev_discharge_mwh=rng.uniform(0.0, 8.0),
+    )
+
+
+def heuristic_joint_action(obs: MarketObservation, personality: str = "balanced") -> JointAction:
+    demand = obs.demand_mwh
+    renewable_offer = min(obs.renewable_availability_mwh, demand * 0.55)
+    peaker_offer = min(obs.peaker_capacity_mwh, max(0.0, demand - renewable_offer))
+
+    if personality == "greedy":
+        industrial_price = 95.0
+        peaker_price = max(62.0, obs.leader_price_signal * 1.08)
+        charge = 1.0
+        discharge = 5.0 if obs.scarcity_index > 0.2 else 2.0
+    elif personality == "risk_averse":
+        industrial_price = 90.0
+        peaker_price = max(54.0, obs.leader_price_signal * 0.98)
+        charge = 5.0 if obs.renewable_availability_mwh > demand else 1.0
+        discharge = 2.0 if obs.scarcity_index > 0.35 else 0.0
+    else:
+        industrial_price = 85.0
+        peaker_price = max(58.0, obs.leader_price_signal * 1.02)
+        charge = 3.0 if obs.renewable_availability_mwh > demand else 0.0
+        discharge = 4.0 if obs.renewable_availability_mwh < 0.8 * demand else 0.0
+
+    bids = [
+        AgentBid(
+            agent_id="renewable_1",
+            role="renewable_prosumer",
+            bid_type="supply",
+            quantity_mwh=max(0.0, renewable_offer),
+            price_usd_per_mwh=20.0,
+        ),
+        AgentBid(
+            agent_id="peaker_1",
+            role="peaker_plant",
+            bid_type="supply",
+            quantity_mwh=max(0.0, peaker_offer),
+            price_usd_per_mwh=peaker_price,
+        ),
+        AgentBid(
+            agent_id="industrial_1",
+            role="industrial_load",
+            bid_type="demand",
+            quantity_mwh=demand,
+            price_usd_per_mwh=industrial_price,
+        ),
+    ]
+
+    return JointAction(bids=bids, ev_charge_mwh=charge, ev_discharge_mwh=discharge)
+
+
+def adaptive_stackelberg_action(obs: MarketObservation, personality: str = "balanced") -> JointAction:
+    demand = obs.demand_mwh
+    scarcity = max(0.0, obs.scarcity_index)
+    leader = max(1.0, obs.leader_price_signal)
+
+    renewable_offer = min(obs.renewable_availability_mwh, demand * (0.52 + 0.18 * (1.0 - scarcity)))
+    peaker_offer = min(obs.peaker_capacity_mwh, max(0.0, demand - renewable_offer) * (1.0 + 0.25 * scarcity))
+
+    if personality == "opportunistic":
+        peaker_markup = 1.16
+        load_budget = 1.6
+        charge_bias = 0.5
+    elif personality == "risk_averse":
+        peaker_markup = 1.03
+        load_budget = 1.35
+        charge_bias = 1.25
+    else:
+        peaker_markup = 1.1
+        load_budget = 1.45
+        charge_bias = 1.0
+
+    bids = [
+        AgentBid(
+            agent_id="renewable_1",
+            role="renewable_prosumer",
+            bid_type="supply",
+            quantity_mwh=max(0.0, renewable_offer),
+            price_usd_per_mwh=max(15.0, leader * 0.82),
+        ),
+        AgentBid(
+            agent_id="peaker_1",
+            role="peaker_plant",
+            bid_type="supply",
+            quantity_mwh=max(0.0, peaker_offer),
+            price_usd_per_mwh=max(42.0, leader * peaker_markup),
+        ),
+        AgentBid(
+            agent_id="industrial_1",
+            role="industrial_load",
+            bid_type="demand",
+            quantity_mwh=demand,
+            price_usd_per_mwh=leader * load_budget,
+        ),
+    ]
+
+    if scarcity > 0.25:
+        discharge = min(obs.ev_storage_mwh, 3.0 + 8.0 * scarcity)
+        charge = 0.0
+    else:
+        charge = min(obs.ev_storage_capacity_mwh - obs.ev_storage_mwh, 2.0 * charge_bias)
+        discharge = 0.0
+
+    return JointAction(bids=bids, ev_charge_mwh=max(0.0, charge), ev_discharge_mwh=max(0.0, discharge))

smartgrid_mas/engine/reward.py

@@ -0,0 +1,50 @@
+from smartgrid_mas.models import MarketReward
+
+
+def compute_reward(dispatch: dict, clearing_price: float, demand_mwh: float, prior_gap: float) -> MarketReward:
+    delivered = dispatch["delivered_supply_mwh"]
+    unmet = dispatch["unmet_demand_mwh"]
+    oversupply = dispatch["oversupply_mwh"]
+    correction_count = dispatch["correction_count"]
+
+    demand_satisfaction = min(1.0, delivered / max(demand_mwh, 1e-6))
+
+    unit_cost = clearing_price if clearing_price > 0 else 45.0
+    total_cost = delivered * unit_cost
+    cost_efficiency = max(0.0, 1.0 - total_cost / 12000.0)
+
+    renewable_utilization = min(1.0, dispatch["renewable_dispatch_mwh"] / max(delivered, 1e-6))
+
+    current_gap = delivered - demand_mwh
+    stability_delta = abs(current_gap - prior_gap)
+    stability_score = max(0.0, 1.0 - stability_delta / 80.0)
+
+    infeasibility_penalty = min(1.0, correction_count * 0.15 + dispatch["storage_loss_mwh"] * 0.01)
+    blackout_penalty = min(1.0, unmet / max(demand_mwh, 1e-6))
+
+    raw = (
+        0.34 * demand_satisfaction
+        + 0.23 * cost_efficiency
+        + 0.18 * renewable_utilization
+        + 0.15 * stability_score
+        - 0.2 * infeasibility_penalty
+        - 0.2 * blackout_penalty
+        - 0.03 * min(1.0, oversupply / max(demand_mwh, 1e-6))
+    )
+    score = max(0.0, min(1.0, raw))
+
+    reason = (
+        f"delivered={delivered:.1f} demand={demand_mwh:.1f} unmet={unmet:.1f} "
+        f"price={unit_cost:.1f} corrections={correction_count}"
+    )
+
+    return MarketReward(
+        score=score,
+        reason=reason,
+        demand_satisfaction_score=demand_satisfaction,
+        cost_efficiency_score=cost_efficiency,
+        renewable_utilization_score=renewable_utilization,
+        stability_score=stability_score,
+        infeasibility_penalty=infeasibility_penalty,
+        blackout_penalty=blackout_penalty,
+    )

smartgrid_mas/env.py

@@ -0,0 +1,274 @@
+import random
+import uuid
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+from smartgrid_mas.engine.dynamics import evolve_grid
+from smartgrid_mas.engine.ldu import enforce_dispatch
+from smartgrid_mas.engine.market import clear_market
+from smartgrid_mas.engine.reward import compute_reward
+from smartgrid_mas.models import (
+    JointAction,
+    MarketObservation,
+    MarketReward,
+    ResetResponse,
+    StateResponse,
+    StepResponse,
+)
+from smartgrid_mas.tasks import TaskConfig, get_task
+
+
+SCHEMA_INFO = (
+    "Provide a JointAction with supply and demand bids from multiple agents plus EV charge/discharge "
+    "commands. Market clears bids first, then LDU enforces physical feasibility and logs corrections."
+)
+
+
+@dataclass
+class Session:
+    task: TaskConfig
+    rng: random.Random
+    session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    step: int = 0
+    done: bool = False
+    demand_mwh: float = 0.0
+    renewable_mwh: float = 0.0
+    peaker_capacity_mwh: float = 0.0
+    ev_storage_mwh: float = 0.0
+    ev_storage_capacity_mwh: float = 0.0
+    base_price: float = 0.0
+    last_clearing_price: float = 0.0
+    prior_gap: float = 0.0
+    correction_count: int = 0
+    infeasible_actions: int = 0
+    total_demand_met: float = 0.0
+    total_cost: float = 0.0
+    reward_history: list = field(default_factory=list)
+    event_log: list = field(default_factory=list)
+    shock_seen: bool = False
+    personalities: Dict[str, str] = field(default_factory=dict)
+
+    def to_observation(self, hint: Optional[str] = None, error_message: Optional[str] = None) -> MarketObservation:
+        public_signal = (
+            "Shock regime active; renewable volatility is elevated"
+            if self.shock_seen
+            else "Normal regime; optimize demand satisfaction with low infeasibility"
+        )
+        return MarketObservation(
+            step=self.step,
+            steps_taken=self.step,
+            max_steps=self.task.max_steps,
+            demand_mwh=round(self.demand_mwh, 3),
+            renewable_availability_mwh=round(self.renewable_mwh, 3),
+            peaker_capacity_mwh=round(self.peaker_capacity_mwh, 3),
+            ev_storage_mwh=round(self.ev_storage_mwh, 3),
+            ev_storage_capacity_mwh=round(self.ev_storage_capacity_mwh, 3),
+            last_clearing_price=round(self.last_clearing_price, 3),
+            leader_price_signal=round(self.base_price, 3),
+            scarcity_index=round(max(0.0, (self.demand_mwh - self.renewable_mwh) / max(self.demand_mwh, 1e-6)), 4),
+            shock_active=self.shock_seen,
+            public_signal=public_signal,
+            schema_info=SCHEMA_INFO,
+            hint=hint,
+            error_message=error_message,
+        )
+
+
+class SmartGridMarketEnv:
+    def __init__(self):
+        self._sessions: Dict[str, Session] = {}
+        self._latest_session_id: Optional[str] = None
+
+    def reset(self, task_id: str = "default", seed: Optional[int] = None) -> ResetResponse:
+        task = get_task(task_id)
+        rng = random.Random(seed)
+        session = Session(
+            task=task,
+            rng=rng,
+            demand_mwh=task.initial_demand_mwh,
+            renewable_mwh=task.initial_renewable_mwh,
+            peaker_capacity_mwh=task.peaker_capacity_mwh,
+            ev_storage_mwh=task.ev_storage_mwh,
+            ev_storage_capacity_mwh=task.ev_storage_capacity_mwh,
+            base_price=task.base_price_usd_per_mwh,
+            last_clearing_price=task.base_price_usd_per_mwh,
+            personalities={
+                "renewable_1": rng.choice(["opportunistic", "balanced"]),
+                "peaker_1": rng.choice(["greedy", "balanced", "risk_averse"]),
+                "industrial_1": rng.choice(["risk_averse", "balanced"]),
+                "ev_1": rng.choice(["balanced", "risk_averse"]),
+            },
+        )
+        self._sessions[session.session_id] = session
+        self._latest_session_id = session.session_id
+
+        return ResetResponse(
+            session_id=session.session_id,
+            task_id=task.task_id,
+            task_description=task.description,
+            schema_info=SCHEMA_INFO,
+            steps_taken=0,
+            observation=session.to_observation(hint=task.hint),
+        )
+
+    def step(self, action: JointAction, session_id: Optional[str] = None) -> StepResponse:
+        session = self._get_session(session_id)
+        if session.done:
+            return StepResponse(
+                observation=session.to_observation(error_message="Episode finished. Call reset."),
+                reward=compute_reward(
+                    dispatch={
+                        "delivered_supply_mwh": 0.0,
+                        "unmet_demand_mwh": 0.0,
+                        "oversupply_mwh": 0.0,
+                        "correction_count": 0,
+                        "storage_loss_mwh": 0.0,
+                        "renewable_dispatch_mwh": 0.0,
+                    },
+                    clearing_price=session.last_clearing_price,
+                    demand_mwh=max(1.0, session.demand_mwh),
+                    prior_gap=0.0,
+                ),
+                done=True,
+                truncated=False,
+                info={"error": "episode_done"},
+            )
+
+        market = clear_market(action.bids, leader_price_signal=session.base_price)
+        dispatch, next_storage = enforce_dispatch(
+            market_result=market,
+            demand_mwh=session.demand_mwh,
+            renewable_available_mwh=session.renewable_mwh,
+            peaker_capacity_mwh=session.peaker_capacity_mwh,
+            ev_storage_mwh=session.ev_storage_mwh,
+            ev_storage_capacity_mwh=session.ev_storage_capacity_mwh,
+            ev_charge_mwh=action.ev_charge_mwh,
+            ev_discharge_mwh=action.ev_discharge_mwh,
+        )
+
+        reward = compute_reward(
+            dispatch=dispatch,
+            clearing_price=market["clearing_price"] or session.base_price,
+            demand_mwh=session.demand_mwh,
+            prior_gap=session.prior_gap,
+        )
+
+        session.step += 1
+        session.ev_storage_mwh = next_storage
+        session.last_clearing_price = market["clearing_price"] or session.base_price
+        session.prior_gap = dispatch["delivered_supply_mwh"] - session.demand_mwh
+        session.correction_count += dispatch["correction_count"]
+        if dispatch["correction_count"] > 0:
+            session.infeasible_actions += 1
+        session.total_demand_met += min(session.demand_mwh, dispatch["delivered_supply_mwh"])
+        session.total_cost += dispatch["delivered_supply_mwh"] * session.last_clearing_price
+        session.reward_history.append(reward.score)
+
+        private_views = self._build_private_agent_views(session, market, dispatch)
+
+        next_demand, next_renewable, next_price, dyn_info = evolve_grid(
+            demand_mwh=session.demand_mwh,
+            renewable_mwh=session.renewable_mwh,
+            base_price_usd_per_mwh=session.base_price,
+            step=session.step,
+            task=session.task,
+            rng=session.rng,
+        )
+        session.demand_mwh = next_demand
+        session.renewable_mwh = next_renewable
+        session.base_price = next_price
+        session.shock_seen = session.shock_seen or dyn_info["shock_active"]
+
+        event = {
+            "step": session.step,
+            "market": market,
+            "dispatch": dispatch,
+            "reward": reward.model_dump(),
+            "dynamics": dyn_info,
+            "agent_private_views": private_views,
+        }
+        session.event_log.append(event)
+
+        done = session.step >= session.task.max_steps
+        session.done = done
+
+        info = {
+            "market": market,
+            "dispatch": dispatch,
+            "dynamics": dyn_info,
+            "agent_private_views": private_views,
+            "summary": {
+                "avg_reward": round(sum(session.reward_history) / len(session.reward_history), 4),
+                "total_demand_met_mwh": round(session.total_demand_met, 3),
+                "total_cost_usd": round(session.total_cost, 3),
+                "infeasible_actions": session.infeasible_actions,
+                "ldu_corrections": session.correction_count,
+                "leader_adjusted_bids": market["leader_adjusted_bids"],
+                "personality_map": session.personalities,
+            },
+        }
+
+        return StepResponse(
+            observation=session.to_observation(),
+            reward=reward,
+            done=done,
+            truncated=False,
+            info=info,
+        )
+
+    def state(self, session_id: Optional[str] = None) -> StateResponse:
+        session = self._get_session(session_id)
+        return StateResponse(
+            current_task_id=session.task.task_id,
+            steps_taken=session.step,
+            episode_done=session.done,
+            observation=session.to_observation(),
+        )
+
+    def events(self, session_id: Optional[str] = None) -> Dict:
+        session = self._get_session(session_id)
+        return {"session_id": session.session_id, "events": session.event_log[-50:]}
+
+    def get_schema(self) -> Dict:
+        return {
+            "action_schema": JointAction.model_json_schema(),
+            "observation_schema": MarketObservation.model_json_schema(),
+            "reward_schema": MarketReward.model_json_schema(),
+            "tasks": ["default"],
+            "notes": "Hybrid Theme 1+2+3.1 baseline implementation with LDU as core physical layer",
+        }
+
+    def _get_session(self, session_id: Optional[str]) -> Session:
+        sid = session_id or self._latest_session_id
+        if sid is None or sid not in self._sessions:
+            raise KeyError("No active session. Call /reset first.")
+        return self._sessions[sid]
+
+    def _build_private_agent_views(self, session: Session, market: Dict, dispatch: Dict) -> Dict[str, Dict]:
+        scarcity = max(0.0, (session.demand_mwh - session.renewable_mwh) / max(session.demand_mwh, 1e-6))
+        spread = max(0.0, session.base_price - session.last_clearing_price)
+        return {
+            "renewable_1": {
+                "personality": session.personalities.get("renewable_1", "balanced"),
+                "curtailment_risk": round(max(0.0, session.renewable_mwh - market.get("cleared_mwh", 0.0)), 3),
+                "forecast_bias": round(session.rng.uniform(-3.0, 3.0), 3),
+            },
+            "peaker_1": {
+                "personality": session.personalities.get("peaker_1", "balanced"),
+                "scarcity_index": round(scarcity, 4),
+                "margin_signal": round(market.get("clearing_price", session.base_price) - 42.0, 3),
+            },
+            "industrial_1": {
+                "personality": session.personalities.get("industrial_1", "balanced"),
+                "budget_pressure": round(
+                    market.get("clearing_price", session.base_price) / max(session.base_price, 1e-6),
+                    4,
+                ),
+                "unmet_demand_mwh": dispatch["unmet_demand_mwh"],
+            },
+            "ev_1": {
+                "personality": session.personalities.get("ev_1", "balanced"),
+                "soc_ratio": round(session.ev_storage_mwh / max(session.ev_storage_capacity_mwh, 1e-6), 4),
+                "arbitrage_spread": round(spread, 3),
+            },
+        }

smartgrid_mas/models.py

@@ -0,0 +1,98 @@
+from typing import Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+AgentRole = Literal[
+    "renewable_prosumer",
+    "ev_aggregator",
+    "peaker_plant",
+    "industrial_load",
+]
+BidType = Literal["supply", "demand"]
+
+
+class AgentBid(BaseModel):
+    agent_id: str = Field(..., description="Unique agent id")
+    role: AgentRole = Field(..., description="Agent role")
+    bid_type: BidType = Field(..., description="Supply or demand bid")
+    quantity_mwh: float = Field(..., ge=0.0, description="Bid quantity in MWh")
+    price_usd_per_mwh: float = Field(..., ge=0.0, description="Bid price")
+
+
+class JointAction(BaseModel):
+    bids: List[AgentBid] = Field(default_factory=list, description="Bids from all agents")
+    ev_charge_mwh: float = Field(0.0, ge=0.0, description="EV fleet charge command")
+    ev_discharge_mwh: float = Field(0.0, ge=0.0, description="EV fleet discharge command")
+
+
+class MarketObservation(BaseModel):
+    step: int
+    steps_taken: int
+    max_steps: int
+    demand_mwh: float
+    renewable_availability_mwh: float
+    peaker_capacity_mwh: float
+    ev_storage_mwh: float
+    ev_storage_capacity_mwh: float
+    last_clearing_price: float
+    leader_price_signal: float
+    scarcity_index: float
+    shock_active: bool
+    public_signal: str
+    schema_info: str
+    hint: Optional[str] = None
+    error_message: Optional[str] = None
+
+
+class MarketReward(BaseModel):
+    score: float = Field(..., ge=0.0, le=1.0)
+    reason: str
+    demand_satisfaction_score: float
+    cost_efficiency_score: float
+    renewable_utilization_score: float
+    stability_score: float
+    infeasibility_penalty: float
+    blackout_penalty: float
+
+
+class ResetRequest(BaseModel):
+    task_id: str = "default"
+    seed: Optional[int] = None
+
+
+class ResetResponse(BaseModel):
+    session_id: str
+    task_id: str
+    task_description: str
+    schema_info: str
+    steps_taken: int
+    observation: MarketObservation
+
+
+class StepRequest(BaseModel):
+    action: JointAction
+
+
+class StepResponse(BaseModel):
+    observation: MarketObservation
+    reward: MarketReward
+    done: bool
+    truncated: bool
+    info: Dict
+
+
+class StateResponse(BaseModel):
+    current_task_id: str
+    steps_taken: int
+    episode_done: bool
+    observation: Optional[MarketObservation] = None
+
+
+class EpisodeSummary(BaseModel):
+    average_reward: float
+    total_demand_met: float
+    total_cost: float
+    infeasible_actions: int
+    corrections: int
+    shock_response_score: float

smartgrid_mas/tasks.py

@@ -0,0 +1,56 @@
+from dataclasses import dataclass
+from typing import Dict
+
+
+@dataclass
+class TaskConfig:
+    task_id: str
+    description: str
+    max_steps: int
+    initial_demand_mwh: float
+    initial_renewable_mwh: float
+    peaker_capacity_mwh: float
+    ev_storage_mwh: float
+    ev_storage_capacity_mwh: float
+    base_price_usd_per_mwh: float
+    demand_trend_mwh: float
+    renewable_trend_mwh: float
+    demand_volatility: float
+    renewable_volatility: float
+    shock_step: int
+    shock_renewable_drop: float
+    hint: str
+
+
+TASKS: Dict[str, TaskConfig] = {
+    "default": TaskConfig(
+        task_id="default",
+        description=(
+            "Hybrid multi-agent smart-grid market simulation. Agents submit strategic bids, "
+            "market clears, and LDU enforces physical feasibility with correction logs."
+        ),
+        max_steps=24,
+        initial_demand_mwh=120.0,
+        initial_renewable_mwh=70.0,
+        peaker_capacity_mwh=85.0,
+        ev_storage_mwh=25.0,
+        ev_storage_capacity_mwh=60.0,
+        base_price_usd_per_mwh=45.0,
+        demand_trend_mwh=1.2,
+        renewable_trend_mwh=-0.6,
+        demand_volatility=4.0,
+        renewable_volatility=6.0,
+        shock_step=16,
+        shock_renewable_drop=22.0,
+        hint=(
+            "Coordinate bids with expected dispatch feasibility. Market-optimal bids that violate "
+            "physical constraints are corrected by LDU and reduce reward."
+        ),
+    )
+}
+
+
+def get_task(task_id: str) -> TaskConfig:
+    if task_id not in TASKS:
+        raise ValueError(f"Unknown task_id '{task_id}'. Available: {list(TASKS.keys())}")
+    return TASKS[task_id]

smartgrid_mas/train_baseline.py

@@ -0,0 +1,85 @@
+import argparse
+import csv
+import os
+import random
+from typing import List
+
+import matplotlib.pyplot as plt
+
+from smartgrid_mas.engine.policies import (
+    adaptive_stackelberg_action,
+    heuristic_joint_action,
+    random_joint_action,
+)
+from smartgrid_mas.env import SmartGridMarketEnv
+
+
+def run_episode(env: SmartGridMarketEnv, policy_name: str, seed: int) -> float:
+    reset = env.reset(task_id="default", seed=seed)
+    sid = reset.session_id
+    obs = reset.observation
+    rng = random.Random(seed)
+
+    rewards: List[float] = []
+    while True:
+        if policy_name == "random":
+            action = random_joint_action(obs, rng)
+        elif policy_name == "adaptive":
+            action = adaptive_stackelberg_action(obs, personality="balanced")
+        else:
+            action = heuristic_joint_action(obs, personality="balanced")
+
+        step = env.step(action=action, session_id=sid)
+        rewards.append(step.reward.score)
+        obs = step.observation
+        if step.done:
+            break
+
+    return sum(rewards) / max(1, len(rewards))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Minimal baseline training/eval runner")
+    parser.add_argument("--episodes", type=int, default=30)
+    parser.add_argument("--outdir", type=str, default="artifacts")
+    args = parser.parse_args()
+
+    os.makedirs(args.outdir, exist_ok=True)
+
+    env = SmartGridMarketEnv()
+    random_curve = []
+    heuristic_curve = []
+    adaptive_curve = []
+
+    for ep in range(args.episodes):
+        random_curve.append(run_episode(env, "random", seed=1000 + ep))
+        heuristic_curve.append(run_episode(env, "heuristic", seed=2000 + ep))
+        adaptive_curve.append(run_episode(env, "adaptive", seed=3000 + ep))
+
+    csv_path = os.path.join(args.outdir, "baseline_metrics.csv")
+    with open(csv_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.writer(f)
+        writer.writerow(["episode", "random_avg_reward", "heuristic_avg_reward", "adaptive_avg_reward"])
+        for i, (r, h, a) in enumerate(zip(random_curve, heuristic_curve, adaptive_curve), start=1):
+            writer.writerow([i, round(r, 6), round(h, 6), round(a, 6)])
+
+    plt.figure(figsize=(10, 5))
+    plt.plot(range(1, args.episodes + 1), random_curve, label="Random baseline")
+    plt.plot(range(1, args.episodes + 1), heuristic_curve, label="Heuristic improved")
+    plt.plot(range(1, args.episodes + 1), adaptive_curve, label="Adaptive Stackelberg")
+    plt.xlabel("Episode")
+    plt.ylabel("Average reward")
+    plt.title("Baseline vs Improved Policy Reward")
+    plt.legend()
+    plt.grid(alpha=0.25)
+
+    fig_path = os.path.join(args.outdir, "reward_comparison.png")
+    plt.tight_layout()
+    plt.savefig(fig_path, dpi=160)
+
+    print(f"Saved metrics CSV: {csv_path}")
+    print(f"Saved reward plot: {fig_path}")
+
+
+if __name__ == "__main__":
+    main()

training/minimal_train.py

@@ -0,0 +1,5 @@
+from smartgrid_mas.train_baseline import main
+
+
+if __name__ == "__main__":
+    main()