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

open_pharma_plugins_territory_alignment/models.py

@@ -0,0 +1,201 @@
+"""Pydantic domain models for territory alignment."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ---------------------------------------------------------------------------
+# Input models
+# ---------------------------------------------------------------------------
+
+
+class HCP(BaseModel):
+    """An HCP loaded from hcps.csv. Extra columns are preserved."""
+
+    model_config = ConfigDict(extra="allow")
+
+    hcp_id: str
+    name: str
+    specialty: str = ""
+    segment: str = Field(default="medium", description="high | medium | low")
+    tier: int = Field(default=2, ge=1, le=3)
+    lat: float | None = None
+    lng: float | None = None
+    account_id: str = ""
+    consent_email: bool = True
+    consent_phone: bool = True
+    consent_visit: bool = True
+    annual_potential: float = 0.0
+    product_requirements: list[str] = Field(default_factory=list)
+
+
+class Rep(BaseModel):
+    rep_id: str
+    name: str
+    base_lat: float = 0.0
+    base_lng: float = 0.0
+    product_expertise: list[str] = Field(default_factory=list)
+    max_weekly_hours: float = 40.0
+    max_daily_calls: int = 8
+    available_days: list[str] = Field(default_factory=lambda: ["mon", "tue", "wed", "thu", "fri"])
+
+
+class CurrentAssignment(BaseModel):
+    hcp_id: str
+    primary_rep: str
+    secondary_rep: str = ""
+
+
+class Constraint(BaseModel):
+    type: str
+    scope: str
+    value: Any
+    description: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Objective configuration
+# ---------------------------------------------------------------------------
+
+
+class ObjectiveWeights(BaseModel):
+    workload_balance: float = Field(default=0.30, ge=0.0, le=1.0)
+    travel_efficiency: float = Field(default=0.25, ge=0.0, le=1.0)
+    disruption: float = Field(default=0.25, ge=0.0, le=1.0)
+    coverage: float = Field(default=0.20, ge=0.0, le=1.0)
+
+
+# ---------------------------------------------------------------------------
+# Scenario levers (ta_align input)
+# ---------------------------------------------------------------------------
+
+
+class Override(BaseModel):
+    hcp_id: str = Field(description="HCP to pin to a specific rep")
+    rep_id: str = Field(description="Rep to assign")
+    reason: str = ""
+
+
+class NewHire(BaseModel):
+    rep_id: str
+    name: str
+    base_lat: float
+    base_lng: float
+    product_expertise: list[str] = Field(default_factory=list)
+    max_weekly_hours: float = 40.0
+
+
+# ---------------------------------------------------------------------------
+# Output models
+# ---------------------------------------------------------------------------
+
+
+class AssignmentResult(BaseModel):
+    """A single HCP assignment in the output plan."""
+
+    model_config = ConfigDict(extra="allow")
+
+    hcp_id: str
+    hcp_name: str
+    primary_rep: str
+    previous_rep: str
+    is_changed: bool
+    change_reason: str = ""
+    estimated_travel_min: float = 0.0
+    estimated_annual_visits: int = 0
+    segment: str = ""
+    tier: int = 0
+
+
+class TerritorySummary(BaseModel):
+    rep_id: str
+    rep_name: str
+    hcp_count: int
+    total_potential: float
+    workload_hours_weekly: float
+    travel_hours_weekly: float
+    segment_high: int = 0
+    segment_medium: int = 0
+    segment_low: int = 0
+    relationships_kept: int = 0
+    relationships_new: int = 0
+
+
+class RawMetrics(BaseModel):
+    workload_gini: float
+    avg_travel_min: float
+    max_travel_min: float
+    pct_reassigned: float
+    pct_priority_covered: float
+
+
+class ObjectiveScores(BaseModel):
+    workload_balance: float
+    travel_efficiency: float
+    disruption: float
+    coverage: float
+    composite: float
+    raw: RawMetrics
+
+
+class UnassignedHCP(BaseModel):
+    hcp_id: str
+    reason: str
+
+
+class ScenarioResult(BaseModel):
+    scenario_name: str
+    assignments: list[AssignmentResult]
+    territory_summary: list[TerritorySummary]
+    objectives: ObjectiveScores
+    unassigned: list[UnassignedHCP]
+    weights_used: ObjectiveWeights
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Operational mode output
+# ---------------------------------------------------------------------------
+
+
+class VisitCluster(BaseModel):
+    cluster_id: str
+    hcp_ids: list[str]
+    centroid_lat: float | None = None
+    centroid_lng: float | None = None
+    estimated_route_km: float = 0.0
+    estimated_travel_min: float = 0.0
+    hcp_count: int = 0
+    suggested_day: str = ""
+    travel_warning: str = ""
+
+
+class VisitStop(BaseModel):
+    hcp_id: str
+    hcp_name: str
+    visit_order: int
+    cluster_id: str
+    lat: float | None = None
+    lng: float | None = None
+    travel_km_from_previous: float = 0.0
+
+
+class RemoteAlternative(BaseModel):
+    hcp_id: str
+    hcp_name: str
+    distance_km: float
+    reason: str
+
+
+class VisitPlan(BaseModel):
+    rep_id: str
+    rep_name: str
+    period: str
+    clusters: list[VisitCluster]
+    visit_sequence: list[VisitStop]
+    remote_alternatives: list[RemoteAlternative]
+    total_route_km: float
+    total_hcps: int
+    remote_count: int

open_pharma_plugins_territory_alignment/scoring.py

@@ -0,0 +1,125 @@
+"""Multi-objective scoring and normalisation for territory alignment."""
+
+from __future__ import annotations
+
+from .geo import haversine, travel_minutes
+from .models import (
+    HCP,
+    AssignmentResult,
+    ObjectiveScores,
+    ObjectiveWeights,
+    RawMetrics,
+    Rep,
+)
+
+
+def score_alignment(
+    assignments: list[AssignmentResult],
+    hcps: list[HCP],
+    reps: list[Rep],
+    weights: ObjectiveWeights,
+    baseline: RawMetrics | None = None,
+) -> ObjectiveScores:
+    """Score an alignment across four normalised objectives."""
+    hcp_map = {h.hcp_id: h for h in hcps}
+    rep_map = {r.rep_id: r for r in reps}
+
+    raw = _compute_raw(assignments, hcp_map, rep_map)
+
+    if baseline:
+        wb = _normalise(raw.workload_gini, baseline.workload_gini)
+        te = _normalise(raw.avg_travel_min, baseline.avg_travel_min)
+        di = _normalise(raw.pct_reassigned, baseline.pct_reassigned)
+        co = _normalise(100.0 - raw.pct_priority_covered, 100.0 - baseline.pct_priority_covered)
+    else:
+        wb = min(raw.workload_gini, 1.0)
+        te = min(raw.avg_travel_min / 60.0, 1.0) if raw.avg_travel_min > 0 else 0.0
+        di = min(raw.pct_reassigned / 100.0, 1.0)
+        co = min((100.0 - raw.pct_priority_covered) / 100.0, 1.0)
+
+    composite = (
+        weights.workload_balance * wb + weights.travel_efficiency * te + weights.disruption * di + weights.coverage * co
+    )
+
+    return ObjectiveScores(
+        workload_balance=round(wb, 4),
+        travel_efficiency=round(te, 4),
+        disruption=round(di, 4),
+        coverage=round(co, 4),
+        composite=round(composite, 4),
+        raw=raw,
+    )
+
+
+def _compute_raw(
+    assignments: list[AssignmentResult],
+    hcp_map: dict[str, HCP],
+    rep_map: dict[str, Rep],
+) -> RawMetrics:
+    rep_workloads: dict[str, float] = {r: 0.0 for r in rep_map}
+    rep_travel: dict[str, list[float]] = {r: [] for r in rep_map}
+    reassigned = 0
+    priority_total = 0
+    priority_covered = 0
+
+    for a in assignments:
+        hcp = hcp_map.get(a.hcp_id)
+        rep = rep_map.get(a.primary_rep)
+        if not hcp or not rep:
+            continue
+
+        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
+        weekly_hours = (hours_per_visit * visits_per_year) / 48.0
+        rep_workloads[a.primary_rep] = rep_workloads.get(a.primary_rep, 0.0) + weekly_hours
+
+        if hcp.lat is not None and hcp.lng is not None:
+            dist = haversine(rep.base_lat, rep.base_lng, hcp.lat, hcp.lng)
+            rep_travel.setdefault(a.primary_rep, []).append(travel_minutes(dist))
+
+        if a.is_changed:
+            reassigned += 1
+
+        if hcp.segment == "high":
+            priority_total += 1
+            priority_covered += 1
+
+    all_hcps_high = sum(1 for h in hcp_map.values() if h.segment == "high")
+    if all_hcps_high > priority_total:
+        priority_total = all_hcps_high
+
+    workloads = [v for v in rep_workloads.values() if v > 0]
+    gini = _gini(workloads) if workloads else 0.0
+
+    all_travel = [t for ts in rep_travel.values() for t in ts]
+    avg_travel = sum(all_travel) / max(len(all_travel), 1)
+    max_travel = max(all_travel) if all_travel else 0.0
+
+    pct_reassigned = (reassigned / max(len(assignments), 1)) * 100.0
+    pct_covered = (priority_covered / max(priority_total, 1)) * 100.0
+
+    return RawMetrics(
+        workload_gini=round(gini, 4),
+        avg_travel_min=round(avg_travel, 1),
+        max_travel_min=round(max_travel, 1),
+        pct_reassigned=round(pct_reassigned, 1),
+        pct_priority_covered=round(pct_covered, 1),
+    )
+
+
+def _gini(values: list[float]) -> float:
+    """Gini coefficient (0 = perfect equality, 1 = max inequality)."""
+    if not values or all(v == 0 for v in values):
+        return 0.0
+    n = len(values)
+    sorted_v = sorted(values)
+    total = sum(sorted_v)
+    weighted_sum = sum((i + 1) * v for i, v in enumerate(sorted_v))
+    return round((2.0 * weighted_sum) / (n * total) - (n + 1.0) / n, 4)
+
+
+def _normalise(value: float, baseline: float) -> float:
+    """Normalise a metric relative to baseline. Returns 0-1 range."""
+    if baseline <= 0:
+        return 0.0 if value <= 0 else 1.0
+    return min(max(value / baseline, 0.0), 2.0) / 2.0