Build a Buyer App Dispute Reconciliation and Reverse Carrier Coordinator — implementation

## Build
Coordinate multi-party returns between buyer apps and logistics providers using Beckn delivery specs. Match reverse pickup manifests against original delivery tracking records.

## User
Network operations logistics coordinator

## Workflow
1. Receive approved return requests from buyer apps with item dimensions and addresses.
2. Generate Beckn final-mile delivery fulfillment requests for reverse carrier dispatch.
3. Reconcile return tracking updates against original forward-delivery waybill records.
4. Publish an automated return receipt dossier triggering refund approval.

## Interface
Interactive logistics dispatch console tracking forward and reverse fulfillment states across mock carriers.

## Data
Create synthetic delivery logs based on Beckn final-mile delivery schemas with matching forward and reverse tracking IDs.
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 specifications for fulfillment tracking and carrier handover events.

## Tools
langgraph, pydantic.
LangGraph maintains state across asynchronous multi-hop fulfillment cycles and reverse delivery handoffs.
LLM capable of coordinating state machines and structured JSON validation for logistics events.

## 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
- Generates valid Beckn fulfillment payloads containing pickup and dropoff location tags.
- Reconciles mismatched return package weights against baseline forward delivery specs.
- Triggers refund approval signals only upon verified carrier return receipt.

## Starter Examples
```json
[
  {
    "input": {
      "original_waybill": "WB-99120",
      "return_carrier_id": "CARRIER-EXPRESS-01",
      "item_weight_kg": 1.2,
      "return_event": "PACKAGE_COLLECTED_FROM_BUYER",
      "seal_intact": true
    },
    "expected_output": {
      "fulfillment_state": "IN_REVERSE_TRANSIT",
      "weight_reconciled": true,
      "refund_gate": "HOLD_FOR_DELIVERY_SCAN",
      "next_action": "AWAIT_SELLER_HUB_RECEIPT"
    }
  },
  {
    "input": {
      "original_waybill": "WB-44180",
      "return_carrier_id": "CARRIER-LOCAL-09",
      "item_weight_kg": 0.1,
      "return_event": "SELLER_REJECTED_EMPTY_BOX",
      "seal_intact": false
    },
    "expected_output": {
      "fulfillment_state": "DISPUTED_RETURN",
      "weight_reconciled": false,
      "refund_gate": "BLOCKED_FRAUD_INVESTIGATION",
      "next_action": "ESCALATE_TO_ARBITRATION"
    }
  }
]
```

## Safety
Uses dummy tracking IDs and mock geolocation addresses without live logistics carrier API writes.
Use mock external writes. Require human review before any real deployment.