// Package env defines all data models for the GridMind-RL environment. package env // BatchJob represents a pending industrial/commercial batch process job. type BatchJob struct { ID int `json:"id"` // Unique job identifier DeadlineSlot int `json:"deadline_slot"` // Latest timestep by which the job must run Duration int `json:"duration"` // Steps the job takes to complete PowerDraw float64 `json:"power_draw"` // kW drawn when job is running Scheduled bool `json:"scheduled"` // Whether a time slot has been assigned ScheduledAt int `json:"scheduled_at"` // Timestep at which job was scheduled (-1 if not yet) Completed bool `json:"completed"` // Whether the job finished execution MissedDeadline bool `json:"missed_deadline"` // True if deadline was exceeded } // BuildingState holds the full simulation state for a single building. type BuildingState struct { // Core physical state IndoorTemperature float64 `json:"indoor_temperature"` // °C ThermalStorageLevel float64 `json:"thermal_storage_level"` // 0.0–1.0 normalized ProcessDemand float64 `json:"process_demand"` // kW current process need // Market & grid signals CurrentPrice float64 `json:"current_price"` // $/kWh GridStressSignal float64 `json:"grid_stress_signal"` // 0.0–1.0 (DR urgency) CarbonIntensity float64 `json:"carbon_intensity"` // gCO2/kWh // Temporal HourOfDay int `json:"hour_of_day"` // 0–23 Step int `json:"step"` // 0–95 within a 96-step (24h) episode // Batch job queue: pending deadlines (raw slots) BatchQueue []int `json:"batch_queue"` // deadline slots of pending jobs // Running cost tracker CumulativeCost float64 `json:"cumulative_cost"` // $ total this episode CumulativeCarbon float64 `json:"cumulative_carbon"` // gCO2 total this episode // Internal tracking (not exposed in observation) Jobs []BatchJob `json:"-"` OutdoorTemperature float64 `json:"-"` // °C for weather perturbation PrevHVACLevel float64 `json:"-"` // for stability penalty BaselineCost float64 `json:"-"` // always-on policy running cost BaselineCarbon float64 `json:"-"` // baseline policy gCO2 (for grading) SetpointTemperature float64 `json:"-"` // target indoor temp (°C) MaxHVACPower float64 `json:"-"` // kW MaxStorageCapacity float64 `json:"-"` // kWh ThermalLossRate float64 `json:"-"` // fraction lost per step BuildingID int `json:"-"` // which building in federation } // ObservationModel is the JSON-serializable observation returned on each step/state. type ObservationModel struct { IndoorTemperature float64 `json:"indoor_temperature"` ThermalStorageLevel float64 `json:"thermal_storage_level"` ProcessDemand float64 `json:"process_demand"` CurrentPrice float64 `json:"current_price"` GridStressSignal float64 `json:"grid_stress_signal"` CarbonIntensity float64 `json:"carbon_intensity"` HourOfDay int `json:"hour_of_day"` BatchQueue []int `json:"batch_queue"` CumulativeCost float64 `json:"cumulative_cost"` Step int `json:"step"` BuildingID int `json:"building_id"` } // ActionModel is the parsed agent action for a single step. type ActionModel struct { HVACPowerLevel float64 `json:"hvac_power_level"` // 0.0–1.0 ThermalChargeRate float64 `json:"thermal_charge_rate"` // -1.0 to 1.0 BatchJobSlot int `json:"batch_job_slot"` // 0–4 (0=now, 1–4=defer) LoadShedFraction float64 `json:"load_shed_fraction"` // 0.0–0.5 BuildingID int `json:"building_id"` // which building to act on } // RewardComponents holds the individual components of the dense reward signal. type RewardComponents struct { CostSavings float64 `json:"cost_savings"` // negative = expensive TempConstraint float64 `json:"temp_constraint"` // positive = within bounds GridResponse float64 `json:"grid_response"` // bonus for DR compliance DeadlinePenalty float64 `json:"deadline_penalty"` // negative for missed jobs EfficiencyBonus float64 `json:"efficiency_bonus"` // storage arbitrage StabilityPenalty float64 `json:"stability_penalty"` // HVAC oscillation penalty CarbonReward float64 `json:"carbon_reward"` // low-carbon bonus Total float64 `json:"total"` } // StepResponse is the full HTTP body returned from POST /step. type StepResponse struct { Observation ObservationModel `json:"observation"` Reward float64 `json:"reward"` Done bool `json:"done"` Info StepInfo `json:"info"` } // StepInfo carries auxiliary information per step. type StepInfo struct { RewardComponents RewardComponents `json:"reward_components"` EnergyUsed float64 `json:"energy_used_kwh"` CarbonEmitted float64 `json:"carbon_emitted_gco2"` PriceSignal float64 `json:"price_signal"` GridStress float64 `json:"grid_stress"` BatchCompleted []int `json:"batch_completed"` // IDs completed this step BatchMissed []int `json:"batch_missed"` // IDs that missed deadline Episode int `json:"episode"` Step int `json:"step"` } // ResetRequest is the JSON body for POST /reset. type ResetRequest struct { Seed *int64 `json:"seed,omitempty"` // optional random seed TaskID int `json:"task_id"` // 1, 2, or 3 Difficulty string `json:"difficulty,omitempty"` // "easy", "medium", "hard" or "" (auto) NumBuildings int `json:"num_buildings,omitempty"` // 1–3 for federation } // ResetResponse is returned from POST /reset. type ResetResponse struct { Observations []ObservationModel `json:"observations"` // one per building Episode int `json:"episode"` TaskID int `json:"task_id"` Seed int64 `json:"seed"` } // StateResponse is returned from GET /state. type StateResponse struct { Buildings []BuildingStatePublic `json:"buildings"` PriceCurve []float64 `json:"price_curve_episode"` // full episode ToU prices CarbonCurve []float64 `json:"carbon_curve_episode"` // full episode carbon intensities Episode int `json:"episode"` Step int `json:"step"` TaskID int `json:"task_id"` Done bool `json:"done"` Seed int64 `json:"seed"` } // BuildingStatePublic is the dashboard-friendly full state per building. type BuildingStatePublic struct { ObservationModel OutdoorTemperature float64 `json:"outdoor_temperature"` SetpointTemperature float64 `json:"setpoint_temperature"` BaselineCost float64 `json:"baseline_cost"` BaselineCarbon float64 `json:"baseline_carbon"` CumulativeCarbon float64 `json:"cumulative_carbon"` Jobs []BatchJob `json:"jobs"` // History for chart rendering TempHistory []float64 `json:"temp_history"` CostHistory []float64 `json:"cost_history"` HVACHistory []float64 `json:"hvac_history"` LoadShedHistory []float64 `json:"load_shed_history"` RewardHistory []RewardComponents `json:"reward_history"` } // ReplayEntry records a single timestep for episode replay export. type ReplayEntry struct { Step int `json:"step"` Observation ObservationModel `json:"observation"` Action ActionModel `json:"action"` Reward float64 `json:"reward"` Components RewardComponents `json:"components"` Done bool `json:"done"` } // EpisodeGrade is the final grade returned for a completed episode. type EpisodeGrade struct { TaskID int `json:"task_id"` Score float64 `json:"score"` // 0.0–1.0 SubScores map[string]float64 `json:"sub_scores"` ExploitDetected bool `json:"exploit_detected"` PenaltyApplied float64 `json:"penalty_applied"` Details map[string]interface{} `json:"details"` }