JHW

/WORK · Selected project ·

AI-Powered
Optimiser Scheduler

Streamlit · Hugging Face · Optimisation

Animated demo of the optimiser scheduler producing routes on a map.

Live demo

If the Space is sleeping, give it a moment to wake up — or open it in a new tab ↗.

Effective last‑mile delivery planning is a balance of operational constraints and geography. This project turns that challenge into a focused, reproducible application: a Streamlit interface backed by Google OR‑Tools for route optimization, with road‑network travel times sourced from APIs (Google Maps Directions/Distance Matrix or OSRM) and results visualized on an interactive map.

Problem Statement

Last‑mile operations rarely match the simplicity of a whiteboard sketch. Vehicles differ in capacity and shift hours, customers require deliveries within specific time windows, and travel times vary by time of day and route conditions. Manual planning, static routes, or lightweight heuristics do not scale with growing demand or volatility. The result is missed windows, excess mileage, and operational strain.

This project addresses that gap with a constrained, data‑driven planner that respects time windows, capacity, depots, and traffic patterns—producing plans that are both defensible and easy to review.

Value Proposition

Route Optimization

Map Visualization

Calendar View

Interactive Dashboard

Architecture Overview

                        ┌─────────────────────┐
                        │  User Frontend (UI) │
                        │   Streamlit (Python)│
                        └────────┬────────────┘
                                 │
                ┌────────────────────────────────┐
                │  App Logic & Optimizer Service │
                │  (OR-Tools, Validation, I/O)   │
                └────────────────────────────────┘
                                 │
         ┌───────────────────────┼──────────────────────────┐
         │                       │                          │
 ┌────────────────┐     ┌──────────────────────┐    ┌───────────────────────┐
 │ Data Ingestion │     │  Routing APIs        │    │  Map Renderer         │
 │ (CSV: orders,  │────▶│  Google Directions & │    │  Folium/Leaflet       │
 │ vehicles,      │     │  Distance Matrix,    │    │  (interactive map,    │
 │ time-matrices) │     │  or OSRM             │    │  overlays & popups)   │
 └────────────────┘     └──────────────────────┘    └───────────────────────┘
                                 │
                       ┌─────────▼─────────┐
                       │  Route Planner &  │
                       │  Export (CSV/JSON)│
                       └────────────────────┘

Features and Pages

Map Page

Interactive map showing routes, depots, and delivery clusters

Interactive map showing routes, depots, and delivery clusters

The map provides a clear, geographic view of your operation. Delivery locations and depot positions are drawn on an interactive base map, with filters in the sidebar to tailor the display to specific dates, vehicles, or status. At a glance, you can see how stops cluster, how routes traverse the network, and where potential bottlenecks may form. Key summary metrics (number of deliveries, assigned vs. unassigned, and late/on‑time breakdowns) accompany the map so you can correlate what you see with operational reality.

Interactive map showing routes, depots, and delivery clusters

Real‑time operational view: routes by color, stop markers with popups, and depot locations.

When routes are generated, the map highlights each vehicle’s path with distinct colors and markers. Popups reveal stop details—ETA, time window, priority, and demand—so you can review the sequence on the ground. A delivery schedule calendar complements the map by showing time spans across the day for each delivery, making it easy to spot overlaps, slack, and potential conflicts.

Optimizer Page: Step‑by‑Step Guide

The optimizer assigns deliveries to vehicles to build efficient, feasible routes. Use the sidebar to set parameters, generate plans, review results, and iterate.

  1. Set optimization parameters (sidebar)
    • Select Delivery Dates: Choose the dates to include; select “All” to include all.
    • Priority Importance: Higher values give more weight to high‑priority deliveries.
    • Time Window Importance: Higher values enforce stricter adherence to delivery windows.
    • Load Balancing vs. Distance: Higher values distribute deliveries more evenly across vehicles (less focus on pure distance minimization).
    • Maximum Vehicles: Limit the number of vehicles available to the solver.
    • Minimum Time Window Compliance: Set the minimum percentage of deliveries that must meet their time windows.
  2. Generate routes
    • Review current delivery statistics and vehicle availability.
    • Click “Generate Optimal Routes” to run the solver.
    • The algorithm assigns deliveries to vehicles based on your parameters and travel‑time source.
  3. Review results
    • Overall Performance: Assigned deliveries, vehicles used, time‑window compliance.
    • Time & Distance Distribution: See how workload is spread across vehicles.
    • Route Map: An interactive map per date; hover for details, filter by day.
    • Calendar View: Delivery schedules by date. Legend: green = on‑time, orange = late, red = unassigned.
    Optimization results overview with KPIs and charts

    Fast optimization with clear KPIs, route metrics, and distribution summaries.

  4. Adjust and refine
    • Not enough vehicles? Increase the maximum vehicles allowed.
    • Time windows not met? Decrease the time‑window importance or the minimum compliance target.
    • High‑priority deliveries not assigned? Increase priority importance.
    • Routes too unbalanced? Increase the load‑balancing parameter.

The route computation integrates road‑network travel times from Google Maps Directions/Distance Matrix or OSRM. The solver sequences stops to respect time windows, priorities, service times, and capacity limits while minimizing total travel time/distance.

Routing with API‑derived travel times and optimal stop sequencing

Under the hood: API‑derived ETAs drive a VRP‑TW solver to compute the best sequence and duration.

Calendar schedule visualization by vehicle and date

Calendar view: visualize and tune by duration, distance, and package importance to balance operations.

Tip: Always click “Generate Optimal Routes” after changing parameters to apply updates.

Data, Briefly

Inputs are simple CSVs. Deliveries include IDs, coordinates or addresses, demand (weight/volume), and time windows. Vehicles include capacities, depot locations, and shift hours. Optional time‑of‑day matrices reflect traffic patterns for morning, midday, evening, and night. A locations index keeps coordinates aligned across matrices and outputs.

Optimization Approach

Below is a compact formulation that captures the core elements used by the solver and the optimizer’s tunable preferences.

Sets

N = {1, …, n} customers, depot indexed as 0.
K = {1, …, m} vehicles.

Parameters

qi: demand at customer i; Qk: capacity of vehicle k.
[ai, bi]: time window at customer i; si: service time at i.
cij: travel distance (or cost) from i to j.
tij: travel time from i to j (from Google/OSRM or matrices).
wi: priority weight for customer i (higher = more important).
M: a large constant for time‑window constraints.
Vmax: maximum vehicles allowed by the user.
α, β, γ, λ ≥ 0: user‑tunable weights for distance, lateness, load balancing, and unassigned penalties.

Decision Variables

xijk ∈ {0, 1}: 1 if vehicle k travels from i to j, else 0.
Tik ≥ 0: arrival time of vehicle k at node i.
Lik ≥ 0: load on vehicle k upon arrival at node i.
ui ∈ {0, 1}: 1 if customer i is served by any vehicle, else 0.
zk ∈ {0, 1}: 1 if vehicle k is used, else 0.
ℓi ≥ 0: lateness at customer i.
Wk ≥ 0: working time proxy for vehicle k (optional balance term).

Objective (multi‑term, user‑weighted)

min  α ∑k∈K ∑i∈N0 ∑j∈N0 cij xijk  +  β ∑i∈N wi ℓi
    +  γ ∑k∈K (Wk − W̄)2  +  λ ∑i∈N wi (1 − ui)

where N0 = N ∪ {0} and W̄ is the mean of Wk across vehicles (the balance term may be approximated or omitted in a purely linear model).

Objective intuition and UI links

Distance/travel cost: α · ∑k∈K ∑i∈N0 ∑j∈N0 cij xijk

  • What it does: Rewards shorter routes (less distance/time).
  • Turn it up when you want the solver to strongly prefer compact routes and fewer detours.

Lateness penalty: β · ∑i∈N wi ℓi

  • What it does: Punishes arriving after a stop’s time window; wi makes high‑priority stops “hurt” more when late.
  • Turn it up to push schedules to stay within windows, especially for important customers.
  • UI link: Time Window Importance (and Priority Importance via wi).

Workload balance: γ · ∑k∈K (Wk − W̄)2

  • What it does: Evens out work across vehicles. Wk is a vehicle’s total work (e.g., route time/distance); W̄ is the average across vehicles.
  • Turn it up to avoid one “hero” truck doing most of the work, even if it adds some distance.
  • UI link: Load Balancing vs Distance (trade‑off vs α).

Unserved penalty: λ · ∑i∈N wi · (1 − ui)

  • What it does: Penalizes dropping deliveries; wi makes skipping high‑priority stops very expensive.
  • Turn it up to force serving more (or all) stops, accepting extra distance or more vehicles if feasible.
  • UI link: Priority Importance (via wi). Complements Minimum Time Window Compliance.

Vehicle limit

∑k zk ≤ Vmax. Lower caps force consolidation; higher caps give slack to meet windows and reduce lateness.

∑k∈K zk ≤ Vmax

Working time proxy (optional, for balance term)

Encourages similar total work per vehicle. Driven by Load Balancing vs Distance.

Wk ≥ ∑i∈N0 ∑j∈N0 tij xijk    ∀ k ∈ K

Domains

Variable types and non‑negativity are fixed; parameters change costs and feasibility pressure, not domains.

xijk ∈ {0, 1},  ui ∈ {0, 1},  zk ∈ {0, 1},
Tik,  Lik,  ℓi,  Wk ≥ 0

Assumptions

  • Single depot; each route starts and ends at the depot.
  • Deterministic travel times for a chosen time‑of‑day profile (or API snapshot).
  • Service times are known and additive; no precedence constraints.
  • Travel cost/time obeys triangle inequality (typical for road networks).
  • Penalties reflect business preferences: distance, on‑time performance, balance, and priority.

Road‑Network Travel Times (Google Maps or OSRM)

Accurate ETAs require road‑network travel times, not straight lines. The app supports:

In practice, you can toggle between sources. For Google, configure your API key as an environment variable and select Directions/Distance Matrix for route and ETA computation. For OSRM, point to a table/route endpoint. The solver then consumes those times to produce realistic, feasible routes.

Limitations and Roadmap

This implementation uses precomputed or API‑fetched travel times but does not continuously adapt to unexpected incidents without a refresh. It assumes a single depot and simplified service times. For very large instances, time‑bounded solves may be preferable to guarantee responsiveness. Future extensions include multi‑depot support, driver breaks/skills, EV energy constraints, scenario comparison, KPI dashboards, and live re‑optimization triggered by events.

Summary

By combining an accessible Streamlit UI, OR‑Tools for optimization, and road‑aware routing data from Google Maps or OSRM, this project turns a complex planning task into a repeatable workflow. The result is an operational plan that reflects constraints and traffic reality, is easy to validate on a map, and can be deployed reliably across environments.

Repository

The complete project source is hosted on GitHub. The repository contains the Streamlit app, OR-Tools solver code, example CSVs and a README with setup & run instructions.

References

Keep in touch

Contact

Email me

Based in
Singapore