Initial Tiny Dispatch Coach demo

README.md

@@ -1,13 +1,36 @@
 ---
 title: Tiny Dispatch Coach
-emoji: 🚀
+emoji: 🚚
 colorFrom: green
-colorTo: pink
+colorTo: yellow
 sdk: gradio
-sdk_version: 6.15.2
-python_version: '3.13'
+sdk_version: 6.14.0
 app_file: app.py
 pinned: false
+license: mit
+short_description: Small-model route coach
+tags:
+  - gradio
+  - hackathon
+  - small-models
+  - operations-research
+  - logistics
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Tiny Dispatch Coach
+
+Tiny Dispatch Coach is a Backyard AI project for small delivery teams.
+
+It converts a daily order sheet and messy dispatcher notes into:
+
+- structured delivery constraints,
+- route plans with time-window and capacity checks,
+- before/after metrics against a manual baseline,
+- driver-ready route cards,
+- a simple visual route map.
+
+The app is designed for the Build Small Hackathon rule set: Gradio, Hugging Face
+Spaces, and models under 32B parameters. The first public version ships with a
+deterministic offline planner so the demo is usable without cloud APIs. During
+the hack window, the natural-language constraint parser can be swapped to a
+local small model backend such as MiniCPM or Llama via llama.cpp.

app.py

@@ -0,0 +1,573 @@
+import csv
+import io
+import math
+import re
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Tuple
+
+import gradio as gr
+import pandas as pd
+
+
+DEPOT = {
+    "customer": "Depot",
+    "lat": 40.7280,
+    "lng": -73.9980,
+}
+
+SAMPLE_PATH = Path(__file__).with_name("sample_orders.csv")
+AVG_SPEED_KMPH = 22.0
+CAPACITY = 18
+START_MINUTE = 8 * 60
+
+
+@dataclass(frozen=True)
+class Stop:
+    order_id: str
+    customer: str
+    lat: float
+    lng: float
+    demand: int
+    service_min: int
+    ready_time: int
+    due_time: int
+    priority: str
+    notes: str
+    manual_sequence: int
+
+
+@dataclass(frozen=True)
+class PlanStop:
+    stop: Stop
+    arrival: int
+    start: int
+    depart: int
+    distance_km: float
+    late_min: int
+    wait_min: int
+
+
+def time_to_min(value: str) -> int:
+    value = str(value or "").strip()
+    if not value:
+        return 17 * 60
+    match = re.match(r"^(\d{1,2}):(\d{2})$", value)
+    if not match:
+        return 17 * 60
+    hour, minute = int(match.group(1)), int(match.group(2))
+    return max(0, min(23 * 60 + 59, hour * 60 + minute))
+
+
+def min_to_time(value: int) -> str:
+    value = max(0, int(round(value)))
+    return f"{value // 60:02d}:{value % 60:02d}"
+
+
+def haversine_km(a_lat: float, a_lng: float, b_lat: float, b_lng: float) -> float:
+    radius = 6371.0
+    lat1, lat2 = math.radians(a_lat), math.radians(b_lat)
+    d_lat = math.radians(b_lat - a_lat)
+    d_lng = math.radians(b_lng - a_lng)
+    h = (
+        math.sin(d_lat / 2) ** 2
+        + math.cos(lat1) * math.cos(lat2) * math.sin(d_lng / 2) ** 2
+    )
+    return 2 * radius * math.asin(math.sqrt(h))
+
+
+def travel_minutes(distance_km: float) -> int:
+    return int(math.ceil((distance_km / AVG_SPEED_KMPH) * 60))
+
+
+def parse_orders(file_obj) -> List[Stop]:
+    if file_obj is None:
+        df = pd.read_csv(SAMPLE_PATH)
+    else:
+        file_path = file_obj if isinstance(file_obj, str) else file_obj.name
+        df = pd.read_csv(file_path)
+
+    required = {
+        "order_id",
+        "customer",
+        "lat",
+        "lng",
+        "demand",
+        "service_min",
+        "ready_time",
+        "due_time",
+        "priority",
+        "notes",
+    }
+    missing = sorted(required - set(df.columns))
+    if missing:
+        raise gr.Error(f"CSV is missing required columns: {', '.join(missing)}")
+
+    if "manual_sequence" not in df.columns:
+        df["manual_sequence"] = range(1, len(df) + 1)
+
+    stops: List[Stop] = []
+    for row in df.to_dict("records"):
+        stops.append(
+            Stop(
+                order_id=str(row["order_id"]),
+                customer=str(row["customer"]),
+                lat=float(row["lat"]),
+                lng=float(row["lng"]),
+                demand=int(row["demand"]),
+                service_min=int(row["service_min"]),
+                ready_time=time_to_min(str(row["ready_time"])),
+                due_time=time_to_min(str(row["due_time"])),
+                priority=str(row["priority"]).lower(),
+                notes=str(row.get("notes", "")),
+                manual_sequence=int(row.get("manual_sequence", len(stops) + 1)),
+            )
+        )
+    return stops
+
+
+def parse_dispatch_notes(notes: str) -> Dict[str, object]:
+    text = (notes or "").lower()
+    constraints: Dict[str, object] = {
+        "prefer_early_priority": True,
+        "avoid_late_penalty": 2.0,
+        "max_route_load": CAPACITY,
+        "depot_start": START_MINUTE,
+        "boost_terms": [],
+    }
+
+    if "cold" in text or "fresh" in text or "produce" in text:
+        constraints["boost_terms"].append("fresh")
+    if "medical" in text or "clinic" in text or "medicine" in text:
+        constraints["boost_terms"].append("medical")
+    if "school" in text:
+        constraints["boost_terms"].append("school")
+    if "lunch" in text or "noon" in text:
+        constraints["soft_due_before"] = 12 * 60
+
+    hour_match = re.search(r"(?:start|leave|depart)\D{0,12}(\d{1,2})(?::(\d{2}))?", text)
+    if hour_match:
+        hour = int(hour_match.group(1))
+        minute = int(hour_match.group(2) or 0)
+        if 1 <= hour <= 23:
+            constraints["depot_start"] = hour * 60 + minute
+
+    capacity_match = re.search(r"(?:capacity|load|max load|van)\D{0,12}(\d{1,3})", text)
+    if capacity_match:
+        constraints["max_route_load"] = max(1, int(capacity_match.group(1)))
+
+    return constraints
+
+
+def priority_weight(stop: Stop, constraints: Dict[str, object]) -> float:
+    score = 0.0
+    if stop.priority == "high":
+        score -= 1.4
+    if constraints.get("soft_due_before") and stop.due_time <= int(constraints["soft_due_before"]):
+        score -= 0.8
+    searchable = f"{stop.customer} {stop.notes}".lower()
+    for term in constraints.get("boost_terms", []):
+        if term in searchable:
+            score -= 1.0
+    return score
+
+
+def nearest_neighbor(stops: List[Stop], constraints: Dict[str, object]) -> List[Stop]:
+    remaining = list(stops)
+    planned: List[Stop] = []
+    cur_lat, cur_lng = DEPOT["lat"], DEPOT["lng"]
+    current_time = int(constraints["depot_start"])
+    current_load = 0
+    route_capacity = int(constraints["max_route_load"])
+
+    while remaining:
+        best: Optional[Tuple[float, Stop]] = None
+        for stop in remaining:
+            distance = haversine_km(cur_lat, cur_lng, stop.lat, stop.lng)
+            eta = current_time + travel_minutes(distance)
+            late = max(0, eta - stop.due_time)
+            capacity_pressure = 999 if current_load + stop.demand > route_capacity else 0
+            wait = max(0, stop.ready_time - eta)
+            score = (
+                distance
+                + late * 0.12 * float(constraints["avoid_late_penalty"])
+                + wait * 0.01
+                + priority_weight(stop, constraints)
+                + capacity_pressure
+            )
+            if best is None or score < best[0]:
+                best = (score, stop)
+
+        chosen = best[1]
+        distance = haversine_km(cur_lat, cur_lng, chosen.lat, chosen.lng)
+        arrival = current_time + travel_minutes(distance)
+        current_time = max(arrival, chosen.ready_time) + chosen.service_min
+        current_load += chosen.demand
+        planned.append(chosen)
+        remaining.remove(chosen)
+        cur_lat, cur_lng = chosen.lat, chosen.lng
+
+    return planned
+
+
+def two_opt(route: List[Stop]) -> List[Stop]:
+    if len(route) < 4:
+        return route
+    improved = True
+    best = route[:]
+    while improved:
+        improved = False
+        for i in range(1, len(best) - 2):
+            for j in range(i + 1, len(best)):
+                if j - i == 1:
+                    continue
+                candidate = best[:]
+                candidate[i:j] = reversed(best[i:j])
+                if route_distance(candidate) + 1e-9 < route_distance(best):
+                    best = candidate
+                    improved = True
+        route = best
+    return best
+
+
+def route_distance(route: Iterable[Stop]) -> float:
+    cur_lat, cur_lng = DEPOT["lat"], DEPOT["lng"]
+    total = 0.0
+    last_lat, last_lng = cur_lat, cur_lng
+    for stop in route:
+        total += haversine_km(last_lat, last_lng, stop.lat, stop.lng)
+        last_lat, last_lng = stop.lat, stop.lng
+    total += haversine_km(last_lat, last_lng, cur_lat, cur_lng)
+    return total
+
+
+def simulate(route: List[Stop], start_minute: int) -> Tuple[List[PlanStop], Dict[str, float]]:
+    cur_lat, cur_lng = DEPOT["lat"], DEPOT["lng"]
+    current = start_minute
+    plan: List[PlanStop] = []
+    load = 0
+    total_distance = 0.0
+    total_late = 0
+    total_wait = 0
+
+    for stop in route:
+        distance = haversine_km(cur_lat, cur_lng, stop.lat, stop.lng)
+        arrival = current + travel_minutes(distance)
+        start = max(arrival, stop.ready_time)
+        wait = max(0, start - arrival)
+        late = max(0, start - stop.due_time)
+        depart = start + stop.service_min
+        plan.append(
+            PlanStop(
+                stop=stop,
+                arrival=arrival,
+                start=start,
+                depart=depart,
+                distance_km=distance,
+                late_min=late,
+                wait_min=wait,
+            )
+        )
+        total_distance += distance
+        total_late += late
+        total_wait += wait
+        load += stop.demand
+        current = depart
+        cur_lat, cur_lng = stop.lat, stop.lng
+
+    back = haversine_km(cur_lat, cur_lng, DEPOT["lat"], DEPOT["lng"])
+    total_distance += back
+    finish = current + travel_minutes(back)
+    metrics = {
+        "distance_km": total_distance,
+        "late_min": total_late,
+        "wait_min": total_wait,
+        "finish_min": finish,
+        "load": load,
+        "on_time_rate": 100.0 * (1 - sum(1 for p in plan if p.late_min > 0) / max(1, len(plan))),
+    }
+    return plan, metrics
+
+
+def manual_route(stops: List[Stop]) -> List[Stop]:
+    return sorted(stops, key=lambda stop: stop.manual_sequence)
+
+
+def route_table(plan: List[PlanStop]) -> pd.DataFrame:
+    return pd.DataFrame(
+        [
+            {
+                "#": idx + 1,
+                "Order": item.stop.order_id,
+                "Customer": item.stop.customer,
+                "Arrive": min_to_time(item.arrival),
+                "Start": min_to_time(item.start),
+                "Depart": min_to_time(item.depart),
+                "Window": f"{min_to_time(item.stop.ready_time)}-{min_to_time(item.stop.due_time)}",
+                "Demand": item.stop.demand,
+                "Late min": item.late_min,
+                "Notes": item.stop.notes,
+            }
+            for idx, item in enumerate(plan)
+        ]
+    )
+
+
+def metrics_markdown(auto_metrics: Dict[str, float], manual_metrics: Dict[str, float]) -> str:
+    distance_delta = manual_metrics["distance_km"] - auto_metrics["distance_km"]
+    late_delta = manual_metrics["late_min"] - auto_metrics["late_min"]
+    return f"""
+### Dispatch Score
+
+| Metric | Manual baseline | Tiny Dispatch Coach | Change |
+|---|---:|---:|---:|
+| Distance | {manual_metrics['distance_km']:.1f} km | {auto_metrics['distance_km']:.1f} km | {distance_delta:+.1f} km |
+| Late minutes | {manual_metrics['late_min']:.0f} | {auto_metrics['late_min']:.0f} | {late_delta:+.0f} |
+| Waiting minutes | {manual_metrics['wait_min']:.0f} | {auto_metrics['wait_min']:.0f} | {manual_metrics['wait_min'] - auto_metrics['wait_min']:+.0f} |
+| Finish time | {min_to_time(manual_metrics['finish_min'])} | {min_to_time(auto_metrics['finish_min'])} | |
+| On-time rate | {manual_metrics['on_time_rate']:.0f}% | {auto_metrics['on_time_rate']:.0f}% | {auto_metrics['on_time_rate'] - manual_metrics['on_time_rate']:+.0f} pts |
+
+**Coach note:** This route prioritizes high-risk time windows first, then uses a nearest-neighbor pass with a 2-opt cleanup. It is intentionally transparent so a dispatcher can override it.
+"""
+
+
+def constraints_markdown(constraints: Dict[str, object]) -> str:
+    rows = "\n".join(f"- **{key}**: `{value}`" for key, value in constraints.items())
+    return f"### Parsed Dispatcher Notes\n{rows}"
+
+
+def route_cards(plan: List[PlanStop]) -> str:
+    cards = []
+    for idx, item in enumerate(plan, start=1):
+        status = "late" if item.late_min else "on time"
+        cards.append(
+            f"""
+<div class="route-card">
+  <div class="route-card-top">
+    <span class="route-index">{idx}</span>
+    <span class="route-title">{item.stop.customer}</span>
+    <span class="route-status {status.replace(' ', '-')}">{status}</span>
+  </div>
+  <div class="route-meta">{item.stop.order_id} · arrive {min_to_time(item.arrival)} · depart {min_to_time(item.depart)} · load {item.stop.demand}</div>
+  <div class="route-note">{item.stop.notes}</div>
+</div>
+"""
+        )
+    return "<div class='route-cards'>" + "\n".join(cards) + "</div>"
+
+
+def route_map(plan: List[PlanStop]) -> str:
+    points = [(DEPOT["lat"], DEPOT["lng"], "Depot")]
+    points.extend((item.stop.lat, item.stop.lng, item.stop.customer) for item in plan)
+    lat_values = [p[0] for p in points]
+    lng_values = [p[1] for p in points]
+    min_lat, max_lat = min(lat_values), max(lat_values)
+    min_lng, max_lng = min(lng_values), max(lng_values)
+    pad_lat = max(0.002, (max_lat - min_lat) * 0.12)
+    pad_lng = max(0.002, (max_lng - min_lng) * 0.12)
+    min_lat -= pad_lat
+    max_lat += pad_lat
+    min_lng -= pad_lng
+    max_lng += pad_lng
+
+    def xy(lat: float, lng: float) -> Tuple[float, float]:
+        x = 40 + (lng - min_lng) / (max_lng - min_lng) * 820
+        y = 520 - (lat - min_lat) / (max_lat - min_lat) * 460
+        return x, y
+
+    coords = [xy(lat, lng) for lat, lng, _ in points]
+    path = " ".join(f"{x:.1f},{y:.1f}" for x, y in coords + [coords[0]])
+    marker_html = []
+    for idx, ((lat, lng, label), (x, y)) in enumerate(zip(points, coords)):
+        is_depot = idx == 0
+        fill = "#0f766e" if is_depot else "#f59e0b"
+        text = "D" if is_depot else str(idx)
+        marker_html.append(
+            f"""
+<g>
+  <circle cx="{x:.1f}" cy="{y:.1f}" r="15" fill="{fill}" stroke="#fff" stroke-width="3" />
+  <text x="{x:.1f}" y="{y + 5:.1f}" text-anchor="middle" font-size="13" font-weight="700" fill="#fff">{text}</text>
+  <text x="{x + 20:.1f}" y="{y - 10:.1f}" font-size="12" fill="#1f2937">{label}</text>
+</g>
+"""
+        )
+    return f"""
+<div class="map-wrap">
+  <svg viewBox="0 0 900 560" role="img" aria-label="Route map">
+    <rect x="0" y="0" width="900" height="560" rx="8" fill="#f8fafc" />
+    <path d="M {path}" fill="none" stroke="#2563eb" stroke-width="4" stroke-linejoin="round" stroke-linecap="round" opacity="0.78" />
+    {''.join(marker_html)}
+  </svg>
+</div>
+"""
+
+
+def analyze(file_obj, notes: str):
+    stops = parse_orders(file_obj)
+    constraints = parse_dispatch_notes(notes)
+    auto_route = two_opt(nearest_neighbor(stops, constraints))
+    manual = manual_route(stops)
+    auto_plan, auto_metrics = simulate(auto_route, int(constraints["depot_start"]))
+    manual_plan, manual_metrics = simulate(manual, int(constraints["depot_start"]))
+
+    return (
+        metrics_markdown(auto_metrics, manual_metrics),
+        constraints_markdown(constraints),
+        route_table(auto_plan),
+        route_cards(auto_plan),
+        route_map(auto_plan),
+    )
+
+
+CUSTOM_CSS = """
+.gradio-container {
+  --radius-lg: 8px;
+}
+.hero {
+  min-height: 260px;
+  border-radius: 8px;
+  padding: 36px;
+  background:
+    linear-gradient(rgba(9, 47, 44, .72), rgba(9, 47, 44, .62)),
+    url('https://images.unsplash.com/photo-1601584115197-04ecc0da31d7?auto=format&fit=crop&w=1600&q=80');
+  background-size: cover;
+  background-position: center;
+  color: white;
+  display: flex;
+  flex-direction: column;
+  justify-content: end;
+}
+.hero h1 {
+  font-size: 42px;
+  line-height: 1.05;
+  margin: 0 0 10px 0;
+  letter-spacing: 0;
+}
+.hero p {
+  max-width: 760px;
+  font-size: 16px;
+  margin: 0;
+}
+.route-cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  gap: 10px;
+}
+.route-card {
+  border: 1px solid #d6d3d1;
+  border-radius: 8px;
+  padding: 12px;
+  background: #fff;
+}
+.route-card-top {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.route-index {
+  display: inline-grid;
+  place-items: center;
+  width: 26px;
+  height: 26px;
+  border-radius: 50%;
+  background: #0f766e;
+  color: white;
+  font-weight: 700;
+}
+.route-title {
+  font-weight: 700;
+  flex: 1;
+}
+.route-status {
+  border-radius: 999px;
+  padding: 3px 8px;
+  font-size: 12px;
+  background: #dcfce7;
+  color: #166534;
+}
+.route-status.late {
+  background: #fee2e2;
+  color: #991b1b;
+}
+.route-meta {
+  color: #57534e;
+  font-size: 13px;
+  margin-top: 8px;
+}
+.route-note {
+  color: #292524;
+  font-size: 14px;
+  margin-top: 6px;
+}
+.map-wrap {
+  border: 1px solid #d6d3d1;
+  border-radius: 8px;
+  overflow: hidden;
+  background: white;
+}
+"""
+
+
+DEFAULT_NOTES = (
+    "Start at 8:00. School and clinic stops are urgent. Fresh produce should be "
+    "delivered before lunch. Van capacity 18."
+)
+
+
+with gr.Blocks(
+    title="Tiny Dispatch Coach",
+    css=CUSTOM_CSS,
+    theme=gr.themes.Soft(primary_hue="emerald", secondary_hue="amber", neutral_hue="stone"),
+) as demo:
+    gr.HTML(
+        """
+<section class="hero">
+  <h1>Tiny Dispatch Coach</h1>
+  <p>Turn a small delivery sheet and messy dispatcher notes into a route plan, tradeoff explanation, and driver-ready cards. Built for small models, Gradio, and real neighborhood logistics.</p>
+</section>
+"""
+    )
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            order_file = gr.File(
+                label="Orders CSV",
+                file_types=[".csv"],
+                type="filepath",
+            )
+            notes = gr.Textbox(
+                label="Dispatcher notes",
+                value=DEFAULT_NOTES,
+                lines=5,
+            )
+            run = gr.Button("Plan route", variant="primary")
+        with gr.Column(scale=1):
+            gr.Markdown(
+                """
+### CSV columns
+`order_id`, `customer`, `lat`, `lng`, `demand`, `service_min`, `ready_time`, `due_time`, `priority`, `notes`, optional `manual_sequence`.
+
+Leave the file empty to run the included sample route.
+"""
+            )
+
+    metrics = gr.Markdown()
+    constraints = gr.Markdown()
+    table = gr.Dataframe(label="Optimized route", interactive=False)
+    cards = gr.HTML(label="Driver cards")
+    map_html = gr.HTML(label="Route map")
+
+    run.click(
+        analyze,
+        inputs=[order_file, notes],
+        outputs=[metrics, constraints, table, cards, map_html],
+    )
+    demo.load(
+        analyze,
+        inputs=[order_file, notes],
+        outputs=[metrics, constraints, table, cards, map_html],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,3 @@
+gradio>=6.14.0
+pandas>=2.2.0
+

sample_orders.csv

@@ -0,0 +1,9 @@
+order_id,customer,lat,lng,demand,service_min,ready_time,due_time,priority,notes,manual_sequence
+SYN-1001,Synthetic Stop A,40.7241,-73.9962,7,8,09:00,11:00,high,Perishable demo order before lunch,1
+SYN-1002,Synthetic Stop B,40.7316,-73.9893,5,6,09:30,12:00,normal,Demo back-door delivery note,2
+SYN-1003,Synthetic Stop C,40.7362,-74.0027,4,10,08:30,10:30,high,Time-critical demo parcel,4
+SYN-1004,Synthetic Stop D,40.7194,-74.0060,3,5,10:00,14:00,normal,Call-on-arrival demo note,3
+SYN-1005,Synthetic Stop E,40.7438,-73.9901,8,8,11:00,15:30,normal,Two demo cartons,5
+SYN-1006,Synthetic Stop F,40.7282,-74.0111,2,5,13:00,16:00,low,Flexible demo stop,6
+SYN-1007,Synthetic Stop G,40.7218,-73.9857,6,7,08:00,09:45,high,Early-window demo stop,7
+SYN-1008,Synthetic Stop H,40.7335,-74.0082,4,5,12:00,17:00,normal,Demo front-desk note,8