Build a Warehouse Dock Turnaround and Carrier Detention Dispute Reconciler — implementation

## Build
Cross-examine warehouse electronic gate timestamp records against carrier detention fee invoices. Verify actual queue delays against dock appointment logs to formulate evidence-backed dispute responses.

## User
Warehouse Contract Manager

## Workflow
1. Extract gate-in, dock-in, unloading complete, and gate-out timestamps from warehouse management logs.
2. Compare timestamps against scheduled carrier pickup windows and contractual grace period limits.
3. Determine whether driver turnaround exceedance was caused by warehouse bottlenecks or late carrier arrival.
4. Synthesize an evidence breakdown ledger and draft a verified carrier detention settlement letter.

## Interface
A time-log audit view with stacked timeline bars representing carrier transit, gate waiting, and dock bay turnaround.

## Data
Generate synthetic CSV warehouse RFID gate logs alongside carrier detention claim tickets.
Starter examples below are synthetic. They are not downloaded records.

## Source
[Singapore open data API](https://guide.data.gov.sg/developer-guide/api-overview)
Employ data.gov.sg API query parameter conventions to filter time-series gate event logs.

## Tools
pydantic-ai, fastapi, pandas.
Pydantic AI structures event timestamp calculations into auditable output types with strict delta checks.
Fast hosted model capable of precise time delta comparisons and audit report structuring.

## 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
- Computes carrier detention hours accurately minus contractual two-hour free allowances.
- Assigns delay liability to the carrier when gate arrival was outside the scheduled booking slot.
- Generates an itemized detention ledger detailing approved versus rejected demurrage hours.
- Requires human contract manager verification before final carrier notice dispatch.

## Starter Examples
```json
[
  {
    "input": {
      "claim_id": "DET-2025-01",
      "carrier_id": "HaulWell Logistics",
      "scheduled_slot": "2025-03-15T09:00:00+08:00",
      "actual_gate_in": "2025-03-15T08:55:00+08:00",
      "dock_assigned": "2025-03-15T12:30:00+08:00",
      "gate_out": "2025-03-15T13:45:00+08:00",
      "free_hours": 2,
      "billed_detention_hours": 2.75
    },
    "expected_output": {
      "liability": "warehouse_fault",
      "turnaround_duration_hours": 4.83,
      "allowed_billable_hours": 2.83,
      "disposition": "claim_accepted_partial",
      "reconciled_hours": 2.75,
      "settlement_note": "Approved 2.75 detention hours as warehouse bay assignment was delayed by 3.5 hours."
    }
  },
  {
    "input": {
      "claim_id": "DET-2025-02",
      "carrier_id": "FastPort Drayage",
      "scheduled_slot": "2025-03-15T09:00:00+08:00",
      "actual_gate_in": "2025-03-15T11:45:00+08:00",
      "dock_assigned": "2025-03-15T12:00:00+08:00",
      "gate_out": "2025-03-15T13:00:00+08:00",
      "free_hours": 2,
      "billed_detention_hours": 1.25
    },
    "expected_output": {
      "liability": "carrier_fault",
      "turnaround_duration_hours": 1.25,
      "allowed_billable_hours": 0,
      "disposition": "claim_rejected",
      "reconciled_hours": 0,
      "settlement_note": "Carrier arrived 2 hours 45 minutes late for appointed slot. Turnaround inside terminal was under 2 hours."
    }
  }
]
```

## Safety
Calculates billable hours and drafts settlement notes; no automated payments or credit adjustments occur.
Use mock external writes. Require human review before any real deployment.