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

open_pharma_plugins_territory_alignment/tools/ta_visualize.py

@@ -0,0 +1,504 @@
+"""ta_visualize — interactive HTML map of territory alignment scenarios."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class VisualizeArgs(BaseModel):
+    scenarios: list[str] = Field(
+        min_length=1,
+        max_length=2,
+        description="1-2 scenario names. Single = territory map; two = before/after comparison",
+    )
+    show_movements: bool = Field(
+        default=True,
+        description="Draw arrows for HCPs that changed rep between scenarios",
+    )
+    show_rep_bases: bool = Field(
+        default=True,
+        description="Show rep home-base locations as distinct markers",
+    )
+    file_name: str | None = Field(
+        default=None,
+        description="Output filename stem (auto-generated if omitted)",
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "ta_visualize",
+    "description": (
+        "Generate an interactive HTML map visualising one or two territory "
+        "alignment scenarios. Shows HCPs as colour-coded markers grouped by "
+        "assigned rep, rep home-base locations, and (for two-scenario comparison) "
+        "movement arrows for reassigned HCPs with a toggle switch. Opens in any "
+        "browser. Call ta_align first to create scenarios."
+    ),
+    "args": VisualizeArgs,
+}
+
+_REP_COLORS = [
+    "#2196F3",
+    "#4CAF50",
+    "#FF9800",
+    "#9C27B0",
+    "#F44336",
+    "#00BCD4",
+    "#795548",
+    "#607D8B",
+    "#E91E63",
+    "#8BC34A",
+    "#FF5722",
+    "#3F51B5",
+    "#009688",
+    "#FFC107",
+    "#673AB7",
+    "#CDDC39",
+]
+
+
+def _sanitize_filename(name: str) -> str:
+    import re as _re
+
+    clean = _re.sub(r"[^a-zA-Z0-9_\-]", "_", name)
+    return clean[:100] if clean else "output"
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+
+    from ..data import _scenarios_dir, get_hcps, get_reps, is_loaded, load_all, load_scenario
+
+    if not is_loaded():
+        load_all()
+
+    scenario_names = arguments["scenarios"]
+    show_movements = arguments.get("show_movements", True)
+    show_rep_bases = arguments.get("show_rep_bases", True)
+    file_name = arguments.get("file_name")
+
+    scenarios: dict[str, dict[str, Any]] = {}
+    for name in scenario_names:
+        data = load_scenario(name)
+        if data is None:
+            return [
+                {
+                    "type": "text",
+                    "text": json.dumps({"error": f"Scenario '{name}' not found. Run ta_align first."}),
+                }
+            ]
+        scenarios[name] = data
+
+    hcps = get_hcps()
+    hcp_map = {h.hcp_id: h for h in hcps}
+    reps = get_reps()
+    rep_map = {r.rep_id: r for r in reps}
+
+    all_rep_ids = set()
+    for sc in scenarios.values():
+        for a in sc.get("assignments", []):
+            all_rep_ids.add(a["primary_rep"])
+    for r in reps:
+        all_rep_ids.add(r.rep_id)
+
+    color_map = {}
+    for i, rid in enumerate(sorted(all_rep_ids)):
+        color_map[rid] = _REP_COLORS[i % len(_REP_COLORS)]
+
+    is_comparison = len(scenario_names) == 2
+
+    map_data = _build_map_data(
+        scenarios,
+        scenario_names,
+        hcp_map,
+        rep_map,
+        color_map,
+        show_movements and is_comparison,
+        show_rep_bases,
+    )
+
+    if not file_name:
+        file_name = "_vs_".join(scenario_names)
+
+    html = _render_html(map_data, scenario_names, is_comparison, color_map)
+
+    from shared.filesystem import atomic_write_text, ensure_private_dir
+
+    out_dir = ensure_private_dir(_scenarios_dir().parent)
+    file_name = _sanitize_filename(file_name)
+    html_path = out_dir / f"{file_name}.html"
+    atomic_write_text(html_path, html)
+
+    result = {
+        "success": True,
+        "html_path": str(html_path),
+        "scenarios": scenario_names,
+        "comparison": is_comparison,
+        "hcp_count": len(hcp_map),
+        "rep_count": len(all_rep_ids),
+    }
+    return [{"type": "text", "text": json.dumps(result, indent=2)}]
+
+
+def _build_map_data(
+    scenarios: dict[str, dict[str, Any]],
+    names: list[str],
+    hcp_map: dict,
+    rep_map: dict,
+    color_map: dict[str, str],
+    show_movements: bool,
+    show_rep_bases: bool,
+) -> dict[str, Any]:
+    scenario_layers: dict[str, Any] = {}
+
+    for name in names:
+        sc = scenarios[name]
+        markers = []
+        for a in sc.get("assignments", []):
+            hcp = hcp_map.get(a["hcp_id"])
+            if not hcp or hcp.lat is None or hcp.lng is None:
+                continue
+            segment = a.get("segment", "medium")
+            radius = 10 if segment == "high" else 7 if segment == "medium" else 5
+            markers.append(
+                {
+                    "lat": hcp.lat,
+                    "lng": hcp.lng,
+                    "hcp_id": a["hcp_id"],
+                    "hcp_name": a.get("hcp_name", hcp.name),
+                    "rep_id": a["primary_rep"],
+                    "color": color_map.get(a["primary_rep"], "#999"),
+                    "segment": segment,
+                    "tier": a.get("tier", 0),
+                    "radius": radius,
+                    "travel_min": a.get("estimated_travel_min", 0),
+                    "is_changed": a.get("is_changed", False),
+                    "previous_rep": a.get("previous_rep", ""),
+                }
+            )
+
+        unassigned = []
+        for u in sc.get("unassigned", []):
+            hcp = hcp_map.get(u["hcp_id"])
+            if hcp and hcp.lat is not None and hcp.lng is not None:
+                unassigned.append(
+                    {
+                        "lat": hcp.lat,
+                        "lng": hcp.lng,
+                        "hcp_id": u["hcp_id"],
+                        "hcp_name": hcp.name,
+                        "reason": u.get("reason", ""),
+                    }
+                )
+
+        objectives = sc.get("objectives", {})
+        scenario_layers[name] = {
+            "markers": markers,
+            "unassigned": unassigned,
+            "objectives": objectives,
+            "assignment_count": len(sc.get("assignments", [])),
+        }
+
+    rep_bases = []
+    if show_rep_bases:
+        for r in rep_map.values():
+            if r.base_lat != 0 or r.base_lng != 0:
+                rep_bases.append(
+                    {
+                        "lat": r.base_lat,
+                        "lng": r.base_lng,
+                        "rep_id": r.rep_id,
+                        "rep_name": r.name,
+                        "color": color_map.get(r.rep_id, "#999"),
+                    }
+                )
+
+    movements = []
+    if show_movements and len(names) == 2:
+        sc_a = scenarios[names[0]]
+        sc_b = scenarios[names[1]]
+        map_a = {a["hcp_id"]: a["primary_rep"] for a in sc_a.get("assignments", [])}
+        map_b = {a["hcp_id"]: a["primary_rep"] for a in sc_b.get("assignments", [])}
+
+        for hcp_id in set(map_a.keys()) & set(map_b.keys()):
+            if map_a[hcp_id] != map_b[hcp_id]:
+                hcp = hcp_map.get(hcp_id)
+                if not hcp or hcp.lat is None or hcp.lng is None:
+                    continue
+                old_rep = rep_map.get(map_a[hcp_id])
+                new_rep = rep_map.get(map_b[hcp_id])
+                if not old_rep or not new_rep:
+                    continue
+                movements.append(
+                    {
+                        "hcp_id": hcp_id,
+                        "hcp_name": hcp.name,
+                        "lat": hcp.lat,
+                        "lng": hcp.lng,
+                        "old_rep_id": map_a[hcp_id],
+                        "new_rep_id": map_b[hcp_id],
+                        "old_color": color_map.get(map_a[hcp_id], "#999"),
+                        "new_color": color_map.get(map_b[hcp_id], "#999"),
+                    }
+                )
+
+    return {
+        "scenario_layers": scenario_layers,
+        "rep_bases": rep_bases,
+        "movements": movements,
+    }
+
+
+def _render_html(
+    map_data: dict[str, Any],
+    scenario_names: list[str],
+    is_comparison: bool,
+    color_map: dict[str, str],
+) -> str:
+    from html import escape
+
+    from shared.filesystem import json_for_html_script
+
+    data_json = json_for_html_script(map_data)
+    names_json = json_for_html_script(scenario_names)
+    colors_json = json_for_html_script(color_map)
+    title = " vs ".join(scenario_names) if is_comparison else scenario_names[0]
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Territory Alignment: {escape(title)}</title>
+<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
+  integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY=" crossorigin="" />
+<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"
+  integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo=" crossorigin=""></script>
+<style>
+* {{ margin: 0; padding: 0; box-sizing: border-box; }}
+body {{ font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif; }}
+#map {{ width: 100%; height: 100vh; }}
+.panel {{
+  position: absolute; top: 10px; right: 10px; z-index: 1000;
+  background: rgba(255,255,255,0.95); border-radius: 8px;
+  padding: 16px; max-width: 320px; box-shadow: 0 2px 12px rgba(0,0,0,0.15);
+  font-size: 13px; max-height: 90vh; overflow-y: auto;
+}}
+.panel h2 {{ font-size: 15px; color: #1a365d; margin-bottom: 8px; border-bottom: 2px solid #2c5282; padding-bottom: 4px; }}
+.panel h3 {{ font-size: 13px; color: #2c5282; margin-top: 10px; margin-bottom: 4px; }}
+.legend-item {{ display: flex; align-items: center; gap: 6px; margin: 3px 0; }}
+.legend-dot {{ width: 14px; height: 14px; border-radius: 50%; flex-shrink: 0; border: 2px solid rgba(0,0,0,0.2); }}
+.legend-base {{ width: 14px; height: 14px; flex-shrink: 0; border: 2px solid rgba(0,0,0,0.3); transform: rotate(45deg); }}
+.stats {{ margin-top: 8px; }}
+.stats td {{ padding: 2px 8px 2px 0; }}
+.stats td:last-child {{ font-weight: 600; }}
+.toggle-group {{ margin: 10px 0; display: flex; gap: 0; }}
+.toggle-btn {{
+  flex: 1; padding: 6px 10px; border: 1px solid #2c5282; background: #fff;
+  color: #2c5282; cursor: pointer; font-size: 12px; font-weight: 600;
+  transition: all 0.15s;
+}}
+.toggle-btn:first-child {{ border-radius: 4px 0 0 4px; }}
+.toggle-btn:last-child {{ border-radius: 0 4px 4px 0; }}
+.toggle-btn.active {{ background: #2c5282; color: #fff; }}
+.movement-toggle {{ margin: 8px 0; }}
+.movement-toggle label {{ cursor: pointer; font-size: 12px; }}
+.delta {{ font-size: 11px; margin-left: 4px; }}
+.delta.better {{ color: #38a169; }}
+.delta.worse {{ color: #e53e3e; }}
+.segment-key {{ display: flex; gap: 12px; margin-top: 6px; font-size: 11px; color: #718096; }}
+.segment-key span {{ display: flex; align-items: center; gap: 3px; }}
+.seg-dot {{ border-radius: 50%; background: #a0aec0; display: inline-block; }}
+</style>
+</head>
+<body>
+<div id="map"></div>
+<div class="panel" id="panel"></div>
+
+<script>
+const MAP_DATA = {data_json};
+const SCENARIO_NAMES = {names_json};
+const COLOR_MAP = {colors_json};
+const IS_COMPARISON = {"true" if is_comparison else "false"};
+
+const map = L.map('map');
+L.tileLayer('https://{{s}}.basemaps.cartocdn.com/light_all/{{z}}/{{x}}/{{y}}@2x.png', {{
+  attribution: '&copy; OpenStreetMap &copy; CARTO',
+  maxZoom: 18
+}}).addTo(map);
+
+let currentScenario = SCENARIO_NAMES[0];
+let hcpLayers = {{}};
+let baseLayers = L.layerGroup().addTo(map);
+let movementLayer = L.layerGroup();
+let showMovements = true;
+
+function buildPanel() {{
+  const panel = document.getElementById('panel');
+  let html = '<h2>Territory Alignment</h2>';
+
+  if (IS_COMPARISON) {{
+    html += '<div class="toggle-group">';
+    SCENARIO_NAMES.forEach(name => {{
+      const cls = name === currentScenario ? 'active' : '';
+      html += `<button class="toggle-btn ${{cls}}" onclick="switchScenario('${{name}}')">${{name}}</button>`;
+    }});
+    html += '</div>';
+    html += '<div class="movement-toggle"><label><input type="checkbox" id="mvToggle" ' +
+      (showMovements ? 'checked' : '') + ' onchange="toggleMovements()"> Show movements</label></div>';
+  }}
+
+  const sc = MAP_DATA.scenario_layers[currentScenario];
+  const obj = sc.objectives;
+  html += '<h3>Scores</h3><table class="stats">';
+  html += `<tr><td>Composite</td><td>${{(obj.composite || 0).toFixed(3)}}</td></tr>`;
+  html += `<tr><td>Workload</td><td>${{(obj.workload_balance || 0).toFixed(3)}}</td></tr>`;
+  html += `<tr><td>Travel</td><td>${{(obj.travel_efficiency || 0).toFixed(3)}}</td></tr>`;
+  html += `<tr><td>Disruption</td><td>${{(obj.disruption || 0).toFixed(3)}}</td></tr>`;
+  html += `<tr><td>Coverage</td><td>${{(obj.coverage || 0).toFixed(3)}}</td></tr>`;
+  html += `<tr><td>Assigned</td><td>${{sc.assignment_count}}</td></tr>`;
+  html += `<tr><td>Unassigned</td><td>${{sc.unassigned.length}}</td></tr>`;
+  html += '</table>';
+
+  if (IS_COMPARISON) {{
+    const other = SCENARIO_NAMES.find(n => n !== currentScenario);
+    const scOther = MAP_DATA.scenario_layers[other];
+    const moved = MAP_DATA.movements.length;
+    html += `<h3>Changes vs ${{other}}</h3>`;
+    html += `<table class="stats"><tr><td>HCPs moved</td><td>${{moved}}</td></tr></table>`;
+  }}
+
+  html += '<h3>Rep Legend</h3>';
+  const repCounts = {{}};
+  sc.markers.forEach(m => {{ repCounts[m.rep_id] = (repCounts[m.rep_id] || 0) + 1; }});
+  Object.keys(COLOR_MAP).sort().forEach(rid => {{
+    const c = repCounts[rid] || 0;
+    if (c > 0 || MAP_DATA.rep_bases.some(b => b.rep_id === rid)) {{
+      const repBase = MAP_DATA.rep_bases.find(b => b.rep_id === rid);
+      const label = repBase ? `${{rid}} (${{repBase.rep_name}})` : rid;
+      html += `<div class="legend-item"><div class="legend-dot" style="background:${{COLOR_MAP[rid]}}"></div>${{label}} <span style="color:#718096">(${{c}})</span></div>`;
+    }}
+  }});
+
+  html += '<h3>Segment Size</h3>';
+  html += '<div class="segment-key">';
+  html += '<span><span class="seg-dot" style="width:10px;height:10px;"></span> high</span>';
+  html += '<span><span class="seg-dot" style="width:7px;height:7px;"></span> medium</span>';
+  html += '<span><span class="seg-dot" style="width:5px;height:5px;"></span> low</span>';
+  html += '</div>';
+
+  panel.innerHTML = html;
+}}
+
+function drawMarkers() {{
+  Object.values(hcpLayers).forEach(lg => lg.remove());
+  hcpLayers = {{}};
+
+  const sc = MAP_DATA.scenario_layers[currentScenario];
+  const lg = L.layerGroup().addTo(map);
+
+  sc.markers.forEach(m => {{
+    const movedHcp = IS_COMPARISON && MAP_DATA.movements.find(mv => mv.hcp_id === m.hcp_id);
+    const opts = {{
+      radius: m.radius,
+      fillColor: m.color,
+      color: movedHcp ? '#e53e3e' : 'rgba(0,0,0,0.3)',
+      weight: movedHcp ? 3 : 1.5,
+      fillOpacity: 0.8,
+      dashArray: movedHcp ? '4 3' : null,
+    }};
+    const circle = L.circleMarker([m.lat, m.lng], opts);
+    let popup = `<b>${{m.hcp_name}}</b><br>ID: ${{m.hcp_id}}<br>Rep: ${{m.rep_id}}<br>` +
+      `Segment: ${{m.segment}} &middot; Tier: ${{m.tier}}<br>Travel: ${{m.travel_min}} min`;
+    if (movedHcp) {{
+      popup += `<br><span style="color:#e53e3e;font-weight:600">Moved from ${{movedHcp.old_rep_id}} → ${{movedHcp.new_rep_id}}</span>`;
+    }}
+    circle.bindPopup(popup);
+    circle.addTo(lg);
+  }});
+
+  sc.unassigned.forEach(u => {{
+    const circle = L.circleMarker([u.lat, u.lng], {{
+      radius: 6, fillColor: '#e53e3e', color: '#fff', weight: 2, fillOpacity: 0.9,
+    }});
+    circle.bindPopup(`<b>${{u.hcp_name}}</b><br>ID: ${{u.hcp_id}}<br><span style="color:#e53e3e">Unassigned: ${{u.reason}}</span>`);
+    circle.addTo(lg);
+  }});
+
+  hcpLayers[currentScenario] = lg;
+}}
+
+function drawBases() {{
+  baseLayers.clearLayers();
+  MAP_DATA.rep_bases.forEach(b => {{
+    const icon = L.divIcon({{
+      className: '',
+      html: `<div style="width:18px;height:18px;background:${{b.color}};border:3px solid rgba(0,0,0,0.3);` +
+        `transform:rotate(45deg);box-shadow:0 1px 4px rgba(0,0,0,0.3);"></div>`,
+      iconSize: [18, 18],
+      iconAnchor: [9, 9],
+    }});
+    const marker = L.marker([b.lat, b.lng], {{ icon }});
+    marker.bindPopup(`<b>${{b.rep_name}}</b><br>ID: ${{b.rep_id}}<br>Home base`);
+    marker.addTo(baseLayers);
+  }});
+}}
+
+function drawMovements() {{
+  movementLayer.clearLayers();
+  if (!showMovements || !IS_COMPARISON) return;
+
+  MAP_DATA.movements.forEach(mv => {{
+    const oldBase = MAP_DATA.rep_bases.find(b => b.rep_id === mv.old_rep_id);
+    const newBase = MAP_DATA.rep_bases.find(b => b.rep_id === mv.new_rep_id);
+
+    if (oldBase && newBase) {{
+      L.polyline([[oldBase.lat, oldBase.lng], [mv.lat, mv.lng]], {{
+        color: mv.old_color, weight: 1.5, opacity: 0.35, dashArray: '4 4'
+      }}).bindPopup(
+        `<b>${{mv.hcp_name}}</b><br>${{mv.old_rep_id}} &rarr; ${{mv.new_rep_id}}`
+      ).addTo(movementLayer);
+      L.polyline([[mv.lat, mv.lng], [newBase.lat, newBase.lng]], {{
+        color: mv.new_color, weight: 2, opacity: 0.6
+      }}).addTo(movementLayer);
+    }}
+  }});
+
+  movementLayer.addTo(map);
+}}
+
+function switchScenario(name) {{
+  currentScenario = name;
+  drawMarkers();
+  drawMovements();
+  buildPanel();
+}}
+
+function toggleMovements() {{
+  showMovements = document.getElementById('mvToggle').checked;
+  if (showMovements) {{
+    drawMovements();
+  }} else {{
+    movementLayer.clearLayers();
+    movementLayer.remove();
+  }}
+}}
+
+// Init
+drawMarkers();
+drawBases();
+drawMovements();
+buildPanel();
+
+// Fit bounds
+const allPoints = [];
+MAP_DATA.scenario_layers[SCENARIO_NAMES[0]].markers.forEach(m => allPoints.push([m.lat, m.lng]));
+MAP_DATA.rep_bases.forEach(b => allPoints.push([b.lat, b.lng]));
+if (allPoints.length > 0) {{
+  map.fitBounds(L.latLngBounds(allPoints).pad(0.1));
+}}
+</script>
+</body>
+</html>"""

shared/__init__.py

@@ -0,0 +1,11 @@
+"""`shared` — reusable library for open-pharma-plugins capabilities.
+
+A plain library at the src/ root (peer to mcp_framework), importable by any
+capability from source AND the wheel — it is NOT a server/capability (no __main__, no
+tools, no console entry). Submodules:
+
+  - shared.env           config + get_env (the single call-time entry for reading env vars)
+
+Reuse these across capabilities instead of importing a sibling capability's server package
+(that only resolves once installed, and couples the servers together).
+"""