Build a Solar-Aware Structural Concrete Slab Staging Optimizer — implementation

## Build
Coordinate mass concrete slab delivery windows against pvlib clear-sky ambient temperature and transit buffers. Schedule structural pours during safe solar windows to prevent thermal curing defects.

## User
Construction Logistics Dispatcher

## Workflow
1. Ingest structural slab mix specifications, gate capacity, and hourly ambient temperature projections.
2. Calculate temperature-adjusted work restrictions and delivery transit times across suburban routes.
3. Model solar surface irradiance impact on batch transit using pvlib clear-sky calculations.
4. Generate optimized slab staging intervals and alert dispatchers when temperatures exceed limits.

## Interface
Interactive timeline calendar showing scheduled pours, heat index warning bands, and batch truck arrival slot allocations.

## Data
Generate synthetic batch orders. These represent simplified synthetic app records, not complete official schema files, containing slump requirements, transit pairs, and hourly simulated ambient temperature arrays.
Starter examples below are synthetic. They are not downloaded records.

## Source
[PVLib solar modeling](https://raw.githubusercontent.com/pvlib/pvlib-python/main/README.md)
Uses pvlib clear-sky irradiance modeling methods to estimate direct solar radiation load impacting concrete transit drums.

## Tools
optuna, pvlib, fastapi.
Optuna optimizes truck arrival staging schedules to minimize both waiting time and peak thermal exposure.
Local Python optimization engine paired with an instruction-following model for shift briefing generation.

## 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
- Rejects delivery slots where projected ambient drum exposure exceeds 38 degrees Celsius during placement.
- Schedules all batch trucks with exactly a 15-minute buffer between successive gate arrivals starting from the requested pour start time.
- Calculates total trucks needed strictly by dividing the total volume by truck capacity.
- Outputs an hourly logistical slot allocation timetable with thermal risk classifications.

## Starter Examples
```json
[
  {
    "input": {
      "pour_id": "POUR-881",
      "volume_m3": 30,
      "truck_capacity_m3": 10,
      "start_time": "04:00",
      "buffer_mins": 15
    },
    "expected_output": {
      "total_trucks": 3,
      "approved_slots": [
        "04:00",
        "04:15",
        "04:30"
      ]
    }
  },
  {
    "input": {
      "pour_id": "POUR-882",
      "volume_m3": 20,
      "truck_capacity_m3": 10,
      "start_time": "06:00",
      "buffer_mins": 15
    },
    "expected_output": {
      "total_trucks": 2,
      "approved_slots": [
        "06:00",
        "06:15"
      ]
    }
  }
]
```

## Safety
Logistical schedules are advisory; pour approvals must comply with site structural engineer testing and slump verification standards.
Use mock external writes. Require human review before any real deployment.