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

open_pharma_plugins_territory_alignment/tools/ta_cluster.py

@@ -0,0 +1,247 @@
+"""ta_cluster — visit clusters and sequencing (operational mode)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class AppointmentArg(BaseModel):
+    hcp_id: str = Field(description="HCP with a fixed appointment")
+    date: str = Field(description="ISO date, e.g. '2026-08-25'")
+    time: str = Field(default="09:00", description="HH:MM, e.g. '10:00'")
+
+
+class ClusterArgs(BaseModel):
+    rep_id: str = Field(description="Rep to build a visit plan for")
+    period: str = Field(
+        default="next_week",
+        description="Planning period: 'next_week', 'next_month', or ISO week '2026-W35'",
+    )
+    appointments: list[AppointmentArg] = Field(
+        default_factory=list, description="Fixed appointments to schedule around"
+    )
+    max_daily_travel_min: int = Field(default=120, description="Max travel minutes per day")
+    remote_threshold_min: int = Field(default=60, description="One-way travel above this suggests a remote alternative")
+
+
+TOOL: dict[str, Any] = {
+    "name": "ta_cluster",
+    "description": (
+        "Build a visit plan for a rep: cluster their assigned HCPs "
+        "geographically, sequence visits within each cluster using a "
+        "nearest-neighbor route, and flag remote alternatives where travel "
+        "exceeds the threshold. Requires territory data to be loaded and at "
+        "least one alignment scenario to exist (uses the latest by default)."
+    ),
+    "args": ClusterArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+
+    from ..data import get_hcps, get_reps, is_loaded, list_scenarios, load_all, load_scenario
+    from ..geo import centroid, grid_cluster, haversine, nearest_neighbor_route, travel_minutes, two_opt_improve
+    from ..models import RemoteAlternative, VisitCluster, VisitPlan, VisitStop
+
+    if not is_loaded():
+        load_all()
+
+    rep_id = arguments["rep_id"]
+    period = arguments.get("period", "next_week")
+    remote_threshold = arguments.get("remote_threshold_min", 60)
+    max_daily_travel = arguments.get("max_daily_travel_min", 120)
+    appointments_raw = arguments.get("appointments", [])
+
+    reps = get_reps()
+    rep = next((r for r in reps if r.rep_id == rep_id), None)
+    if rep is None:
+        return [{"type": "text", "text": json.dumps({"error": f"Rep '{rep_id}' not found."})}]
+
+    scenarios = list_scenarios()
+    if not scenarios:
+        return [{"type": "text", "text": json.dumps({"error": "No alignment scenario found. Run ta_align first."})}]
+
+    latest = load_scenario(scenarios[-1]["name"])
+    if latest is None:
+        return [{"type": "text", "text": json.dumps({"error": "Could not load latest scenario."})}]
+
+    rep_hcp_ids = {a["hcp_id"] for a in latest.get("assignments", []) if a["primary_rep"] == rep_id}
+
+    hcps = get_hcps()
+    hcp_map = {h.hcp_id: h for h in hcps}
+    rep_hcps = [hcp_map[hid] for hid in rep_hcp_ids if hid in hcp_map]
+
+    if not rep_hcps:
+        return [
+            {
+                "type": "text",
+                "text": json.dumps({"error": f"No HCPs assigned to rep '{rep_id}' in the latest scenario."}),
+            }
+        ]
+
+    visitable = [h for h in rep_hcps if h.consent_visit]
+
+    geo_hcps = [(h.lat, h.lng, h.hcp_id) for h in visitable if h.lat is not None and h.lng is not None]
+    non_geo = [h for h in visitable if h.lat is None or h.lng is None]
+
+    appointment_hcp_ids: dict[str, str] = {}
+    for appt in appointments_raw:
+        hid = appt["hcp_id"] if isinstance(appt, dict) else appt.hcp_id
+        date = appt["date"] if isinstance(appt, dict) else appt.date
+        appointment_hcp_ids[hid] = date
+
+    days = list(rep.available_days) if rep.available_days else ["mon", "tue", "wed", "thu", "fri"]
+    max_calls = rep.max_daily_calls
+
+    clusters_out: list[VisitCluster] = []
+    sequence_out: list[VisitStop] = []
+    remote_out: list[RemoteAlternative] = []
+    total_km = 0.0
+
+    if geo_hcps:
+        cluster_ids = grid_cluster(geo_hcps, target_per_cluster=min(max_calls, 6))
+
+        split_clusters: list[list[str]] = []
+        for id_list in cluster_ids:
+            while len(id_list) > max_calls:
+                split_clusters.append(id_list[:max_calls])
+                id_list = id_list[max_calls:]
+            split_clusters.append(id_list)
+
+        appointment_day_map = _map_appointments_to_days(appointment_hcp_ids, days)
+
+        day_assignments: dict[int, str] = {}
+        for ci, id_list in enumerate(split_clusters):
+            for hid in id_list:
+                if hid in appointment_day_map:
+                    day_assignments[ci] = appointment_day_map[hid]
+                    break
+
+        for ci, id_list in enumerate(split_clusters):
+            cluster_hcps = [hcp_map[hid] for hid in id_list if hid in hcp_map]
+            points = [(h.lat, h.lng) for h in cluster_hcps if h.lat is not None and h.lng is not None]
+
+            if not points:
+                continue
+
+            start = (rep.base_lat, rep.base_lng)
+            order, route_km = nearest_neighbor_route(points, start=start)
+            order, route_km = two_opt_improve(points, order)
+
+            route_min = sum(
+                travel_minutes(
+                    haversine(
+                        points[order[i]][0],
+                        points[order[i]][1],
+                        points[order[i + 1]][0],
+                        points[order[i + 1]][1],
+                    )
+                )
+                for i in range(len(order) - 1)
+            )
+
+            total_km += route_km
+
+            c_lat, c_lng = centroid(points)
+            cid = f"C{ci + 1:02d}"
+
+            if ci in day_assignments:
+                day = day_assignments[ci]
+            else:
+                day = days[ci % len(days)]
+
+            warning = ""
+            if route_min > max_daily_travel:
+                warning = f"route travel {route_min:.0f} min exceeds {max_daily_travel} min daily limit"
+
+            clusters_out.append(
+                VisitCluster(
+                    cluster_id=cid,
+                    hcp_ids=id_list,
+                    centroid_lat=round(c_lat, 4),
+                    centroid_lng=round(c_lng, 4),
+                    estimated_route_km=round(route_km, 1),
+                    estimated_travel_min=round(route_min, 1),
+                    hcp_count=len(id_list),
+                    suggested_day=day,
+                    travel_warning=warning,
+                )
+            )
+
+            prev_point = start
+            for visit_i, idx in enumerate(order):
+                h = cluster_hcps[idx]
+                hop_km = haversine(prev_point[0], prev_point[1], points[idx][0], points[idx][1])
+                sequence_out.append(
+                    VisitStop(
+                        hcp_id=h.hcp_id,
+                        hcp_name=h.name,
+                        visit_order=visit_i + 1,
+                        cluster_id=cid,
+                        lat=points[idx][0],
+                        lng=points[idx][1],
+                        travel_km_from_previous=round(hop_km, 1),
+                    )
+                )
+                prev_point = points[idx]
+
+                one_way = travel_minutes(haversine(rep.base_lat, rep.base_lng, h.lat, h.lng))
+                if one_way > remote_threshold:
+                    remote_out.append(
+                        RemoteAlternative(
+                            hcp_id=h.hcp_id,
+                            hcp_name=h.name,
+                            distance_km=round(haversine(rep.base_lat, rep.base_lng, h.lat, h.lng), 1),
+                            reason=f"one-way travel {one_way:.0f} min exceeds {remote_threshold} min threshold",
+                        )
+                    )
+
+    for h in non_geo:
+        sequence_out.append(
+            VisitStop(
+                hcp_id=h.hcp_id,
+                hcp_name=h.name,
+                visit_order=len(sequence_out) + 1,
+                cluster_id="UNGEO",
+                lat=None,
+                lng=None,
+                travel_km_from_previous=0.0,
+            )
+        )
+
+    plan = VisitPlan(
+        rep_id=rep_id,
+        rep_name=rep.name,
+        period=period,
+        clusters=clusters_out,
+        visit_sequence=sequence_out,
+        remote_alternatives=remote_out,
+        total_route_km=round(total_km, 1),
+        total_hcps=len(visitable),
+        remote_count=len(remote_out),
+    )
+
+    return [{"type": "text", "text": json.dumps(json.loads(plan.model_dump_json()), indent=2)}]
+
+
+def _map_appointments_to_days(
+    appointment_hcp_ids: dict[str, str],
+    available_days: list[str],
+) -> dict[str, str]:
+    """Map appointment HCP IDs to a day-of-week string based on the ISO date."""
+    import datetime
+
+    day_names = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
+    result: dict[str, str] = {}
+    for hcp_id, date_str in appointment_hcp_ids.items():
+        try:
+            dt = datetime.date.fromisoformat(date_str)
+            dow = day_names[dt.weekday()]
+            if dow in available_days:
+                result[hcp_id] = dow
+        except ValueError:
+            continue
+    return result

open_pharma_plugins_territory_alignment/tools/ta_compare.py

@@ -0,0 +1,173 @@
+"""ta_compare — side-by-side scenario comparison."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class CompareArgs(BaseModel):
+    scenarios: list[str] = Field(
+        min_length=2,
+        max_length=4,
+        description="Names of 2-4 saved scenarios to compare",
+    )
+    focus: str = Field(
+        default="",
+        description="Objective to highlight: workload, travel, disruption, or coverage",
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "ta_compare",
+    "description": (
+        "Compare 2-4 saved territory alignment scenarios side by side. "
+        "Returns an objectives matrix, Pareto analysis, per-HCP movement "
+        "summary, and a plain-language trade-off narrative. Use after "
+        "generating multiple scenarios with ta_align."
+    ),
+    "args": CompareArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+
+    from ..data import load_scenario
+
+    names = arguments["scenarios"]
+    focus = arguments.get("focus", "")
+
+    scenarios: dict[str, dict[str, Any]] = {}
+    for name in names:
+        data = load_scenario(name)
+        if data is None:
+            return [
+                {"type": "text", "text": json.dumps({"error": f"Scenario '{name}' not found. Run ta_align first."})}
+            ]
+        scenarios[name] = data
+
+    comparison_table = _build_comparison_table(scenarios)
+    pareto = _pareto_analysis(scenarios)
+    movements = _movement_summary(scenarios)
+    narrative = _build_narrative(scenarios, comparison_table, pareto, focus)
+
+    result = {
+        "comparison_table": comparison_table,
+        "pareto": pareto,
+        "movement_summary": movements,
+        "trade_off_narrative": narrative,
+    }
+    return [{"type": "text", "text": json.dumps(result, indent=2)}]
+
+
+def _build_comparison_table(
+    scenarios: dict[str, dict[str, Any]],
+) -> dict[str, dict[str, float]]:
+    table: dict[str, dict[str, float]] = {}
+    for name, data in scenarios.items():
+        obj = data.get("objectives", {})
+        table[name] = {
+            "workload_balance": obj.get("workload_balance", 0),
+            "travel_efficiency": obj.get("travel_efficiency", 0),
+            "disruption": obj.get("disruption", 0),
+            "coverage": obj.get("coverage", 0),
+            "composite": obj.get("composite", 0),
+        }
+    return table
+
+
+def _pareto_analysis(
+    scenarios: dict[str, dict[str, Any]],
+) -> dict[str, Any]:
+    names = list(scenarios.keys())
+    objectives_keys = ["workload_balance", "travel_efficiency", "disruption", "coverage"]
+
+    scores: dict[str, list[float]] = {}
+    for name, data in scenarios.items():
+        obj = data.get("objectives", {})
+        scores[name] = [obj.get(k, 0) for k in objectives_keys]
+
+    dominated: set[str] = set()
+    for i, n1 in enumerate(names):
+        for n2 in names[i + 1 :]:
+            s1, s2 = scores[n1], scores[n2]
+            if all(a <= b for a, b in zip(s1, s2)) and any(a < b for a, b in zip(s1, s2)):
+                dominated.add(n2)
+            elif all(a <= b for a, b in zip(s2, s1)) and any(a < b for a, b in zip(s2, s1)):
+                dominated.add(n1)
+
+    optimal = [n for n in names if n not in dominated]
+
+    return {
+        "pareto_optimal": optimal,
+        "dominated": list(dominated),
+    }
+
+
+def _movement_summary(
+    scenarios: dict[str, dict[str, Any]],
+) -> dict[str, Any]:
+    names = list(scenarios.keys())
+    if len(names) < 2:
+        return {}
+
+    rep_maps: dict[str, dict[str, str]] = {}
+    for name, data in scenarios.items():
+        rep_maps[name] = {a["hcp_id"]: a["primary_rep"] for a in data.get("assignments", [])}
+
+    pairwise: dict[str, dict[str, int]] = {}
+    for i, n1 in enumerate(names):
+        for n2 in names[i + 1 :]:
+            m1, m2 = rep_maps[n1], rep_maps[n2]
+            common = set(m1.keys()) & set(m2.keys())
+            moved = sum(1 for h in common if m1[h] != m2[h])
+            key = f"{n1}_vs_{n2}"
+            pairwise[key] = {
+                "moved": moved,
+                "total": len(common),
+                "pct_moved": round(moved / max(len(common), 1) * 100, 1),
+            }
+
+    return pairwise
+
+
+def _build_narrative(
+    scenarios: dict[str, dict[str, Any]],
+    table: dict[str, dict[str, float]],
+    pareto: dict[str, Any],
+    focus: str,
+) -> str:
+    names = list(table.keys())
+    if len(names) < 2:
+        return "Need at least 2 scenarios to compare."
+
+    parts: list[str] = []
+
+    optimal = pareto.get("pareto_optimal", [])
+    if optimal:
+        parts.append(f"Pareto-optimal scenario(s): {', '.join(optimal)}.")
+
+    dominated = pareto.get("dominated", [])
+    if dominated:
+        parts.append(f"Dominated (worse on all objectives): {', '.join(dominated)}.")
+
+    best_composite = min(names, key=lambda n: table[n]["composite"])
+    parts.append(f"Lowest composite score: {best_composite} ({table[best_composite]['composite']:.3f}).")
+
+    if focus and focus in ("workload", "travel", "disruption", "coverage"):
+        key_map = {
+            "workload": "workload_balance",
+            "travel": "travel_efficiency",
+            "disruption": "disruption",
+            "coverage": "coverage",
+        }
+        fk = key_map[focus]
+        best = min(names, key=lambda n: table[n][fk])
+        worst = max(names, key=lambda n: table[n][fk])
+        parts.append(
+            f"Focus '{focus}': best = {best} ({table[best][fk]:.3f}), worst = {worst} ({table[worst][fk]:.3f})."
+        )
+
+    return " ".join(parts)

open_pharma_plugins_territory_alignment/tools/ta_evaluate.py

@@ -0,0 +1,119 @@
+"""ta_evaluate — detailed scoring breakdown for a saved scenario."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class EvaluateArgs(BaseModel):
+    scenario_name: str = Field(description="Name of a saved scenario to evaluate")
+
+
+TOOL: dict[str, Any] = {
+    "name": "ta_evaluate",
+    "description": (
+        "Evaluate a saved territory alignment scenario in detail. Returns "
+        "objective scores, per-rep territory breakdown (HCP count, potential, "
+        "workload, travel, segment coverage), relationship continuity stats, "
+        "and workload distribution analysis. Call ta_align first to create a scenario."
+    ),
+    "args": EvaluateArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+
+    from ..data import get_hcps, is_loaded, load_all, load_scenario
+
+    name = arguments["scenario_name"]
+    scenario = load_scenario(name)
+
+    if scenario is None:
+        return [
+            {
+                "type": "text",
+                "text": json.dumps({"error": f"Scenario '{name}' not found. Run ta_align first or check ta_status."}),
+            }
+        ]
+
+    if not is_loaded():
+        load_all()
+
+    objectives = scenario.get("objectives", {})
+    territories = scenario.get("territory_summary", [])
+    assignments = scenario.get("assignments", [])
+    unassigned = scenario.get("unassigned", [])
+
+    workloads = [t["workload_hours_weekly"] for t in territories]
+    travel_hours = [t["travel_hours_weekly"] for t in territories]
+
+    kept = sum(t.get("relationships_kept", 0) for t in territories)
+    new = sum(t.get("relationships_new", 0) for t in territories)
+    total_rel = kept + new
+
+    evaluation = {
+        "scenario_name": name,
+        "objectives": objectives,
+        "territory_details": territories,
+        "coverage_analysis": _coverage_analysis(assignments, unassigned, get_hcps()),
+        "relationship_continuity": {
+            "kept": kept,
+            "new": new,
+            "pct_kept": round(kept / max(total_rel, 1) * 100, 1),
+        },
+        "workload_distribution": {
+            "min": round(min(workloads), 1) if workloads else 0,
+            "max": round(max(workloads), 1) if workloads else 0,
+            "median": round(sorted(workloads)[len(workloads) // 2], 1) if workloads else 0,
+            "std_dev": round(_std(workloads), 2) if workloads else 0,
+        },
+        "travel_distribution": {
+            "min_hours": round(min(travel_hours), 2) if travel_hours else 0,
+            "max_hours": round(max(travel_hours), 2) if travel_hours else 0,
+            "median_hours": round(sorted(travel_hours)[len(travel_hours) // 2], 2) if travel_hours else 0,
+        },
+        "unassigned": unassigned,
+    }
+
+    return [{"type": "text", "text": json.dumps(evaluation, indent=2)}]
+
+
+def _coverage_analysis(
+    assignments: list[dict],
+    unassigned: list[dict],
+    all_hcps: list[Any],
+) -> dict[str, Any]:
+    from ..models import HCP
+
+    segment_totals: dict[str, int] = {}
+    for h in all_hcps:
+        seg = h.segment if isinstance(h, HCP) else "unknown"
+        segment_totals[seg] = segment_totals.get(seg, 0) + 1
+
+    segment_covered: dict[str, int] = {}
+    for a in assignments:
+        seg = a.get("segment", "unknown")
+        segment_covered[seg] = segment_covered.get(seg, 0) + 1
+
+    result: dict[str, Any] = {}
+    for seg in sorted(segment_totals.keys()):
+        total = segment_totals[seg]
+        covered = segment_covered.get(seg, 0)
+        result[seg] = {
+            "total": total,
+            "covered": covered,
+            "unassigned": total - covered,
+            "pct": round(covered / max(total, 1) * 100, 1),
+        }
+    return result
+
+
+def _std(values: list[float]) -> float:
+    if len(values) < 2:
+        return 0.0
+    mean = sum(values) / len(values)
+    variance = sum((v - mean) ** 2 for v in values) / len(values)
+    return variance**0.5

open_pharma_plugins_territory_alignment/tools/ta_status.py

@@ -0,0 +1,34 @@
+"""ta_status — data overview and scenario inventory."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class StatusArgs(BaseModel):
+    pass
+
+
+TOOL: dict[str, Any] = {
+    "name": "ta_status",
+    "description": (
+        "Show the current state of loaded territory data: HCP and rep counts, "
+        "segment distribution, geocoding coverage, unassigned HCPs, and a list "
+        "of saved scenarios with timestamps. Call this first to confirm data is "
+        "loaded before running ta_align or ta_cluster."
+    ),
+    "args": StatusArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+
+    from ..data import get_summary, is_loaded, load_all
+
+    if not is_loaded():
+        load_all()
+
+    return [{"type": "text", "text": json.dumps(get_summary(), indent=2)}]