Build an SME Freight Invoice Discrepancy Queue and Carrier Correction Drafter — implementation

## Build
Reconcile logistics service provider freight invoices against contracted rate cards and demurrage rules. Isolate excessive fuel surcharges, detention penalties, and draft dispute correction notices.

## User
SME Freight Procurement Specialist

## Workflow
1. Extract freight invoice lines, ocean bill numbers, and carrier detention charges from normalized PDFs.
2. Compare invoiced line items against agreed rate card limits and free-time allowance schedules.
3. Identify unjustified demurrage fees caused by terminal equipment downtime or customs hold delays.
4. Assemble an itemized invoice variance dossier and compile a formal carrier credit request draft.

## Interface
A discrepancy queue showing disputed carrier charges, contract baseline comparison sliders, and one-click dispute letter generators.

## Data
Construct synthetic normalized freight invoice records and mock contractual rate cards in JSON format.
Starter examples below are synthetic. They are not downloaded records.

## Source
[Singapore open data API](https://guide.data.gov.sg/developer-guide/api-overview)
Adopt data.gov.sg dataset nomenclature and metadata structures to manage structured logistics rate cards.

## Tools
semantic-kernel, pydantic, fastapi.
Semantic Kernel facilitates pipeline chaining between numerical rate card audits and structured communication drafting.
Local or hosted LLM with multi-step reasoning capabilities and JSON output format.

## 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
- Pinpoints demurrage charges assessed within agreed container free-time periods.
- Calculates Singapore dollar rate card variance across local trucking and terminal surcharges.
- Drafts carrier dispute emails detailing bill of lading numbers and contractual fee caps.
- Prevents approval of invoices containing unexplained surcharges over 50 SGD.

## Starter Examples
```json
[
  {
    "input": {
      "invoice_id": "FRT-2025-101",
      "carrier_name": "Regional Feeder Lines",
      "bill_of_lading": "BL-77123",
      "ocean_freight_billed": 1200,
      "contracted_freight": 1200,
      "demurrage_billed": 450,
      "container_free_days": 5,
      "actual_dwell_days": 3
    },
    "expected_output": {
      "reconciliation_result": "dispute_required",
      "variance_amount": 450,
      "disputed_items": [
        "Demurrage assessed for 3 days dwell when contract provides 5 free days"
      ],
      "proposed_credit_amount": 450,
      "dispute_letter_summary": "Carrier billed SGD 450 demurrage in error during free-time window."
    }
  },
  {
    "input": {
      "invoice_id": "FRT-2025-102",
      "carrier_name": "Straits Trucking Pte Ltd",
      "bill_of_lading": "BL-88412",
      "ocean_freight_billed": 650,
      "contracted_freight": 650,
      "demurrage_billed": 0,
      "container_free_days": 3,
      "actual_dwell_days": 2
    },
    "expected_output": {
      "reconciliation_result": "cleared",
      "variance_amount": 0,
      "disputed_items": [],
      "proposed_credit_amount": 0,
      "dispute_letter_summary": null
    }
  }
]
```

## Safety
Drafts dispute communications; financial credits and ledger modifications require human controller authorization.
Use mock external writes. Require human review before any real deployment.