ifixkart-backend/swarm/scenarios/whatsapp_preflight.py

236 lines
10 KiB
Python

"""
@scenario WhatsAppPreflightScenario (swarm/scenarios/whatsapp_preflight.py)
@purpose Simulates customer reception, click-through rates, and phone number block/spam risk
for proposed WhatsApp campaigns before broadcasting via OpenWA.
"""
import asyncio
import time
import json
from typing import Dict, Any, Callable, Optional, List
from pydantic import BaseModel, Field
from swarm.core.persona_generator import generate_personas, AgentPersona
from swarm.core.calibration import (
fetch_historical_baseline,
compute_simulation_dispersion,
synthesize_calibrated_projection,
)
from swarm.core.synthesizer import generate_markdown_report
from swarm.providers import get_llm_provider
from swarm.scenarios.base_scenario import BaseScenario, ScenarioResult
class WhatsAppArchetypeReasoning(BaseModel):
archetype_id: str
spam_reaction: str
interview_quote: str
class WhatsAppPreflightScenario(BaseScenario):
async def run(
self,
input_params: Dict[str, Any],
store_id: int = 1,
cancellation_check: Optional[Callable[[], bool]] = None,
heartbeat_callback: Optional[Callable[[], None]] = None
) -> ScenarioResult:
start_time = time.perf_counter()
# 1. Parse inputs
message_template = str(input_params.get("message_template", "Hey there! Exclusive 20% off all display repairs this weekend at iFixKart!"))
offer_type = str(input_params.get("offer_type", "20% Discount"))
frequency = int(input_params.get("frequency_per_month", 2))
target_segment = str(input_params.get("target_segment", "Past Customers"))
# 2. Baseline
baseline = fetch_historical_baseline("whatsapp_preflight", store_id)
if heartbeat_callback:
heartbeat_callback()
if cancellation_check and cancellation_check():
raise InterruptedError("Simulation cancelled by user.")
# 3. Personas
personas = generate_personas(count=50, seed=101)
agent_outcomes: List[float] = []
agent_logs: List[Dict[str, Any]] = []
spam_block_count = 0
click_count = 0
# Frequency penalty
freq_irritation_multiplier = 1.0 + max(0, frequency - 2) * 0.35
for p in personas:
# Willingness to click
click_prob = min(0.65, max(0.02, baseline.empirical_mean + (p.price_sensitivity * 0.12) - (p.whatsapp_irritation_threshold * 0.05)))
# Risk of reporting spam / blocking
block_hazard = p.whatsapp_irritation_threshold * freq_irritation_multiplier * 0.15
if frequency > 4:
block_hazard += 0.20
will_block = block_hazard > 0.45
if will_block:
spam_block_count += 1
click_prob = 0.0
elif click_prob > 0.15:
click_count += 1
agent_outcomes.append(click_prob)
agent_logs.append({
"agent_id": p.agent_id,
"archetype": p.archetype_name,
"click_prob": round(click_prob, 3),
"block_hazard": round(block_hazard, 3),
"decision": "BLOCK" if will_block else ("CLICK" if click_prob > 0.15 else "IGNORE")
})
if heartbeat_callback:
heartbeat_callback()
# 4. Dispersion & Calibration
dispersion = compute_simulation_dispersion(agent_outcomes)
projection = synthesize_calibrated_projection(baseline, dispersion)
# 5. LLM Synthesis
provider = get_llm_provider()
archetype_breakdown = []
interview_samples = []
total_prompt_tokens = 0
total_completion_tokens = 0
total_cost = 0.0
# Group by archetype
arch_groups = {}
for p in personas:
arch_groups.setdefault(p.archetype_id, []).append(p)
for arch_id, p_list in arch_groups.items():
if cancellation_check and cancellation_check():
raise InterruptedError("Simulation cancelled by user.")
async def _eval_wa_archetype(arch_id: str, p_list: List[AgentPersona]):
sub_logs = [log for log in agent_logs if log["agent_id"] in {p.agent_id for p in p_list}]
sub_clicks = sum(1 for log in sub_logs if log["decision"] == "CLICK")
sub_blocks = sum(1 for log in sub_logs if log["decision"] == "BLOCK")
prompt = (
f"You are simulating customer reactions to an iFixKart WhatsApp broadcast message.\n"
f"Message Copy: \"{message_template}\"\n"
f"Monthly frequency: {frequency} messages/month.\n"
f"Archetype: {p_list[0].archetype_name} (Total: {len(p_list)}, Clicks: {sub_clicks}, Blocks: {sub_blocks}).\n"
f"Provide a 1-sentence reaction and a simulated customer quote about this broadcast."
)
try:
reasoning, usage = await provider.generate_structured(
prompt=prompt,
schema=WhatsAppArchetypeReasoning,
system_prompt="You are a messaging deliverability & customer sentiment analyst."
)
return {
"breakdown": {
"name": p_list[0].archetype_name,
"share": f"{len(p_list)/len(personas):.0%}",
"rate": f"{sub_clicks/max(1, len(p_list)):.1%}",
"friction": reasoning.spam_reaction
},
"sample": {
"persona": f"{p_list[0].archetype_name} ({p_list[0].name})",
"quote": reasoning.interview_quote
},
"usage": usage
}
except Exception:
return {
"breakdown": {
"name": p_list[0].archetype_name,
"share": f"{len(p_list)/len(personas):.0%}",
"rate": f"{sub_clicks/max(1, len(p_list)):.1%}",
"friction": "Tolerates targeted repair offers if infrequent."
},
"sample": {
"persona": f"{p_list[0].archetype_name} ({p_list[0].name})",
"quote": "I don't mind a useful discount message once a month, but if you text weekly I'll block the number."
},
"usage": None
}
results = await asyncio.gather(*(_eval_wa_archetype(a_id, p_l) for a_id, p_l in arch_groups.items()))
for r in results:
archetype_breakdown.append(r["breakdown"])
interview_samples.append(r["sample"])
if r["usage"]:
total_prompt_tokens += r["usage"].prompt_tokens
total_completion_tokens += r["usage"].completion_tokens
total_cost += r["usage"].estimated_cost_usd
# 6. Block Risk Score (0 - 100)
simulated_block_rate = spam_block_count / max(1, len(personas))
block_risk_score = min(100.0, simulated_block_rate * 300.0)
if block_risk_score < 25.0:
risk_verdict = "LOW RISK (Safe for broadcast)"
elif block_risk_score < 50.0:
risk_verdict = "MODERATE RISK (Monitor unsubscribes)"
else:
risk_verdict = "HIGH RISK (Threat of WhatsApp number restriction)"
summary_metrics = {
"message_length_chars": len(message_template),
"monthly_frequency": frequency,
"target_segment": target_segment,
"baseline_ctr_pct": round(baseline.empirical_mean * 100.0, 2),
"projected_ctr_pct": round(projection.calibrated_projected_value * 100.0, 2),
"baseline_open_rate_pct": round(baseline.empirical_mean * 100.0 * 2.5, 2),
"projected_open_rate_pct": round(projection.calibrated_projected_value * 100.0 * 2.5, 2),
"simulated_block_rate_pct": round(simulated_block_rate * 100.0, 2),
"whatsapp_block_risk_score": round(block_risk_score, 1),
"spam_block_risk_score": round(block_risk_score, 1),
"risk_verdict": risk_verdict,
"safety_verdict": risk_verdict
}
# 7. Render Report
elapsed_ms = int((time.perf_counter() - start_time) * 1000)
telemetry = {
"formatted_inputs": json.dumps(input_params, indent=2),
"recommendation_summary": (
f"Block risk score is {block_risk_score:.1f}/100. "
f"{'Message copy is acceptable for broadcasting.' if block_risk_score < 30.0 else 'High opt-out risk! Reduce frequency from ' + str(frequency) + ' to 2/month and add clear opt-out instructions.'}"
),
"execution_time_ms": elapsed_ms,
"model_name": getattr(provider, "model", "mock"),
"total_tokens": total_prompt_tokens + total_completion_tokens,
"prompt_tokens": total_prompt_tokens,
"completion_tokens": total_completion_tokens,
"total_cost_usd": round(total_cost, 6)
}
report_md = generate_markdown_report(
scenario_type="whatsapp_preflight",
scenario_title=f"WhatsApp Campaign Pre-Flight (Risk Score: {block_risk_score:.1f}/100)",
input_params=input_params,
baseline=baseline,
dispersion=dispersion,
projection=projection,
archetype_breakdown=archetype_breakdown,
interview_samples=interview_samples,
telemetry=telemetry
)
return ScenarioResult(
scenario_type="whatsapp_preflight",
scenario_title=f"WhatsApp Pre-Flight ({risk_verdict})",
baseline=baseline,
dispersion=dispersion,
projection=projection,
summary_metrics=summary_metrics,
archetype_breakdown=archetype_breakdown,
interview_samples=interview_samples,
agent_logs=agent_logs,
report_markdown=report_md,
execution_time_ms=elapsed_ms,
prompt_tokens=total_prompt_tokens,
completion_tokens=total_completion_tokens,
total_cost_usd=round(total_cost, 6)
)