Build a Decentralized Kirana Order Routing and Inventory Allocation Mesh — implementation

## Build
Aggregate hyperlocal grocery stock availability across independent small neighborhood merchants using Beckn protocol schemas. Allocate incoming consumer basket line items across multiple proximate shops to minimize fulfillment delays.

## User
Hyperlocal commerce network operator

## Workflow
1. Ingest real-time stock updates from mock Kirana shop point-of-sale feeds formatted as Beckn item catalogs.
2. Parse multi-item buyer shopping carts submitted through mock Beckn buyer applications.
3. Execute split-order optimization to partition items across nearby shops with verifiable in-stock quantities.
4. Generate synchronized on_select quote packets and pickup routing plans for local couriers.

## Interface
Hyperlocal fulfillment monitor displaying consumer carts, store availability heatmaps, and route splits.

## Data
Generate synthetic Kirana store inventories across a 5km urban radius and mock buyer cart payloads.
Starter examples below are synthetic. They are not downloaded records.

## Source
[Beckn protocol specifications](https://raw.githubusercontent.com/beckn/protocol-specifications/master/README.md)
Adopts Beckn protocol ordering stage specifications (select, on_select, init, confirm) for multi-merchant split carts.

## Tools
crewai, pydantic, fastapi.
CrewAI facilitates specialized agent roles for merchant stock evaluation, route distance estimation, and quote reconciliation.
Hosted Claude or local instruction model capable of multi-agent tool execution and deterministic JSON outputs.

## 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
- Partitions multi-item basket into minimum number of merchant pickup stops.
- Generates valid Beckn on_select quote responses containing item breakdowns and tax line items.
- Handles stockouts by re-routing specific line items to secondary shops within a 2km radius.

## Starter Examples
```json
[
  {
    "input": {
      "buyer_location": {
        "lat": 12.9716,
        "lng": 77.5946
      },
      "cart": [
        {
          "item_id": "atta_10kg",
          "quantity": 1
        },
        {
          "item_id": "mustard_oil_1l",
          "quantity": 2
        }
      ],
      "nearby_stores": [
        {
          "store_id": "kirana_1",
          "distance_km": 0.8,
          "inventory": {
            "atta_10kg": 5,
            "mustard_oil_1l": 0
          }
        },
        {
          "store_id": "kirana_2",
          "distance_km": 1.2,
          "inventory": {
            "atta_10kg": 0,
            "mustard_oil_1l": 10
          }
        }
      ]
    },
    "expected_output": {
      "routing_status": "SPLIT_FULFILLMENT",
      "allocated_routes": [
        {
          "store_id": "kirana_1",
          "items": [
            {
              "item_id": "atta_10kg",
              "quantity": 1
            }
          ]
        },
        {
          "store_id": "kirana_2",
          "items": [
            {
              "item_id": "mustard_oil_1l",
              "quantity": 2
            }
          ]
        }
      ],
      "total_pickup_stops": 2,
      "unfulfilled_items": []
    }
  },
  {
    "input": {
      "buyer_location": {
        "lat": 12.9716,
        "lng": 77.5946
      },
      "cart": [
        {
          "item_id": "spices_turmeric_500g",
          "quantity": 3
        }
      ],
      "nearby_stores": [
        {
          "store_id": "kirana_3",
          "distance_km": 1.5,
          "inventory": {
            "spices_turmeric_500g": 1
          }
        }
      ]
    },
    "expected_output": {
      "routing_status": "PARTIAL_UNFULFILLED",
      "allocated_routes": [
        {
          "store_id": "kirana_3",
          "items": [
            {
              "item_id": "spices_turmeric_500g",
              "quantity": 1
            }
          ]
        }
      ],
      "total_pickup_stops": 1,
      "unfulfilled_items": [
        {
          "item_id": "spices_turmeric_500g",
          "shortage_quantity": 2
        }
      ]
    }
  }
]
```

## Safety
Demonstration environment only; no actual monetary debits, delivery dispatch, or retailer commitments occur.
Use mock external writes. Require human review before any real deployment.