Build a Beckn Delivery SLA Monitoring and Penalty Engine — implementation

## Build
Evaluate Beckn final-mile fulfillment payloads to calculate delivery agent compliance against network service level agreements. Generate structured penalty deductions and compliance dossiers for delayed callbacks or damaged parcels within decentralized open networks.

## User
Fulfillment network operations manager

## Workflow
1. Ingest Beckn final-mile delivery fulfillment success metrics and delayed callback logs.
2. Calculate on-time delivery rates and payload integrity scores for mock independent agents.
3. Compute variable penalty deductions based on delivery failures and SLA non-compliance.
4. Synthesize a structured agent performance dossier for decentralized registry updates.

## Interface
Web dashboard showing agent compliance metrics, warning statuses, and calculated penalty deductions.

## Data
Generate simplified synthetic payload records containing mock agent delivery metrics and simulated Beckn final-mile callback logs.
Starter examples below are synthetic. They are not downloaded records.

## Source
[Beckn protocol specifications](https://raw.githubusercontent.com/beckn/protocol-specifications/master/README.md)
Uses Beckn protocol specifications covering final-mile delivery and asynchronous callback performance.

## Tools
pydantic-ai, fastapi, pandas.
Pydantic AI strictly parses the fulfillment schema while pandas handles batch SLA penalty calculations across mock delivery metrics.
Local or hosted LLM capable of evaluating edge case delivery exceptions against standard SLA policies.

## 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
- Calculates SLA compliance rate correctly as (on_time_deliveries / deliveries_assigned) * 100.
- Applies a base penalty deduction of 100 if compliance rate falls below 90 percent.
- Adds an additional penalty of 25 for every damaged parcel reported in the payload.

## Starter Examples
```json
[
  {
    "input": {
      "agent_id": "AGENT-404",
      "deliveries_assigned": 50,
      "on_time_deliveries": 42,
      "damaged_parcels": 2
    },
    "expected_output": {
      "sla_compliance_rate": 84,
      "penalty_applied": true,
      "deduction_amount": 150,
      "status": "WARNING_ISSUED"
    }
  },
  {
    "input": {
      "agent_id": "AGENT-505",
      "deliveries_assigned": 30,
      "on_time_deliveries": 30,
      "damaged_parcels": 0
    },
    "expected_output": {
      "sla_compliance_rate": 100,
      "penalty_applied": false,
      "deduction_amount": 0,
      "status": "COMPLIANT"
    }
  }
]
```

## Safety
Uses mock agent IDs; processes no real delivery data, live financial deductions, or personally identifiable information.
Use mock external writes. Require human review before any real deployment.