Referral Program

#!/usr/bin/env python3
"""Affiliate Commission Modeler - Model affiliate commission structures and economics.

Calculates per-tier commission economics, lifetime partner value, and compares
flat fee vs recurring percentage commission models.

Usage:
    python affiliate_commission_modeler.py affiliate.json
    python affiliate_commission_modeler.py affiliate.json --format json
"""

import argparse
import json
import sys
from typing import Any


def safe_divide(num: float, den: float, default: float = 0.0) -> float:
    """Safely divide."""
    return num / den if den != 0 else default


DEFAULT_TIERS = [
    {"name": "Standard", "min_conversions": 0, "commission_pct": 20},
    {"name": "Silver", "min_conversions": 10, "commission_pct": 25},
    {"name": "Gold", "min_conversions": 25, "commission_pct": 30},
]


def model_commissions(data: dict) -> dict:
    """Model affiliate commission economics."""
    business = data.get("business", {})
    program = data.get("program", {})
    partners = data.get("partners", [])

    avg_monthly_revenue = business.get("avg_monthly_revenue_per_customer", 0)
    avg_customer_lifetime_months = business.get("avg_customer_lifetime_months", 24)
    avg_ltv = avg_monthly_revenue * avg_customer_lifetime_months
    gross_margin_pct = business.get("gross_margin_pct", 80) / 100

    tiers = program.get("tiers", DEFAULT_TIERS)
    cookie_window_days = program.get("cookie_window_days", 30)
    payment_threshold = program.get("payment_threshold", 50)
    commission_type = program.get("commission_type", "recurring")  # recurring or flat

    flat_fee = program.get("flat_fee_per_conversion", 0)

    # Tier analysis
    tier_analysis = []
    for tier in tiers:
        commission_pct = tier.get("commission_pct", 20) / 100

        if commission_type == "recurring":
            monthly_commission_per_customer = avg_monthly_revenue * commission_pct
            lifetime_commission_per_customer = monthly_commission_per_customer * avg_customer_lifetime_months
            effective_cac = lifetime_commission_per_customer
        else:
            monthly_commission_per_customer = 0
            lifetime_commission_per_customer = flat_fee
            effective_cac = flat_fee

        # Margin after commission
        if commission_type == "recurring":
            margin_after_commission = (avg_monthly_revenue * gross_margin_pct) - monthly_commission_per_customer
            margin_after_commission_pct = safe_divide(margin_after_commission, avg_monthly_revenue) * 100
        else:
            # Flat fee only impacts first month
            margin_after_commission = (avg_monthly_revenue * gross_margin_pct) - safe_divide(flat_fee, avg_customer_lifetime_months)
            margin_after_commission_pct = safe_divide(margin_after_commission, avg_monthly_revenue) * 100

        ltv_after_commission = avg_ltv * gross_margin_pct - lifetime_commission_per_customer
        ltv_cac = safe_divide(avg_ltv * gross_margin_pct, effective_cac) if effective_cac > 0 else float('inf')

        tier_analysis.append({
            "tier_name": tier.get("name", "Unknown"),
            "min_conversions": tier.get("min_conversions", 0),
            "commission_pct": tier.get("commission_pct", 20),
            "monthly_commission_per_customer": round(monthly_commission_per_customer, 2),
            "lifetime_commission_per_customer": round(lifetime_commission_per_customer, 2),
            "effective_cac": round(effective_cac, 2),
            "margin_after_commission_pct": round(margin_after_commission_pct, 1),
            "ltv_after_commission": round(ltv_after_commission, 2),
            "ltv_cac_ratio": round(ltv_cac, 1) if ltv_cac != float('inf') else "Infinite",
            "sustainable": ltv_after_commission > 0,
        })

    # Partner analysis
    partner_analysis = []
    total_partner_revenue = 0
    total_partner_cost = 0

    for partner in partners:
        name = partner.get("name", "Unknown")
        conversions = partner.get("monthly_conversions", 0)
        total_conversions = partner.get("total_conversions", conversions)

        # Find applicable tier
        applicable_tier = tiers[0]
        for tier in tiers:
            if total_conversions >= tier.get("min_conversions", 0):
                applicable_tier = tier

        commission_pct = applicable_tier.get("commission_pct", 20) / 100

        if commission_type == "recurring":
            monthly_payout = conversions * avg_monthly_revenue * commission_pct
            # Also paying on retained customers from previous months
            retained_customers = partner.get("active_customers", conversions)
            total_monthly_payout = retained_customers * avg_monthly_revenue * commission_pct
        else:
            monthly_payout = conversions * flat_fee
            total_monthly_payout = monthly_payout

        monthly_revenue_generated = conversions * avg_monthly_revenue
        annual_payout = total_monthly_payout * 12
        annual_revenue = monthly_revenue_generated * 12

        total_partner_revenue += annual_revenue
        total_partner_cost += annual_payout

        partner_analysis.append({
            "name": name,
            "tier": applicable_tier.get("name", "Standard"),
            "monthly_conversions": conversions,
            "total_conversions": total_conversions,
            "monthly_revenue_generated": round(monthly_revenue_generated, 2),
            "monthly_payout": round(total_monthly_payout, 2),
            "annual_payout": round(annual_payout, 2),
            "roi": round(safe_divide(annual_revenue, annual_payout), 1) if annual_payout > 0 else "Infinite",
        })

    # Model comparison (recurring vs flat)
    model_comparison = None
    if commission_type == "recurring":
        # Compare against flat fee equivalent
        # What flat fee gives same total payout as recurring over lifetime?
        recurring_lifetime = avg_monthly_revenue * (tiers[0]["commission_pct"] / 100) * avg_customer_lifetime_months
        model_comparison = {
            "current_model": "Recurring",
            "current_lifetime_cost": round(recurring_lifetime, 2),
            "equivalent_flat_fee": round(recurring_lifetime, 2),
            "note": f"A ${recurring_lifetime:.0f} flat fee equals your standard-tier recurring commission over {avg_customer_lifetime_months} months",
            "recurring_advantage": "Aligns partner incentives with retention (they benefit from your retention)",
            "flat_advantage": "Lower total cost if customers retain longer than expected; simpler accounting",
        }

    return {
        "summary": {
            "commission_type": commission_type,
            "tier_count": len(tiers),
            "partner_count": len(partners),
            "avg_ltv": round(avg_ltv, 2),
            "cookie_window_days": cookie_window_days,
            "total_annual_partner_revenue": round(total_partner_revenue, 2),
            "total_annual_partner_cost": round(total_partner_cost, 2),
            "program_roi": round(safe_divide(total_partner_revenue, total_partner_cost), 1) if total_partner_cost > 0 else "N/A",
        },
        "tier_analysis": tier_analysis,
        "partner_analysis": partner_analysis,
        "model_comparison": model_comparison,
    }


def format_text(result: dict) -> str:
    """Format as human-readable text."""
    lines = []
    s = result["summary"]

    lines.append("=" * 60)
    lines.append("AFFILIATE COMMISSION MODEL")
    lines.append("=" * 60)
    lines.append("")
    lines.append(f"Commission Type: {s['commission_type'].title()}")
    lines.append(f"Tiers: {s['tier_count']}  |  Partners: {s['partner_count']}")
    lines.append(f"Avg Customer LTV: ${s['avg_ltv']:,.2f}")
    lines.append(f"Cookie Window: {s['cookie_window_days']} days")
    lines.append(f"Program ROI: {s['program_roi']}x" if isinstance(s['program_roi'], (int, float)) else f"Program ROI: {s['program_roi']}")
    lines.append("")

    lines.append("-" * 60)
    lines.append("TIER ECONOMICS")
    lines.append("-" * 60)
    for tier in result["tier_analysis"]:
        sustainable = "OK" if tier["sustainable"] else "UNSUSTAINABLE"
        lines.append(f"\n  {tier['tier_name']} ({tier['commission_pct']}% | {tier['min_conversions']}+ conversions)")
        lines.append(f"    Commission/customer/mo: ${tier['monthly_commission_per_customer']:,.2f}")
        lines.append(f"    Lifetime commission:    ${tier['lifetime_commission_per_customer']:,.2f}")
        lines.append(f"    Margin after commission: {tier['margin_after_commission_pct']:.1f}%")
        ltv_cac = tier['ltv_cac_ratio']
        lines.append(f"    LTV:CAC:                {ltv_cac}:1" if isinstance(ltv_cac, (int, float)) else f"    LTV:CAC:                {ltv_cac}")
        lines.append(f"    Status:                 {sustainable}")

    if result["partner_analysis"]:
        lines.append("")
        lines.append("-" * 60)
        lines.append("PARTNER PERFORMANCE")
        lines.append("-" * 60)
        for p in result["partner_analysis"]:
            roi_str = f"{p['roi']}x" if isinstance(p['roi'], (int, float)) else p['roi']
            lines.append(f"  {p['name']} [{p['tier']}]: {p['monthly_conversions']} conv/mo | ${p['monthly_payout']:,.0f}/mo payout | ROI: {roi_str}")

    if result.get("model_comparison"):
        mc = result["model_comparison"]
        lines.append("")
        lines.append("-" * 40)
        lines.append("MODEL COMPARISON")
        lines.append("-" * 40)
        lines.append(f"  Current: {mc['current_model']}")
        lines.append(f"  Lifetime cost/customer: ${mc['current_lifetime_cost']:,.2f}")
        lines.append(f"  Equivalent flat fee: ${mc['equivalent_flat_fee']:,.2f}")
        lines.append(f"  Recurring advantage: {mc['recurring_advantage']}")
        lines.append(f"  Flat advantage: {mc['flat_advantage']}")

    lines.append("")
    return "\n".join(lines)


def main() -> None:
    """Main entry point."""
    parser = argparse.ArgumentParser(
        description="Model affiliate commission structures and economics."
    )
    parser.add_argument(
        "input_file",
        help="Path to JSON file with affiliate program data",
    )
    parser.add_argument(
        "--format",
        choices=["text", "json"],
        default="text",
        help="Output format (default: text)",
    )
    args = parser.parse_args()

    try:
        with open(args.input_file, "r") as f:
            data = json.load(f)
    except FileNotFoundError:
        print(f"Error: File not found: {args.input_file}", file=sys.stderr)
        sys.exit(1)
    except json.JSONDecodeError as e:
        print(f"Error: Invalid JSON: {e}", file=sys.stderr)
        sys.exit(1)

    result = model_commissions(data)

    if args.format == "json":
        print(json.dumps(result, indent=2))
    else:
        print(format_text(result))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Referral Economics Calculator - Model referral program economics and ROI.

Calculates reward sizing, K-factor, referral CAC, ROI projections, and break-even
analysis. Compares double-sided vs single-sided reward structures.

Usage:
    python referral_economics_calculator.py program.json
    python referral_economics_calculator.py program.json --format json
"""

import argparse
import json
import sys
from typing import Any


def safe_divide(num: float, den: float, default: float = 0.0) -> float:
    """Safely divide."""
    return num / den if den != 0 else default


def calculate_k_factor(avg_invitations: float, invitation_conversion_rate: float) -> float:
    """Calculate viral coefficient (K-factor)."""
    return avg_invitations * invitation_conversion_rate


def rate_k_factor(k: float) -> str:
    """Rate K-factor against benchmarks."""
    if k >= 1.0:
        return "Viral (exponential growth)"
    elif k >= 0.7:
        return "Strong referral contribution"
    elif k >= 0.3:
        return "Moderate referral contribution"
    elif k >= 0.1:
        return "Weak -- program needs optimization"
    else:
        return "Negligible -- fundamental redesign needed"


def model_economics(data: dict) -> dict:
    """Model referral program economics."""
    program = data.get("program", {})
    business = data.get("business", {})

    # Business metrics
    avg_ltv = business.get("avg_customer_ltv", 0)
    avg_first_payment = business.get("avg_first_payment", 0)
    other_cac = business.get("other_channel_cac", 0)
    active_users = business.get("active_users", 0)
    avg_monthly_revenue = business.get("avg_monthly_revenue_per_customer", 0)

    # Program metrics
    referrer_reward = program.get("referrer_reward", 0)
    referred_reward = program.get("referred_reward", 0)
    is_double_sided = referred_reward > 0
    reward_type = program.get("reward_type", "credit")  # credit, cash, discount, feature

    avg_invitations = program.get("avg_invitations_per_user", 0)
    invitation_conversion = program.get("invitation_conversion_rate", 0)
    active_referrer_pct = program.get("active_referrer_pct", 5) / 100

    # K-factor
    k_factor = calculate_k_factor(avg_invitations, invitation_conversion)
    k_rating = rate_k_factor(k_factor)

    # Cost per referral
    total_reward_per_referral = referrer_reward + referred_reward
    referral_cac = total_reward_per_referral  # Assuming 1:1 reward to acquisition

    # CAC comparison
    cac_savings_pct = safe_divide(other_cac - referral_cac, other_cac) * 100

    # LTV:CAC for referrals
    ltv_cac_ratio = safe_divide(avg_ltv, referral_cac) if referral_cac > 0 else float('inf')

    # Maximum sustainable reward
    target_referral_cac_pct = 15  # 15% of LTV
    max_reward = avg_ltv * (target_referral_cac_pct / 100)
    if is_double_sided:
        max_per_side = max_reward / 2
    else:
        max_per_side = max_reward

    # Revenue projections
    active_referrers = int(active_users * active_referrer_pct)
    monthly_referrals_sent = active_referrers * avg_invitations
    monthly_new_customers = int(monthly_referrals_sent * invitation_conversion)
    monthly_referral_revenue = monthly_new_customers * avg_monthly_revenue
    annual_referral_revenue = monthly_referral_revenue * 12
    monthly_reward_cost = monthly_new_customers * total_reward_per_referral
    annual_reward_cost = monthly_reward_cost * 12

    # ROI
    annual_profit = annual_referral_revenue - annual_reward_cost
    roi_pct = safe_divide(annual_profit, annual_reward_cost) * 100

    # Referral revenue share
    total_monthly_revenue = active_users * avg_monthly_revenue if avg_monthly_revenue > 0 else 1
    referral_revenue_share = safe_divide(monthly_referral_revenue, total_monthly_revenue) * 100

    # Double-sided vs single-sided comparison
    comparison = None
    if is_double_sided:
        # Model what single-sided would look like (assume 40% lower conversion)
        single_conversion = invitation_conversion * 0.6
        single_new_customers = int(monthly_referrals_sent * single_conversion)
        single_cost = single_new_customers * referrer_reward
        single_revenue = single_new_customers * avg_monthly_revenue * 12

        comparison = {
            "double_sided": {
                "annual_customers": monthly_new_customers * 12,
                "annual_revenue": round(annual_referral_revenue, 2),
                "annual_cost": round(annual_reward_cost, 2),
                "annual_profit": round(annual_profit, 2),
            },
            "single_sided_estimate": {
                "annual_customers": single_new_customers * 12,
                "annual_revenue": round(single_revenue, 2),
                "annual_cost": round(single_cost * 12, 2),
                "annual_profit": round(single_revenue - single_cost * 12, 2),
                "note": "Estimated at 40% lower conversion rate without referred reward",
            },
        }

    return {
        "k_factor": {
            "value": round(k_factor, 3),
            "rating": k_rating,
            "avg_invitations": avg_invitations,
            "invitation_conversion_rate": invitation_conversion,
        },
        "unit_economics": {
            "referral_cac": round(referral_cac, 2),
            "other_channel_cac": other_cac,
            "cac_savings_pct": round(cac_savings_pct, 1),
            "ltv_cac_ratio": round(ltv_cac_ratio, 1) if ltv_cac_ratio != float('inf') else "Infinite",
            "max_sustainable_reward": round(max_reward, 2),
            "max_per_side": round(max_per_side, 2),
            "current_reward_sustainable": total_reward_per_referral <= max_reward,
        },
        "projections": {
            "active_referrers": active_referrers,
            "monthly_referrals_sent": int(monthly_referrals_sent),
            "monthly_new_customers": monthly_new_customers,
            "monthly_referral_revenue": round(monthly_referral_revenue, 2),
            "annual_referral_revenue": round(annual_referral_revenue, 2),
            "monthly_reward_cost": round(monthly_reward_cost, 2),
            "annual_reward_cost": round(annual_reward_cost, 2),
            "annual_profit": round(annual_profit, 2),
            "roi_pct": round(roi_pct, 1),
            "referral_revenue_share_pct": round(referral_revenue_share, 1),
        },
        "reward_structure": {
            "type": "double_sided" if is_double_sided else "single_sided",
            "referrer_reward": referrer_reward,
            "referred_reward": referred_reward,
            "total_per_referral": total_reward_per_referral,
            "reward_type": reward_type,
        },
        "comparison": comparison,
    }


def format_text(result: dict) -> str:
    """Format as human-readable text."""
    lines = []

    lines.append("=" * 60)
    lines.append("REFERRAL PROGRAM ECONOMICS")
    lines.append("=" * 60)
    lines.append("")

    # K-factor
    kf = result["k_factor"]
    lines.append("-" * 40)
    lines.append("VIRAL COEFFICIENT (K-FACTOR)")
    lines.append("-" * 40)
    lines.append(f"  K-factor: {kf['value']}")
    lines.append(f"  Rating: {kf['rating']}")
    lines.append(f"  Avg invitations/user: {kf['avg_invitations']}")
    lines.append(f"  Invitation conversion: {kf['invitation_conversion_rate']*100:.1f}%")
    lines.append("")

    # Unit economics
    ue = result["unit_economics"]
    lines.append("-" * 40)
    lines.append("UNIT ECONOMICS")
    lines.append("-" * 40)
    lines.append(f"  Referral CAC:          ${ue['referral_cac']:>10,.2f}")
    lines.append(f"  Other Channel CAC:     ${ue['other_channel_cac']:>10,.2f}")
    lines.append(f"  CAC Savings:           {ue['cac_savings_pct']:>10.1f}%")
    ltv_cac = ue['ltv_cac_ratio']
    lines.append(f"  LTV:CAC Ratio:         {ltv_cac}:1" if isinstance(ltv_cac, (int, float)) else f"  LTV:CAC Ratio:         {ltv_cac}")
    lines.append(f"  Max Sustainable Reward: ${ue['max_sustainable_reward']:>9,.2f}")
    sustainable = "Yes" if ue["current_reward_sustainable"] else "NO -- reward exceeds 15% of LTV"
    lines.append(f"  Current Reward OK:     {sustainable}")
    lines.append("")

    # Projections
    pr = result["projections"]
    lines.append("-" * 40)
    lines.append("REVENUE PROJECTIONS")
    lines.append("-" * 40)
    lines.append(f"  Active Referrers:      {pr['active_referrers']:>10,}")
    lines.append(f"  Monthly Referrals:     {pr['monthly_referrals_sent']:>10,}")
    lines.append(f"  Monthly New Customers: {pr['monthly_new_customers']:>10,}")
    lines.append(f"  Monthly Revenue:       ${pr['monthly_referral_revenue']:>10,.2f}")
    lines.append(f"  Annual Revenue:        ${pr['annual_referral_revenue']:>10,.2f}")
    lines.append(f"  Annual Reward Cost:    ${pr['annual_reward_cost']:>10,.2f}")
    lines.append(f"  Annual Profit:         ${pr['annual_profit']:>10,.2f}")
    lines.append(f"  ROI:                   {pr['roi_pct']:>10.1f}%")
    lines.append(f"  Revenue Share:         {pr['referral_revenue_share_pct']:>10.1f}% of total")
    lines.append("")

    # Reward structure
    rs = result["reward_structure"]
    lines.append("-" * 40)
    lines.append("REWARD STRUCTURE")
    lines.append("-" * 40)
    lines.append(f"  Type: {rs['type'].replace('_', ' ').title()}")
    lines.append(f"  Referrer: ${rs['referrer_reward']:,.2f} ({rs['reward_type']})")
    if rs["referred_reward"] > 0:
        lines.append(f"  Referred: ${rs['referred_reward']:,.2f} ({rs['reward_type']})")
    lines.append(f"  Total/Referral: ${rs['total_per_referral']:,.2f}")
    lines.append("")

    # Comparison
    if result.get("comparison"):
        comp = result["comparison"]
        lines.append("-" * 40)
        lines.append("DOUBLE vs SINGLE-SIDED COMPARISON")
        lines.append("-" * 40)
        ds = comp["double_sided"]
        ss = comp["single_sided_estimate"]
        lines.append(f"  {'':20} {'Double':>12} {'Single (est)':>12}")
        lines.append(f"  {'Customers/yr':20} {ds['annual_customers']:>12,} {ss['annual_customers']:>12,}")
        lines.append(f"  {'Revenue/yr':20} ${ds['annual_revenue']:>10,.0f} ${ss['annual_revenue']:>10,.0f}")
        lines.append(f"  {'Cost/yr':20} ${ds['annual_cost']:>10,.0f} ${ss['annual_cost']:>10,.0f}")
        lines.append(f"  {'Profit/yr':20} ${ds['annual_profit']:>10,.0f} ${ss['annual_profit']:>10,.0f}")

    lines.append("")
    return "\n".join(lines)


def main() -> None:
    """Main entry point."""
    parser = argparse.ArgumentParser(
        description="Calculate referral program economics and ROI."
    )
    parser.add_argument(
        "input_file",
        help="Path to JSON file with program economics data",
    )
    parser.add_argument(
        "--format",
        choices=["text", "json"],
        default="text",
        help="Output format (default: text)",
    )
    args = parser.parse_args()

    try:
        with open(args.input_file, "r") as f:
            data = json.load(f)
    except FileNotFoundError:
        print(f"Error: File not found: {args.input_file}", file=sys.stderr)
        sys.exit(1)
    except json.JSONDecodeError as e:
        print(f"Error: Invalid JSON: {e}", file=sys.stderr)
        sys.exit(1)

    result = model_economics(data)

    if args.format == "json":
        print(json.dumps(result, indent=2))
    else:
        print(format_text(result))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Referral Funnel Analyzer - Analyze the 4-stage referral loop with diagnostics.

Evaluates each stage (trigger, share, convert, reward) against benchmarks, identifies
the weakest stage, and provides prioritized improvement recommendations.

Usage:
    python referral_funnel_analyzer.py funnel.json
    python referral_funnel_analyzer.py funnel.json --format json
"""

import argparse
import json
import sys
from typing import Any


STAGE_BENCHMARKS = {
    "awareness": {"target": 40, "good": 25, "label": "Program Awareness (% of active users who know it exists)"},
    "active_referrers": {"target": 15, "good": 5, "label": "Active Referrers (% of aware users who send referrals)"},
    "share_rate": {"target": 40, "good": 20, "label": "Share Rate (% of prompted users who share)"},
    "referred_conversion": {"target": 25, "good": 15, "label": "Referred Conversion (% of referrals that convert)"},
    "reward_redemption": {"target": 90, "good": 70, "label": "Reward Redemption (% redeemed within 30 days)"},
}

STAGE_RECOMMENDATIONS = {
    "awareness": [
        "Add persistent referral widget to user dashboard",
        "Trigger referral prompt after NPS 9-10 responses",
        "Send post-activation email with referral link (3-5 days after activation)",
        "Add referral CTA to monthly usage digest emails",
        "Show referral prompt after milestone achievements",
    ],
    "active_referrers": [
        "Improve incentive visibility (show reward prominently in prompt)",
        "Use double-sided rewards if currently single-sided",
        "Time triggers to high-satisfaction moments (post-milestone, post-support resolution)",
        "Test different reward types (credit vs cash vs feature unlock)",
        "Add tiered rewards for multiple referrals (gamification)",
    ],
    "share_rate": [
        "Add one-click copy link button (most popular share method)",
        "Pre-fill share messages in first person (sounds personal, not marketing)",
        "Add native share sheet on mobile for frictionless sharing",
        "Include multiple share channels (email, Slack, LinkedIn, Twitter)",
        "Reduce steps between referral prompt and actual share action",
    ],
    "referred_conversion": [
        "Personalize landing page with referrer name and photo",
        "Display the incentive above the fold on referral landing page",
        "Pre-fill referred user email if available from share mechanism",
        "Add SSO/social login to reduce signup friction",
        "Ensure 30-day attribution cookie for multi-session conversion",
    ],
    "reward_redemption": [
        "Auto-apply account credits immediately (no manual redemption)",
        "Send instant notification when referral converts",
        "Show cumulative earnings in referral dashboard",
        "Send reminder email for unredeemed rewards after 7 days",
        "Make redemption one-click (no extra steps or forms)",
    ],
}


def safe_divide(num: float, den: float, default: float = 0.0) -> float:
    """Safely divide."""
    return num / den if den != 0 else default


def rate_stage(value: float, benchmark: dict) -> str:
    """Rate a stage against benchmarks."""
    if value >= benchmark["target"]:
        return "Excellent"
    elif value >= benchmark["good"]:
        return "Good"
    elif value >= benchmark["good"] * 0.5:
        return "Needs Improvement"
    else:
        return "Critical"


def analyze_funnel(data: dict) -> dict:
    """Analyze referral funnel stages."""
    stages = data.get("stages", {})
    active_users = data.get("active_users", 0)

    stage_analysis = []
    weakest_stage = None
    weakest_score = 100

    for stage_key, benchmark in STAGE_BENCHMARKS.items():
        value = stages.get(stage_key)
        if value is None:
            continue

        rating = rate_stage(value, benchmark)
        gap_to_target = benchmark["target"] - value

        stage_data = {
            "stage": stage_key,
            "label": benchmark["label"],
            "current_value_pct": value,
            "target_pct": benchmark["target"],
            "good_pct": benchmark["good"],
            "gap_to_target_pp": round(gap_to_target, 1),
            "rating": rating,
        }

        # Track weakest stage
        normalized_score = safe_divide(value, benchmark["target"]) * 100
        if normalized_score < weakest_score:
            weakest_score = normalized_score
            weakest_stage = stage_key

        stage_analysis.append(stage_data)

    # Generate recommendations for weakest stages (sorted by gap)
    recommendations = []
    for stage in sorted(stage_analysis, key=lambda s: -s["gap_to_target_pp"]):
        if stage["gap_to_target_pp"] > 0:
            recs = STAGE_RECOMMENDATIONS.get(stage["stage"], [])
            recommendations.append({
                "stage": stage["stage"],
                "priority": "Critical" if stage["rating"] == "Critical" else "High" if stage["rating"] == "Needs Improvement" else "Medium",
                "gap_pp": stage["gap_to_target_pp"],
                "actions": recs[:3],  # Top 3 actions
            })

    # Overall funnel health
    avg_gap = sum(s["gap_to_target_pp"] for s in stage_analysis) / len(stage_analysis) if stage_analysis else 0
    if avg_gap <= 5:
        overall = "Healthy"
    elif avg_gap <= 15:
        overall = "Needs Optimization"
    else:
        overall = "Underperforming"

    # Impact estimation
    impact = None
    if active_users > 0 and weakest_stage:
        # If we fix the weakest stage to target, what's the downstream impact?
        awareness_pct = stages.get("awareness", 40) / 100
        referrer_pct = stages.get("active_referrers", 10) / 100
        share_rate = stages.get("share_rate", 30) / 100
        conversion_rate = stages.get("referred_conversion", 20) / 100
        avg_invitations = data.get("avg_invitations_per_referrer", 3)

        current_monthly_customers = int(
            active_users * awareness_pct * referrer_pct * avg_invitations * conversion_rate
        )

        # Simulate fixing weakest stage to target
        fixed_values = dict(stages)
        if weakest_stage in STAGE_BENCHMARKS:
            fixed_values[weakest_stage] = STAGE_BENCHMARKS[weakest_stage]["target"]

        fixed_awareness = fixed_values.get("awareness", 40) / 100
        fixed_referrer = fixed_values.get("active_referrers", 10) / 100
        fixed_conversion = fixed_values.get("referred_conversion", 20) / 100

        fixed_monthly_customers = int(
            active_users * fixed_awareness * fixed_referrer * avg_invitations * fixed_conversion
        )

        impact = {
            "weakest_stage": weakest_stage,
            "current_monthly_referred_customers": current_monthly_customers,
            "projected_monthly_after_fix": fixed_monthly_customers,
            "incremental_customers_per_month": fixed_monthly_customers - current_monthly_customers,
        }

    return {
        "summary": {
            "overall_health": overall,
            "stages_analyzed": len(stage_analysis),
            "weakest_stage": weakest_stage,
            "avg_gap_to_target_pp": round(avg_gap, 1),
        },
        "stage_analysis": stage_analysis,
        "recommendations": recommendations,
        "impact_estimate": impact,
    }


def format_text(result: dict) -> str:
    """Format analysis as human-readable text."""
    lines = []
    s = result["summary"]

    lines.append("=" * 60)
    lines.append("REFERRAL FUNNEL ANALYSIS")
    lines.append("=" * 60)
    lines.append("")
    lines.append(f"Overall Health: {s['overall_health']}")
    lines.append(f"Weakest Stage: {s['weakest_stage']}")
    lines.append(f"Avg Gap to Target: {s['avg_gap_to_target_pp']}pp")
    lines.append("")

    lines.append("-" * 60)
    lines.append("STAGE-BY-STAGE ANALYSIS")
    lines.append("-" * 60)
    for stage in result["stage_analysis"]:
        lines.append(f"\n  {stage['label']}")
        lines.append(f"    Current: {stage['current_value_pct']}%  |  Target: {stage['target_pct']}%  |  Gap: {stage['gap_to_target_pp']}pp  |  {stage['rating']}")

    if result["recommendations"]:
        lines.append("")
        lines.append("-" * 60)
        lines.append("PRIORITIZED RECOMMENDATIONS")
        lines.append("-" * 60)
        for rec in result["recommendations"]:
            lines.append(f"\n  [{rec['priority']}] {rec['stage']} (gap: {rec['gap_pp']}pp)")
            for action in rec["actions"]:
                lines.append(f"    - {action}")

    if result.get("impact_estimate"):
        imp = result["impact_estimate"]
        lines.append("")
        lines.append("-" * 40)
        lines.append("IMPACT ESTIMATE")
        lines.append("-" * 40)
        lines.append(f"  If '{imp['weakest_stage']}' reaches target:")
        lines.append(f"    Current: {imp['current_monthly_referred_customers']:,} customers/month")
        lines.append(f"    Projected: {imp['projected_monthly_after_fix']:,} customers/month")
        lines.append(f"    Incremental: +{imp['incremental_customers_per_month']:,} customers/month")

    lines.append("")
    return "\n".join(lines)


def main() -> None:
    """Main entry point."""
    parser = argparse.ArgumentParser(
        description="Analyze the 4-stage referral funnel with diagnostics."
    )
    parser.add_argument(
        "input_file",
        help="Path to JSON file with referral funnel metrics",
    )
    parser.add_argument(
        "--format",
        choices=["text", "json"],
        default="text",
        help="Output format (default: text)",
    )
    args = parser.parse_args()

    try:
        with open(args.input_file, "r") as f:
            data = json.load(f)
    except FileNotFoundError:
        print(f"Error: File not found: {args.input_file}", file=sys.stderr)
        sys.exit(1)
    except json.JSONDecodeError as e:
        print(f"Error: Invalid JSON: {e}", file=sys.stderr)
        sys.exit(1)

    result = analyze_funnel(data)

    if args.format == "json":
        print(json.dumps(result, indent=2))
    else:
        print(format_text(result))


if __name__ == "__main__":
    main()