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

open_pharma_plugins_territory_alignment/solver.py

@@ -0,0 +1,504 @@
+"""Assignment solver: greedy seed + swap-based local search."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .geo import haversine, travel_minutes
+from .models import (
+    HCP,
+    AssignmentResult,
+    Constraint,
+    CurrentAssignment,
+    ObjectiveWeights,
+    Override,
+    Rep,
+    ScenarioResult,
+    TerritorySummary,
+    UnassignedHCP,
+)
+from .scoring import score_alignment
+
+
+def solve(
+    hcps: list[HCP],
+    reps: list[Rep],
+    current_alignment: list[CurrentAssignment],
+    constraints: list[Constraint],
+    weights: ObjectiveWeights,
+    overrides: list[Override] | None = None,
+    lock_reps: list[str] | None = None,
+    scenario_name: str = "unnamed",
+    max_iterations: int = 2000,
+) -> ScenarioResult:
+    """Run greedy assignment + local search optimisation."""
+    hcp_map = {h.hcp_id: h for h in hcps}
+    rep_map = {r.rep_id: r for r in reps}
+    current_map = {a.hcp_id: a.primary_rep for a in current_alignment}
+    override_map = {o.hcp_id: o.rep_id for o in (overrides or [])}
+    locked = set(lock_reps or [])
+    max_per_rep = _get_max_per_rep(constraints)
+    account_groups = _get_account_groups(constraints, hcps)
+
+    locked_hcps: set[str] = set()
+    for hcp_id, rep_id in current_map.items():
+        if rep_id in locked:
+            locked_hcps.add(hcp_id)
+    for hcp_id in override_map:
+        locked_hcps.add(hcp_id)
+
+    assignment: dict[str, str] = {}
+    rep_counts: dict[str, int] = {r.rep_id: 0 for r in reps}
+    rep_workloads: dict[str, float] = {r.rep_id: 0.0 for r in reps}
+    unassigned: list[UnassignedHCP] = []
+
+    for hcp_id, rep_id in override_map.items():
+        if hcp_id in hcp_map and rep_id in rep_map:
+            assignment[hcp_id] = rep_id
+            rep_counts[rep_id] = rep_counts.get(rep_id, 0) + 1
+            rep_workloads[rep_id] = rep_workloads.get(rep_id, 0.0) + _hcp_weekly_hours(hcp_map[hcp_id])
+
+    for hcp_id in locked_hcps:
+        if hcp_id not in assignment and hcp_id in current_map:
+            rep_id = current_map[hcp_id]
+            if rep_id in rep_map:
+                assignment[hcp_id] = rep_id
+                rep_counts[rep_id] = rep_counts.get(rep_id, 0) + 1
+                rep_workloads[rep_id] = rep_workloads.get(rep_id, 0.0) + _hcp_weekly_hours(hcp_map[hcp_id])
+
+    _assign_account_groups(
+        account_groups,
+        hcps,
+        reps,
+        assignment,
+        rep_counts,
+        rep_workloads,
+        constraints,
+        current_map,
+        max_per_rep,
+        rep_map,
+        locked_hcps,
+    )
+
+    remaining = [h for h in hcps if h.hcp_id not in assignment]
+    remaining.sort(key=lambda h: h.annual_potential, reverse=True)
+
+    for hcp in remaining:
+        best_rep = _best_eligible_rep(
+            hcp,
+            reps,
+            rep_counts,
+            rep_workloads,
+            constraints,
+            current_map,
+            max_per_rep,
+            rep_map,
+        )
+        if best_rep:
+            assignment[hcp.hcp_id] = best_rep
+            rep_counts[best_rep] = rep_counts.get(best_rep, 0) + 1
+            rep_workloads[best_rep] = rep_workloads.get(best_rep, 0.0) + _hcp_weekly_hours(hcp)
+        else:
+            unassigned.append(
+                UnassignedHCP(
+                    hcp_id=hcp.hcp_id,
+                    reason=_unassign_reason(hcp, reps, rep_counts, constraints, max_per_rep, rep_map),
+                )
+            )
+
+    iterations_used = _local_search(
+        assignment,
+        hcps,
+        reps,
+        constraints,
+        weights,
+        current_map,
+        locked_hcps,
+        max_per_rep,
+        hcp_map,
+        rep_map,
+        max_iterations,
+        account_groups,
+    )
+
+    assignments = _build_assignments(assignment, hcp_map, rep_map, current_map)
+    objectives = score_alignment(assignments, hcps, reps, weights)
+    territory = _build_territory_summary(assignments, hcp_map, rep_map, current_map)
+
+    return ScenarioResult(
+        scenario_name=scenario_name,
+        assignments=assignments,
+        territory_summary=territory,
+        objectives=objectives,
+        unassigned=unassigned,
+        weights_used=weights,
+        metadata={
+            "solver": "greedy_local_search",
+            "iterations": iterations_used,
+        },
+    )
+
+
+# -- greedy helpers --
+
+
+def _hcp_weekly_hours(hcp: HCP) -> float:
+    hours_per_visit = 1.0 if hcp.segment == "high" else 0.75 if hcp.segment == "medium" else 0.5
+    visits_per_year = 24 if hcp.segment == "high" else 12 if hcp.segment == "medium" else 6
+    return (hours_per_visit * visits_per_year) / 48.0
+
+
+def _best_eligible_rep(
+    hcp: HCP,
+    reps: list[Rep],
+    rep_counts: dict[str, int],
+    rep_workloads: dict[str, float],
+    constraints: list[Constraint],
+    current_map: dict[str, str],
+    max_per_rep: int,
+    rep_map: dict[str, Rep],
+) -> str | None:
+    """Find the best eligible rep for an HCP."""
+    best_score = float("inf")
+    best_rep = None
+    hcp_hours = _hcp_weekly_hours(hcp)
+
+    for rep in reps:
+        if not _is_eligible(hcp, rep, constraints):
+            continue
+        if rep_counts.get(rep.rep_id, 0) >= max_per_rep:
+            continue
+        if rep_workloads.get(rep.rep_id, 0.0) + hcp_hours > rep.max_weekly_hours:
+            continue
+
+        travel = 0.0
+        if hcp.lat is not None and hcp.lng is not None:
+            travel = haversine(rep.base_lat, rep.base_lng, hcp.lat, hcp.lng)
+
+        disruption = 0.0 if current_map.get(hcp.hcp_id) == rep.rep_id else 1.0
+
+        score = travel * 0.5 + disruption * 50.0
+        if score < best_score:
+            best_score = score
+            best_rep = rep.rep_id
+
+    return best_rep
+
+
+def _is_eligible(hcp: HCP, rep: Rep, constraints: list[Constraint]) -> bool:
+    """Check if rep meets hard constraints for this HCP."""
+    for c in constraints:
+        if c.type == "product_match" and c.value == "required":
+            if hcp.product_requirements:
+                if not any(p in rep.product_expertise for p in hcp.product_requirements):
+                    return False
+    return True
+
+
+def _unassign_reason(
+    hcp: HCP,
+    reps: list[Rep],
+    rep_counts: dict[str, int],
+    constraints: list[Constraint],
+    max_per_rep: int,
+    rep_map: dict[str, Rep],
+) -> str:
+    eligible = [r for r in reps if _is_eligible(hcp, r, constraints)]
+    if not eligible:
+        return "no eligible rep has required product expertise"
+    hcp_hours = _hcp_weekly_hours(hcp)
+    for r in eligible:
+        if rep_counts.get(r.rep_id, 0) < max_per_rep:
+            rep = rep_map.get(r.rep_id)
+            if rep and rep.max_weekly_hours >= hcp_hours:
+                return "unknown"
+    at_capacity = all(rep_counts.get(r.rep_id, 0) >= max_per_rep for r in eligible)
+    if at_capacity:
+        return "all eligible reps at capacity"
+    return "all eligible reps would exceed weekly hour limit"
+
+
+def _get_max_per_rep(constraints: list[Constraint]) -> int:
+    for c in constraints:
+        if c.type == "max_hcps_per_rep" and c.scope == "global":
+            try:
+                return int(c.value)
+            except (ValueError, TypeError):
+                pass
+    return 200
+
+
+def _get_account_groups(
+    constraints: list[Constraint],
+    hcps: list[HCP],
+) -> dict[str, list[str]]:
+    """Return {account_id: [hcp_ids]} for accounts with a same_primary_rep constraint."""
+    constrained_accounts: set[str] = set()
+    for c in constraints:
+        if c.type == "account_grouping" and c.value == "same_primary_rep":
+            parts = c.scope.split(":", 1)
+            if len(parts) == 2 and parts[0] == "account":
+                constrained_accounts.add(parts[1])
+
+    groups: dict[str, list[str]] = {}
+    for h in hcps:
+        if h.account_id in constrained_accounts:
+            groups.setdefault(h.account_id, []).append(h.hcp_id)
+    return groups
+
+
+def _assign_account_groups(
+    account_groups: dict[str, list[str]],
+    hcps: list[HCP],
+    reps: list[Rep],
+    assignment: dict[str, str],
+    rep_counts: dict[str, int],
+    rep_workloads: dict[str, float],
+    constraints: list[Constraint],
+    current_map: dict[str, str],
+    max_per_rep: int,
+    rep_map: dict[str, Rep],
+    locked_hcps: set[str],
+) -> None:
+    """Assign account-grouped HCPs to a single rep per account."""
+    hcp_map = {h.hcp_id: h for h in hcps}
+    for account_id, hcp_ids in account_groups.items():
+        unassigned_ids = [hid for hid in hcp_ids if hid not in assignment]
+        if not unassigned_ids:
+            continue
+
+        already_assigned_rep = None
+        for hid in hcp_ids:
+            if hid in assignment:
+                already_assigned_rep = assignment[hid]
+                break
+
+        group_hcps = [hcp_map[hid] for hid in unassigned_ids if hid in hcp_map]
+        if not group_hcps:
+            continue
+
+        group_hours = sum(_hcp_weekly_hours(h) for h in group_hcps)
+
+        if already_assigned_rep and already_assigned_rep in rep_map:
+            rep = rep_map[already_assigned_rep]
+            all_eligible = all(_is_eligible(h, rep, constraints) for h in group_hcps)
+            fits_count = rep_counts.get(already_assigned_rep, 0) + len(group_hcps) <= max_per_rep
+            fits_hours = rep_workloads.get(already_assigned_rep, 0.0) + group_hours <= rep.max_weekly_hours
+            if all_eligible and fits_count and fits_hours:
+                for h in group_hcps:
+                    assignment[h.hcp_id] = already_assigned_rep
+                    rep_counts[already_assigned_rep] = rep_counts.get(already_assigned_rep, 0) + 1
+                    rep_workloads[already_assigned_rep] = rep_workloads.get(
+                        already_assigned_rep, 0.0
+                    ) + _hcp_weekly_hours(h)
+                continue
+
+        best_rep = None
+        best_score = float("inf")
+        for rep in reps:
+            all_eligible = all(_is_eligible(h, rep, constraints) for h in group_hcps)
+            if not all_eligible:
+                continue
+            if rep_counts.get(rep.rep_id, 0) + len(group_hcps) > max_per_rep:
+                continue
+            if rep_workloads.get(rep.rep_id, 0.0) + group_hours > rep.max_weekly_hours:
+                continue
+
+            travel = 0.0
+            geo_count = 0
+            for h in group_hcps:
+                if h.lat is not None and h.lng is not None:
+                    travel += haversine(rep.base_lat, rep.base_lng, h.lat, h.lng)
+                    geo_count += 1
+            avg_travel = travel / max(geo_count, 1)
+
+            disruption = sum(1 for h in group_hcps if current_map.get(h.hcp_id) != rep.rep_id)
+            score = avg_travel * 0.5 + disruption * 50.0
+            if score < best_score:
+                best_score = score
+                best_rep = rep.rep_id
+
+        if best_rep:
+            for h in group_hcps:
+                assignment[h.hcp_id] = best_rep
+                rep_counts[best_rep] = rep_counts.get(best_rep, 0) + 1
+                rep_workloads[best_rep] = rep_workloads.get(best_rep, 0.0) + _hcp_weekly_hours(h)
+
+
+# -- local search --
+
+
+def _local_search(
+    assignment: dict[str, str],
+    hcps: list[HCP],
+    reps: list[Rep],
+    constraints: list[Constraint],
+    weights: ObjectiveWeights,
+    current_map: dict[str, str],
+    locked_hcps: set[str],
+    max_per_rep: int,
+    hcp_map: dict[str, HCP],
+    rep_map: dict[str, Rep],
+    max_iterations: int,
+    account_groups: dict[str, list[str]] | None = None,
+) -> int:
+    """Improve assignment via pairwise swaps. Returns iterations used."""
+    grouped_hcps: set[str] = set()
+    for ids in (account_groups or {}).values():
+        grouped_hcps.update(ids)
+
+    movable = [
+        h for h in hcps if h.hcp_id in assignment and h.hcp_id not in locked_hcps and h.hcp_id not in grouped_hcps
+    ]
+
+    current_assignments = _build_assignments(assignment, hcp_map, rep_map, current_map)
+    current_score = score_alignment(current_assignments, hcps, reps, weights)
+    best_composite = current_score.composite
+
+    for iteration in range(max_iterations):
+        improved = False
+
+        for i, h1 in enumerate(movable):
+            for h2 in movable[i + 1 :]:
+                r1 = assignment[h1.hcp_id]
+                r2 = assignment[h2.hcp_id]
+                if r1 == r2:
+                    continue
+
+                rep1 = rep_map.get(r1)
+                rep2 = rep_map.get(r2)
+                if not rep1 or not rep2:
+                    continue
+                if not _is_eligible(h1, rep2, constraints):
+                    continue
+                if not _is_eligible(h2, rep1, constraints):
+                    continue
+
+                assignment[h1.hcp_id] = r2
+                assignment[h2.hcp_id] = r1
+
+                trial = _build_assignments(assignment, hcp_map, rep_map, current_map)
+                trial_score = score_alignment(trial, hcps, reps, weights)
+
+                if trial_score.composite < best_composite - 0.0005:
+                    best_composite = trial_score.composite
+                    improved = True
+                else:
+                    assignment[h1.hcp_id] = r1
+                    assignment[h2.hcp_id] = r2
+
+        if not improved:
+            return iteration + 1
+
+    return max_iterations
+
+
+# -- output builders --
+
+
+def _build_assignments(
+    assignment: dict[str, str],
+    hcp_map: dict[str, HCP],
+    rep_map: dict[str, Rep],
+    current_map: dict[str, str],
+) -> list[AssignmentResult]:
+    results: list[AssignmentResult] = []
+    for hcp_id, rep_id in sorted(assignment.items()):
+        hcp = hcp_map.get(hcp_id)
+        rep = rep_map.get(rep_id)
+        if not hcp or not rep:
+            continue
+
+        prev_rep = current_map.get(hcp_id, "")
+        is_changed = prev_rep != rep_id and prev_rep != ""
+
+        travel = 0.0
+        if hcp.lat is not None and hcp.lng is not None:
+            travel = travel_minutes(haversine(rep.base_lat, rep.base_lng, hcp.lat, hcp.lng))
+
+        visits = 24 if hcp.segment == "high" else 12 if hcp.segment == "medium" else 6
+
+        data: dict[str, Any] = {
+            "hcp_id": hcp_id,
+            "hcp_name": hcp.name,
+            "primary_rep": rep_id,
+            "previous_rep": prev_rep,
+            "is_changed": is_changed,
+            "change_reason": "optimiser_reassigned" if is_changed else "",
+            "estimated_travel_min": round(travel, 1),
+            "estimated_annual_visits": visits,
+            "segment": hcp.segment,
+            "tier": hcp.tier,
+        }
+        data.update(hcp.model_extra)
+        results.append(AssignmentResult.model_validate(data))
+
+    return results
+
+
+def _build_territory_summary(
+    assignments: list[AssignmentResult],
+    hcp_map: dict[str, HCP],
+    rep_map: dict[str, Rep],
+    current_map: dict[str, str],
+) -> list[TerritorySummary]:
+    rep_data: dict[str, dict[str, Any]] = {}
+
+    for a in assignments:
+        hcp = hcp_map.get(a.hcp_id)
+        if not hcp:
+            continue
+        rd = rep_data.setdefault(
+            a.primary_rep,
+            {
+                "hcp_count": 0,
+                "total_potential": 0.0,
+                "workload": 0.0,
+                "travel": 0.0,
+                "seg_high": 0,
+                "seg_med": 0,
+                "seg_low": 0,
+                "kept": 0,
+                "new": 0,
+            },
+        )
+        rd["hcp_count"] += 1
+        rd["total_potential"] += hcp.annual_potential
+
+        hours_per = 1.0 if hcp.segment == "high" else 0.75 if hcp.segment == "medium" else 0.5
+        visits = 24 if hcp.segment == "high" else 12 if hcp.segment == "medium" else 6
+        rd["workload"] += (hours_per * visits) / 48.0
+        rd["travel"] += a.estimated_travel_min / 60.0 * (visits / 48.0)
+
+        if hcp.segment == "high":
+            rd["seg_high"] += 1
+        elif hcp.segment == "medium":
+            rd["seg_med"] += 1
+        else:
+            rd["seg_low"] += 1
+
+        if current_map.get(a.hcp_id) == a.primary_rep:
+            rd["kept"] += 1
+        else:
+            rd["new"] += 1
+
+    result = []
+    for rep_id in sorted(rep_data.keys()):
+        rd = rep_data[rep_id]
+        rep = rep_map.get(rep_id)
+        result.append(
+            TerritorySummary(
+                rep_id=rep_id,
+                rep_name=rep.name if rep else rep_id,
+                hcp_count=rd["hcp_count"],
+                total_potential=round(rd["total_potential"], 0),
+                workload_hours_weekly=round(rd["workload"], 1),
+                travel_hours_weekly=round(rd["travel"], 1),
+                segment_high=rd["seg_high"],
+                segment_medium=rd["seg_med"],
+                segment_low=rd["seg_low"],
+                relationships_kept=rd["kept"],
+                relationships_new=rd["new"],
+            )
+        )
+    return result

open_pharma_plugins_territory_alignment/tools/ta_align.py

@@ -0,0 +1,138 @@
+"""ta_align — generate or adjust territory alignment (strategic mode)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class OverrideArg(BaseModel):
+    hcp_id: str = Field(description="HCP to pin to a specific rep")
+    rep_id: str = Field(description="Rep to assign")
+    reason: str = Field(default="", description="Why this override exists")
+
+
+class NewHireArg(BaseModel):
+    rep_id: str = Field(description="New rep identifier")
+    name: str = Field(description="New rep name")
+    base_lat: float = Field(description="Home-base latitude")
+    base_lng: float = Field(description="Home-base longitude")
+    product_expertise: list[str] = Field(
+        default_factory=list, description="Products the new rep covers (semicolon-separated)"
+    )
+    max_weekly_hours: float = Field(default=40.0, description="Weekly hour capacity")
+
+
+class AlignArgs(BaseModel):
+    scenario_name: str = Field(description="Label for this scenario, e.g. 'baseline' or 'minus_r004'")
+    weight_workload: float | None = Field(default=None, description="Override workload balance weight (default 0.30)")
+    weight_travel: float | None = Field(default=None, description="Override travel efficiency weight (default 0.25)")
+    weight_disruption: float | None = Field(default=None, description="Override disruption weight (default 0.25)")
+    weight_coverage: float | None = Field(default=None, description="Override coverage weight (default 0.20)")
+    vacancies: list[str] = Field(
+        default_factory=list,
+        description="Rep IDs to model as vacant; their HCPs are redistributed",
+    )
+    new_hires: list[NewHireArg] = Field(default_factory=list, description="New reps to add for this scenario")
+    overrides: list[OverrideArg] = Field(
+        default_factory=list, description="Manual HCP-to-rep pins the solver must respect"
+    )
+    lock_reps: list[str] = Field(
+        default_factory=list,
+        description="Rep IDs whose current HCPs must not be reassigned",
+    )
+    max_iterations: int = Field(default=2000, description="Max local-search iterations")
+
+
+TOOL: dict[str, Any] = {
+    "name": "ta_align",
+    "description": (
+        "Generate a territory alignment scenario. Assigns HCPs to reps under "
+        "multi-objective optimisation balancing workload, travel, disruption, "
+        "and coverage. Supports vacancies, new hires, manual overrides, and "
+        "locked reps. Results are saved as a named scenario for later "
+        "evaluation or comparison. Call ta_status first to confirm data is loaded."
+    ),
+    "args": AlignArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+
+    from ..data import (
+        get_constraints,
+        get_current_alignment,
+        get_hcps,
+        get_reps,
+        is_loaded,
+        load_all,
+        save_scenario,
+    )
+    from ..models import NewHire, ObjectiveWeights, Override
+    from ..solver import solve
+
+    if not is_loaded():
+        load_all()
+
+    scenario_name = arguments["scenario_name"]
+
+    w = ObjectiveWeights()
+    if arguments.get("weight_workload") is not None:
+        w.workload_balance = arguments["weight_workload"]
+    if arguments.get("weight_travel") is not None:
+        w.travel_efficiency = arguments["weight_travel"]
+    if arguments.get("weight_disruption") is not None:
+        w.disruption = arguments["weight_disruption"]
+    if arguments.get("weight_coverage") is not None:
+        w.coverage = arguments["weight_coverage"]
+
+    vacancies = arguments.get("vacancies", [])
+    new_hires_raw = arguments.get("new_hires", [])
+    new_hires = (
+        [
+            NewHire(
+                rep_id=nh["rep_id"],
+                name=nh["name"],
+                base_lat=nh["base_lat"],
+                base_lng=nh["base_lng"],
+                product_expertise=nh.get("product_expertise", []),
+                max_weekly_hours=nh.get("max_weekly_hours", 40.0),
+            )
+            for nh in new_hires_raw
+        ]
+        if new_hires_raw
+        else []
+    )
+
+    overrides_raw = arguments.get("overrides", [])
+    overrides = (
+        [Override(hcp_id=o["hcp_id"], rep_id=o["rep_id"], reason=o.get("reason", "")) for o in overrides_raw]
+        if overrides_raw
+        else []
+    )
+
+    lock_reps = arguments.get("lock_reps", [])
+
+    hcps = get_hcps()
+    reps = get_reps(vacancies=vacancies, new_hires=new_hires)
+    alignment = get_current_alignment()
+    constraints = get_constraints()
+
+    result = solve(
+        hcps=hcps,
+        reps=reps,
+        current_alignment=alignment,
+        constraints=constraints,
+        weights=w,
+        overrides=overrides,
+        lock_reps=lock_reps,
+        scenario_name=scenario_name,
+        max_iterations=arguments.get("max_iterations", 2000),
+    )
+
+    result_dict = json.loads(result.model_dump_json())
+    save_scenario(scenario_name, result_dict)
+
+    return [{"type": "text", "text": json.dumps(result_dict, indent=2)}]