Build a Buyer Multi-Hop Return Route and Compensation Explainer — implementation

## Build
Analyze complex return scenarios across multiple mock logistics carriers in open networks. Reconcile restock penalties and courier fee shares into clear settlement explanations.

## User
Post-fulfillment logistics operations analyst

## Workflow
1. Ingest multi-leg return fulfillment events and tracking checkpoints from mock Beckn BAP callbacks.
2. Calculate reverse transit mileages, return handling surcharges, and merchant restocking deductibles.
3. Detect discrepancies between asserted courier handoffs and actual pickup scan events.
4. Generate a structured variance dossier and claimant breakdown notice for advocate review.

## Interface
Multi-hop route visualizer with breakdown calculation tables and disputed carrier cost alerts.

## Data
Construct synthetic multi-hop logistics tracking events following Beckn Final Mile Delivery specifications.
Starter examples below are synthetic. They are not downloaded records.

## Source
[Beckn protocol specifications](https://raw.githubusercontent.com/beckn/protocol-specifications/master/README.md)
Applies Beckn Final Mile Delivery callback lifecycle schemas and asynchronous fulfillment status flows.

## Tools
ray-serve, pydantic, fastapi.
Serves distributed rule evaluation models for high-throughput reconciliation of asynchronous delivery handoffs.
API-hosted Claude or local Llama for plain-language variance statement 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
- Compute exact leg-by-leg logistics charges and merchant deductibles from mock events.
- Isolate transit tracking gaps across distinct carrier handoff nodes.
- Output itemized dispute settlement summaries in normalized JSON.
- Flag unauthorized fee clawbacks for human logistics auditor review.

## Starter Examples
```json
[
  {
    "input": {
      "return_order_id": "RET-7741",
      "carrier_legs": [
        {
          "carrier": "courier-hyperlocal-a",
          "status": "picked_up",
          "charge": 40
        },
        {
          "carrier": "courier-intercity-b",
          "status": "delivered_to_hub",
          "charge": 110
        }
      ],
      "merchant_restock_rate": 0.05,
      "item_value": 1000
    },
    "expected_output": {
      "total_reverse_logistics_cost": 150,
      "merchant_deduction": 50,
      "buyer_refund_amount": 950,
      "discrepancy_detected": false,
      "disposition": "settlement_approved"
    }
  },
  {
    "input": {
      "return_order_id": "RET-9012",
      "carrier_legs": [
        {
          "carrier": "courier-local-x",
          "status": "picked_up",
          "charge": 45
        },
        {
          "carrier": "courier-intercity-y",
          "status": "lost_in_transit",
          "charge": 120
        }
      ],
      "merchant_restock_rate": 0,
      "item_value": 2400
    },
    "expected_output": {
      "total_reverse_logistics_cost": 45,
      "merchant_deduction": 0,
      "buyer_refund_amount": 2400,
      "discrepancy_detected": true,
      "disposition": "carrier_liability_claim"
    }
  }
]
```

## Safety
Strictly diagnostic; generates non-binding settlement audits without executing banking or payment commands.
Use mock external writes. Require human review before any real deployment.