Build a Buyer-Seller Settlement Reconciliation and Fee Explainer — implementation

## Build
Cross-reference settled commerce orders against agreed buyer app finder fees, tax deductions, and seller withholdings. Synthesize clear fee breakdown explanations to resolve merchant payout inquiries without executing transfers.

## User
E-commerce merchant support analyst

## Workflow
1. Parse completed order line items, fulfillment timestamps, and contractual fee agreements from mock settlement files.
2. Calculate finder fees, logistics deductions, and statutory tax collected at source on gross transactions.
3. Reconcile differences between merchant invoicing totals and estimated net payouts across order batches.
4. Produce an explainable settlement audit receipt for merchant dispute teams without initiating banking operations.

## Interface
Web dashboard showing order-by-order fee deductions, variance alerts, and exportable reconciliation receipts.

## Data
Assemble mock ONDC order items and settlement schedules in local JSON files adhering to standard ONDC draft schemas.
Starter examples below are synthetic. They are not downloaded records.

## Source
[ONDC protocol specifications](https://raw.githubusercontent.com/ONDC-Official/ONDC-Protocol-Specs/master/README.md)
Adopts ONDC protocol draft versioning and buyer-seller network role specifications to map transaction structures.

## Tools
dspy, pandas, fastapi.
Optimizes prompt formulations to synthesize human-readable fee explainability memos from numeric tabular inputs.
Fast hosted model suitable for few-shot prompt compilation and arithmetic explanation.

## 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
- Matches order line items against agreed platform finder fee percentages exactly.
- Identifies fee discrepancies exceeding a one-rupee tolerance threshold.
- Produces narrative payout summaries without performing real automated payment movements.

## Starter Examples
```json
[
  {
    "input": {
      "settlement_id": "SET-1029",
      "order_id": "ORD-55412",
      "gross_amount": 1200,
      "buyer_finder_fee_pct": 3,
      "logistics_fee": 150,
      "withholding_tax_pct": 1
    },
    "expected_output": {
      "calculated_net_payout": 1002,
      "deductions": {
        "buyer_finder_fee": 36,
        "logistics_charge": 150,
        "statutory_withholding": 12
      },
      "status": "balanced",
      "explanation": "Gross 1200.00 minus 3% finder fee (36.00), logistics (150.00), and 1% withholding (12.00) yields 1002.00."
    }
  },
  {
    "input": {
      "settlement_id": "SET-1030",
      "order_id": "ORD-55413",
      "gross_amount": 800,
      "buyer_finder_fee_pct": 5,
      "logistics_fee": 200,
      "withholding_tax_pct": 1
    },
    "expected_output": {
      "calculated_net_payout": 552,
      "deductions": {
        "buyer_finder_fee": 40,
        "logistics_charge": 200,
        "statutory_withholding": 8
      },
      "status": "balanced",
      "explanation": "Gross 800.00 minus 5% finder fee (40.00), logistics (200.00), and 1% withholding (8.00) yields 552.00."
    }
  }
]
```

## Safety
Maintains read-only accounting simulations and never executes actual bank debits or digital wallet transactions.
Use mock external writes. Require human review before any real deployment.