FairRelay

AI-Powered Load Consolidation Engine · Fairness-Aware Route Allocation · Multi-Agent Intelligence

Problem • Solution • Consolidation Pipeline • Fair Dispatch • Architecture • Dashboards • Quick Start • API Reference

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/km`
Carbon Credit Value (USD)	`carbonSaved / 1000 × $25/ton`
Fuel Saved (INR)	`distanceSaved × Rs.22.5/km`
Cost 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 Work	Fair income distribution	Gini 0.85 → 0.12 across all drivers
SDG 10 — Reduced Inequalities	Equal opportunity	Wellness-aware, gender-safe dispatch
SDG 13 — Climate Action	Reduce 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)

cd brain

# Create virtual environment
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Linux/macOS

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your DATABASE_URL, GOOGLE_API_KEY etc.

# Run database migrations
alembic upgrade head

# Start the server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Access Points:

Page	URL
API Docs (Swagger)	http://localhost:8000/docs
ReDoc	http://localhost:8000/redoc
Consolidation Dashboard	http://localhost:8000/demo/consolidation
Fair Dispatch Demo	http://localhost:8000/demo/allocate
Agent Visualization	http://localhost:8000/demo/visualization

2. Backend-DM (Operations Server)

cd ops/backend-dm

npm install

cp .env.example .env
# Edit .env: DATABASE_URL, JWT_SECRET, BRAIN_URL=http://localhost:8000

npx prisma generate
npx prisma db push

node index.js
# Runs on http://localhost:3000

3. AI Supply Chain Dashboard

cd ops/AIsupplychain/aisupply

npm install

# Create .env
echo "VITE_API_URL=http://localhost:3000" > .env

npm run dev
# Runs on http://localhost:5173

4. Landing Page

cd landing

npm install
npm run dev
# Runs on http://localhost:5174

API Reference

Load Consolidation

Method	Endpoint	Description
`POST`	`/api/v1/consolidate`	Run 5-agent consolidation pipeline (LangGraph)
`POST`	`/api/v1/consolidate/sync`	Run consolidation (sync fallback, no LangGraph)
`POST`	`/api/v1/consolidate/simulate`	Multi-scenario simulation with recommendation

Consolidation Request

{
  "shipments": [
    {
      "id": "SH-001",
      "pickupLat": 19.076, "pickupLng": 72.877,
      "dropLat": 18.520, "dropLng": 73.856,
      "pickupLocation": "Mumbai", "dropLocation": "Pune",
      "weight": 450, "volume": 2.1,
      "timeWindowStart": "2026-03-10T08:00:00",
      "timeWindowEnd": "2026-03-10T18:00:00",
      "priority": "HIGH"
    }
  ],
  "trucks": [
    {
      "id": "TRK-001",
      "name": "Tata Ace Gold",
      "maxWeight": 2000, "maxVolume": 8.0,
      "co2PerKm": 0.21
    }
  ],
  "options": {
    "maxGroupRadiusKm": 30,
    "timeWindowToleranceMinutes": 120
  }
}

Consolidation Response

{
  "groups": [
    {
      "groupId": 0,
      "truckId": "TRK-001",
      "truckName": "Tata Ace Gold",
      "shipmentCount": 4,
      "shipments": [{ "id": "SH-001", "pickupLocation": "Mumbai", "dropLocation": "Pune", "weight": 450, "volume": 2.1 }],
      "totalWeight": 1680, "totalVolume": 6.8,
      "utilizationWeight": 84.0, "utilizationVolume": 85.0,
      "confidence": 87
    }
  ],
  "metrics": {
    "utilizationBefore": 38.2,
    "utilizationAfter": 78.5,
    "utilizationImprovement": 40.3,
    "tripsReduced": 6,
    "tripReductionPercent": 60.0,
    "distanceSavedKm": 487.3,
    "carbonSavedKg": 102.3,
    "carbonCreditUSD": 2.56,
    "fuelSavedINR": 10964.25,
    "optimizationScore": 82,
    "avgConfidence": 85
  },
  "insights": [
    { "type": "pattern", "text": "High-density corridor: Mumbai-Pune (4 shipments)", "impact": "high" },
    { "type": "learning", "text": "Q-table updated. Reward: 76.4. Best action: radius=30km, tolerance=120min", "impact": "medium" }
  ],
  "agentSteps": [
    { "agent": "GeoClusteringAgent", "action": "completed", "method": "kmeans", "clusters": 3, "duration_ms": 45 }
  ]
}

Fair Dispatch

Method	Endpoint	Description
`POST`	`/api/v1/allocate/langgraph`	Run 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/feedback`	Submit driver feedback for learning

Fair Dispatch Request

{
  "date": "2026-03-10",
  "warehouse": { "lat": 12.9716, "lng": 77.5946 },
  "packages": [
    {
      "id": "pkg_001",
      "weight_kg": 2.5,
      "address": "123 Main St, Bangalore",
      "latitude": 12.97, "longitude": 77.60,
      "priority": "NORMAL"
    }
  ],
  "drivers": [
    {
      "id": "driver_001",
      "name": "Raju",
      "vehicle_capacity_kg": 150,
      "vehicle_type": "PETROL"
    }
  ]
}

Fair Dispatch Response

{
  "status": "SUCCESS",
  "global_fairness": {
    "gini_index": 0.12,
    "avg_workload": 63.2,
    "std_dev": 5.4
  },
  "assignments": [
    {
      "driver_id": "driver_001",
      "fairness_score": 0.92,
      "route_summary": { "num_packages": 22, "total_weight_kg": 48.5, "estimated_time_minutes": 145 },
      "explanation": "Your route covers the Koramangala area with 22 packages. Expected completion: 2.5 hours."
    }
  ]
}

Operations (Backend-DM)

Method	Endpoint	Description
`GET`	`/api/dashboard/stats`	Dashboard KPIs
`GET`	`/api/drivers`	List all drivers
`POST`	`/api/dispatch/assign`	Assign mission to driver
`POST`	`/api/absorption/initiate`	Initiate goods handover
`POST`	`/api/absorption/verify`	Verify QR handshake
`GET`	`/api/ewaybill/generate/:id`	Generate e-Way Bill PDF
`GET`	`/api/hubs`	List 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.com`
Backend-DM	Render	`backend-dm.onrender.com`
Dashboard	Vercel	`dashboard.fairrelay.io`
Landing 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.

Try ML Intern: https://smolagents-ml-intern.hf.space
Source code: https://github.com/huggingface/ml-intern

Usage

from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = 'MouleeswaranM/FairRelay'
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id)

For non-causal architectures, replace AutoModelForCausalLM with the appropriate AutoModel class.

Downloads last month: 44

Inference Providers NEW

This model isn't deployed by any Inference Provider. 🙋 Ask for provider support