ifixkart-backend/swarm/scenarios/whatsapp_preflight.py

214 lines
8.9 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 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.")
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."
)
total_prompt_tokens += usage.prompt_tokens
total_completion_tokens += usage.completion_tokens
total_cost += usage.estimated_cost_usd
spam_reaction = reasoning.spam_reaction
quote = reasoning.interview_quote
except Exception:
spam_reaction = "Tolerates targeted repair offers if infrequent."
quote = "I don't mind a useful discount message once a month, but if you text weekly I'll block the number."
archetype_breakdown.append({
"name": p_list[0].archetype_name,
"share": f"{len(p_list)/len(personas):.0%}",
"rate": f"{sub_clicks/len(p_list):.1%}",
"friction": spam_reaction
})
interview_samples.append({
"persona": f"{p_list[0].archetype_name} ({p_list[0].name})",
"quote": quote
})
# 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),
"simulated_block_rate_pct": round(simulated_block_rate * 100.0, 2),
"whatsapp_block_risk_score": round(block_risk_score, 1),
"risk_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)
)