Hugging Face's logo

MouleeswaranM
/
FairRelay

LiteRT
ml-intern
Model card Files
xet
 Community
35
FairRelay / brain /docs /integration.md
MouleeswaranM's picture
MouleeswaranM
Upload folder using huggingface_hub
fcf8749 verified
preview code
|
raw
history blame
7.95 kB

Fair Dispatch System API Integration Guide

This document describes how external delivery services can integrate with the Fair Dispatch System allocation API.

Overview

The Fair Dispatch System provides a single seamless API for fair route allocation. External systems send drivers and packages as JSON, and receive optimized assignments with fairness metrics.

  • Endpoint: POST /api/v1/allocate
  • Content-Type: application/json
  • Authentication: None required for demo (configure for production)

Request Schema: AllocationRequest 

{
  "allocation_date": "2026-02-10",
  "warehouse": {
    "lat": 12.9716,
    "lng": 77.5946
  },
  "drivers": [
    {
      "id": "external_driver_001",
      "name": "Raju",
      "preferred_language": "en",
      "vehicle_capacity_kg": 150
    }
  ],
  "packages": [
    {
      "id": "external_pkg_001",
      "weight_kg": 2.5,
      "fragility_level": 3,
      "address": "Some street, Area, City",
      "latitude": 12.97,
      "longitude": 77.6,
      "priority": "NORMAL"
    }
  ]
}

Field Descriptions

Field Type Required Description
allocation_date string (date) Yes Date for the allocation (YYYY-MM-DD)
warehouse.lat float Yes Warehouse latitude
warehouse.lng float Yes Warehouse longitude
drivers array Yes At least 1 driver required
drivers[].id string Yes External driver ID
drivers[].name string Yes Driver name
drivers[].vehicle_capacity_kg float No Vehicle capacity (default: 100)
drivers[].preferred_language string No Language: en, ta, hi, te, kn (default: en)
packages array Yes At least 1 package required
packages[].id string Yes External package ID
packages[].weight_kg float Yes Package weight (min: 0.01)
packages[].fragility_level int No Fragility 1-5 (default: 1)
packages[].address string Yes Delivery address
packages[].latitude float Yes Delivery latitude
packages[].longitude float Yes Delivery longitude
packages[].priority string No NORMAL, HIGH, or EXPRESS (default: NORMAL)

Response Schema: AllocationResponse 

{
  "allocation_run_id": "550e8400-e29b-41d4-a716-446655440000",
  "allocation_date": "2026-02-10",
  "global_fairness": {
    "avg_workload": 63.2,
    "std_dev": 18.4,
    "gini_index": 0.29
  },
  "assignments": [
    {
      "driver_id": "550e8400-e29b-41d4-a716-446655440001",
      "driver_external_id": "external_driver_001",
      "driver_name": "Raju",
      "route_id": "550e8400-e29b-41d4-a716-446655440002",
      "workload_score": 65.3,
      "fairness_score": 0.82,
      "route_summary": {
        "num_packages": 22,
        "total_weight_kg": 48.5,
        "num_stops": 14,
        "route_difficulty_score": 2.1,
        "estimated_time_minutes": 145
      },
      "explanation": "You received a moderate route..."
    }
  ]
}

Global Fairness Metrics

Metric Description
avg_workload Average workload score across all drivers
std_dev Standard deviation of workload (lower = fairer)
gini_index Gini coefficient 0-1 (lower = fairer distribution)

cURL Examples

Minimal Example (2 drivers, 2 packages) 

curl -X POST "http://localhost:8000/api/v1/allocate" \
  -H "Content-Type: application/json" \
  -d '{
    "allocation_date": "2026-02-10",
    "warehouse": { "lat": 12.9716, "lng": 77.5946 },
    "drivers": [
      {"id": "driver_001", "name": "Raju", "vehicle_capacity_kg": 150, "preferred_language": "en"},
      {"id": "driver_002", "name": "Priya", "vehicle_capacity_kg": 120, "preferred_language": "ta"}
    ],
    "packages": [
      {"id": "pkg_001", "weight_kg": 2.5, "fragility_level": 3, "address": "4A Ruby Apartment", "latitude": 12.97, "longitude": 77.60, "priority": "NORMAL"},
      {"id": "pkg_002", "weight_kg": 8.0, "fragility_level": 2, "address": "No. 12 Oak Street", "latitude": 12.98, "longitude": 77.61, "priority": "HIGH"}
    ]
  }'

Full Example (5 drivers, 10 packages) 

curl -X POST "http://localhost:8000/api/v1/allocate" \
  -H "Content-Type: application/json" \
  -d '{
    "allocation_date": "2026-02-10",
    "warehouse": { "lat": 12.9716, "lng": 77.5946 },
    "drivers": [
      {"id": "drv_001", "name": "Raju", "vehicle_capacity_kg": 150, "preferred_language": "en"},
      {"id": "drv_002", "name": "Priya", "vehicle_capacity_kg": 120, "preferred_language": "ta"},
      {"id": "drv_003", "name": "Kumar", "vehicle_capacity_kg": 180, "preferred_language": "en"},
      {"id": "drv_004", "name": "Lakshmi", "vehicle_capacity_kg": 100, "preferred_language": "hi"},
      {"id": "drv_005", "name": "Arjun", "vehicle_capacity_kg": 160, "preferred_language": "te"}
    ],
    "packages": [
      {"id": "pkg_001", "weight_kg": 2.5, "fragility_level": 3, "address": "Koramangala 3rd Main", "latitude": 12.9352, "longitude": 77.6245, "priority": "NORMAL"},
      {"id": "pkg_002", "weight_kg": 8.0, "fragility_level": 2, "address": "Indiranagar 2nd Cross", "latitude": 12.9716, "longitude": 77.6411, "priority": "HIGH"},
      {"id": "pkg_003", "weight_kg": 1.5, "fragility_level": 1, "address": "Brigade Road", "latitude": 12.9719, "longitude": 77.6074, "priority": "NORMAL"},
      {"id": "pkg_004", "weight_kg": 5.0, "fragility_level": 4, "address": "MG Road", "latitude": 12.9756, "longitude": 77.6066, "priority": "EXPRESS"},
      {"id": "pkg_005", "weight_kg": 3.2, "fragility_level": 2, "address": "Residency Road", "latitude": 12.9682, "longitude": 77.5973, "priority": "NORMAL"},
      {"id": "pkg_006", "weight_kg": 6.8, "fragility_level": 3, "address": "Commercial Street", "latitude": 12.9833, "longitude": 77.6072, "priority": "HIGH"},
      {"id": "pkg_007", "weight_kg": 2.1, "fragility_level": 1, "address": "Cunningham Road", "latitude": 12.9927, "longitude": 77.5855, "priority": "NORMAL"},
      {"id": "pkg_008", "weight_kg": 4.5, "fragility_level": 5, "address": "Lavelle Road", "latitude": 12.9644, "longitude": 77.5957, "priority": "EXPRESS"},
      {"id": "pkg_009", "weight_kg": 7.2, "fragility_level": 2, "address": "Vittal Mallya Road", "latitude": 12.9738, "longitude": 77.5956, "priority": "NORMAL"},
      {"id": "pkg_010", "weight_kg": 1.8, "fragility_level": 1, "address": "Infantry Road", "latitude": 12.9864, "longitude": 77.5961, "priority": "HIGH"}
    ]
  }'

Demo Page

A visual demo page is available at:

http://localhost:8000/demo/allocate

Features:

  • JSON input editor with pre-filled example
  • One-click allocation execution
  • Real-time metrics display (Gini, StdDev, Avg Workload)
  • Response JSON viewer
  • Copy-paste cURL examples

Notes for External Integrators

  1. Driver IDs: Use your own external IDs. The system tracks them via driver_external_id in responses.

  2. Package IDs: Similarly, package IDs map to your system.

  3. Learning Agent: The system internally uses historical data from previous allocations to improve fairness. This is DB-backed and doesn't require extra input fields.

  4. Idempotency: Each allocation creates a new allocation_run_id. Re-running with the same data creates a new run.

  5. Error Handling: On validation errors, you'll receive HTTP 400 with a detail field explaining the issue.

API Endpoints Reference

Method Endpoint Description
POST /api/v1/allocate Main allocation endpoint
POST /api/v1/allocate/langgraph LangGraph-based allocation (same interface)
GET /api/v1/drivers/{id} Get driver details
GET /api/v1/routes/{id} Get route details
POST /api/v1/feedback Submit driver feedback
GET /demo/allocate Visual demo page
GET /health Health check