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

open_pharma_plugins_hcp_intelligence/tools/update_account.py

@@ -0,0 +1,84 @@
+"""update_account — simulates a CRM writeback of enrichment results."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class UpdateAccountArgs(BaseModel):
+    account_id: str = Field(description="Account ID to update (e.g. 'HCP-AU-001')")
+    status: str = Field(
+        description="New enrichment status: 'enriched' (profile complete), 'failed' (enrichment unsuccessful), or 'pending' (reset)"
+    )
+    profile_json: str | None = Field(
+        default=None,
+        description=(
+            "The full HcpProfile or HcoProfile as a JSON string. Required when "
+            "status is 'enriched'. This is the structured profile output from the "
+            "intelligence workflow."
+        ),
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "update_account",
+    "description": (
+        "Write enrichment results back to an account, simulating a CRM writeback. "
+        "Pass the account ID, the new status ('enriched' or 'failed'), and the "
+        "full profile JSON. The profile is stored alongside the account and can be "
+        "retrieved later via get_account. Use this after completing the HCP/HCO "
+        "profiling workflow to persist the results."
+    ),
+    "args": UpdateAccountArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+
+    from .._crm_store import get_account_by_id, write_enrichment
+
+    account_id = arguments["account_id"]
+    status = arguments["status"]
+    profile_json = arguments.get("profile_json")
+
+    record = get_account_by_id(account_id)
+    if record is None:
+        return [{"type": "text", "text": json.dumps({"error": f"Account '{account_id}' not found"})}]
+
+    if status not in ("enriched", "failed", "pending"):
+        return [
+            {
+                "type": "text",
+                "text": json.dumps({"error": f"Invalid status '{status}'. Use 'enriched', 'failed', or 'pending'."}),
+            }
+        ]
+
+    if status == "enriched" and not profile_json:
+        return [{"type": "text", "text": json.dumps({"error": "profile_json is required when status is 'enriched'"})}]
+
+    if profile_json:
+        try:
+            json.loads(profile_json)
+        except json.JSONDecodeError as e:
+            return [{"type": "text", "text": json.dumps({"error": f"Invalid profile_json: {e}"})}]
+
+    write_enrichment(account_id, profile_json or "", status)
+
+    return [
+        {
+            "type": "text",
+            "text": json.dumps(
+                {
+                    "success": True,
+                    "account_id": account_id,
+                    "name": record["name"],
+                    "status": status,
+                    "message": f"Account {account_id} ({record['name']}) updated to '{status}'.",
+                },
+                indent=2,
+            ),
+        }
+    ]

open_pharma_plugins_next_best_engagement/__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 = (
+    "Next-Best-Engagement recommends which HCPs to engage, through which "
+    "channel, by which rep, subject to capacity, consent, and frequency "
+    "constraints. Load an HCP universe (CSV or built-in fixtures), then "
+    "generate an optimised engagement plan."
+)
+
+SYSTEM_DEPS = []

open_pharma_plugins_next_best_engagement/__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_next_best_engagement/_optimizer.py

@@ -0,0 +1,400 @@
+"""Two-phase greedy optimizer for engagement plan allocation."""
+
+from __future__ import annotations
+
+import math
+from datetime import date, timedelta
+from typing import Any
+
+from ._scoring import score_hcp
+from .models import (
+    ConstraintConfig,
+    EngagementPlan,
+    PlanMetrics,
+    PlannedEngagement,
+    RepUtilization,
+    TierCoverage,
+    UnassignedHCP,
+    UniverseRow,
+)
+
+
+def generate_plan(
+    universe: list[UniverseRow],
+    rep_info: dict[str, dict[str, Any]],
+    config: ConstraintConfig,
+    today: date | None = None,
+) -> EngagementPlan:
+    """Generate an optimized engagement plan."""
+    today = today or date.today()
+    period_start = today
+    period_end = today + timedelta(days=config.period_days)
+
+    weeks_in_period = config.period_days / 7
+    rep_remaining: dict[str, int] = {
+        rep_id: int(info["capacity"] * weeks_in_period) for rep_id, info in rep_info.items()
+    }
+
+    hcp_action_counts: dict[str, list[str]] = {}
+    tier_counts: dict[str, int] = {}
+    for hcp in universe:
+        tier_counts[hcp.tier] = tier_counts.get(hcp.tier, 0) + 1
+
+    tier_coverage_actual: dict[str, float] = {t: 0.0 for t in tier_counts}
+
+    scored = []
+    for hcp in universe:
+        s, rationale = score_hcp(hcp, config, tier_coverage_actual, today)
+        scored.append((s, hcp, rationale))
+    scored.sort(key=lambda x: x[0], reverse=True)
+
+    engagements: list[PlannedEngagement] = []
+    unassigned: list[UnassignedHCP] = []
+    assigned_hcps: set[str] = set()
+    no_action_reasons: dict[str, int] = {}
+
+    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,
+    }
+
+    # Phase 1: Coverage pass
+    for tier in ["A", "B", "C", "D"]:
+        target_count = math.ceil(target_map[tier] * tier_counts.get(tier, 0))
+        tier_assigned = 0
+
+        tier_scored = [(s, hcp, r) for s, hcp, r in scored if hcp.tier == tier and hcp.hcp_id not in assigned_hcps]
+        tier_scored.sort(key=lambda x: x[0], reverse=True)
+
+        for s, hcp, rationale in tier_scored:
+            if tier_assigned >= target_count:
+                break
+
+            result = _try_assign(
+                hcp,
+                s,
+                rationale,
+                config,
+                hcp_action_counts,
+                rep_remaining,
+                rep_info,
+                period_start,
+                period_end,
+                today,
+            )
+            if result is None:
+                _record_unassigned(hcp, "no_rep_capacity", unassigned, no_action_reasons)
+                assigned_hcps.add(hcp.hcp_id)
+                continue
+            action, engagement = result
+            if action == "no_action":
+                _record_unassigned(hcp, _no_action_reason(hcp, config, today), unassigned, no_action_reasons)
+                assigned_hcps.add(hcp.hcp_id)
+                continue
+
+            engagements.append(engagement)
+            assigned_hcps.add(hcp.hcp_id)
+            rep_remaining[engagement.rep_id] -= 1
+            hcp_action_counts.setdefault(hcp.hcp_id, []).append(action)
+            tier_assigned += 1
+
+    # Re-score remaining HCPs with updated coverage for Phase 2
+    tier_assigned: dict[str, int] = {}
+    for e in engagements:
+        tier_assigned[e.tier] = tier_assigned.get(e.tier, 0) + 1
+    tier_coverage_actual = {
+        tier: tier_assigned.get(tier, 0) / count for tier, count in tier_counts.items() if count > 0
+    }
+
+    # Phase 2: Opportunity fill
+    remaining = []
+    for hcp in universe:
+        if hcp.hcp_id not in assigned_hcps:
+            s, rationale = score_hcp(hcp, config, tier_coverage_actual, today)
+            remaining.append((s, hcp, rationale))
+    remaining.sort(key=lambda x: x[0], reverse=True)
+
+    for s, hcp, rationale in remaining:
+        if s < config.no_action_threshold:
+            _record_unassigned(hcp, "below_threshold", unassigned, no_action_reasons)
+            continue
+
+        result = _try_assign(
+            hcp,
+            s,
+            rationale,
+            config,
+            hcp_action_counts,
+            rep_remaining,
+            rep_info,
+            period_start,
+            period_end,
+            today,
+        )
+        if result is None:
+            _record_unassigned(hcp, "no_rep_capacity", unassigned, no_action_reasons)
+            continue
+        action, engagement = result
+        if action == "no_action":
+            _record_unassigned(hcp, _no_action_reason(hcp, config, today), unassigned, no_action_reasons)
+            continue
+
+        engagements.append(engagement)
+        assigned_hcps.add(hcp.hcp_id)
+        rep_remaining[engagement.rep_id] -= 1
+        hcp_action_counts.setdefault(hcp.hcp_id, []).append(action)
+
+    metrics = _build_metrics(
+        universe,
+        engagements,
+        rep_info,
+        rep_remaining,
+        config,
+        no_action_reasons,
+        weeks_in_period,
+        tier_counts,
+        target_map,
+    )
+
+    return EngagementPlan(
+        period_start=period_start,
+        period_end=period_end,
+        generated_at=today.isoformat(),
+        engagements=engagements,
+        unassigned=unassigned,
+        metrics=metrics,
+    )
+
+
+# ---- internal helpers ----
+
+
+def _try_assign(
+    hcp: UniverseRow,
+    score: float,
+    rationale: str,
+    config: ConstraintConfig,
+    hcp_action_counts: dict[str, list[str]],
+    rep_remaining: dict[str, int],
+    rep_info: dict[str, dict[str, Any]],
+    period_start: date,
+    period_end: date,
+    today: date,
+) -> tuple[str, PlannedEngagement] | None:
+    """Try to assign an action to an HCP. Returns None if no rep has capacity."""
+    rep_id = _pick_rep(hcp, rep_remaining, rep_info)
+    if rep_id is None:
+        return None
+
+    action = _select_action(hcp, config, hcp_action_counts.get(hcp.hcp_id, []), today)
+    engagement = _create_engagement(
+        hcp,
+        action,
+        rep_id,
+        rep_info,
+        score,
+        rationale,
+        period_start,
+        period_end,
+    )
+    return action, engagement
+
+
+def _select_action(
+    hcp: UniverseRow,
+    config: ConstraintConfig,
+    prior_actions: list[str],
+    today: date,
+) -> str:
+    """Rule cascade: pick the best action for this HCP."""
+    visit_count = sum(1 for a in prior_actions if a == "in_person_visit")
+    email_count = sum(1 for a in prior_actions if a == "approved_email")
+
+    last_visit = hcp.last_visit_date
+    days_since_visit = (today - last_visit).days if last_visit else 999
+
+    # Rule 0: Min gap — skip if contacted too recently
+    most_recent = max(
+        (d for d in [hcp.last_visit_date, hcp.last_email_date, hcp.last_meeting_date] if d),
+        default=None,
+    )
+    if most_recent and (today - most_recent).days < config.min_gap_days:
+        return "no_action"
+
+    # Rule 1: High-tier + overdue for visit + phone consent → in-person visit
+    if hcp.tier in ("A", "B") and days_since_visit >= 45 and hcp.consent_phone:
+        if visit_count < config.max_visits_per_hcp:
+            return "in_person_visit"
+
+    # Rule 2: Recently visited + email consent → email follow-up
+    if days_since_visit < 30 and hcp.consent_email:
+        if email_count < config.max_emails_per_hcp:
+            return "approved_email"
+
+    # Rule 3: Not recently visited + phone consent → remote meeting
+    if days_since_visit >= 30 and hcp.consent_phone:
+        if visit_count < config.max_visits_per_hcp:
+            return "remote_meeting"
+
+    # Rule 4: Email fallback
+    if hcp.consent_email and email_count < config.max_emails_per_hcp:
+        return "approved_email"
+
+    # Rule 5: Phone fallback
+    if hcp.consent_phone and visit_count < config.max_visits_per_hcp:
+        return "in_person_visit"
+
+    return "no_action"
+
+
+def _pick_rep(
+    hcp: UniverseRow,
+    rep_remaining: dict[str, int],
+    rep_info: dict[str, dict[str, Any]],
+) -> str | None:
+    """Pick a rep with capacity — prefer the assigned rep, then least-loaded in territory."""
+    if hcp.rep_id in rep_remaining and rep_remaining[hcp.rep_id] > 0:
+        return hcp.rep_id
+
+    candidates = [
+        (rep_id, rep_remaining.get(rep_id, 0))
+        for rep_id, info in rep_info.items()
+        if hcp.territory_id in info["territories"] and rep_remaining.get(rep_id, 0) > 0
+    ]
+    if not candidates:
+        return None
+    candidates.sort(key=lambda x: x[1], reverse=True)
+    return candidates[0][0]
+
+
+def _create_engagement(
+    hcp: UniverseRow,
+    action: str,
+    rep_id: str,
+    rep_info: dict[str, dict[str, Any]],
+    score: float,
+    rationale: str,
+    period_start: date,
+    period_end: date,
+) -> PlannedEngagement:
+    if score >= 0.8:
+        priority = 1
+    elif score >= 0.6:
+        priority = 2
+    elif score >= 0.4:
+        priority = 3
+    elif score >= 0.2:
+        priority = 4
+    else:
+        priority = 5
+
+    rep_name = rep_info.get(rep_id, {}).get("name", rep_id)
+
+    data: dict[str, Any] = {
+        "hcp_id": hcp.hcp_id,
+        "hcp_name": hcp.hcp_name,
+        "specialty": hcp.specialty,
+        "tier": hcp.tier,
+        "territory_id": hcp.territory_id,
+        "rep_id": rep_id,
+        "rep_name": rep_name,
+        "action_type": action,
+        "priority": priority,
+        "score": round(score, 3),
+        "suggested_window_start": period_start,
+        "suggested_window_end": period_end,
+        "rationale": rationale,
+    }
+    data.update(hcp.model_extra)
+    return PlannedEngagement.model_validate(data)
+
+
+def _no_action_reason(hcp: UniverseRow, config: ConstraintConfig, today: date) -> str:
+    """Determine why an HCP got no_action."""
+    most_recent = max(
+        (d for d in [hcp.last_visit_date, hcp.last_email_date, hcp.last_meeting_date] if d),
+        default=None,
+    )
+    if most_recent and (today - most_recent).days < config.min_gap_days:
+        return "too_recent"
+    if not hcp.consent_email and not hcp.consent_phone:
+        return "no_consent"
+    return "channels_exhausted"
+
+
+def _record_unassigned(
+    hcp: UniverseRow,
+    reason: str,
+    unassigned: list[UnassignedHCP],
+    no_action_reasons: dict[str, int],
+) -> None:
+    no_action_reasons[reason] = no_action_reasons.get(reason, 0) + 1
+    unassigned.append(UnassignedHCP(hcp_id=hcp.hcp_id, hcp_name=hcp.hcp_name, tier=hcp.tier, reason=reason))
+
+
+def _build_metrics(
+    universe: list[UniverseRow],
+    engagements: list[PlannedEngagement],
+    rep_info: dict[str, dict[str, Any]],
+    rep_remaining: dict[str, int],
+    config: ConstraintConfig,
+    no_action_reasons: dict[str, int],
+    weeks_in_period: float,
+    tier_counts: dict[str, int],
+    target_map: dict[str, float],
+) -> PlanMetrics:
+    total_eligible = len(universe)
+    total_planned = len(engagements)
+
+    # Coverage by tier
+    tier_planned: dict[str, int] = {}
+    for e in engagements:
+        tier_planned[e.tier] = tier_planned.get(e.tier, 0) + 1
+
+    coverage_by_tier: dict[str, TierCoverage] = {}
+    for tier in sorted(tier_counts.keys()):
+        total = tier_counts[tier]
+        planned = tier_planned.get(tier, 0)
+        actual_pct = planned / total if total else 0.0
+        coverage_by_tier[tier] = TierCoverage(
+            target_pct=target_map.get(tier, 0.5),
+            actual_pct=round(actual_pct, 3),
+            total=total,
+            planned=planned,
+            gap=max(0, math.ceil(target_map.get(tier, 0.5) * total) - planned),
+        )
+
+    # Rep utilization
+    rep_utilization = []
+    for rep_id, info in sorted(rep_info.items()):
+        capacity = int(info["capacity"] * weeks_in_period)
+        assigned = capacity - rep_remaining.get(rep_id, 0)
+        rep_utilization.append(
+            RepUtilization(
+                rep_id=rep_id,
+                rep_name=info["name"],
+                capacity=capacity,
+                assigned=assigned,
+                utilization_pct=round(assigned / capacity, 3) if capacity else 0.0,
+            )
+        )
+
+    # Channel mix
+    channel_mix: dict[str, int] = {}
+    for e in engagements:
+        channel_mix[e.action_type] = channel_mix.get(e.action_type, 0) + 1
+
+    coverage_pct = total_planned / total_eligible if total_eligible else 0.0
+
+    return PlanMetrics(
+        total_eligible=total_eligible,
+        total_planned=total_planned,
+        coverage_pct=round(coverage_pct, 3),
+        coverage_by_tier=coverage_by_tier,
+        rep_utilization=rep_utilization,
+        channel_mix=channel_mix,
+        no_action_count=sum(no_action_reasons.values()),
+        no_action_reasons=no_action_reasons,
+    )

open_pharma_plugins_next_best_engagement/_renderer.py

@@ -0,0 +1,149 @@
+"""Output renderers — CSV file export and JSON serialisation."""
+
+from __future__ import annotations
+
+import csv
+import io
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from shared.filesystem import atomic_write_text, ensure_private_dir
+
+from .models import EngagementPlan
+
+
+def render_csv(plan: EngagementPlan, output_dir: str) -> dict[str, str]:
+    """Write the plan to CSV files. Returns paths of written files."""
+    from datetime import datetime, timezone
+
+    out = ensure_private_dir(Path(output_dir))
+
+    ts = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+    engagements_path = out / f"engagements_{ts}.csv"
+    summary_path = out / f"plan_summary_{ts}.csv"
+
+    _write_engagements_csv(plan, engagements_path)
+    _write_summary_csv(plan, summary_path)
+
+    return {
+        "engagements_csv": str(engagements_path),
+        "summary_csv": str(summary_path),
+    }
+
+
+def render_json(plan: EngagementPlan) -> str:
+    """Serialise the plan to a JSON string."""
+    return plan.model_dump_json(indent=2)
+
+
+_DEFAULT_ENGAGEMENT_COLUMNS = [
+    "hcp_id",
+    "hcp_name",
+    "specialty",
+    "tier",
+    "territory_id",
+    "rep_id",
+    "rep_name",
+    "action_type",
+    "priority",
+    "score",
+    "suggested_window_start",
+    "suggested_window_end",
+    "rationale",
+]
+
+
+def _write_engagements_csv(plan: EngagementPlan, path: Path) -> None:
+    buffer = io.StringIO(newline="")
+    if not plan.engagements:
+        writer = csv.DictWriter(buffer, fieldnames=_DEFAULT_ENGAGEMENT_COLUMNS)
+        writer.writeheader()
+        atomic_write_text(path, buffer.getvalue())
+        return
+
+    rows = [_engagement_to_row(e) for e in plan.engagements]
+    fieldnames = list(rows[0].keys())
+
+    writer = csv.DictWriter(buffer, fieldnames=fieldnames)
+    writer.writeheader()
+    writer.writerows(rows)
+    atomic_write_text(path, buffer.getvalue())
+
+
+def _write_summary_csv(plan: EngagementPlan, path: Path) -> None:
+    m = plan.metrics
+    rows: list[dict[str, Any]] = []
+
+    rows.append({"section": "overview", "metric": "total_eligible", "value": m.total_eligible})
+    rows.append({"section": "overview", "metric": "total_planned", "value": m.total_planned})
+    rows.append({"section": "overview", "metric": "coverage_pct", "value": m.coverage_pct})
+    rows.append({"section": "overview", "metric": "no_action_count", "value": m.no_action_count})
+
+    for tier, cov in sorted(m.coverage_by_tier.items()):
+        rows.append(
+            {
+                "section": f"tier_{tier}",
+                "metric": "target_pct",
+                "value": cov.target_pct,
+            }
+        )
+        rows.append(
+            {
+                "section": f"tier_{tier}",
+                "metric": "actual_pct",
+                "value": cov.actual_pct,
+            }
+        )
+        rows.append({"section": f"tier_{tier}", "metric": "total", "value": cov.total})
+        rows.append({"section": f"tier_{tier}", "metric": "planned", "value": cov.planned})
+        rows.append({"section": f"tier_{tier}", "metric": "gap", "value": cov.gap})
+
+    for ru in m.rep_utilization:
+        rows.append(
+            {
+                "section": f"rep_{ru.rep_id}",
+                "metric": "capacity",
+                "value": ru.capacity,
+            }
+        )
+        rows.append(
+            {
+                "section": f"rep_{ru.rep_id}",
+                "metric": "assigned",
+                "value": ru.assigned,
+            }
+        )
+        rows.append(
+            {
+                "section": f"rep_{ru.rep_id}",
+                "metric": "utilization_pct",
+                "value": ru.utilization_pct,
+            }
+        )
+
+    for channel, count in sorted(m.channel_mix.items()):
+        rows.append({"section": "channel_mix", "metric": channel, "value": count})
+
+    buffer = io.StringIO(newline="")
+    writer = csv.DictWriter(buffer, fieldnames=["section", "metric", "value"])
+    writer.writeheader()
+    writer.writerows({key: _safe_csv_cell(value) for key, value in row.items()} for row in rows)
+    atomic_write_text(path, buffer.getvalue())
+
+
+def _engagement_to_row(e: Any) -> dict[str, Any]:
+    """Convert a PlannedEngagement to a flat dict for CSV, including extra columns."""
+    data = e.model_dump()
+    for key in ("suggested_window_start", "suggested_window_end"):
+        val = data.get(key)
+        if isinstance(val, date):
+            data[key] = val.isoformat()
+    return {key: _safe_csv_cell(value) for key, value in data.items()}
+
+
+def _safe_csv_cell(value: Any) -> Any:
+    """Prevent spreadsheet applications from interpreting exported text as a formula."""
+    if isinstance(value, str) and value.startswith(("=", "+", "-", "@", "\t", "\r", "\n")):
+        return "'" + value
+    return value