Challenge #5
LogisticsNow
Team FairRelay
FairRelay
AI-Powered Load Consolidation Engine · Fairness-Aware Route Allocation · Multi-Agent Intelligence
The Problem
Logistics networks transport shipments with partially filled vehicles due to poor load planning. There is no AI-driven system for automatic load consolidation that intelligently groups shipments, maximizes vehicle capacity, simulates strategies, and learns continuously.
At the same time, 15M+ gig delivery workers in India face systemic dispatch bias — traditional systems assign 3x more deliveries to some drivers (Gini = 0.85) while others earn near nothing.
FairRelay solves both.
Our Solution
FairRelay is a full-stack AI logistics platform with two core engines:
Engine What It Does Agents Load Consolidation Engine Groups shipments by geography + time windows, bin-packs into trucks using OR-Tools CP-SAT solver, scores confidence, and learns via Q-Learning 5 agents Fair Dispatch Engine Allocates routes to drivers using fairness-aware AI with Gini coefficient optimization, wellness tracking, EV-aware routing, and LLM explanations 8+ agents
Both engines are orchestrated via LangGraph multi-agent workflows, exposed as single API endpoints, and come with live visualization dashboards.
Hackathon Deliverables Mapping
Expected Deliverable Our Implementation Consolidation Engine Prototype 5-agent LangGraph pipeline — KMeans geo-clustering + OR-Tools CP-SAT bin-packing Visualization Dashboard Interactive dark-themed dashboard with Leaflet maps, Chart.js analytics, agent pipeline viz, heatmaps Performance Simulation Multi-scenario simulator comparing Tight/Balanced/Aggressive strategies with full KPI comparison Continuous Optimization Tabular Q-Learning agent with file-based experience store, reward function, and policy recommendation
5-Agent Consolidation Pipeline
POST /api/v1/consolidate → One API call. Five agents. Optimized loads.
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ AGENT 1 │ │ AGENT 2 │ │ AGENT 3 │
│ Geo-Clustering │───>│ Time-Window │───>│ Capacity │
│ (KMeans + │ │ Filtering │ │ Optimization │
│ Silhouette) │ │ (Overlap check) │ │ (OR-Tools SAT) │
└──────────────────┘ └──────────────────┘ └──────────────────┘
│
▼
┌──────────────────┐ ┌──────────────────┐
│ AGENT 5 │ │ AGENT 4 │
│ Continuous │<───│ Scoring & │
│ Learning │ │ Confidence │
│ (Q-Learning) │ │ (Composite AI) │
└──────────────────┘ └──────────────────┘
Agent Breakdown
# Agent Algorithm What It Does 1 Geo-Clustering scikit-learn KMeans + Silhouette scoring Groups shipments by pickup/drop proximity. Auto-selects optimal K (2–10). Splits oversized clusters via greedy radius fallback. 2 Time-Window Interval overlap analysis Filters clusters by delivery time compatibility. Configurable tolerance (default 120 min). Splits time-incompatible shipments into separate groups. 3 Capacity Optimization Google OR-Tools CP-SAT Integer Programming Bin-packs shipments into trucks respecting weight + volume. Minimizes trucks used. Falls back to First-Fit-Decreasing heuristic if solver unavailable. 3-second solver timeout. 4 Scoring & Confidence Weighted composite scoring Per-group confidence = capFit×0.4 + geoScore×0.35 + timeScore×0.25. Global optimization score factors in utilization, trip reduction, and improvement gain. Computes all KPIs vs naive baseline. 5 Continuous Learning Tabular Q-Learning (RL) Stores experience in data/rl_experience.json (max 500 episodes). Reward = f(utilization, trips, carbon, score). Updates Q-table to recommend optimal (radius, tolerance) parameters. Detects policy convergence/degradation trends.
Consolidation KPIs Produced
KPI Description Vehicle Utilization (Before/After) Percentage improvement from naive to consolidated Trips Reduced Absolute count + percentage of eliminated trips Distance Saved (km) Haversine-calculated route distance reduction CO2 Saved (kg) distanceSaved × 0.21 kg/kmCarbon Credit Value (USD) carbonSaved / 1000 × $25/tonFuel Saved (INR) distanceSaved × Rs.22.5/kmCost Reduction (%) Direct cost savings from trip elimination Optimization Score (0–100) Weighted composite with letter grade (A+/A/B/C/D) Avg AI Confidence (0–100) Mean per-group confidence across all bins
Scenario Simulation
POST /api/v1/consolidate/simulate
Run multiple consolidation strategies in parallel and get the best recommendation:
Scenario Radius Time Tolerance Use Case Tight Clustering 15 km 60 min Dense urban, strict deadlines Balanced 30 km 120 min General purpose Aggressive Merge 60 km 240 min Inter-city, flexible windows
The system runs all scenarios, compares optimization scores, and recommends the best strategy.
Fair Dispatch Pipeline
POST /api/v1/allocate/langgraph → Fairness-aware route allocation
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Initialize │ → │ Clustering │ → │ ML Effort │
│ Node │ │ Agent (KMeans) │ │ Agent (XGBoost)│
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ EV Recovery │ ← │ Fairness │ ← │ Route Planner │
│ Node │ │ Manager │ │ (Hungarian) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
▼ ▼ (if Gini > 0.25)
┌─────────────────┐ ┌─────────────────┐
│ Driver Liaison │ │ Reoptimize │
│ Agent │ │ Loop │
└─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Learning │ → │ LLM Explain │ → │ Finalize │
│ Agent │ │ (Gemini) │ │ Node │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Agent Purpose Key Algorithm Initialize Node Validates inputs, sets up allocation state Schema validation Clustering Agent Groups packages by geography K-Means ML Effort Agent Scores driver-route effort pairs XGBoost Route Planner Solves optimal driver-route assignment Hungarian Algorithm Fairness Manager Evaluates workload inequality Gini Index (threshold: 0.25) EV Recovery Node Handles electric vehicle battery constraints Charging station insertion Driver Liaison Processes driver negotiations/appeals Rule-based + AI Learning Agent Improves future allocations from feedback Feedback loop LLM Explain Node Generates natural language explanations Google Gemini
Fairness Algorithms
Workload Score:
workload = a × num_packages + b × total_weight_kg + c × route_difficulty + d × estimated_time
Gini Index (0 = perfect equality, 1 = maximum inequality):
G = (2 × Σ(i × x_i)) / (n × Σx_i) − (n + 1) / n
Individual Fairness Score:
fairness_score = 1 − |workload − avg_workload| / max(avg_workload, 1)
Key Result: Gini reduced from 0.85 → 0.12 (Grade A fairness)
Architecture
┌──────────────────────────────────────────────────────────────────────┐
│ FAIRRELAY PLATFORM │
├──────────────┬──────────────┬──────────────┬────────────────────────┤
│ Landing │ AI Supply │ Flutter │ Streamlit │
│ Page │ Chain │ Mobile │ Women │
│ (React) │ Dashboard │ App │ Empowerment Hub │
│ Vercel │ (React) │ (Android) │ (Python) │
│ │ Vercel │ │ │
├──────────────┴──────┬───────┴──────────────┴────────────────────────┤
│ │ │
│ Backend-DM (Node.js/Express) │
│ JWT Auth · Prisma ORM · Socket.IO │
│ Driver Relay · Absorption Handshake · e-Way Bills │
│ Render │
│ │ │
│ │ BRAIN_URL proxy │
│ ▼ │
│ Brain (Python/FastAPI) │
│ LangGraph Multi-Agent Orchestration │
│ 5-Agent Consolidation + 8-Agent Fair Dispatch │
│ OR-Tools · XGBoost · KMeans · Q-Learning · Gemini │
│ Render │
│ │ │
│ PostgreSQL (Neon) │
└─────────────────────────────────────────────────────────────────────┘
Tech Stack
Layer Technology AI Engine (Brain) Python 3.11, FastAPI, LangGraph, scikit-learn, XGBoost, Google OR-Tools CP-SAT, Gemini API Operations Backend Node.js, Express 5, Prisma ORM, PostgreSQL, Socket.IO, Puppeteer, JWT/RBAC Dashboard React 19, TypeScript, Vite, Redux Toolkit, TailwindCSS, Leaflet, Recharts Mobile Flutter, Dart, Google Maps, Provider, Dio Landing Page React, TypeScript, Vite Visualization Leaflet maps, Chart.js, custom agent pipeline UI, heatmaps Database PostgreSQL 14+ (Neon serverless), SQLAlchemy async Deployment Render (backends), Vercel (frontends), Gunicorn
Dashboards & Visualization
Load Consolidation Dashboard (/demo/consolidation)
5-Agent Pipeline Visualization — Each agent lights up in sequence with execution time and output metrics
AI Optimization Score Ring — Doughnut chart with letter grade (A+/A/B/C/D)
8 KPI Cards — Utilization, trips reduced, distance saved, CO2, fuel savings, confidence, groups, cost reduction
Interactive Route Map — Three views: Optimized (color-coded), Before (naive gray), Compare (overlay)
Consolidated Groups Table — Truck assignment, weight/volume utilization bars, AI confidence badges
Analytics Charts — Utilization before vs after, Group confidence radar, Weight distribution doughnut
Shipment Compatibility Heatmap — N x N pairwise compatibility matrix (geo + time)
Scenario Comparison Panel — Side-by-side results for Tight/Balanced/Aggressive with recommendation badge
AI Learning Insights — Pattern detection, corridor identification, Q-Learning convergence status
Agent Decision Logs — Terminal-style log viewer for full pipeline transparency
Fair Dispatch Visualization (/demo/visualization)
8-Agent Pipeline Visualization — Real-time agent status with animated transitions
Live Map — Route visualization on Leaflet with driver assignments
Fairness Metrics — Gini index, individual scores, equity analysis
Agent Activity Feed — Decision logs from every agent in the pipeline
Operations Dashboard (React)
Real-time Driver Tracking — Live map with Socket.IO updates
Dispatch Management — Assign missions, view driver profiles, experience-based routing
Absorption Handshake — Peer-to-peer goods exchange with QR codes
e-Way Bill Generation — Professional government-format PDFs via Puppeteer
Analytics — Fleet KPIs, delivery stats, driver performance
Key Features
AI Load Consolidation
Intelligent Shipment Grouping — KMeans geo-clustering with silhouette optimization + time window filtering
Capacity Optimization — OR-Tools CP-SAT integer programming to minimize trucks, maximize utilization
Scenario Simulation — Multi-strategy comparison with automated recommendation
Continuous Optimization — Q-Learning RL agent that improves radius/tolerance parameters over time
Shipment Compatibility Analysis — Pairwise heatmap scoring (60% geo + 40% time)
Fairness-Aware Dispatch
Gini Coefficient Optimization — Measurably fair workload distribution (Gini <= 0.15 guaranteed)
Driver Wellness Engine — Hours worked, rest tracking, illness flags, burnout prevention
Night Safety Routing — Automatic safety filtering for women drivers on night routes
EV-Aware Routing — Battery constraints and charging station integration
Explainable Decisions — 100% of allocations come with Gemini-generated natural language explanations
Operations Platform
Driver Relay System — Multi-zone handoffs at virtual hubs for long-haul optimization
Absorption Handshake — Offline-capable cryptographic QR verification for goods exchange
Dynamic e-Way Bills — Government-format PDF generation via Puppeteer, no external APIs
Real-time Tracking — Socket.IO powered live driver and delivery status updates
SDG Impact
SDG Target Our Contribution SDG 8 — Decent WorkFair income distribution Gini 0.85 → 0.12 across all drivers SDG 10 — Reduced InequalitiesEqual opportunity Wellness-aware, gender-safe dispatch SDG 13 — Climate ActionReduce emissions 14.2 kg CO2 saved per allocation run, EV-first routing
Quick Start
Prerequisites
Python 3.11+
Node.js 18+
PostgreSQL 14+ (or SQLite for development)
Git
1. Brain (AI Engine)
1 cd brain
2
3 # Create virtual environment
4 python -m venv venv
5 venv \ Scripts \ activate # Windows
6 # source venv/bin/activate # Linux/macOS
7
8 # Install dependencies
9 pip install -r requirements.txt
10
11 # Configure environment
12 cp .env.example .env
13 # Edit .env with your DATABASE_URL, GOOGLE_API_KEY etc.
14
15 # Run database migrations
16 alembic upgrade head
17
18 # Start the server
19 uvicorn app.main:app --reload --host 0.0 .0.0 --port 8000
Access Points:
2. Backend-DM (Operations Server)
1 cd ops/backend-dm
2
3 npm install
4
5 cp .env.example .env
6 # Edit .env: DATABASE_URL, JWT_SECRET, BRAIN_URL=http://localhost:8000
7
8 npx prisma generate
9 npx prisma db push
10
11 node index.js
12 # Runs on http://localhost:3000
3. AI Supply Chain Dashboard
1 cd ops/AIsupplychain/aisupply
2
3 npm install
4
5 # Create .env
6 echo "VITE_API_URL=http://localhost:3000" > .env
7
8 npm run dev
9 # Runs on http://localhost:5173
4. Landing Page
1 cd landing
2
3 npm install
4 npm run dev
5 # Runs on http://localhost:5174
API Reference
Load Consolidation
Method Endpoint Description POST/api/v1/consolidateRun 5-agent consolidation pipeline (LangGraph) POST/api/v1/consolidate/syncRun consolidation (sync fallback, no LangGraph) POST/api/v1/consolidate/simulateMulti-scenario simulation with recommendation
Consolidation Request
1 {
2 "shipments" : [
3 {
4 "id" : "SH-001" ,
5 "pickupLat" : 19.076 , "pickupLng" : 72.877 ,
6 "dropLat" : 18.520 , "dropLng" : 73.856 ,
7 "pickupLocation" : "Mumbai" , "dropLocation" : "Pune" ,
8 "weight" : 450 , "volume" : 2.1 ,
9 "timeWindowStart" : "2026-03-10T08:00:00" ,
10 "timeWindowEnd" : "2026-03-10T18:00:00" ,
11 "priority" : "HIGH"
12 }
13 ] ,
14 "trucks" : [
15 {
16 "id" : "TRK-001" ,
17 "name" : "Tata Ace Gold" ,
18 "maxWeight" : 2000 , "maxVolume" : 8.0 ,
19 "co2PerKm" : 0.21
20 }
21 ] ,
22 "options" : {
23 "maxGroupRadiusKm" : 30 ,
24 "timeWindowToleranceMinutes" : 120
25 }
26 }
Consolidation Response
1 {
2 "groups" : [
3 {
4 "groupId" : 0 ,
5 "truckId" : "TRK-001" ,
6 "truckName" : "Tata Ace Gold" ,
7 "shipmentCount" : 4 ,
8 "shipments" : [ { "id" : "SH-001" , "pickupLocation" : "Mumbai" , "dropLocation" : "Pune" , "weight" : 450 , "volume" : 2.1 } ] ,
9 "totalWeight" : 1680 , "totalVolume" : 6.8 ,
10 "utilizationWeight" : 84.0 , "utilizationVolume" : 85.0 ,
11 "confidence" : 87
12 }
13 ] ,
14 "metrics" : {
15 "utilizationBefore" : 38.2 ,
16 "utilizationAfter" : 78.5 ,
17 "utilizationImprovement" : 40.3 ,
18 "tripsReduced" : 6 ,
19 "tripReductionPercent" : 60.0 ,
20 "distanceSavedKm" : 487.3 ,
21 "carbonSavedKg" : 102.3 ,
22 "carbonCreditUSD" : 2.56 ,
23 "fuelSavedINR" : 10964.25 ,
24 "optimizationScore" : 82 ,
25 "avgConfidence" : 85
26 } ,
27 "insights" : [
28 { "type" : "pattern" , "text" : "High-density corridor: Mumbai-Pune (4 shipments)" , "impact" : "high" } ,
29 { "type" : "learning" , "text" : "Q-table updated. Reward: 76.4. Best action: radius=30km, tolerance=120min" , "impact" : "medium" }
30 ] ,
31 "agentSteps" : [
32 { "agent" : "GeoClusteringAgent" , "action" : "completed" , "method" : "kmeans" , "clusters" : 3 , "duration_ms" : 45 }
33 ]
34 }
Fair Dispatch
Method Endpoint Description POST/api/v1/allocate/langgraphRun 8-agent fair dispatch pipeline GET/api/v1/drivers/{id}Get driver details and stats GET/api/v1/routes/{id}Get route details and packages POST/api/v1/feedbackSubmit driver feedback for learning
Fair Dispatch Request
1 {
2 "date" : "2026-03-10" ,
3 "warehouse" : { "lat" : 12.9716 , "lng" : 77.5946 } ,
4 "packages" : [
5 {
6 "id" : "pkg_001" ,
7 "weight_kg" : 2.5 ,
8 "address" : "123 Main St, Bangalore" ,
9 "latitude" : 12.97 , "longitude" : 77.60 ,
10 "priority" : "NORMAL"
11 }
12 ] ,
13 "drivers" : [
14 {
15 "id" : "driver_001" ,
16 "name" : "Raju" ,
17 "vehicle_capacity_kg" : 150 ,
18 "vehicle_type" : "PETROL"
19 }
20 ]
21 }
Fair Dispatch Response
1 {
2 "status" : "SUCCESS" ,
3 "global_fairness" : {
4 "gini_index" : 0.12 ,
5 "avg_workload" : 63.2 ,
6 "std_dev" : 5.4
7 } ,
8 "assignments" : [
9 {
10 "driver_id" : "driver_001" ,
11 "fairness_score" : 0.92 ,
12 "route_summary" : { "num_packages" : 22 , "total_weight_kg" : 48.5 , "estimated_time_minutes" : 145 } ,
13 "explanation" : "Your route covers the Koramangala area with 22 packages. Expected completion: 2.5 hours."
14 }
15 ]
16 }
Operations (Backend-DM)
Method Endpoint Description GET/api/dashboard/statsDashboard KPIs GET/api/driversList all drivers POST/api/dispatch/assignAssign mission to driver POST/api/absorption/initiateInitiate goods handover POST/api/absorption/verifyVerify QR handshake GET/api/ewaybill/generate/:idGenerate e-Way Bill PDF GET/api/hubsList virtual relay hubs
Project Structure
fairrelay/
├── brain/ # AI Engine (Python/FastAPI)
│ ├── app/
│ │ ├── api/
│ │ │ ├── consolidation.py # Load consolidation endpoints
│ │ │ ├── allocation_langgraph.py # Fair dispatch endpoints
│ │ │ ├── admin.py
│ │ │ ├── drivers.py
│ │ │ └── feedback.py
│ │ ├── services/
│ │ │ ├── consolidation_engine.py # 5 consolidation agents
│ │ │ ├── consolidation_workflow.py # LangGraph consolidation flow
│ │ │ ├── langgraph_workflow.py # LangGraph dispatch flow
│ │ │ ├── langgraph_nodes.py # Dispatch agent implementations
│ │ │ ├── ml_effort_agent.py # XGBoost scoring
│ │ │ ├── fairness_manager_agent.py # Gini evaluation
│ │ │ ├── route_planner_agent.py # Hungarian algorithm
│ │ │ └── gemini_explain_node.py # LLM explanations
│ │ ├── schemas/
│ │ │ ├── consolidation.py # Consolidation Pydantic models
│ │ │ └── allocation.py # Dispatch Pydantic models
│ │ ├── models/ # SQLAlchemy ORM models
│ │ ├── config.py
│ │ ├── database.py
│ │ └── main.py
│ ├── frontend/
│ │ ├── consolidation.html # Consolidation dashboard
│ │ ├── visualization.html # Agent visualization
│ │ └── demo.html # API demo page
│ ├── data/
│ │ └── rl_experience.json # Q-Learning experience store
│ ├── alembic/ # Database migrations
│ ├── requirements.txt
│ ├── Dockerfile
│ ├── gunicorn.conf.py
│ └── render.yaml
│
├── ops/ # Operations Platform
│ ├── backend-dm/ # Node.js backend
│ │ ├── controllers/
│ │ │ ├── routeController.js # Relay logic & assignment
│ │ │ ├── ewayBillController.js # PDF generation
│ │ │ └── dispatchController.js # Brain proxy
│ │ ├── services/
│ │ │ ├── dispatch.js # Brain API integration
│ │ │ ├── puppeteer.service.js # PDF rendering
│ │ │ └── qr.service.js # QR code generation
│ │ ├── prisma/schema.prisma
│ │ ├── render.yaml
│ │ └── index.js
│ │
│ ├── AIsupplychain/aisupply/ # React Dashboard (Vite)
│ │ ├── src/
│ │ │ ├── pages/ # Dashboard, Drivers, Routes, Bills, Tracking
│ │ │ ├── store/ # Redux slices
│ │ │ └── components/
│ │ └── vercel.json
│ │
│ └── logistic_flutter/
│ ├── orchastra_ps4/ecology/ # Flutter Mobile App
│ └── streamlit/ # Women Empowerment Hub
│
└── landing/ # Marketing Website (React/Vite)
├── src/components/
│ ├── Hero.tsx # Problem statement + stats
│ ├── Features.tsx # 6 feature cards
│ ├── LiveDemo.tsx # Interactive allocation demo
│ └── HowItWorks.tsx # 3-step integration guide
└── vercel.json
Deployment
Component Platform URL Pattern Brain (AI Engine) Render brain-api.onrender.comBackend-DM Render backend-dm.onrender.comDashboard Vercel dashboard.fairrelay.ioLanding Page Vercel fairrelay.io
Both backend services include render.yaml for one-click Render deployment. Frontend apps include vercel.json with API rewrites configured.
Performance Results
Metric Before After Improvement Vehicle Utilization ~38% ~78% +40 percentage points Trips Required 10 4 60% reduction Distance Traveled 2,847 km 1,523 km 46% less CO2 Emissions — -102 kg saved Carbon negative Fuel Cost — -Rs. 10,964 saved Per consolidation run Workload Gini Index 0.85 0.12 Grade A fairness Decision Explainability 0% 100% Full transparency
Fair routes. Optimized loads. Explainable by default.
Built for
LogisticsNow Hackathon 2026 · Challenge #5: AI Load Consolidation
Generated by ML Intern
This model repository was generated by
ML Intern , an agent for machine learning research and development on the Hugging Face Hub.
Usage
1 from transformers import AutoModelForCausalLM , AutoTokenizer
2
3 model_id = 'MouleeswaranM/FairRelay'
4 tokenizer = AutoTokenizer . from_pretrained ( model_id )
5 model = AutoModelForCausalLM . from_pretrained ( model_id )
For non-causal architectures, replace AutoModelForCausalLM with the appropriate AutoModel class.