brain/docs/integration.md

# 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

```json
{
  "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

```json
{
  "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)

```bash
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)

```bash
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 |