open-pharma-plugins 2.2.0__tar.gz → 2.2.1__tar.gz

{open_pharma_plugins-2.2.0/src/open_pharma_plugins.egg-info → open_pharma_plugins-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-pharma-plugins
-Version: 2.2.0
+Version: 2.2.1
 Summary: Open Pharma Plugins: Agent Skills + MCP tools for pharmaceutical commercial operations — HCP intelligence, territory alignment, competitive intelligence, field training, engagement planning, and campaign creation.
 Author: EAI Commercial Team
 License-Expression: Apache-2.0

{open_pharma_plugins-2.2.0 → open_pharma_plugins-2.2.1}/src/capabilities/competitive-intelligence/open_pharma_plugins_competitive_intelligence/tools/ci_status.py

@@ -77,7 +77,7 @@ def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
             "openfda": {
                 "url": "https://api.fda.gov/drug",
                 "auth": "optional API key",
-                "rate_limit": "240/min with key, 40/min without",
+                "rate_limit": "240/min; 1,000/day per IP without key or 120,000/day per key",
             },
             "dailymed": {"url": "https://dailymed.nlm.nih.gov/dailymed/services/v2", "auth": "none"},
             "pubmed": {

{open_pharma_plugins-2.2.0 → open_pharma_plugins-2.2.1}/src/capabilities/next-best-engagement/open_pharma_plugins_next_best_engagement/__init__.py

@@ -1,13 +1,13 @@
 from mcp_framework import build_registry
 
-__version__ = "1.0.1"
+__version__ = "1.0.2"
 
 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 "
+    "channel, by which rep, subject to visit capacity, explicit consent, "
+    "and minimum-gap constraints. Load an HCP universe (CSV or built-in fixtures), then "
     "generate an optimised engagement plan."
 )
 

{open_pharma_plugins-2.2.0 → open_pharma_plugins-2.2.1}/src/capabilities/next-best-engagement/open_pharma_plugins_next_best_engagement/_optimizer.py

@@ -7,6 +7,7 @@ from datetime import date, timedelta
 from typing import Any
 
 from ._scoring import score_hcp
+from ._universe import fingerprint_universe
 from .models import (
     ConstraintConfig,
     EngagementPlan,
@@ -24,9 +25,11 @@ def generate_plan(
     rep_info: dict[str, dict[str, Any]],
     config: ConstraintConfig,
     today: date | None = None,
+    universe_generation: int = 0,
 ) -> EngagementPlan:
     """Generate an optimized engagement plan."""
     today = today or date.today()
+    _validate_universe(universe, today)
     period_start = today
     period_end = today + timedelta(days=config.period_days)
 
@@ -35,19 +38,26 @@ def generate_plan(
         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}
-
+    tier_coverage_actual = {hcp.tier: 0.0 for hcp in universe}
     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)
 
+    # Coverage targets and metrics use the same pre-allocation action-eligibility
+    # boundary as the planning pass: consent/gap checks plus the score threshold.
+    eligible_universe = [
+        hcp
+        for score, hcp, _ in scored
+        if _eligibility_reason(hcp, config, today) is None and score >= config.no_action_threshold
+    ]
+    tier_counts: dict[str, int] = {}
+    for hcp in eligible_universe:
+        tier_counts[hcp.tier] = tier_counts.get(hcp.tier, 0) + 1
+
+    tier_coverage_actual = {t: 0.0 for t in tier_counts}
+
     engagements: list[PlannedEngagement] = []
     unassigned: list[UnassignedHCP] = []
     assigned_hcps: set[str] = set()
@@ -72,12 +82,21 @@ def generate_plan(
             if tier_assigned >= target_count:
                 break
 
+            eligibility_reason = _eligibility_reason(hcp, config, today)
+            if eligibility_reason is not None:
+                _record_unassigned(hcp, eligibility_reason, unassigned, no_action_reasons)
+                assigned_hcps.add(hcp.hcp_id)
+                continue
+            if s < config.no_action_threshold:
+                _record_unassigned(hcp, "below_threshold", unassigned, no_action_reasons)
+                assigned_hcps.add(hcp.hcp_id)
+                continue
+
             result = _try_assign(
                 hcp,
                 s,
                 rationale,
                 config,
-                hcp_action_counts,
                 rep_remaining,
                 rep_info,
                 period_start,
@@ -96,8 +115,8 @@ def generate_plan(
 
             engagements.append(engagement)
             assigned_hcps.add(hcp.hcp_id)
-            rep_remaining[engagement.rep_id] -= 1
-            hcp_action_counts.setdefault(hcp.hcp_id, []).append(action)
+            if action == "in_person_visit":
+                rep_remaining[engagement.rep_id] -= 1
             tier_assigned += 1
 
     # Re-score remaining HCPs with updated coverage for Phase 2
@@ -117,6 +136,10 @@ def generate_plan(
     remaining.sort(key=lambda x: x[0], reverse=True)
 
     for s, hcp, rationale in remaining:
+        eligibility_reason = _eligibility_reason(hcp, config, today)
+        if eligibility_reason is not None:
+            _record_unassigned(hcp, eligibility_reason, unassigned, no_action_reasons)
+            continue
         if s < config.no_action_threshold:
             _record_unassigned(hcp, "below_threshold", unassigned, no_action_reasons)
             continue
@@ -126,7 +149,6 @@ def generate_plan(
             s,
             rationale,
             config,
-            hcp_action_counts,
             rep_remaining,
             rep_info,
             period_start,
@@ -143,11 +165,12 @@ def generate_plan(
 
         engagements.append(engagement)
         assigned_hcps.add(hcp.hcp_id)
-        rep_remaining[engagement.rep_id] -= 1
-        hcp_action_counts.setdefault(hcp.hcp_id, []).append(action)
+        if action == "in_person_visit":
+            rep_remaining[engagement.rep_id] -= 1
 
     metrics = _build_metrics(
-        universe,
+        len(universe),
+        eligible_universe,
         engagements,
         rep_info,
         rep_remaining,
@@ -159,6 +182,8 @@ def generate_plan(
     )
 
     return EngagementPlan(
+        universe_fingerprint=fingerprint_universe(universe),
+        universe_generation=universe_generation,
         period_start=period_start,
         period_end=period_end,
         generated_at=today.isoformat(),
@@ -171,28 +196,38 @@ def generate_plan(
 # ---- internal helpers ----
 
 
+def _validate_universe(universe: list[UniverseRow], today: date) -> None:
+    seen_hcp_ids: set[str] = set()
+    for hcp in universe:
+        if hcp.hcp_id in seen_hcp_ids:
+            raise ValueError(f"Duplicate hcp_id: {hcp.hcp_id}")
+        seen_hcp_ids.add(hcp.hcp_id)
+        for field_name in ("last_visit_date", "last_email_date", "last_meeting_date"):
+            touch_date = getattr(hcp, field_name)
+            if touch_date is not None and touch_date > today:
+                raise ValueError(f"{field_name} is future-dated relative to the planning date")
+
+
 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:
+    """Assign to the declared rep, enforcing capacity only for in-person visits."""
+    action = _select_action(hcp, config, today)
+    if action == "in_person_visit" and rep_remaining.get(hcp.rep_id, 0) <= 0:
         return None
 
-    action = _select_action(hcp, config, hcp_action_counts.get(hcp.hcp_id, []), today)
     engagement = _create_engagement(
         hcp,
         action,
-        rep_id,
+        hcp.rep_id,
         rep_info,
         score,
         rationale,
@@ -205,13 +240,9 @@ def _try_assign(
 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
 
@@ -224,51 +255,28 @@ def _select_action(
         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"
+    if hcp.tier in ("A", "B") and days_since_visit >= 45 and hcp.consent_phone is True:
+        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"
+    if days_since_visit < 30 and hcp.consent_email is True:
+        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"
+    if days_since_visit >= 30 and hcp.consent_phone is True:
+        return "remote_meeting"
 
     # Rule 4: Email fallback
-    if hcp.consent_email and email_count < config.max_emails_per_hcp:
+    if hcp.consent_email is True:
         return "approved_email"
 
     # Rule 5: Phone fallback
-    if hcp.consent_phone and visit_count < config.max_visits_per_hcp:
+    if hcp.consent_phone is True:
         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,
@@ -292,36 +300,47 @@ def _create_engagement(
 
     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)
+    data: dict[str, Any] = dict(hcp.model_extra or {})
+    data.update(
+        {
+            "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,
+        }
+    )
     return PlannedEngagement.model_validate(data)
 
 
 def _no_action_reason(hcp: UniverseRow, config: ConstraintConfig, today: date) -> str:
     """Determine why an HCP got no_action."""
+    return _eligibility_reason(hcp, config, today) or "channels_exhausted"
+
+
+def _eligibility_reason(hcp: UniverseRow, config: ConstraintConfig, today: date) -> str | None:
+    """Return a fail-closed eligibility reason before score-based filtering."""
     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 hcp.consent_email is True or hcp.consent_phone is True:
+        return None
+    if hcp.consent_email is None or hcp.consent_phone is None:
+        return "missing_consent"
     if not hcp.consent_email and not hcp.consent_phone:
         return "no_consent"
-    return "channels_exhausted"
+    return None
 
 
 def _record_unassigned(
@@ -335,7 +354,8 @@ def _record_unassigned(
 
 
 def _build_metrics(
-    universe: list[UniverseRow],
+    total_universe: int,
+    eligible_universe: list[UniverseRow],
     engagements: list[PlannedEngagement],
     rep_info: dict[str, dict[str, Any]],
     rep_remaining: dict[str, int],
@@ -345,7 +365,7 @@ def _build_metrics(
     tier_counts: dict[str, int],
     target_map: dict[str, float],
 ) -> PlanMetrics:
-    total_eligible = len(universe)
+    total_eligible = len(eligible_universe)
     total_planned = len(engagements)
 
     # Coverage by tier
@@ -389,6 +409,7 @@ def _build_metrics(
     coverage_pct = total_planned / total_eligible if total_eligible else 0.0
 
     return PlanMetrics(
+        total_universe=total_universe,
         total_eligible=total_eligible,
         total_planned=total_planned,
         coverage_pct=round(coverage_pct, 3),

{open_pharma_plugins-2.2.0 → open_pharma_plugins-2.2.1}/src/capabilities/next-best-engagement/open_pharma_plugins_next_best_engagement/_renderer.py

@@ -7,29 +7,43 @@ import io
 from datetime import date
 from pathlib import Path
 from typing import Any
+from uuid import uuid4
 
-from shared.filesystem import atomic_write_text, ensure_private_dir
+from shared.filesystem import ensure_private_dir, exclusive_write_text, remove_files
 
-from .models import EngagementPlan
+from .models import EngagementPlan, is_formula_unsafe_text
 
 
 def render_csv(plan: EngagementPlan, output_dir: str) -> dict[str, str]:
-    """Write the plan to CSV files. Returns paths of written files."""
+    """Write the plan to a new pair of CSV files. Returns paths of written files."""
     from datetime import datetime, timezone
 
+    engagements_content = _engagements_csv_content(plan)
+    summary_content = _summary_csv_content(plan)
     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)
+    for _ in range(10):
+        run_id = f"{datetime.now(timezone.utc):%Y%m%d_%H%M%S}_{uuid4().hex}"
+        engagements_path = out / f"engagements_{run_id}.csv"
+        summary_path = out / f"plan_summary_{run_id}.csv"
+        created_paths: list[Path] = []
+        try:
+            exclusive_write_text(engagements_path, engagements_content)
+            created_paths.append(engagements_path)
+            exclusive_write_text(summary_path, summary_content)
+            created_paths.append(summary_path)
+        except FileExistsError:
+            remove_files(created_paths)
+        except Exception:
+            remove_files(created_paths)
+            raise
+        else:
+            return {
+                "engagements_csv": str(engagements_path),
+                "summary_csv": str(summary_path),
+            }
 
-    return {
-        "engagements_csv": str(engagements_path),
-        "summary_csv": str(summary_path),
-    }
+    raise FileExistsError("Could not allocate unique plan-render output paths.")
 
 
 def render_json(plan: EngagementPlan) -> str:
@@ -54,27 +68,23 @@ _DEFAULT_ENGAGEMENT_COLUMNS = [
 ]
 
 
-def _write_engagements_csv(plan: EngagementPlan, path: Path) -> None:
+def _engagements_csv_content(plan: EngagementPlan) -> str:
     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())
+    extra_columns = sorted({key for row in rows for key in row if key not in _DEFAULT_ENGAGEMENT_COLUMNS})
+    fieldnames = [*_DEFAULT_ENGAGEMENT_COLUMNS, *extra_columns]
 
     writer = csv.DictWriter(buffer, fieldnames=fieldnames)
     writer.writeheader()
     writer.writerows(rows)
-    atomic_write_text(path, buffer.getvalue())
+    return buffer.getvalue()
 
 
-def _write_summary_csv(plan: EngagementPlan, path: Path) -> None:
+def _summary_csv_content(plan: EngagementPlan) -> str:
     m = plan.metrics
     rows: list[dict[str, Any]] = []
 
+    rows.append({"section": "overview", "metric": "total_universe", "value": m.total_universe})
     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})
@@ -129,7 +139,7 @@ def _write_summary_csv(plan: EngagementPlan, path: Path) -> None:
     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())
+    return buffer.getvalue()
 
 
 def _engagement_to_row(e: Any) -> dict[str, Any]:
@@ -144,6 +154,6 @@ def _engagement_to_row(e: Any) -> dict[str, Any]:
 
 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")):
+    if isinstance(value, str) and is_formula_unsafe_text(value):
         return "'" + value
     return value

{open_pharma_plugins-2.2.0 → open_pharma_plugins-2.2.1}/src/capabilities/next-best-engagement/open_pharma_plugins_next_best_engagement/_scoring.py

@@ -42,7 +42,7 @@ def score_hcp(
         velocity = 0.3
     factors.append(("engagement_velocity", velocity, velocity * w.engagement_velocity))
 
-    # 4. Channel freshness — penalise single-channel repetition
+    # 4. Channel diversity — reward recent use of more than one channel type
     touches = [
         (hcp.last_visit_date, "visit"),
         (hcp.last_email_date, "email"),
@@ -50,11 +50,11 @@ def score_hcp(
     ]
     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
+        diversity = 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))
+        diversity = unique / len(recent_channels)
+    factors.append(("channel_diversity", diversity, diversity * w.channel_diversity))
 
     # 5. Coverage debt — how far is this tier from its target?
     target_map = {