hum-router 0.2.0__tar.gz

hum_router-0.2.0/.github/workflows/build.yml

@@ -0,0 +1,32 @@
+name: Build & Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      # --no-sources ignores the local-path pyroutingkit override
+      # (dev convenience only) and resolves it from PyPI instead.
+      - name: Install dependencies
+        run: uv sync --all-extras --no-sources
+
+      - name: Run tests
+        run: uv run --no-sources pytest tests/ -m "not slow" -v --tb=short

hum_router-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv python install 3.12
+      - run: uv sync --all-extras --no-sources
+      - run: uv run --no-sources pytest tests/ -m "not slow" --tb=short
+
+  build-and-publish:
+    name: Build & publish to PyPI
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      id-token: write  # trusted publishing (OIDC)
+      contents: read   # declaring permissions zeroes the rest; checkout needs this
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Build wheel + sdist (pure Python)
+        run: uv build
+
+      # Regression guard: non-.py package data must ship in the wheel
+      # (config YAMLs and the app frontend were once lost to .gitignore).
+      - name: Verify wheel contents
+        run: |
+          unzip -l dist/*.whl | grep -q "multimodal_router/config/routing.yaml"
+          unzip -l dist/*.whl | grep -q "multimodal_router/config/country_modes.yaml"
+          unzip -l dist/*.whl | grep -q "multimodal_router/config/seed_ports.yaml"
+          unzip -l dist/*.whl | grep -q "multimodal_router/app/static/index.html"
+          echo "wheel contents OK"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Trusted publishing (OIDC) — configure at
+        # https://pypi.org/manage/account/publishing/
+        # Publisher: GitHub, repo: nullbutt/hum-router, workflow: publish.yml

hum_router-0.2.0/.gitignore

@@ -0,0 +1,30 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+/build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# OSM data files
+data/
+*.osm.pbf
+
+# C++ build artifacts
+routingkit_wrapper/build/
+*.so
+*.dylib
+
+# Generated visualizations
+*.html
+*.png
+
+# Pipeline output (generated artifacts)
+pipeline_output*/
+
+# macOS
+.DS_Store
+!src/multimodal_router/app/static/*.html

hum_router-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

hum_router-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,193 @@
+# 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/foundry_deployment/README.md

@@ -0,0 +1,117 @@
+# Foundry Deployment
+
+The engine maps onto Palantir Foundry in three pieces — batch transforms,
+ontology objects, and a compute module for interactive serving. Nothing in
+`src/multimodal_router` imports Foundry: transforms and the compute module
+call the wheel's `multimodal_router.stages` / `multimodal_router.engine`
+APIs with plain local paths, and all configuration ships inside the wheel
+(`multimodal_router.settings`).
+
+```
+        Monthly (OSM refresh)                        On demand
+        ─────────────────────                        ─────────
+  T1 osm_ingest                                T3 route_<region>
+  PBF + boundaries -> tagged Parquets          graph + od_pairs +
+              │                                EDGE_OVERRIDES -> alternatives
+  T2 build_<region>   (parallel per region)             │
+  -> graph files (unified_* + CCH topology)    T4 merge -> route_results
+  -> gateways, border_crossings (tabular)                │
+              │                                          ▼
+              └───────────► ONTOLOGY ◄───────────────────┘
+        RouteAlternative · Gateway · BorderCrossing · EdgeOverride
+                              ▲
+              Workshop map ───┤ actions: Close/Reopen Segment…
+                              ▼
+        COMPUTE MODULE (RoutingEngine resident, ~10 ms queries,
+        overrides re-applied via partial customization ~100 ms)
+```
+
+## Contents
+
+```
+foundry_deployment/
+├── README.md            this file
+├── ontology.md          object types, actions, function wiring
+├── meta.yml             package config for the transforms repo
+├── transforms/
+│   ├── deployment.py    EDIT ME: project path + enabled regions
+│   ├── io_helpers.py    the only file touching Foundry I/O APIs
+│   ├── t1_osm_ingest.py
+│   ├── t2_build_region.py   one transform generated per region
+│   ├── t3_route_pairs.py    one transform generated per region
+│   └── t4_merge_results.py
+└── compute_module/
+    ├── app.py           functions mode: route / locate_edge / network_meta
+    ├── bootstrap.py     graph download via public datasets REST API
+    ├── Dockerfile
+    └── README.md
+```
+
+## Transform tiers (measured locally on equivalent hardware)
+
+| Transform | Wraps (stages API) | Frequency | Duration | Memory |
+|-----------|--------------------|-----------|----------|--------|
+| T1 osm_ingest | `stages.ingest_osm` | monthly | ~3 min / 4 GB PBF | 64 GB |
+| T2 build_<region> | `stages.filter_countries` + `stages.build_region` | monthly, parallel | ~2 min / 2.8M-node region | 64 GB |
+| T3 route_<region> | `stages.route_pairs` | on demand | 50+ pairs/s after ~10 s engine start | 30 GB |
+| T4 merge | concat | after T3 | seconds | 8 GB |
+
+T2's output dataset holds files (unified Parquets + the CCH topology
+binaries `tail/head/order/rank/node_count`), so T3 and the compute module
+skip the expensive nested dissection.
+
+## Setup
+
+1. Build + upload wheels (`pyroutingkit` manylinux from its CI,
+   `hum-router` via `uv build`) to Foundry's package repository.
+2. Upload source datasets: the PBF (file dataset), Natural Earth
+   boundaries (file dataset with .shp + sidecars), O/D pairs (tabular).
+3. Create the **ontology-writable** `edge_overrides` dataset and the
+   object types/actions per `ontology.md`.
+4. Copy `transforms/` into a transforms-python repository; set the
+   project path + regions in `deployment.py`. The per-region T2/T3
+   transforms are generated from that one list.
+5. Build T1 → T2s; schedule monthly. T3/T4 run on demand (new O/D pairs
+   or changed overrides).
+6. Deploy the compute module (see `compute_module/README.md`) and wire the
+   Workshop map per `ontology.md`.
+
+## Do we need a compute module at all?
+
+Alternatives considered, in order of how much interactivity survives:
+
+1. **No custom serving — precompute + ontology only.** T3 routes every
+   known O/D pair (alternatives included); Workshop just displays
+   RouteAlternative objects. An "on-demand" feel comes from the *Request
+   Routes* action appending to `od_pairs` and triggering T3 (minutes
+   latency). Zero containers, fully transform-native — but no
+   click-anywhere O/D, no waypoints, no instant what-if on edits. **This
+   works today and is the right fallback** if compute modules aren't
+   enabled on the stack; everything else in this deployment is unchanged.
+2. **Serverless Foundry Functions (Python/TS).** Not viable as the query
+   engine: functions are short-lived with limited memory, and the engine
+   needs ~10 s and several GB to come up — per invocation, that's the
+   whole budget. Functions are the right *caller* (they fetch overrides
+   and invoke the module), not the right host.
+3. **Container models / live model deployments.** Foundry can host a
+   container behind a model live deployment. Workable, but the engine
+   isn't a model: the model-adapter I/O contract and model lifecycle
+   (versions, objectives) add friction for plain request/response logic.
+   Compute modules are Palantir's intended primitive for exactly this.
+4. **External hosting.** Run the FastAPI app on a VM; Foundry calls out
+   via external functions/egress. Maximum flexibility, but data leaves
+   platform governance and you own the infra — against the goal of a
+   Foundry-native deployment.
+
+Compute modules remain the recommendation: they are precisely
+"long-running custom container, callable as Foundry Functions", which is
+this workload. Option 1 is the graceful degradation path.
+
+## Platform-API notes
+
+The transforms use the lightweight API (`@lightweight` +
+`Input/Output`); dataset file access is isolated in
+`transforms/io_helpers.py` (tries the lightweight local-download path,
+falls back to `filesystem()` streaming). If your Foundry version's
+lightweight file API differs, that one file is the only thing to adjust.
+The compute module's bootstrap uses only stable public REST endpoints.

hum_router-0.2.0/foundry_deployment/compute_module/Dockerfile

@@ -0,0 +1,33 @@
+# Compute module image for the interactive routing engine.
+#
+# Foundry requires linux/amd64 images and a numeric non-root USER.
+#
+# Build context: this directory, with the two wheels copied into ./wheels:
+#   pyroutingkit-*-manylinux*x86_64.whl  (from pyroutingkit's cibuildwheel CI)
+#   hum_router-*-py3-*.whl        (uv build in hum-router)
+#
+#   docker build --platform linux/amd64 -t hum-router-cm .
+#
+# Graph access (see bootstrap.py): mount the T2 graph dataset as a module
+# resource aliased 'graph' (preferred), or set FOUNDRY_URL + FOUNDRY_TOKEN
+# + GRAPH_DATASET_RID, or pre-mount files at /data/graph.
+
+FROM --platform=linux/amd64 python:3.12-slim
+
+# Foundry compute modules require a non-root user
+RUN useradd --uid 5000 --create-home user
+WORKDIR /app
+
+COPY wheels/ /tmp/wheels/
+RUN pip install --no-cache-dir \
+        /tmp/wheels/*.whl \
+        foundry-compute-modules \
+        requests \
+    && rm -rf /tmp/wheels
+
+COPY app.py bootstrap.py /app/
+
+RUN mkdir -p /data/graph && chown -R 5000:5000 /data /app
+USER 5000
+
+ENTRYPOINT ["python", "/app/app.py"]