hum-router 0.2.0__py3-none-any.whl

hum_router-0.2.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: hum-router
+Version: 0.2.0
+Summary: Multimodal freight routing engine — road, rail, waterway, sea
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.12
+Requires-Dist: apache-sedona[db]
+Requires-Dist: duckdb==1.5.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: geopandas>=1.1
+Requires-Dist: igraph>=1.0.0
+Requires-Dist: matplotlib>=3.10.8
+Requires-Dist: polars==1.29.0
+Requires-Dist: pyarrow>=23.0
+Requires-Dist: pyroutingkit>=0.2.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: searoute>=1.5
+Requires-Dist: snkit>=1.9
+Requires-Dist: uvicorn>=0.32
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-benchmark; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Multimodal Router
+
+A freight routing engine that finds and compares routes across **road, ferry,
+rail, sea, and inland waterway** networks. Built for humanitarian logistics,
+designed to run anywhere OpenStreetMap covers — and to deploy on Palantir
+Foundry as batch transforms plus an interactive service.
+
+Given an origin and destination, the engine returns **ranked alternatives**
+("possible routes", not one answer): the truck route, the rail option, the
+sea option, the ferry crossing — each with distance, time, and cost, with a
+leg-by-leg breakdown and geometry. Field users can **edit the network**
+(close a road, flag a slow segment, avoid a border crossing) and reroutes
+honor the edit in milliseconds.
+
+## The core idea: one topology, many metrics
+
+The engine is built on Customizable Contraction Hierarchies (CCH, via
+[pyroutingkit](https://github.com/nullbutt/pyroutingkit)). CCH splits work
+into three phases:
+
+| Phase | Cost | When |
+|-------|------|------|
+| Topology preprocessing (nested dissection) | seconds–minutes | once per graph build, cached to disk |
+| Metric customization (apply a weight vector) | seconds | per profile, lazily |
+| Partial customization (change a few weights) | milliseconds | per field edit |
+| Query | microseconds–ms | per route |
+
+Every product feature is the same operation — a weight vector over the
+frozen arc order of one unified multimodal graph:
+
+```
+mode filter ("trucks only")      -> excluded modes get INF weight
+avoid border crossing            -> arcs at that crossing get INF
+avoid area (polygon)             -> arcs inside it get INF
+field edit (closed road, speed)  -> partial weight update, ~ms
+impedance distance | time | cost -> which base value is quantized
+```
+
+Nothing is precomputed against fixed weights, so edits, avoids, and mode
+filters are always honored. There is no gateway path cache to invalidate.
+
+## Alternatives model
+
+```
+[road]        road + ro-ro ferry metric, end to end — the truck option
+[road_no_ferry] shown when the truck route rides a ferry
+[multimodal]  everything the request allows — the unconstrained optimum
+[via_rail]    first/last mile by road, the haul on a rail-only metric
+[via_sea]     …on a sea-only metric (seaport to seaport)
+[via_ferry]   …explicit ferry crossing
+[via_inland_waterway] …barge corridor
+```
+
+Via-options are diverse *by construction* — the rail option genuinely rides
+rail between real terminals. Mode changes happen only at gateways (ports,
+rail terminals, ferry docks) through explicit transfer edges that carry the
+dwell time (port handling 48 h, rail terminal 12 h, ro-ro 2 h…). Line-haul
+edges carry pure travel time, so nothing is double-counted. All gateways
+attach to the road network; alternatives are ranked by the requested
+impedance and all three totals are always reported.
+
+## Field edits (overrides)
+
+Overrides live in their own Parquet dataset keyed by **stable OSM identity**
+`(way_id, osm_from, osm_to)`, so they survive monthly OSM refreshes and
+graph rebuilds:
+
+```python
+engine.set_overrides([
+    EdgeOverride(override_id="fld-001", action="close", way_id=478662651,
+                 note="ferry suspended", author="field-team"),
+    EdgeOverride(override_id="fld-002", action="speed_kmh", value=15,
+                 way_id=22397122, note="washboard surface"),
+])   # applies to every live metric via partial customization, ~100ms
+```
+
+Actions: `close`, `speed_kmh`, `factor`. The same dataset is an input to
+the batch pipeline (`05_route_pairs.py --overrides …`).
+
+## Pipeline (Parquet in, Parquet out — Foundry-transform shaped)
+
+```
+01_load_osm.py       PBF + Natural Earth -> country-tagged OSM Parquets
+                     (roads, rail, waterways, ferries, terminals)
+filter_osm.py        global -> per-country/region subsets (keeps countries)
+02_build_road.py     ways -> road_edges/road_nodes (speeds, oneway, way_id)
+03_build_modal.py    rail / waterway / sea (searoute) / ferry networks
+04_build_unified.py  ONE graph: contiguous int32 vertex/arc ids,
+                     transfer edges at gateways, border-crossing detection,
+                     per-arc geometry. Row order == arc order, FROZEN.
+05_route_pairs.py    batch O/D list -> one row PER ALTERNATIVE
+                     (rank, label, km, hours, cost, crossings, WKT)
+run_all.py           orchestrator: ingest -> per-country/region -> merge
+```
+
+The unified graph (stage 04) is the single artifact the engine consumes:
+`unified_nodes`, `unified_edges`, `unified_gateways`, `unified_crossings`.
+The CCH topology cache is built next to it on first use.
+
+## Quick start
+
+```bash
+git clone <repo-url> && cd hum-router
+uv sync --all-extras
+
+# data: an OSM PBF (planet or regional extract) + Natural Earth boundaries
+uv run python scripts/download_natural_earth.py
+
+# ingest + build + route one region
+uv run python pipeline/01_load_osm.py --pbf data/east_africa.osm.pbf \
+    --country ET,DJ --output-dir pipeline_output/01_osm_global
+uv run python pipeline/filter_osm.py --source-dir pipeline_output/01_osm_global \
+    --countries ET,DJ --output-dir pipeline_output/regions/et_dj/01_osm_raw
+uv run python pipeline/02_build_road.py  --input-dir pipeline_output/regions/et_dj/01_osm_raw --output-dir pipeline_output/regions/et_dj/02_road_network
+uv run python pipeline/03_build_modal.py --input-dir pipeline_output/regions/et_dj/01_osm_raw --output-dir pipeline_output/regions/et_dj/03_modal_networks
+uv run python pipeline/04_build_unified.py --road-dir pipeline_output/regions/et_dj/02_road_network --modal-dir pipeline_output/regions/et_dj/03_modal_networks --output-dir pipeline_output/regions/et_dj/04_unified
+uv run python pipeline/05_route_pairs.py --graph-dir pipeline_output/regions/et_dj/04_unified --country ET,DJ --limit 50
+```
+
+## Interactive map app
+
+```bash
+uv run python -m multimodal_router.app \
+    --graph-dir pipeline_output/regions/et_dj/04_unified
+# open http://127.0.0.1:8000
+```
+
+Click to set origin/destination/waypoints; pick impedance and modes;
+alternatives render as colored lines with side-by-side km/hours/cost cards.
+Border crossings are clickable to avoid. **Close segment** / **Slow
+segment** apply field edits to the live engine (~100 ms) and persist to
+`<graph_dir>/edge_overrides.parquet` — the same file `05_route_pairs.py
+--overrides` accepts, so the app and batch runs share one picture of the
+network.
+
+## Engine API
+
+```python
+from multimodal_router.engine import RoutingEngine, RouteRequest, EdgeOverride
+
+engine = RoutingEngine("pipeline_output/regions/et_dj/04_unified")
+
+result = engine.route(RouteRequest(
+    o_lon=38.74, o_lat=9.03,      # Addis Ababa
+    d_lon=43.145, d_lat=11.595,   # Djibouti City
+    impedance="time",             # distance | time | cost
+    modes=frozenset({"road", "ferry", "rail", "sea"}),
+    waypoints=[(41.0, 9.4)],                  # must pass through
+    avoid_crossings=frozenset({17}),          # skip Galafi border post
+))
+
+for opt in result.options:
+    print(opt.label, opt.total_distance_km, opt.total_time_hours,
+          opt.total_cost_usd, opt.crossings_used)
+    for leg in opt.legs:
+        print("  ", leg.mode, leg.distance_km, leg.time_hours, leg.geometry_wkt[:60])
+```
+
+## Measured performance (10-core / 64 GB laptop)
+
+| Operation | ET+DJ region (2.8M nodes, 5.6M arcs) |
+|-----------|--------------------------------------|
+| Stage 01 ingest (4.1 GB East Africa PBF, 10 countries) | ~2.5 min |
+| Stages 02–04 build | ~1 min |
+| CCH topology build (first run, then cached) | ~25 s |
+| Engine start with cached topology | ~10 s |
+| Metric customization (per profile, lazy) | ~1 s |
+| Route query (warm, with alternatives) | ~10 ms |
+| Field-edit override apply (3 live metrics) | ~150 ms |
+| Batch routing | ~50+ pairs/s |
+
+Single node, fits comfortably in 8 cores / 64 GB — the Foundry target.
+
+## Configuration
+
+`config/routing.yaml` — speeds per mode/class, ferry default speed,
+transfer dwell hours per mode pair, intermodal connection radii.
+`config/country_modes.yaml` — which modes each country gets
+(waterway only where there are navigable corridors).
+`config/seed_ports.yaml` — curated seaports, inland ports, rail terminals.
+
+Cost defaults (USD/km by mode + per-transfer fees) live in
+`engine/profiles.py` and can be overridden via `RoutingEngine(cost_config=…)`.
+
+## Tests
+
+```bash
+uv run pytest tests/ -m "not slow"   # ~120 tests
+```
+
+## License
+
+MIT

hum_router-0.2.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+multimodal_router/__init__.py,sha256=14EX64jECkWBjE0duMA0wyqdl2M9hyBRerVZEpbfrhc,63
+multimodal_router/models.py,sha256=oinWH4CE8poksyaAEpF8LQ3rKJVngZn0DJT2TAifd24,2692
+multimodal_router/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+multimodal_router/settings.py,sha256=Qej2HdNPTGwOCNEN-1_UMdnKRsuGDeQYVjI7B-kCQp0,5605
+multimodal_router/stages.py,sha256=LrD6HmNh9FjdQMhHWgTAIezXWj0voYLZynSs8kmFBn8,14925
+multimodal_router/app/__init__.py,sha256=56Q4kjn-bbXaV4YoPSmkNF6cbwuxrQy1zbQmjcxz2gg,68
+multimodal_router/app/__main__.py,sha256=TCGIAYJ0LCSccdpUBg4rBq80ah9WAdBNtcZ-nZjcumQ,949
+multimodal_router/app/server.py,sha256=W2zKp3Dg9Klp0J_4fNRolVRRUcMJzy1Sqthpkh3Uosw,10311
+multimodal_router/app/static/index.html,sha256=z7TtoMesqhiCPo3_x4CUhgYaCwFHzXEzWrK6vGYcFs4,14005
+multimodal_router/build/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+multimodal_router/build/ferry_builder.py,sha256=eKha1gCOhRQoOwlr25x-ZzHgqiL6gX-I8MNuBTaGoHs,8359
+multimodal_router/build/rail_builder.py,sha256=tRETHFb49in-mVGa2oIzypmF9DzhwRYjKmp8XLLrEFA,8280
+multimodal_router/build/road_builder.py,sha256=H1Jrv6n3VQPL6p6EshYjZxPDoZsjcqKZwFiyIsLO8DQ,5867
+multimodal_router/build/sea_builder.py,sha256=nNmfPZhilzFRJ_Xmj1fBa9vj-EkqC5W3FWt-FbS2GJY,5137
+multimodal_router/build/topology.py,sha256=AyPQBXvJpgDMGwSu-s3jB5LjwvP7EHY6d5_rEesA990,7013
+multimodal_router/build/unified_graph.py,sha256=_zIOsAessj6woosThZnzzSOpsdTjcYEc9pUMaZqG7Cs,18599
+multimodal_router/build/waterway_builder.py,sha256=lT7EdQKK3m6EGViqHc0onyatK7DmATmoW9H2ercAfXU,9200
+multimodal_router/config/country_modes.yaml,sha256=azPDS8ZSMv7H0Jnn_uJjoG2vTINblY-wgbLfn6p3rLM,2104
+multimodal_router/config/routing.yaml,sha256=BnqqW7iptuFsxevMQm9uxVt2m2DcZZ7ESlYt2tWCNsc,954
+multimodal_router/config/seed_ports.yaml,sha256=Vcyx9Q17sT4Vqwy0cyPK9-od0Gvf-S79CJ0kejZ04M4,1561
+multimodal_router/engine/__init__.py,sha256=ioWkRqZWlVQuaHwBUYB11Jpv4HKtcW75VjHBCWVoUsA,756
+multimodal_router/engine/engine.py,sha256=gYbIjSGN1OogrfOkQ7j2vA7qV8EOHZX7cTvoRUhGJA4,21895
+multimodal_router/engine/graph.py,sha256=7nYsYR2HF7tbWyPCDp5ynFPUffV12vwCTySnB-oPkwQ,8713
+multimodal_router/engine/overrides.py,sha256=qNAhVaWD8gAQ-daYLyJScuAAmPnZXpdq82BQiWNeEyg,5359
+multimodal_router/engine/profiles.py,sha256=jDXLRJspIuIvIE4Mlc7SZ7ybB-9BzXdJrPBsgE-ayl0,7136
+multimodal_router/engine/types.py,sha256=47tFCja_l9ncwGzwIZPxmY9Pbuzz4RyrSeqMzgw1-fI,2448
+multimodal_router/io/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+multimodal_router/io/country_tagger.py,sha256=UUrtnesuEIPoKinNPQn1HSNTPAouLjPusjtCwW_qtEU,6774
+multimodal_router/io/osm_loader.py,sha256=ja1gGx0MghrjDnj-B8TEsIlu_lv23yRCzOb-iSuObnI,782
+multimodal_router/io/osm_planet_loader.py,sha256=F9Ryeo2FZ9ayKY8dM06Jwvfaj6og6TpGwmA7YANfIpI,19241
+multimodal_router/io/seed_data.py,sha256=oxUFxWUjHVy6fdC0sJb35mBEF7D6ACDtD9rSljZMuPc,2031
+multimodal_router/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+multimodal_router/utils/duckdb_helpers.py,sha256=Z-KXz-qsk6VZCSWYTKLM8viBeT96P-EbNbdgZFQFXtY,6457
+multimodal_router/utils/geo.py,sha256=vzLHhd6WiBde4YkWQmrK6rmlvG2GOus0CLvrFo_VWdQ,1812
+hum_router-0.2.0.dist-info/METADATA,sha256=FdiWUYMhpOe7s4Cis6u9XJhTJ5YealMEvHmES_opGYc,9377
+hum_router-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+hum_router-0.2.0.dist-info/RECORD,,

hum_router-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

multimodal_router/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from multimodal-router!"

multimodal_router/app/__init__.py

@@ -0,0 +1 @@
+"""Interactive routing app: FastAPI backend + MapLibre frontend."""

multimodal_router/app/__main__.py

@@ -0,0 +1,34 @@
+"""Run the interactive routing app.
+
+    uv run python -m multimodal_router.app --graph-dir pipeline_output/regions/et_dj/04_unified
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+
+
+def main() -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)-8s %(name)s — %(message)s",
+        datefmt="%H:%M:%S",
+    )
+    parser = argparse.ArgumentParser(description="Multimodal routing app")
+    parser.add_argument("--graph-dir", required=True,
+                        help="Stage 04 unified graph directory")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+
+    import uvicorn
+
+    from multimodal_router.app.server import create_app
+
+    app = create_app(args.graph_dir)
+    uvicorn.run(app, host=args.host, port=args.port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

multimodal_router/app/server.py

@@ -0,0 +1,285 @@
+"""
+FastAPI server wrapping the RoutingEngine for the interactive map app.
+
+    uv run python -m multimodal_router.app --graph-dir <stage 04 dir>
+
+Endpoints:
+    GET  /                      MapLibre single-page app
+    GET  /api/meta              graph stats + map bounds + config
+    GET  /api/gateways          GeoJSON of gateways (ports, terminals, docks)
+    GET  /api/crossings         GeoJSON of border crossings
+    POST /api/route             alternatives for an O/D (+waypoints/avoids)
+    POST /api/locate            nearest edge to a clicked point
+    GET  /api/overrides         active field edits
+    POST /api/overrides         add an edit (applies live + persists)
+    DELETE /api/overrides/{id}  remove an edit
+
+Field edits persist to <graph_dir>/edge_overrides.parquet — the same file
+the batch pipeline accepts via --overrides, so the app and batch runs see
+one consistent picture of the network.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+import uuid
+from pathlib import Path
+
+import numpy as np
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse
+from pydantic import BaseModel, Field
+
+from multimodal_router.engine import (
+    EdgeOverride,
+    RouteRequest,
+    RoutingEngine,
+    load_overrides,
+)
+from multimodal_router.engine.graph import MODE_CODES, MODE_NAMES
+from multimodal_router.engine.overrides import save_overrides
+
+logger = logging.getLogger(__name__)
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+# ---------------------------------------------------------------------------
+# Request/response models
+# ---------------------------------------------------------------------------
+
+class RoutePayload(BaseModel):
+    o_lon: float
+    o_lat: float
+    d_lon: float
+    d_lat: float
+    impedance: str = "time"
+    modes: list[str] = ["road", "ferry", "rail", "sea", "inland_waterway"]
+    waypoints: list[list[float]] = Field(default_factory=list)  # [[lon, lat]]
+    avoid_crossings: list[int] = Field(default_factory=list)
+    avoid_areas: list[list[list[float]]] = Field(default_factory=list)
+    max_alternatives: int = 5
+    max_detour_factor: float = 8.0
+
+
+class LocatePayload(BaseModel):
+    lon: float
+    lat: float
+
+
+class OverridePayload(BaseModel):
+    action: str  # close | speed_kmh | factor
+    value: float = 0.0
+    way_id: int = -1
+    osm_from: int = -1
+    osm_to: int = -1
+    arc: int = -1
+    note: str = ""
+    author: str = "app"
+
+
+# ---------------------------------------------------------------------------
+# App factory
+# ---------------------------------------------------------------------------
+
+def _wkt_to_coords(wkt: str) -> list[list[float]]:
+    if not wkt or "(" not in wkt:
+        return []
+    inner = wkt[wkt.index("(") + 1: wkt.rindex(")")]
+    coords = []
+    for pt in inner.split(","):
+        x, y = pt.strip().split(" ")
+        coords.append([round(float(x), 6), round(float(y), 6)])
+    return coords
+
+
+def create_app(graph_dir: str | Path) -> FastAPI:
+    graph_dir = Path(graph_dir)
+    app = FastAPI(title="Multimodal Router")
+
+    t0 = time.time()
+    engine = RoutingEngine(graph_dir)
+    logger.info("Engine ready in %.1fs", time.time() - t0)
+
+    # The engine reuses CCH query objects per metric — serialize access.
+    lock = threading.Lock()
+
+    overrides_path = graph_dir / "edge_overrides.parquet"
+    overrides: list[EdgeOverride] = load_overrides(overrides_path)
+    if overrides:
+        with lock:
+            engine.set_overrides(overrides)
+        logger.info("Loaded %d persisted overrides", len(overrides))
+
+    # Lazy KD-tree over edge midpoints for click-to-edge lookup
+    _edge_index: dict = {}
+
+    def edge_index():
+        if "tree" not in _edge_index:
+            from scipy.spatial import cKDTree
+            g = engine.graph
+            sel = np.nonzero(g.arc_mode != MODE_CODES["transfer"])[0]
+            mx = (g.node_x[g.tail[sel]] + g.node_x[g.head[sel]]) / 2
+            my = (g.node_y[g.tail[sel]] + g.node_y[g.head[sel]]) / 2
+            _edge_index["arcs"] = sel
+            _edge_index["tree"] = cKDTree(np.column_stack([mx, my]))
+        return _edge_index["tree"], _edge_index["arcs"]
+
+    # ------------------------------------------------------------------
+
+    @app.get("/")
+    def index():
+        return FileResponse(STATIC_DIR / "index.html")
+
+    @app.get("/api/meta")
+    def meta():
+        g = engine.graph
+        return {
+            "nodes": g.node_count,
+            "arcs": g.arc_count,
+            "gateways": len(g.gateways),
+            "crossings": len(g.crossings),
+            "bounds": [
+                float(g.node_x.min()), float(g.node_y.min()),
+                float(g.node_x.max()), float(g.node_y.max()),
+            ],
+            "modes": ["road", "ferry", "rail", "sea", "inland_waterway"],
+            "impedances": ["time", "distance", "cost"],
+        }
+
+    @app.get("/api/gateways")
+    def gateways():
+        feats = []
+        for gw in engine.graph.gateways:
+            if gw.road_vertex < 0:
+                continue
+            feats.append({
+                "type": "Feature",
+                "geometry": {"type": "Point", "coordinates": [gw.x, gw.y]},
+                "properties": {
+                    "kind": gw.kind, "name": gw.name or "",
+                    "country": gw.country or "",
+                },
+            })
+        return {"type": "FeatureCollection", "features": feats}
+
+    @app.get("/api/crossings")
+    def crossings():
+        feats = []
+        for c in engine.graph.crossings:
+            feats.append({
+                "type": "Feature",
+                "geometry": {"type": "Point", "coordinates": [c["x"], c["y"]]},
+                "properties": {
+                    "crossing_id": c["crossing_id"],
+                    "countries": f'{c["country_a"]}–{c["country_b"]}',
+                    "mode": c["mode"],
+                },
+            })
+        return {"type": "FeatureCollection", "features": feats}
+
+    @app.post("/api/route")
+    def route(p: RoutePayload):
+        req = RouteRequest(
+            o_lon=p.o_lon, o_lat=p.o_lat, d_lon=p.d_lon, d_lat=p.d_lat,
+            impedance=p.impedance,
+            modes=frozenset(p.modes),
+            waypoints=[(w[0], w[1]) for w in p.waypoints],
+            avoid_crossings=frozenset(p.avoid_crossings),
+            avoid_areas=[[(pt[0], pt[1]) for pt in ring] for ring in p.avoid_areas],
+            max_alternatives=p.max_alternatives,
+            max_detour_factor=p.max_detour_factor,
+        )
+        t0 = time.time()
+        with lock:
+            result = engine.route(req)
+        elapsed_ms = (time.time() - t0) * 1000
+
+        options = []
+        for opt in result.options:
+            options.append({
+                "label": opt.label,
+                "modes": opt.modes,
+                "is_multimodal": opt.is_multimodal,
+                "total_distance_km": opt.total_distance_km,
+                "total_time_hours": opt.total_time_hours,
+                "total_cost_usd": opt.total_cost_usd,
+                "gateway_origin": opt.gateway_origin,
+                "gateway_destination": opt.gateway_destination,
+                "crossings_used": opt.crossings_used,
+                "legs": [{
+                    "mode": leg.mode,
+                    "distance_km": leg.distance_km,
+                    "time_hours": leg.time_hours,
+                    "cost_usd": leg.cost_usd,
+                    "from_name": leg.from_name,
+                    "to_name": leg.to_name,
+                    "coordinates": _wkt_to_coords(leg.geometry_wkt),
+                } for leg in opt.legs],
+            })
+        return {"options": options, "elapsed_ms": round(elapsed_ms, 1)}
+
+    @app.post("/api/locate")
+    def locate(p: LocatePayload):
+        tree, arcs = edge_index()
+        dist, i = tree.query([p.lon, p.lat])
+        if dist > 0.05:  # ~5 km — too far from any edge
+            raise HTTPException(404, "No edge near this point")
+        arc = int(arcs[int(i)])
+        g = engine.graph
+        return {
+            "arc": arc,
+            "way_id": int(g.way_id[arc]),
+            "osm_from": int(g.osm_from[arc]),
+            "osm_to": int(g.osm_to[arc]),
+            "mode": MODE_NAMES[int(g.arc_mode[arc])],
+            "distance_km": round(float(g.distance_km[arc]), 3),
+            "crossing_id": int(g.crossing_id[arc]),
+            "coordinates": [
+                [float(g.node_x[g.tail[arc]]), float(g.node_y[g.tail[arc]])],
+                [float(g.node_x[g.head[arc]]), float(g.node_y[g.head[arc]])],
+            ],
+        }
+
+    @app.get("/api/overrides")
+    def list_overrides():
+        return [{
+            "override_id": o.override_id, "action": o.action, "value": o.value,
+            "way_id": o.way_id, "osm_from": o.osm_from, "osm_to": o.osm_to,
+            "arc": o.arc, "note": o.note, "author": o.author,
+            "created_at": o.created_at,
+        } for o in overrides]
+
+    @app.post("/api/overrides")
+    def add_override(p: OverridePayload):
+        if p.action not in ("close", "speed_kmh", "factor"):
+            raise HTTPException(400, "action must be close|speed_kmh|factor")
+        if p.way_id < 0 and p.arc < 0:
+            raise HTTPException(400, "way_id or arc required")
+        o = EdgeOverride(
+            override_id=uuid.uuid4().hex[:12],
+            action=p.action, value=p.value,
+            way_id=p.way_id, osm_from=p.osm_from, osm_to=p.osm_to, arc=p.arc,
+            note=p.note, author=p.author,
+            created_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        )
+        overrides.append(o)
+        with lock:
+            stats = engine.set_overrides(overrides)
+        save_overrides(overrides, overrides_path)
+        return {"override_id": o.override_id, "applied": stats}
+
+    @app.delete("/api/overrides/{override_id}")
+    def remove_override(override_id: str):
+        before = len(overrides)
+        overrides[:] = [o for o in overrides if o.override_id != override_id]
+        if len(overrides) == before:
+            raise HTTPException(404, "Unknown override id")
+        with lock:
+            stats = engine.set_overrides(overrides)
+        save_overrides(overrides, overrides_path)
+        return {"removed": override_id, "applied": stats}
+
+    return app