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

open_pharma_plugins_next_best_engagement/_scoring.py

@@ -0,0 +1,82 @@
+"""Weighted linear scoring engine for HCP engagement opportunities."""
+
+from __future__ import annotations
+
+from datetime import date
+
+from .models import ConstraintConfig, UniverseRow
+
+
+def score_hcp(
+    hcp: UniverseRow,
+    config: ConstraintConfig,
+    tier_coverage: dict[str, float],
+    today: date,
+) -> tuple[float, str]:
+    """Score an HCP and return (score, rationale_string)."""
+    w = config.weights
+    factors: list[tuple[str, float, float]] = []
+
+    # 1. Recency gap — how overdue is this HCP?
+    target_interval = config.period_days
+    last_touch = _most_recent_touch(hcp)
+    if last_touch:
+        days_gap = (today - last_touch).days
+        recency = min(days_gap / max(target_interval, 1), 1.0)
+    else:
+        recency = 1.0
+    factors.append(("recency_gap", recency, recency * w.recency_gap))
+
+    # 2. Tier value
+    tier_scores = {"A": 1.0, "B": 0.7, "C": 0.4, "D": 0.15}
+    tier_val = tier_scores.get(hcp.tier, 0.5)
+    factors.append(("tier_value", tier_val, tier_val * w.tier_value))
+
+    # 3. Engagement velocity — cold HCPs need re-engagement
+    total_90d = hcp.visits_last_90d + hcp.emails_last_90d
+    if total_90d == 0:
+        velocity = 0.8
+    elif total_90d <= 2:
+        velocity = 0.5
+    else:
+        velocity = 0.3
+    factors.append(("engagement_velocity", velocity, velocity * w.engagement_velocity))
+
+    # 4. Channel freshness — penalise single-channel repetition
+    touches = [
+        (hcp.last_visit_date, "visit"),
+        (hcp.last_email_date, "email"),
+        (hcp.last_meeting_date, "meeting"),
+    ]
+    recent_channels = [ch for d, ch in touches if d and (today - d).days <= 90]
+    if len(recent_channels) <= 1:
+        freshness = 0.8 if recent_channels else 1.0
+    else:
+        unique = len(set(recent_channels))
+        freshness = unique / len(recent_channels)
+    factors.append(("channel_freshness", freshness, freshness * w.channel_freshness))
+
+    # 5. Coverage debt — how far is this tier from its target?
+    target_map = {
+        "A": config.tier_a_coverage_pct,
+        "B": config.tier_b_coverage_pct,
+        "C": config.tier_c_coverage_pct,
+        "D": config.tier_d_coverage_pct,
+    }
+    target = target_map.get(hcp.tier, 0.5)
+    actual = tier_coverage.get(hcp.tier, 0.0)
+    debt = max(0.0, target - actual) / max(target, 0.01)
+    factors.append(("coverage_debt", debt, debt * w.coverage_debt))
+
+    total_score = min(max(sum(wt for _, _, wt in factors), 0.0), 1.0)
+
+    factors.sort(key=lambda f: f[2], reverse=True)
+    parts = [f"{name}={raw:.2f} (w={weighted:.2f})" for name, raw, weighted in factors if weighted > 0.01]
+    rationale = f"Tier {hcp.tier}, score {total_score:.2f}: " + ", ".join(parts)
+
+    return total_score, rationale
+
+
+def _most_recent_touch(hcp: UniverseRow) -> date | None:
+    dates = [d for d in (hcp.last_visit_date, hcp.last_email_date, hcp.last_meeting_date) if d]
+    return max(dates) if dates else None

open_pharma_plugins_next_best_engagement/_universe.py

@@ -0,0 +1,145 @@
+"""In-memory universe store for HCP engagement data."""
+
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .models import UniverseRow
+
+if TYPE_CHECKING:
+    from .models import EngagementPlan
+
+_universe: list[UniverseRow] = []
+_rep_info: dict[str, dict[str, Any]] = {}
+_last_plan: EngagementPlan | None = None
+
+
+def load_fixture() -> list[UniverseRow]:
+    """Load the built-in sample universe CSV."""
+    fixture_path = Path(__file__).parent / "fixtures" / "sample_universe.csv"
+    return load_csv(str(fixture_path))
+
+
+def load_csv(file_path: str) -> list[UniverseRow]:
+    """Load a CSV file into the universe store."""
+    global _universe, _rep_info
+
+    rows: list[UniverseRow] = []
+    with open(file_path, newline="") as f:
+        reader = csv.DictReader(f)
+        for raw in reader:
+            _coerce_row(raw)
+            rows.append(UniverseRow.model_validate(raw))
+
+    _universe = rows
+    _build_rep_index()
+    return _universe
+
+
+def _coerce_row(raw: dict[str, Any]) -> None:
+    """Convert string CSV values to the types UniverseRow expects."""
+    for date_field in ("last_visit_date", "last_email_date", "last_meeting_date"):
+        if date_field in raw and not raw[date_field]:
+            raw[date_field] = None
+    for bool_field in ("consent_email", "consent_phone"):
+        if bool_field in raw:
+            raw[bool_field] = raw[bool_field].lower() in ("true", "1", "yes")
+    for int_field in ("rep_max_visits_per_week", "visits_last_90d", "emails_last_90d"):
+        if int_field in raw and raw[int_field]:
+            raw[int_field] = int(raw[int_field])
+        elif int_field in raw:
+            raw[int_field] = 0
+
+    _coerce_extras(raw)
+
+
+_KNOWN_FIELDS = set(UniverseRow.model_fields.keys())
+
+
+def _coerce_extras(raw: dict[str, Any]) -> None:
+    """Best-effort type coercion for extra (pass-through) columns."""
+    for key in raw:
+        if key in _KNOWN_FIELDS:
+            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
+
+
+def _build_rep_index() -> None:
+    """Build a rep lookup from the loaded universe.
+
+    If different rows list different capacities for the same rep, the
+    maximum is used.
+    """
+    global _rep_info
+    _rep_info = {}
+    for row in _universe:
+        if row.rep_id not in _rep_info:
+            _rep_info[row.rep_id] = {
+                "name": row.rep_name or row.rep_id,
+                "territories": set(),
+                "capacity": row.rep_max_visits_per_week,
+            }
+        else:
+            _rep_info[row.rep_id]["capacity"] = max(_rep_info[row.rep_id]["capacity"], row.rep_max_visits_per_week)
+        _rep_info[row.rep_id]["territories"].add(row.territory_id)
+
+
+def store_plan(plan: EngagementPlan) -> None:
+    global _last_plan
+    _last_plan = plan
+
+
+def get_last_plan() -> EngagementPlan | None:
+    return _last_plan
+
+
+def get_universe() -> list[UniverseRow]:
+    return list(_universe)
+
+
+def get_rep_info() -> dict[str, dict[str, Any]]:
+    return dict(_rep_info)
+
+
+def get_summary() -> dict[str, Any]:
+    """Return summary stats of the loaded universe."""
+    if not _universe:
+        return {"loaded": False, "hcp_count": 0}
+
+    tiers: dict[str, int] = {}
+    territories: set[str] = set()
+    specialties: set[str] = set()
+    for row in _universe:
+        tiers[row.tier] = tiers.get(row.tier, 0) + 1
+        territories.add(row.territory_id)
+        specialties.add(row.specialty)
+
+    extra_columns = []
+    if _universe:
+        extra_columns = sorted(_universe[0].model_extra.keys())
+
+    return {
+        "loaded": True,
+        "hcp_count": len(_universe),
+        "rep_count": len(_rep_info),
+        "territory_count": len(territories),
+        "territories": sorted(territories),
+        "specialties": sorted(specialties),
+        "tier_distribution": dict(sorted(tiers.items())),
+        "extra_columns": extra_columns,
+    }

open_pharma_plugins_next_best_engagement/fixtures/sample_universe.csv

@@ -0,0 +1,81 @@
+hcp_id,hcp_name,specialty,tier,territory_id,rep_id,rep_name,rep_max_visits_per_week,consent_email,consent_phone,last_visit_date,last_email_date,last_meeting_date,visits_last_90d,emails_last_90d,kol_flag,affiliation
+HCP-E-001,Sarah Chen,Oncology,A,EAST,REP-E-01,James Rivera,20,true,true,2026-07-10,2026-08-01,,2,3,true,Memorial Cancer Center
+HCP-E-002,Michael Torres,Oncology,A,EAST,REP-E-01,James Rivera,20,true,true,2026-06-15,2026-07-20,,1,2,true,Memorial Cancer Center
+HCP-E-003,Priya Sharma,Cardiology,A,EAST,REP-E-02,Linda Park,20,true,true,,,2026-07-05,0,0,false,City Heart Institute
+HCP-E-004,David Okafor,Cardiology,A,EAST,REP-E-02,Linda Park,20,true,true,2026-08-10,2026-08-12,,3,4,true,City Heart Institute
+HCP-E-005,Rachel Kim,Oncology,B,EAST,REP-E-01,James Rivera,20,true,true,2026-07-25,2026-08-05,,2,2,false,St. Luke's Hospital
+HCP-E-006,Thomas Wright,Cardiology,B,EAST,REP-E-01,James Rivera,20,true,false,2026-06-01,,,1,0,false,Eastside Medical Group
+HCP-E-007,Amara Osei,Oncology,B,EAST,REP-E-02,Linda Park,20,true,true,2026-05-20,2026-06-30,,1,1,false,University Hospital East
+HCP-E-008,Jennifer Liu,Cardiology,B,EAST,REP-E-02,Linda Park,20,false,true,2026-07-30,,,2,0,false,Regional Cardiac Center
+HCP-E-009,Robert Patel,Oncology,B,EAST,REP-E-01,James Rivera,20,true,true,,2026-07-15,,0,1,false,Community Oncology Associates
+HCP-E-010,Fatima Al-Hassan,Cardiology,B,EAST,REP-E-02,Linda Park,20,true,true,2026-04-10,2026-05-25,,1,2,true,City Heart Institute
+HCP-E-011,Andrew Nowak,Oncology,C,EAST,REP-E-01,James Rivera,20,true,true,2026-08-05,2026-08-10,,1,1,false,St. Luke's Hospital
+HCP-E-012,Maria Santos,Cardiology,C,EAST,REP-E-01,James Rivera,20,true,true,,,,0,0,false,Eastside Medical Group
+HCP-E-013,Kevin Zhao,Oncology,C,EAST,REP-E-02,Linda Park,20,true,false,2026-06-20,,,1,0,false,Memorial Cancer Center
+HCP-E-014,Laura Becker,Cardiology,C,EAST,REP-E-02,Linda Park,20,true,true,2026-03-15,2026-07-01,,1,1,false,Regional Cardiac Center
+HCP-E-015,Hassan Yusuf,Oncology,C,EAST,REP-E-01,James Rivera,20,false,false,,,,0,0,false,Community Oncology Associates
+HCP-E-016,Emily Strand,Cardiology,C,EAST,REP-E-02,Linda Park,20,true,true,2026-07-15,,,1,0,false,City Heart Institute
+HCP-E-017,Daniel Cho,Oncology,D,EAST,REP-E-01,James Rivera,20,true,true,,2026-06-10,,0,1,false,St. Luke's Hospital
+HCP-E-018,Olivia Martin,Cardiology,D,EAST,REP-E-01,James Rivera,20,true,false,2026-05-01,,,1,0,false,Eastside Medical Group
+HCP-E-019,Raj Gupta,Oncology,D,EAST,REP-E-02,Linda Park,20,true,true,,,,0,0,false,University Hospital East
+HCP-E-020,Susan O'Neill,Cardiology,D,EAST,REP-E-02,Linda Park,20,false,true,2026-07-20,,,1,0,false,Regional Cardiac Center
+HCP-W-001,James Nakamura,Neurology,A,WEST,REP-W-01,Carlos Mendez,20,true,true,2026-06-25,2026-07-30,,2,2,true,Pacific Neuroscience Institute
+HCP-W-002,Lisa Johansson,Immunology,A,WEST,REP-W-01,Carlos Mendez,20,true,true,2026-07-05,2026-08-08,,2,3,true,West Coast Immunology Center
+HCP-W-003,Wei Zhang,Neurology,A,WEST,REP-W-02,Samantha Brooks,20,true,true,,2026-07-12,,0,1,false,Harbor Medical Center
+HCP-W-004,Patricia Reyes,Immunology,A,WEST,REP-W-02,Samantha Brooks,20,true,true,2026-08-01,2026-08-15,,3,2,true,University Hospital West
+HCP-W-005,Mark Thompson,Neurology,B,WEST,REP-W-01,Carlos Mendez,20,true,true,2026-05-10,2026-06-20,,1,1,false,Pacific Neuroscience Institute
+HCP-W-006,Anna Kowalski,Immunology,B,WEST,REP-W-01,Carlos Mendez,20,true,false,2026-07-18,,,2,0,false,Coastal Rheumatology Group
+HCP-W-007,Bryan Jackson,Neurology,B,WEST,REP-W-02,Samantha Brooks,20,true,true,,2026-05-30,,0,1,false,Harbor Medical Center
+HCP-W-008,Diana Petrova,Immunology,B,WEST,REP-W-02,Samantha Brooks,20,true,true,2026-06-30,2026-07-25,,1,2,false,West Coast Immunology Center
+HCP-W-009,George Fernandez,Neurology,B,WEST,REP-W-01,Carlos Mendez,20,false,true,2026-04-20,,,1,0,false,Valley Neuro Associates
+HCP-W-010,Helen Tran,Immunology,B,WEST,REP-W-02,Samantha Brooks,20,true,true,2026-03-25,2026-08-02,,1,3,true,University Hospital West
+HCP-W-011,Ivan Smirnov,Neurology,C,WEST,REP-W-01,Carlos Mendez,20,true,true,2026-07-28,,,1,0,false,Pacific Neuroscience Institute
+HCP-W-012,Karen Lee,Immunology,C,WEST,REP-W-01,Carlos Mendez,20,true,true,,,,0,0,false,Coastal Rheumatology Group
+HCP-W-013,Nathan Cole,Neurology,C,WEST,REP-W-02,Samantha Brooks,20,true,true,2026-06-05,2026-07-10,,1,1,false,Harbor Medical Center
+HCP-W-014,Priscilla Dubois,Immunology,C,WEST,REP-W-02,Samantha Brooks,20,true,false,2026-08-12,,,1,0,false,West Coast Immunology Center
+HCP-W-015,Oscar Herrera,Neurology,C,WEST,REP-W-01,Carlos Mendez,20,false,false,,,,0,0,false,Valley Neuro Associates
+HCP-W-016,Yuki Tanaka,Immunology,C,WEST,REP-W-02,Samantha Brooks,20,true,true,,2026-06-15,,0,1,false,University Hospital West
+HCP-W-017,Frank Bauer,Neurology,D,WEST,REP-W-01,Carlos Mendez,20,true,true,2026-05-05,,,1,0,false,Pacific Neuroscience Institute
+HCP-W-018,Gloria Vega,Immunology,D,WEST,REP-W-01,Carlos Mendez,20,true,true,,2026-07-01,,0,1,false,Coastal Rheumatology Group
+HCP-W-019,Henry Olsen,Neurology,D,WEST,REP-W-02,Samantha Brooks,20,true,false,,,,0,0,false,Harbor Medical Center
+HCP-W-020,Irene Costa,Immunology,D,WEST,REP-W-02,Samantha Brooks,20,false,true,2026-04-15,,,1,0,false,West Coast Immunology Center
+HCP-C-001,Richard Muller,Cardiology,A,CENTRAL,REP-C-01,Angela Foster,20,true,true,2026-07-08,2026-08-03,,2,2,true,Heartland Cardiovascular
+HCP-C-002,Sophia Andersen,Endocrinology,A,CENTRAL,REP-C-01,Angela Foster,20,true,true,2026-06-20,2026-07-28,,1,2,true,Central Diabetes & Endocrine Center
+HCP-C-003,Charles Obi,Cardiology,A,CENTRAL,REP-C-02,David Kim,20,true,true,,2026-07-05,,0,1,false,Midwest Heart Clinic
+HCP-C-004,Nina Volkov,Endocrinology,A,CENTRAL,REP-C-02,David Kim,20,true,true,2026-08-05,2026-08-14,,3,3,true,University Medical Center Central
+HCP-C-005,Peter Hoffman,Cardiology,B,CENTRAL,REP-C-01,Angela Foster,20,true,true,2026-05-25,2026-06-30,,1,1,false,Heartland Cardiovascular
+HCP-C-006,Aisha Nkomo,Endocrinology,B,CENTRAL,REP-C-01,Angela Foster,20,true,false,2026-07-12,,,2,0,false,Central Diabetes & Endocrine Center
+HCP-C-007,Victor Ionescu,Cardiology,B,CENTRAL,REP-C-02,David Kim,20,true,true,,2026-05-15,,0,1,false,Midwest Heart Clinic
+HCP-C-008,Stephanie Cruz,Endocrinology,B,CENTRAL,REP-C-02,David Kim,20,true,true,2026-06-28,2026-07-20,,1,2,false,Prairie Endocrine Associates
+HCP-C-009,Albert Schneider,Cardiology,B,CENTRAL,REP-C-01,Angela Foster,20,false,true,2026-04-05,,,1,0,false,Regional Heart Center
+HCP-C-010,Beatrice Adeyemi,Endocrinology,B,CENTRAL,REP-C-02,David Kim,20,true,true,2026-03-10,2026-08-01,,1,3,true,University Medical Center Central
+HCP-C-011,Carl Lindqvist,Cardiology,C,CENTRAL,REP-C-01,Angela Foster,20,true,true,2026-07-22,,,1,0,false,Heartland Cardiovascular
+HCP-C-012,Diane Washington,Endocrinology,C,CENTRAL,REP-C-01,Angela Foster,20,true,true,,,,0,0,false,Central Diabetes & Endocrine Center
+HCP-C-013,Eduardo Silva,Cardiology,C,CENTRAL,REP-C-02,David Kim,20,true,true,2026-06-10,2026-07-15,,1,1,false,Midwest Heart Clinic
+HCP-C-014,Fiona McCarthy,Endocrinology,C,CENTRAL,REP-C-02,David Kim,20,true,false,2026-08-08,,,1,0,false,Prairie Endocrine Associates
+HCP-C-015,Greg Antonov,Cardiology,C,CENTRAL,REP-C-01,Angela Foster,20,false,false,,,,0,0,false,Regional Heart Center
+HCP-C-016,Hannah Eriksson,Endocrinology,C,CENTRAL,REP-C-02,David Kim,20,true,true,,2026-06-25,,0,1,false,University Medical Center Central
+HCP-C-017,Ian Fletcher,Cardiology,D,CENTRAL,REP-C-01,Angela Foster,20,true,true,2026-05-15,,,1,0,false,Heartland Cardiovascular
+HCP-C-018,Julia Romano,Endocrinology,D,CENTRAL,REP-C-01,Angela Foster,20,true,true,,2026-07-08,,0,1,false,Central Diabetes & Endocrine Center
+HCP-C-019,Kyle Abrams,Cardiology,D,CENTRAL,REP-C-02,David Kim,20,true,true,,,,0,0,false,Midwest Heart Clinic
+HCP-C-020,Monica Dupont,Endocrinology,D,CENTRAL,REP-C-02,David Kim,20,false,true,2026-04-28,,,1,0,false,Regional Heart Center
+HCP-S-001,Antonio Morales,Oncology,A,SOUTH,REP-S-01,Rebecca Taylor,20,true,true,2026-07-02,2026-07-28,,2,2,true,Southern Cancer Research Center
+HCP-S-002,Natalie Bergstrom,Neurology,A,SOUTH,REP-S-01,Rebecca Taylor,20,true,true,2026-06-18,2026-08-06,,1,3,true,Gulf Coast Neuro Institute
+HCP-S-003,Philip Owusu,Oncology,A,SOUTH,REP-S-02,Marcus Johnson,20,true,true,,2026-07-10,,0,1,false,Sunbelt Medical Center
+HCP-S-004,Camille Bonnet,Neurology,A,SOUTH,REP-S-02,Marcus Johnson,20,true,true,2026-08-03,2026-08-13,,3,2,true,University Neuro Center South
+HCP-S-005,Samuel Okonkwo,Oncology,B,SOUTH,REP-S-01,Rebecca Taylor,20,true,true,2026-05-30,2026-06-28,,1,1,false,Southern Cancer Research Center
+HCP-S-006,Teresa Ramirez,Neurology,B,SOUTH,REP-S-01,Rebecca Taylor,20,true,false,2026-07-20,,,2,0,false,Gulf Coast Neuro Institute
+HCP-S-007,Ulrich Weber,Oncology,B,SOUTH,REP-S-02,Marcus Johnson,20,true,true,,2026-05-22,,0,1,false,Sunbelt Medical Center
+HCP-S-008,Vanessa Boyd,Neurology,B,SOUTH,REP-S-02,Marcus Johnson,20,true,true,2026-06-25,2026-07-22,,1,2,false,Palmetto Neurology Practice
+HCP-S-009,William Fraser,Oncology,B,SOUTH,REP-S-01,Rebecca Taylor,20,false,true,2026-04-12,,,1,0,false,Community Cancer Clinic
+HCP-S-010,Xena Papadopoulos,Neurology,B,SOUTH,REP-S-02,Marcus Johnson,20,true,true,2026-03-20,2026-08-04,,1,3,true,University Neuro Center South
+HCP-S-011,Yosef Abadi,Oncology,C,SOUTH,REP-S-01,Rebecca Taylor,20,true,true,2026-07-30,,,1,0,false,Southern Cancer Research Center
+HCP-S-012,Zoe Campbell,Neurology,C,SOUTH,REP-S-01,Rebecca Taylor,20,true,true,,,,0,0,false,Gulf Coast Neuro Institute
+HCP-S-013,Adam Kowalczyk,Oncology,C,SOUTH,REP-S-02,Marcus Johnson,20,true,true,2026-06-08,2026-07-18,,1,1,false,Sunbelt Medical Center
+HCP-S-014,Bella Nguyen,Neurology,C,SOUTH,REP-S-02,Marcus Johnson,20,true,false,2026-08-10,,,1,0,false,Palmetto Neurology Practice
+HCP-S-015,Cedric Dumont,Oncology,C,SOUTH,REP-S-01,Rebecca Taylor,20,false,false,,,,0,0,false,Community Cancer Clinic
+HCP-S-016,Dina Khalil,Neurology,C,SOUTH,REP-S-02,Marcus Johnson,20,true,true,,2026-06-18,,0,1,false,University Neuro Center South
+HCP-S-017,Ethan Ross,Oncology,D,SOUTH,REP-S-01,Rebecca Taylor,20,true,true,2026-05-08,,,1,0,false,Southern Cancer Research Center
+HCP-S-018,Freya Lindgren,Neurology,D,SOUTH,REP-S-01,Rebecca Taylor,20,true,true,,2026-07-05,,0,1,false,Gulf Coast Neuro Institute
+HCP-S-019,Gavin Murphy,Oncology,D,SOUTH,REP-S-02,Marcus Johnson,20,true,true,,,,0,0,false,Sunbelt Medical Center
+HCP-S-020,Hana Takahashi,Neurology,D,SOUTH,REP-S-02,Marcus Johnson,20,false,true,2026-04-22,,,1,0,false,Palmetto Neurology Practice

open_pharma_plugins_next_best_engagement/models.py

@@ -0,0 +1,135 @@
+"""Pydantic models for next-best-engagement universe, constraints, and plans."""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ---------------------------------------------------------------------------
+# Input models
+# ---------------------------------------------------------------------------
+
+
+class ScoringWeights(BaseModel):
+    """Weights for each scoring factor."""
+
+    recency_gap: float = Field(default=0.30, description="Weight for recency gap factor")
+    tier_value: float = Field(default=0.30, description="Weight for tier value factor")
+    engagement_velocity: float = Field(default=0.15, description="Weight for engagement velocity factor")
+    channel_freshness: float = Field(default=0.15, description="Weight for channel freshness factor")
+    coverage_debt: float = Field(default=0.10, description="Weight for coverage debt factor")
+
+
+class ConstraintConfig(BaseModel):
+    """Constraint parameters for plan generation. All fields optional with sensible defaults."""
+
+    period_days: int = Field(default=30, description="Planning period in days")
+    max_visits_per_hcp: int = Field(default=2, description="Max in-person visits per HCP per period")
+    max_emails_per_hcp: int = Field(default=3, description="Max emails per HCP per period")
+    min_gap_days: int = Field(default=7, description="Minimum days between touches to the same HCP")
+    tier_a_coverage_pct: float = Field(default=0.95, description="Target coverage for Tier A")
+    tier_b_coverage_pct: float = Field(default=0.80, description="Target coverage for Tier B")
+    tier_c_coverage_pct: float = Field(default=0.50, description="Target coverage for Tier C")
+    tier_d_coverage_pct: float = Field(default=0.20, description="Target coverage for Tier D")
+    no_action_threshold: float = Field(default=0.15, description="Score below which no_action is recommended")
+    weights: ScoringWeights = Field(default_factory=ScoringWeights)
+
+
+class UniverseRow(BaseModel):
+    """One row in the HCP engagement universe. Extra columns are preserved as pass-through."""
+
+    model_config = ConfigDict(extra="allow")
+
+    hcp_id: str = Field(description="Unique HCP identifier")
+    hcp_name: str = Field(description="HCP full name")
+    territory_id: str = Field(description="Territory assignment")
+    rep_id: str = Field(description="Assigned rep identifier")
+
+    tier: Literal["A", "B", "C", "D"] = Field(default="B", description="HCP tier from segmentation")
+    specialty: str = Field(default="General", description="Medical specialty")
+    rep_name: str = Field(default="", description="Rep full name")
+    rep_max_visits_per_week: int = Field(default=20, description="Rep weekly visit capacity")
+    consent_email: bool = Field(default=True, description="HCP consented to email")
+    consent_phone: bool = Field(default=True, description="HCP consented to phone/meeting")
+    last_visit_date: date | None = Field(default=None, description="Date of last in-person visit")
+    last_email_date: date | None = Field(default=None, description="Date of last email")
+    last_meeting_date: date | None = Field(default=None, description="Date of last remote meeting")
+    visits_last_90d: int = Field(default=0, description="Visit count in last 90 days")
+    emails_last_90d: int = Field(default=0, description="Email count in last 90 days")
+
+
+# ---------------------------------------------------------------------------
+# Output models
+# ---------------------------------------------------------------------------
+
+
+class PlannedEngagement(BaseModel):
+    """A single recommended engagement action."""
+
+    model_config = ConfigDict(extra="allow")
+
+    hcp_id: str
+    hcp_name: str
+    specialty: str
+    tier: str
+    territory_id: str
+    rep_id: str
+    rep_name: str
+    action_type: Literal[
+        "in_person_visit",
+        "remote_meeting",
+        "approved_email",
+        "no_action",
+    ]
+    priority: int = Field(ge=1, le=5, description="1 = highest priority")
+    score: float = Field(ge=0.0, le=1.0)
+    suggested_window_start: date
+    suggested_window_end: date
+    rationale: str
+
+
+class UnassignedHCP(BaseModel):
+    """An eligible HCP that could not be assigned."""
+
+    hcp_id: str
+    hcp_name: str
+    tier: str
+    reason: str
+
+
+class TierCoverage(BaseModel):
+    target_pct: float
+    actual_pct: float
+    total: int
+    planned: int
+    gap: int
+
+
+class RepUtilization(BaseModel):
+    rep_id: str
+    rep_name: str
+    capacity: int
+    assigned: int
+    utilization_pct: float
+
+
+class PlanMetrics(BaseModel):
+    total_eligible: int
+    total_planned: int
+    coverage_pct: float
+    coverage_by_tier: dict[str, TierCoverage]
+    rep_utilization: list[RepUtilization]
+    channel_mix: dict[str, int]
+    no_action_count: int
+    no_action_reasons: dict[str, int]
+
+
+class EngagementPlan(BaseModel):
+    period_start: date
+    period_end: date
+    generated_at: str
+    engagements: list[PlannedEngagement]
+    unassigned: list[UnassignedHCP]
+    metrics: PlanMetrics

open_pharma_plugins_next_best_engagement/tools/load_universe.py

@@ -0,0 +1,47 @@
+"""load_universe — load HCP engagement data from CSV or built-in fixtures."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class LoadUniverseArgs(BaseModel):
+    source: str = Field(
+        default="fixture",
+        description=("Data source: 'fixture' to load built-in sample data, or an absolute path to a CSV file."),
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "load_universe",
+    "description": (
+        "Load the HCP engagement universe from a CSV file or built-in fixture "
+        "data. The CSV must have columns: hcp_id, hcp_name, territory_id, "
+        "rep_id. Optional columns (tier, specialty, consent_email, "
+        "consent_phone, last_visit_date, etc.) enrich scoring. Any extra "
+        "columns are preserved and passed through to the output plan. "
+        "Call this before recommend_engagements."
+    ),
+    "args": LoadUniverseArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+    import os
+
+    from .._universe import get_summary, load_csv, load_fixture
+
+    source = arguments.get("source", "fixture")
+
+    if source == "fixture":
+        load_fixture()
+    else:
+        if not os.path.isfile(source):
+            return [{"type": "text", "text": json.dumps({"error": f"File not found: {source}"})}]
+        load_csv(source)
+
+    summary = get_summary()
+    return [{"type": "text", "text": json.dumps(summary, indent=2)}]

open_pharma_plugins_next_best_engagement/tools/recommend_engagements.py

@@ -0,0 +1,80 @@
+"""recommend_engagements — score, filter, and optimise the engagement plan."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class RecommendEngagementsArgs(BaseModel):
+    period_days: int = Field(default=30, description="Planning period length in days")
+    max_visits_per_hcp: int = Field(default=2, description="Max in-person visits per HCP in the period")
+    max_emails_per_hcp: int = Field(default=3, description="Max approved emails per HCP in the period")
+    min_gap_days: int = Field(default=7, description="Minimum days between touches to the same HCP")
+    no_action_threshold: float = Field(
+        default=0.15,
+        description="Score below which the HCP receives no action",
+    )
+    tier_a_coverage_pct: float = Field(default=0.95, description="Tier A coverage target")
+    tier_b_coverage_pct: float = Field(default=0.80, description="Tier B coverage target")
+    tier_c_coverage_pct: float = Field(default=0.50, description="Tier C coverage target")
+    tier_d_coverage_pct: float = Field(default=0.20, description="Tier D coverage target")
+    weight_recency_gap: float | None = Field(
+        default=None, description="Override recency gap scoring weight (default 0.30)"
+    )
+    weight_tier_value: float | None = Field(
+        default=None, description="Override tier value scoring weight (default 0.30)"
+    )
+    weight_engagement_velocity: float | None = Field(
+        default=None, description="Override engagement velocity scoring weight (default 0.15)"
+    )
+    weight_channel_freshness: float | None = Field(
+        default=None, description="Override channel freshness scoring weight (default 0.15)"
+    )
+    weight_coverage_debt: float | None = Field(
+        default=None, description="Override coverage debt scoring weight (default 0.10)"
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "recommend_engagements",
+    "description": (
+        "Generate the next-best-engagement plan for the loaded HCP universe. "
+        "Scores each HCP using a weighted linear model (recency gap, tier "
+        "value, engagement velocity, channel freshness, coverage debt), "
+        "selects actions via a rule cascade, and allocates to reps using a "
+        "two-phase greedy optimiser that satisfies coverage targets first, "
+        "then fills remaining capacity by score. Returns a structured "
+        "EngagementPlan with planned engagements, unassigned HCPs, and "
+        "metrics. Call load_universe first."
+    ),
+    "args": RecommendEngagementsArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+
+    from .._optimizer import generate_plan
+    from .._universe import get_rep_info, get_universe, store_plan
+    from ..models import ConstraintConfig, ScoringWeights
+
+    universe = get_universe()
+    if not universe:
+        return [{"type": "text", "text": json.dumps({"error": "No universe loaded. Call load_universe first."})}]
+
+    weight_overrides = {
+        k.removeprefix("weight_"): v for k, v in arguments.items() if k.startswith("weight_") and v is not None
+    }
+    constraint_fields = {k: v for k, v in arguments.items() if v is not None and not k.startswith("weight_")}
+    if weight_overrides:
+        constraint_fields["weights"] = ScoringWeights(**{**ScoringWeights().model_dump(), **weight_overrides})
+
+    rep_info = get_rep_info()
+    config = ConstraintConfig(**constraint_fields)
+    plan = generate_plan(universe, rep_info, config)
+    store_plan(plan)
+
+    result = json.loads(plan.model_dump_json())
+    return [{"type": "text", "text": json.dumps(result, indent=2)}]

open_pharma_plugins_next_best_engagement/tools/render_plan.py

@@ -0,0 +1,90 @@
+"""render_plan — export the engagement plan as CSV files or JSON."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class RenderPlanArgs(BaseModel):
+    format: str = Field(
+        default="csv",
+        description="Output format: 'csv' writes two CSV files, 'json' returns the full plan",
+    )
+    output_dir: str = Field(
+        default="",
+        description=(
+            "Directory for CSV output. Defaults to ~/.open-pharma-plugins/next-best-engagement/. "
+            "Ignored for JSON format."
+        ),
+    )
+    plan_json: str = Field(
+        default="",
+        description=(
+            "The engagement plan as a JSON string. If omitted, uses the last plan generated by recommend_engagements."
+        ),
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "render_plan",
+    "description": (
+        "Export the engagement plan to CSV files or return it as structured "
+        "JSON. CSV mode writes engagements.csv (one row per planned action "
+        "including any extra columns from the input universe) and "
+        "plan_summary.csv (coverage, utilisation, channel mix metrics). "
+        "Call recommend_engagements first to obtain the plan JSON."
+    ),
+    "args": RenderPlanArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+    from pathlib import Path
+
+    from .._renderer import render_csv, render_json
+    from .._universe import get_last_plan
+    from ..models import EngagementPlan
+
+    plan_json = arguments.get("plan_json", "").strip()
+
+    if plan_json:
+        try:
+            plan = EngagementPlan.model_validate_json(plan_json)
+        except Exception as e:
+            return [{"type": "text", "text": json.dumps({"error": f"Invalid plan JSON: {e}"})}]
+    else:
+        plan = get_last_plan()
+        if plan is None:
+            return [
+                {
+                    "type": "text",
+                    "text": json.dumps(
+                        {"error": "No plan available. Call recommend_engagements first or pass plan_json."}
+                    ),
+                }
+            ]
+
+    fmt = arguments.get("format", "csv")
+
+    if fmt == "json":
+        return [{"type": "text", "text": render_json(plan)}]
+
+    output_dir = arguments.get("output_dir", "").strip()
+    if not output_dir:
+        from shared.env import get_env
+
+        output_dir = get_env(
+            "OPEN_PHARMA_NBE_OUTPUT_DIR",
+            str(Path.home() / ".open-pharma-plugins" / "next-best-engagement"),
+        )
+
+    paths = render_csv(plan, output_dir)
+    result = {
+        "status": "ok",
+        "format": "csv",
+        "files": paths,
+    }
+    return [{"type": "text", "text": json.dumps(result, indent=2)}]