Build a Construction Material Delivery Slot and Heat-Aware Staging Scheduler — implementation

## Build
Coordinate construction deliveries across regional transit corridors under intense summer heat forecasts. Evaluate surface unloading limits, material heat sensitivity, and gate congestion to produce verified delivery schedules.

## User
Construction Logistics Coordinator

## Workflow
1. Ingest supplier delivery requests with material thermal thresholds and gate time-window constraints.
2. Query hourly ambient wet-bulb temperature and solar irradiance forecasts for the target delivery corridor.
3. Evaluate truck queue delays and surface temperature thresholds using pvlib solar position calculations.
4. Synthesize heat-safe delivery slot assignments and flag high-risk daytime unloading windows for human review.

## Interface
Web scheduling dashboard displaying delivery manifests, hourly ambient thermal heat profiles, and an interactive slot approval panel.

## Data
Use synthetic normalized JSON delivery manifests alongside hourly weather files derived from public PVGIS or TMY solar irradiance tables.
Starter examples below are synthetic. They are not downloaded records.

## Source
[PVLib solar modeling](https://raw.githubusercontent.com/pvlib/pvlib-python/main/README.md)
Utilizes pvlib solar position calculations (pvlib.solarposition.get_solarposition) to model solar elevation angles and incident surface heating intervals during delivery hours.

## Tools
pydantic-ai, pvlib, fastapi.
Pydantic AI enforces type-safe schemas across delivery requests, thermal limits, and generated staging time slots.
Local or hosted LLM with strong structured output capabilities for scheduling constraints.

## Deliverables
Submit runnable source, pinned dependencies, setup commands, a working interface, example outputs, and a recorded end-to-end demo. Include tests and an action log.

## Acceptance
- Validates incoming delivery orders against allowable material surface temperatures.
- Computes solar elevation angles for proposed delivery hours using pvlib.
- Rejects or reschedules delivery slots exceeding 45°C ambient or 600 W/m² direct solar heating during unloading.
- Outputs a structured schedule JSON ready for gatekeeper review.

## Starter Examples
```json
[
  {
    "input": {
      "deliveries": [
        {
          "delivery_id": "DEL-101",
          "material": "Structural Adhesives",
          "max_temp_c": 38,
          "duration_minutes": 45,
          "requested_window": "12:00-14:00"
        },
        {
          "delivery_id": "DEL-102",
          "material": "Reinforcing Rebar",
          "max_temp_c": 50,
          "duration_minutes": 30,
          "requested_window": "06:00-08:00"
        }
      ],
      "weather_forecast": [
        {
          "hour": 7,
          "temp_c": 32,
          "ghi_wm2": 150
        },
        {
          "hour": 13,
          "temp_c": 44,
          "ghi_wm2": 950
        }
      ]
    },
    "expected_output": {
      "assigned_slots": [
        {
          "delivery_id": "DEL-102",
          "slot_start": "06:30",
          "gate": "Gate-A",
          "status": "APPROVED",
          "thermal_risk": "LOW"
        },
        {
          "delivery_id": "DEL-101",
          "slot_start": "20:00",
          "gate": "Gate-B",
          "status": "RESCHEDULED",
          "thermal_risk": "EXCEEDED_DAYTIME_LIMIT",
          "reason": "Ambient 44C exceeds 38C material ceiling."
        }
      ],
      "requires_human_review": true
    }
  },
  {
    "input": {
      "deliveries": [
        {
          "delivery_id": "DEL-103",
          "material": "Precast Concrete Slabs",
          "max_temp_c": null,
          "duration_minutes": 60,
          "requested_window": "10:00-12:00"
        }
      ],
      "weather_forecast": [
        {
          "hour": 11,
          "temp_c": 41,
          "ghi_wm2": 800
        }
      ]
    },
    "expected_output": {
      "assigned_slots": [],
      "error": "MISSING_THERMAL_SPECIFICATION",
      "flagged_deliveries": [
        "DEL-103"
      ],
      "requires_human_review": true
    }
  }
]
```

## Safety
Simulates yard staging plans; prohibits direct physical gate actuation without site logistics manager verification.
Use mock external writes. Require human review before any real deployment.