Build a Multi-Provider Logistics Route Settlement and Dispute Explainer — implementation

## Build
Evaluate multi-hop delivery fulfillment legs across independent mock carriers to identify mileage variances and charge discrepancies. Construct objective variance dossiers to resolve courier compensation disputes without financial routing.

## User
Logistics network operations dispatcher

## Workflow
1. Ingest multi-leg fulfillment milestone logs and base rate cards from simulated Beckn logistics packets.
2. Compare documented GPS transit distances against contracted route corridors and toll allowances.
3. Identify fuel surcharge discrepancies and detention fee mismatches across carrier handover checkpoints.
4. Generate a structured variance resolution summary for review by carrier dispute arbiters.

## Interface
Multi-carrier timeline view displaying route waypoint timestamps, cost breakdowns, and disputed amount highlights.

## Data
Construct synthetic multi-hop logistics order records and simulated waybill telemetry files in local JSON format.
Starter examples below are synthetic. They are not downloaded records.

## Source
[ONDC network extension](https://raw.githubusercontent.com/ONDC-Official/protocol-network-extension/main/README.md)
Adopts ONDC protocol-network-extension logistics API contract definitions and participant handover states.

## Tools
langfuse, fastapi, pydantic-ai.
Tracks telemetry traces, evaluation metrics, and prompt token usage across multi-carrier discrepancy analyses.
Instruction-tuned hosted model with high precision in numeric dispute reasoning.

## 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 carrier transit legs against minimum and maximum distance tolerances.
- Categorizes fee variances into fuel, toll, or detention line items.
- Emits structured dispute findings without dispatching fund movements.

## Starter Examples
```json
[
  {
    "input": {
      "waybill_id": "WB-4410",
      "contracted_km": 42,
      "actual_gps_km": 43.5,
      "agreed_base_rate": 450,
      "claimed_total": 520,
      "toll_receipt_present": true,
      "toll_amount": 50
    },
    "expected_output": {
      "approved_amount": 500,
      "discrepancy_amount": 20,
      "variance_reason": "Excess mileage within 5% tolerance; unapproved detention surcharge of 20.00 deducted.",
      "disposition": "partial_approval"
    }
  },
  {
    "input": {
      "waybill_id": "WB-4411",
      "contracted_km": 15,
      "actual_gps_km": 28,
      "agreed_base_rate": 200,
      "claimed_total": 410,
      "toll_receipt_present": false,
      "toll_amount": 0
    },
    "expected_output": {
      "approved_amount": 200,
      "discrepancy_amount": 210,
      "variance_reason": "Significant unapproved detour (>10km) without prior dispatcher exception authorization.",
      "disposition": "escalate_to_analyst"
    }
  }
]
```

## Safety
Maintains an auditing framework for logistics invoices without executing courier bank payouts or ledger adjustments.
Use mock external writes. Require human review before any real deployment.