open-pharma-plugins 2.2.0__py3-none-any.whl

open_pharma_plugins_territory_alignment/__init__.py

@@ -0,0 +1,14 @@
+from mcp_framework import build_registry
+
+__version__ = "1.0.1"
+
+SPECS, get_handler, list_tools = build_registry(__name__, ["tools"])
+
+USAGE_NOTE = (
+    "Territory Alignment assigns HCPs to representatives (strategic mode) "
+    "and plans visit routes (operational mode), balancing workload, travel, "
+    "relationship continuity, and priority coverage. Supports named scenario "
+    "comparison for what-if planning."
+)
+
+SYSTEM_DEPS = []

open_pharma_plugins_territory_alignment/__main__.py

@@ -0,0 +1,11 @@
+from pathlib import Path
+
+from mcp_framework import run_main
+
+
+def main() -> None:
+    run_main(__package__ or Path(__file__).resolve().parent.name)
+
+
+if __name__ == "__main__":
+    main()

open_pharma_plugins_territory_alignment/data.py

@@ -0,0 +1,300 @@
+"""Data loading, scenario persistence, and fixture fallback."""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from pathlib import Path
+from typing import Any
+
+from shared.filesystem import atomic_write_json, atomic_write_text, ensure_private_dir
+
+from .models import HCP, Constraint, CurrentAssignment, NewHire, Rep
+
+
+def _data_dir() -> Path:
+    from shared.env import get_env
+
+    custom = get_env("OPEN_PHARMA_TA_DATA_DIR", "")
+    if custom:
+        return Path(custom)
+    return Path(__file__).parent / "fixtures"
+
+
+def _scenarios_dir() -> Path:
+    from shared.env import get_env
+
+    custom = get_env("OPEN_PHARMA_TA_SCENARIOS_DIR", "")
+    if custom:
+        d = Path(custom)
+    else:
+        d = Path.home() / ".open-pharma-plugins" / "territory-alignment" / "scenarios"
+    return ensure_private_dir(d)
+
+
+# -- state --
+
+_hcps: list[HCP] = []
+_reps: list[Rep] = []
+_current_alignment: list[CurrentAssignment] = []
+_constraints: list[Constraint] = []
+_loaded: bool = False
+
+
+def is_loaded() -> bool:
+    return _loaded
+
+
+def load_all() -> dict[str, Any]:
+    """Load all CSV files from the data directory."""
+    global _hcps, _reps, _current_alignment, _constraints, _loaded
+
+    data_dir = _data_dir()
+    _hcps = _load_hcps(data_dir / "hcps.csv")
+    _reps = _load_reps(data_dir / "reps.csv")
+    _current_alignment = _load_alignment(data_dir / "current_alignment.csv")
+    _constraints = _load_constraints(data_dir / "constraints.csv")
+    _loaded = True
+
+    return get_summary()
+
+
+def get_hcps() -> list[HCP]:
+    return list(_hcps)
+
+
+def get_reps(
+    vacancies: list[str] | None = None,
+    new_hires: list[NewHire] | None = None,
+) -> list[Rep]:
+    """Return reps with vacancies removed and new hires added."""
+    vacancy_set = set(vacancies or [])
+    result = [r for r in _reps if r.rep_id not in vacancy_set]
+    for nh in new_hires or []:
+        result.append(
+            Rep(
+                rep_id=nh.rep_id,
+                name=nh.name,
+                base_lat=nh.base_lat,
+                base_lng=nh.base_lng,
+                product_expertise=nh.product_expertise,
+                max_weekly_hours=nh.max_weekly_hours,
+            )
+        )
+    return result
+
+
+def get_current_alignment() -> list[CurrentAssignment]:
+    return list(_current_alignment)
+
+
+def get_constraints() -> list[Constraint]:
+    return list(_constraints)
+
+
+def get_summary() -> dict[str, Any]:
+    if not _loaded:
+        return {"loaded": False}
+
+    segments: dict[str, int] = {}
+    geo_count = 0
+    for h in _hcps:
+        segments[h.segment] = segments.get(h.segment, 0) + 1
+        if h.lat is not None and h.lng is not None:
+            geo_count += 1
+
+    assigned_hcps = {a.hcp_id for a in _current_alignment}
+    unassigned = [h.hcp_id for h in _hcps if h.hcp_id not in assigned_hcps]
+
+    return {
+        "loaded": True,
+        "data_source": str(_data_dir()),
+        "hcp_count": len(_hcps),
+        "rep_count": len(_reps),
+        "alignment_count": len(_current_alignment),
+        "constraint_count": len(_constraints),
+        "segments": segments,
+        "geocoded_pct": round(geo_count / max(len(_hcps), 1) * 100, 1),
+        "unassigned_hcps": unassigned,
+        "scenarios": list_scenarios(),
+    }
+
+
+# -- scenarios --
+
+
+def _sanitize_scenario_name(name: str) -> str:
+    import re
+
+    clean = re.sub(r"[^a-zA-Z0-9_\-]", "_", name)
+    if not clean:
+        raise ValueError("scenario name must contain at least one alphanumeric character")
+    return clean
+
+
+def save_scenario(name: str, result: dict[str, Any]) -> str:
+    safe = _sanitize_scenario_name(name)
+    d = _scenarios_dir()
+    json_path = d / f"{safe}.json"
+    atomic_write_json(json_path, result)
+    _write_scenario_csvs(d, safe, result)
+    return str(json_path)
+
+
+def _write_scenario_csvs(directory: Path, name: str, result: dict[str, Any]) -> None:
+    assignments = result.get("assignments", [])
+    if assignments:
+        _ASSIGN_COLS = [
+            "hcp_id",
+            "hcp_name",
+            "primary_rep",
+            "previous_rep",
+            "is_changed",
+            "change_reason",
+            "estimated_travel_min",
+            "estimated_annual_visits",
+            "segment",
+            "tier",
+        ]
+        a_path = directory / f"{name}_assignments.csv"
+        buffer = io.StringIO(newline="")
+        writer = csv.DictWriter(buffer, fieldnames=_ASSIGN_COLS, extrasaction="ignore")
+        writer.writeheader()
+        writer.writerows(assignments)
+        atomic_write_text(a_path, buffer.getvalue())
+
+    territories = result.get("territory_summary", [])
+    if territories:
+        _TERR_COLS = [
+            "rep_id",
+            "rep_name",
+            "hcp_count",
+            "total_potential",
+            "workload_hours_weekly",
+            "travel_hours_weekly",
+            "segment_high",
+            "segment_medium",
+            "segment_low",
+            "relationships_kept",
+            "relationships_new",
+        ]
+        t_path = directory / f"{name}_territory_summary.csv"
+        buffer = io.StringIO(newline="")
+        writer = csv.DictWriter(buffer, fieldnames=_TERR_COLS, extrasaction="ignore")
+        writer.writeheader()
+        writer.writerows(territories)
+        atomic_write_text(t_path, buffer.getvalue())
+
+
+def load_scenario(name: str) -> dict[str, Any] | None:
+    path = _scenarios_dir() / f"{_sanitize_scenario_name(name)}.json"
+    if path.exists():
+        return json.loads(path.read_text())
+    return None
+
+
+def list_scenarios() -> list[dict[str, str]]:
+    result = []
+    for f in sorted(_scenarios_dir().glob("*.json")):
+        result.append({"name": f.stem, "file": str(f)})
+    return result
+
+
+# -- CSV loaders --
+
+
+def _load_hcps(path: Path) -> list[HCP]:
+    if not path.exists():
+        return []
+    rows: list[HCP] = []
+    with open(path, newline="") as f:
+        for raw in csv.DictReader(f):
+            _coerce_hcp(raw)
+            rows.append(HCP.model_validate(raw))
+    return rows
+
+
+def _coerce_hcp(raw: dict[str, Any]) -> None:
+    for field in ("lat", "lng", "annual_potential"):
+        if field in raw:
+            val = raw[field]
+            if not val:
+                raw[field] = None if field in ("lat", "lng") else 0.0
+            else:
+                raw[field] = float(val)
+    for field in ("consent_email", "consent_phone", "consent_visit"):
+        if field in raw:
+            raw[field] = raw[field].lower() in ("true", "1", "yes")
+    if "tier" in raw and raw["tier"]:
+        raw["tier"] = int(raw["tier"])
+    if "product_requirements" in raw:
+        val = raw["product_requirements"]
+        raw["product_requirements"] = [v.strip() for v in val.split(";")] if val else []
+    _coerce_extras(raw, _HCP_KNOWN_FIELDS)
+
+
+_HCP_KNOWN_FIELDS = set(HCP.model_fields.keys())
+
+
+def _load_reps(path: Path) -> list[Rep]:
+    if not path.exists():
+        return []
+    rows: list[Rep] = []
+    with open(path, newline="") as f:
+        for raw in csv.DictReader(f):
+            _coerce_rep(raw)
+            rows.append(Rep.model_validate(raw))
+    return rows
+
+
+def _coerce_rep(raw: dict[str, Any]) -> None:
+    for field in ("base_lat", "base_lng", "max_weekly_hours"):
+        if field in raw and raw[field]:
+            raw[field] = float(raw[field])
+    if "max_daily_calls" in raw and raw["max_daily_calls"]:
+        raw["max_daily_calls"] = int(raw["max_daily_calls"])
+    for list_field in ("product_expertise", "available_days"):
+        if list_field in raw:
+            val = raw[list_field]
+            raw[list_field] = [v.strip() for v in val.split(";")] if val else []
+
+
+def _load_alignment(path: Path) -> list[CurrentAssignment]:
+    if not path.exists():
+        return []
+    rows: list[CurrentAssignment] = []
+    with open(path, newline="") as f:
+        for raw in csv.DictReader(f):
+            rows.append(CurrentAssignment.model_validate(raw))
+    return rows
+
+
+def _load_constraints(path: Path) -> list[Constraint]:
+    if not path.exists():
+        return []
+    rows: list[Constraint] = []
+    with open(path, newline="") as f:
+        for raw in csv.DictReader(f):
+            rows.append(Constraint.model_validate(raw))
+    return rows
+
+
+def _coerce_extras(raw: dict[str, Any], known: set[str]) -> None:
+    for key in raw:
+        if key in known:
+            continue
+        val = raw[key]
+        if not isinstance(val, str) or not val:
+            continue
+        low = val.lower()
+        if low in ("true", "false"):
+            raw[key] = low == "true"
+            continue
+        try:
+            raw[key] = int(val)
+        except ValueError:
+            try:
+                raw[key] = float(val)
+            except ValueError:
+                pass

open_pharma_plugins_territory_alignment/fixtures/constraints.csv

@@ -0,0 +1,11 @@
+type,scope,value,description
+product_match,global,required,Rep must have product expertise matching HCP requirements
+account_grouping,account:A001,same_primary_rep,All HCPs in account A001 share one primary rep
+account_grouping,account:A005,same_primary_rep,All HCPs in account A005 share one primary rep
+account_grouping,account:A009,same_primary_rep,All HCPs in account A009 share one primary rep
+account_grouping,account:A013,same_primary_rep,All HCPs in account A013 share one primary rep
+account_grouping,account:A014,same_primary_rep,All HCPs in account A014 share one primary rep
+max_hcps_per_rep,global,18,No rep gets more than 18 HCPs
+frequency_cap,segment:high,2,Max weeks between visits for high-segment HCPs
+frequency_cap,segment:medium,4,Max weeks between visits for medium-segment HCPs
+frequency_cap,segment:low,8,Max weeks between visits for low-segment HCPs

open_pharma_plugins_territory_alignment/fixtures/current_alignment.csv

@@ -0,0 +1,81 @@
+hcp_id,primary_rep,secondary_rep
+H001,R001,
+H002,R001,
+H003,R001,
+H004,R002,
+H005,R001,
+H006,R001,
+H007,R002,
+H008,R001,
+H009,R002,
+H010,R001,
+H011,R001,
+H012,R001,
+H013,R002,
+H014,R001,
+H015,R001,
+H016,R002,
+H017,R001,
+H018,R002,
+H019,R001,
+H020,R002,
+H021,R003,
+H022,R003,
+H023,R003,
+H024,R003,
+H025,R003,
+H026,R003,
+H027,R004,
+H028,R004,
+H029,R003,
+H030,R003,
+H031,R004,
+H032,R003,
+H033,R004,
+H034,R003,
+H035,R004,
+H036,R004,
+H037,R004,
+H038,R003,
+H039,R004,
+H040,R003,
+H041,R005,
+H042,R005,
+H043,R006,
+H044,R005,
+H045,R005,
+H046,R006,
+H047,R005,
+H048,R005,
+H049,R005,
+H050,R006,
+H051,R005,
+H052,R006,
+H053,R005,
+H054,R005,
+H055,R006,
+H056,R005,
+H057,R006,
+H058,R005,
+H059,R006,
+H060,R006,
+H061,R007,
+H062,R008,
+H063,R007,
+H064,R007,
+H065,R007,
+H066,R008,
+H067,R007,
+H068,R008,
+H069,R007,
+H070,R007,
+H071,R007,
+H072,R008,
+H073,R007,
+H074,R007,
+H075,R007,
+H076,R008,
+H077,R007,
+H078,R008,
+H079,R007,
+H080,R008,

open_pharma_plugins_territory_alignment/fixtures/hcps.csv

@@ -0,0 +1,81 @@
+hcp_id,name,specialty,segment,tier,lat,lng,account_id,consent_email,consent_phone,consent_visit,annual_potential,product_requirements
+H001,Dr. Sarah Chen,oncology,high,1,40.7648,-73.9653,A001,true,true,true,95000,product_a
+H002,Dr. Michael Torres,cardiology,high,1,40.7505,-73.9764,A001,true,true,true,88000,product_b
+H003,Dr. Priya Sharma,oncology,high,1,40.7282,-74.0060,A001,true,true,true,82000,product_a
+H004,Dr. David Okafor,neurology,high,1,40.6892,-73.9857,A002,true,true,true,78000,product_a;product_b
+H005,Dr. Rachel Kim,cardiology,medium,2,40.7580,-73.9855,A001,true,true,true,45000,product_b
+H006,Dr. Thomas Wright,oncology,medium,2,40.7425,-73.9540,A002,true,false,true,42000,product_a
+H007,Dr. Amara Osei,immunology,medium,2,40.6945,-73.9565,A002,true,true,true,38000,product_b
+H008,Dr. Jennifer Liu,cardiology,medium,2,40.7614,-73.9776,A003,true,true,true,36000,product_a
+H009,Dr. Robert Patel,oncology,medium,2,40.6782,-73.9442,A002,true,true,true,34000,product_a;product_b
+H010,Dr. Fatima Al-Hassan,neurology,medium,2,40.7831,-73.9712,A003,true,true,true,32000,product_b
+H011,Dr. Andrew Nowak,oncology,low,3,40.7505,-73.9934,,true,true,true,12000,product_a
+H012,Dr. Maria Santos,cardiology,low,3,40.7261,-74.0014,,true,true,true,10000,product_b
+H013,Dr. Kevin Zhao,immunology,low,3,40.7112,-73.9505,,true,false,true,9000,product_a
+H014,Dr. Laura Becker,neurology,low,3,40.7400,-74.0055,,true,true,true,8500,product_b
+H015,Dr. Hassan Yusuf,primary_care,low,3,40.7680,-73.9510,,false,false,true,7000,product_a
+H016,Dr. Emily Strand,oncology,low,3,40.6800,-73.9750,,true,true,true,6500,product_a
+H017,Dr. Daniel Cho,cardiology,low,3,40.7527,-73.9772,,true,true,true,6000,product_b
+H018,Dr. Olivia Martin,primary_care,low,3,40.6950,-73.9300,,true,true,true,5500,product_a;product_b
+H019,Dr. Raj Gupta,oncology,low,3,40.7453,-73.9882,,true,true,true,5000,product_a
+H020,Dr. Susan O'Neill,immunology,low,3,40.7020,-73.9880,,true,true,true,4500,product_b
+H021,Dr. James Nakamura,oncology,high,1,40.7425,-74.0310,A004,true,true,true,92000,product_a
+H022,Dr. Lisa Johansson,immunology,high,1,40.7282,-74.0776,A004,true,true,true,85000,product_b
+H023,Dr. Wei Zhang,neurology,high,1,40.7178,-74.0431,A004,true,true,true,80000,product_a;product_b
+H024,Dr. Patricia Reyes,cardiology,high,1,40.7357,-74.0298,A005,true,true,true,76000,product_a
+H025,Dr. Mark Thompson,oncology,medium,2,40.7210,-74.0480,A004,true,true,true,44000,product_a
+H026,Dr. Anna Kowalski,immunology,medium,2,40.7480,-74.0280,A005,true,false,true,40000,product_b
+H027,Dr. Bryan Jackson,neurology,medium,2,40.7100,-74.0650,A005,true,true,true,37000,product_a
+H028,Dr. Diana Petrova,cardiology,medium,2,40.7320,-74.0720,,true,true,true,35000,product_b
+H029,Dr. George Fernandez,oncology,medium,2,40.7540,-74.0230,,true,true,true,33000,product_a;product_b
+H030,Dr. Helen Tran,immunology,medium,2,40.7060,-74.0120,,true,true,true,31000,product_b
+H031,Dr. Ivan Smirnov,neurology,low,3,40.7380,-74.0510,,true,true,true,11000,product_a
+H032,Dr. Karen Lee,oncology,low,3,40.7150,-74.0340,,true,true,true,9500,product_b
+H033,Dr. Nathan Cole,cardiology,low,3,40.7250,-74.0630,,true,true,true,8800,product_a
+H034,Dr. Priscilla Dubois,immunology,low,3,40.7450,-74.0180,,true,false,true,8000,product_b
+H035,Dr. Oscar Herrera,primary_care,low,3,40.7310,-74.0430,,false,false,true,7200,product_a
+H036,Dr. Yuki Tanaka,oncology,low,3,40.7200,-74.0550,,true,true,true,6800,product_a
+H037,Dr. Frank Bauer,neurology,low,3,40.7060,-74.0700,,true,true,true,5800,product_b
+H038,Dr. Gloria Vega,cardiology,low,3,40.7350,-74.0150,,true,true,true,5200,product_a;product_b
+H039,Dr. Henry Olsen,oncology,low,3,40.7470,-74.0350,,true,true,true,4800,product_a
+H040,Dr. Irene Costa,immunology,low,3,40.7120,-74.0260,,true,true,true,4200,product_b
+H041,Dr. Richard Muller,cardiology,high,1,40.7440,-74.1690,A006,true,true,true,90000,product_a
+H042,Dr. Sophia Andersen,oncology,high,1,40.7357,-74.1724,A006,true,true,true,86000,product_b
+H043,Dr. Charles Obi,neurology,high,1,40.7580,-74.2260,A007,true,true,true,79000,product_a;product_b
+H044,Dr. Nina Volkov,immunology,high,1,40.7282,-74.0776,A006,true,true,true,75000,product_a
+H045,Dr. Peter Hoffman,cardiology,medium,2,40.7200,-74.1730,A006,true,true,true,43000,product_b
+H046,Dr. Aisha Nkomo,oncology,medium,2,40.7610,-74.2100,A007,true,false,true,39000,product_a
+H047,Dr. Victor Ionescu,neurology,medium,2,40.7400,-74.1550,,true,true,true,36500,product_b
+H048,Dr. Stephanie Cruz,cardiology,medium,2,40.7500,-74.1850,A007,true,true,true,34500,product_a
+H049,Dr. Albert Schneider,oncology,medium,2,40.7100,-74.1600,,false,true,true,32500,product_a;product_b
+H050,Dr. Beatrice Adeyemi,immunology,medium,2,40.7650,-74.2350,A008,true,true,true,30500,product_b
+H051,Dr. Carl Lindqvist,cardiology,low,3,40.7300,-74.1900,,true,true,true,11500,product_a
+H052,Dr. Diane Washington,oncology,low,3,40.7450,-74.2000,,true,true,true,10500,product_b
+H053,Dr. Eduardo Silva,neurology,low,3,40.7550,-74.1750,,true,true,true,9200,product_a
+H054,Dr. Fiona McCarthy,immunology,low,3,40.7150,-74.1650,,true,false,true,8200,product_b
+H055,Dr. Greg Antonov,primary_care,low,3,40.7350,-74.2100,,false,false,true,7100,product_a
+H056,Dr. Hannah Eriksson,oncology,low,3,40.7250,-74.1580,,true,true,true,6200,product_a
+H057,Dr. Ian Fletcher,cardiology,low,3,40.7480,-74.1930,,true,true,true,5600,product_b
+H058,Dr. Julia Romano,neurology,low,3,40.7050,-74.1700,,true,true,true,5100,product_a;product_b
+H059,Dr. Kyle Abrams,oncology,low,3,40.7380,-74.2050,,true,true,true,4600,product_a
+H060,Dr. Monica Dupont,immunology,low,3,40.7520,-74.2200,,true,true,true,4100,product_b
+H061,Dr. Antonio Morales,oncology,high,1,40.8580,-73.8690,A009,true,true,true,91000,product_a
+H062,Dr. Natalie Bergstrom,neurology,high,1,40.8128,-73.9291,A009,true,true,true,84000,product_b
+H063,Dr. Philip Owusu,cardiology,high,1,40.8449,-73.8648,A009,true,true,true,77000,product_a;product_b
+H064,Dr. Camille Bonnet,immunology,high,1,40.9176,-73.8984,A010,true,true,true,74000,product_a
+H065,Dr. Samuel Okonkwo,oncology,medium,2,40.8400,-73.8450,A009,true,true,true,42000,product_a
+H066,Dr. Teresa Ramirez,neurology,medium,2,40.8200,-73.9100,,true,false,true,38500,product_b
+H067,Dr. Ulrich Weber,cardiology,medium,2,40.8650,-73.8880,,true,true,true,36000,product_a
+H068,Dr. Vanessa Boyd,oncology,medium,2,40.8000,-73.9350,A010,true,true,true,34000,product_b
+H069,Dr. William Fraser,immunology,medium,2,40.8300,-73.8750,,false,true,true,32000,product_a;product_b
+H070,Dr. Xena Papadopoulos,neurology,medium,2,40.9050,-73.9100,A010,true,true,true,30000,product_b
+H071,Dr. Yosef Abadi,oncology,low,3,40.8550,-73.8600,,true,true,true,11200,product_a
+H072,Dr. Zoe Campbell,cardiology,low,3,40.8100,-73.9200,,true,true,true,10000,product_b
+H073,Dr. Adam Kowalczyk,neurology,low,3,40.8700,-73.8950,,true,true,true,9100,product_a
+H074,Dr. Bella Nguyen,immunology,low,3,40.8350,-73.8500,,true,false,true,7800,product_b
+H075,Dr. Cedric Dumont,primary_care,low,3,40.8950,-73.9000,,false,false,true,6800,product_a
+H076,Dr. Dina Khalil,oncology,low,3,40.8250,-73.9400,,true,true,true,6300,product_a
+H077,Dr. Ethan Ross,cardiology,low,3,40.8480,-73.8780,,true,true,true,5400,product_b
+H078,Dr. Freya Lindgren,neurology,low,3,40.8150,-73.9050,,true,true,true,4900,product_a;product_b
+H079,Dr. Gavin Murphy,oncology,low,3,40.8600,-73.8850,,true,true,true,4400,product_a
+H080,Dr. Hana Takahashi,immunology,low,3,40.8050,-73.9150,,true,true,true,3800,product_b

open_pharma_plugins_territory_alignment/fixtures/reps.csv

@@ -0,0 +1,9 @@
+rep_id,name,base_lat,base_lng,product_expertise,max_weekly_hours,max_daily_calls,available_days
+R001,Alice Park,40.7580,-73.9855,product_a;product_b,40,8,mon;tue;wed;thu;fri
+R002,Bob Torres,40.6892,-73.9505,product_a;product_b,40,8,mon;tue;wed;thu;fri
+R003,Carol Wu,40.7282,-74.0431,product_a;product_b,40,8,mon;tue;wed;thu;fri
+R004,Dan Osei,40.7178,-74.0650,product_a,35,6,mon;tue;wed;thu
+R005,Elena Rossi,40.7440,-74.1690,product_a;product_b,40,8,mon;tue;wed;thu;fri
+R006,Frank Bauer,40.7580,-74.2260,product_b,40,8,mon;tue;wed;thu;fri
+R007,Grace Tanaka,40.8580,-73.8690,product_a;product_b,40,8,mon;tue;wed;thu;fri
+R008,Hank Morrison,40.8128,-73.9291,product_a;product_b,40,8,mon;tue;wed;thu;fri

open_pharma_plugins_territory_alignment/geo.py

@@ -0,0 +1,175 @@
+"""Geographic utilities: haversine, distance matrix, clustering, routing."""
+
+from __future__ import annotations
+
+import math
+
+_EARTH_RADIUS_KM = 6371.0
+
+
+def haversine(lat1: float, lng1: float, lat2: float, lng2: float) -> float:
+    """Great-circle distance in km between two points."""
+    lat1, lng1, lat2, lng2 = (math.radians(v) for v in (lat1, lng1, lat2, lng2))
+    dlat = lat2 - lat1
+    dlng = lng2 - lng1
+    a = math.sin(dlat / 2) ** 2 + math.cos(lat1) * math.cos(lat2) * math.sin(dlng / 2) ** 2
+    return 2 * _EARTH_RADIUS_KM * math.asin(math.sqrt(a))
+
+
+def travel_minutes(km: float, speed_kmh: float = 40.0) -> float:
+    """Rough urban travel estimate."""
+    if km <= 0:
+        return 0.0
+    return (km / speed_kmh) * 60.0
+
+
+def distance_matrix(
+    points: list[tuple[float, float]],
+) -> list[list[float]]:
+    """Pairwise haversine distances (km) between points."""
+    n = len(points)
+    mat = [[0.0] * n for _ in range(n)]
+    for i in range(n):
+        for j in range(i + 1, n):
+            d = haversine(points[i][0], points[i][1], points[j][0], points[j][1])
+            mat[i][j] = d
+            mat[j][i] = d
+    return mat
+
+
+def centroid(points: list[tuple[float, float]]) -> tuple[float, float]:
+    """Arithmetic mean of lat/lng points."""
+    if not points:
+        return 0.0, 0.0
+    lat = sum(p[0] for p in points) / len(points)
+    lng = sum(p[1] for p in points) / len(points)
+    return lat, lng
+
+
+def grid_cluster(
+    points: list[tuple[float, float, str]],
+    target_per_cluster: int = 6,
+) -> list[list[str]]:
+    """Simple grid-based clustering. Each point is (lat, lng, id).
+
+    Returns a list of clusters, each a list of point IDs.
+    """
+    if not points:
+        return []
+
+    lats = [p[0] for p in points]
+    lngs = [p[1] for p in points]
+    min_lat, max_lat = min(lats), max(lats)
+    min_lng, max_lng = min(lngs), max(lngs)
+
+    n = len(points)
+    num_clusters = max(1, round(n / target_per_cluster))
+    grid_side = max(1, math.ceil(math.sqrt(num_clusters)))
+
+    lat_step = (max_lat - min_lat + 1e-9) / grid_side
+    lng_step = (max_lng - min_lng + 1e-9) / grid_side
+
+    cells: dict[tuple[int, int], list[str]] = {}
+    for lat, lng, pid in points:
+        r = min(int((lat - min_lat) / lat_step), grid_side - 1)
+        c = min(int((lng - min_lng) / lng_step), grid_side - 1)
+        cells.setdefault((r, c), []).append(pid)
+
+    clusters = list(cells.values())
+
+    merged: list[list[str]] = []
+    for cluster in clusters:
+        if len(cluster) < 2 and merged:
+            merged[-1].extend(cluster)
+        else:
+            merged.append(cluster)
+
+    return merged if merged else [list(cells.values())[0]] if cells else []
+
+
+def nearest_neighbor_route(
+    points: list[tuple[float, float]],
+    start: tuple[float, float] | None = None,
+) -> tuple[list[int], float]:
+    """Nearest-neighbor TSP heuristic. Returns (visit_order, total_km)."""
+    if not points:
+        return [], 0.0
+    if len(points) == 1:
+        d = haversine(start[0], start[1], points[0][0], points[0][1]) if start else 0.0
+        return [0], d
+
+    n = len(points)
+    visited = [False] * n
+    order: list[int] = []
+    total_km = 0.0
+
+    if start:
+        dists = [haversine(start[0], start[1], p[0], p[1]) for p in points]
+        current_idx = min(range(n), key=lambda i: dists[i])
+        total_km += dists[current_idx]
+    else:
+        current_idx = 0
+
+    visited[current_idx] = True
+    order.append(current_idx)
+
+    for _ in range(n - 1):
+        best_dist = float("inf")
+        best_idx = -1
+        for j in range(n):
+            if visited[j]:
+                continue
+            d = haversine(
+                points[current_idx][0],
+                points[current_idx][1],
+                points[j][0],
+                points[j][1],
+            )
+            if d < best_dist:
+                best_dist = d
+                best_idx = j
+        visited[best_idx] = True
+        order.append(best_idx)
+        total_km += best_dist
+        current_idx = best_idx
+
+    return order, total_km
+
+
+def two_opt_improve(
+    points: list[tuple[float, float]],
+    route: list[int],
+    max_iterations: int = 100,
+) -> tuple[list[int], float]:
+    """Improve a route using 2-opt swaps."""
+    n = len(route)
+    if n < 4:
+        total = sum(
+            haversine(points[route[i]][0], points[route[i]][1], points[route[i + 1]][0], points[route[i + 1]][1])
+            for i in range(n - 1)
+        )
+        return route, total
+
+    def route_distance(r: list[int]) -> float:
+        return sum(
+            haversine(points[r[i]][0], points[r[i]][1], points[r[i + 1]][0], points[r[i + 1]][1])
+            for i in range(len(r) - 1)
+        )
+
+    best = list(route)
+    best_dist = route_distance(best)
+
+    for _ in range(max_iterations):
+        improved = False
+        for i in range(1, n - 1):
+            for j in range(i + 1, n):
+                new_route = best[:i] + best[i : j + 1][::-1] + best[j + 1 :]
+                new_dist = route_distance(new_route)
+                if new_dist < best_dist - 0.01:
+                    best = new_route
+                    best_dist = new_dist
+                    improved = True
+        if not improved:
+            break
+
+    return best, best_dist