Product Design for Aging Insurance

@tool(name="ProductBlueprintTool", description="Generate a structured insurance product blueprint tailored to aging populations(customer_type, product_class, risk_profile, optional target_age, income_need, inflation_protection, longevity_risk_concern, health_status, budget_level, region, objectives).", show_result=True)
def ProductBlueprintTool(
    customer_type: str,
    product_class: str,
    risk_profile: str = "moderate",
    target_age: Optional[int] = None,
    income_need: str = "medium",
    inflation_protection: bool = True,
    longevity_risk_concern: bool = True,
    health_status: str = "average",
    budget_level: str = "medium",
    region: str = "generic",
    objectives: Optional[List[str]] = None,
) -> str:
    """
    Generate a structured insurance product blueprint tailored to aging populations.

    Args:
        customer_type: One of ["pre-retiree", "retiree", "elderly_with_health_issues", "group/employer"].
        product_class: One of ["pension", "annuity_immediate", "annuity_deferred", "annuity_variable", "ltc", "hybrid_life_ltc", "group_pension", "innovative_flex_drawdown"].
        risk_profile: "conservative" | "moderate" | "aggressive".
        target_age: Representative customer age; used for ranges & pricing hints.
        income_need: "low" | "medium" | "high" (decumulation need).
        inflation_protection: Whether to include CPI/capped escalation features.
        longevity_risk_concern: Whether to emphasize lifetime guarantees.
        health_status: "good" | "average" | "impaired" (affects LTC/underwriting flags).
        budget_level: "low" | "medium" | "high" (affects premium type & guarantees).
        region: Jurisdiction tag(e.g., "EU", "US", "JP", "MENA", "generic").
        objectives: e.g., ["capital_preservation","income_stability","legacy","tax_efficiency"].

    Returns:
        str: JSON-encoded product blueprint with structure, guarantees, riders, ops & compliance hints.
    """
    def age_band(age: Optional[int], default: str) -> str:
        if age is None:
            return default
        if age < 45: return "35-45"
        if age < 55: return "45-55"
        if age < 65: return "55-65"
        if age < 75: return "65-75"
        return "75-85"

    def default_premium_type(prod: str, budget: str) -> str:
        if prod in ["annuity_immediate"]:
            return "Lump Sum"
        if prod in ["annuity_deferred", "pension", "group_pension"]:
            return "Fixed" if budget != "low" else "Flexible"
        if prod in ["ltc", "hybrid_life_ltc", "innovative_flex_drawdown"]:
            return "Annual" if budget != "low" else "Usage-Based"
        if prod == "annuity_variable":
            return "Variable"
        return "Flexible"

    def base_guarantees(prod: str, longevity: bool, inflation: bool) -> List[str]:
        g = []
        if prod.startswith("annuity") or prod in ["pension", "group_pension", "innovative_flex_drawdown"]:
            if longevity:
                g.append("Guaranteed lifetime income")
        if inflation:
            g.append("Inflation-linked escalation(CPI or capped)")
        if prod in ["annuity_deferred", "pension", "group_pension"]:
            g.append("Guaranteed Minimum Income Benefit(GMIB)")
        if prod == "annuity_variable":
            g.append("Capital protection floor on annuity units")
        if prod == "ltc":
            g.append("Benefit triggers: ADL/cognitive impairment")
        if prod == "hybrid_life_ltc":
            g.append("Accelerated death benefit for LTC")
        return g

    def suggest_riders(prod: str, risk: str, health: str, income_need: str) -> List[str]:
        r = []
        if prod.startswith("annuity"):
            if income_need == "high":
                r.append("Period certain(10-20y)")
            r.append("Joint & survivor(50%-100%)")
            r.append("Impaired life annuity underwriting(if eligible)")
        if prod in ["pension", "group_pension", "innovative_flex_drawdown"]:
            r.append("Longevity protection rider(late-life boost)")
            if risk != "aggressive":
                r.append("Capital preservation lock-in")
        if prod in ["ltc", "hybrid_life_ltc"]:
            r.extend(["Waiver of premium", "Return of premium on death(optional)"])
            if health != "good":
                r.append("Benefit step-up with waiting period")
        return r

    def model_allocation(prod: str, risk: str) -> Dict[str, float]:
        if prod in ["annuity_immediate", "ltc", "hybrid_life_ltc"]:
            return {"Fixed Income": 75.0, "Alternatives": 10.0, "Equities": 15.0}
        if prod in ["annuity_deferred", "pension", "group_pension"]:
            if risk == "conservative":
                return {"Fixed Income": 65.0, "Equities": 25.0, "Alternatives": 10.0}
            if risk == "moderate":
                return {"Fixed Income": 50.0, "Equities": 40.0, "Alternatives": 10.0}
            return {"Fixed Income": 35.0, "Equities": 55.0, "Alternatives": 10.0}
        if prod == "annuity_variable":
            return {"Fixed Income": 30.0, "Equities": 60.0, "Alternatives": 10.0}
        if prod == "innovative_flex_drawdown":
            return {"Fixed Income": 45.0, "Equities": 45.0, "Alternatives": 10.0}
        return {"Fixed Income": 50.0, "Equities": 40.0, "Alternatives": 10.0}

    def indicative_pricing_hint(prod: str, age: Optional[int], risk: str, inflation: bool) -> Dict[str, Any]:
        base = 1.0
        if prod in ["ltc", "hybrid_life_ltc"]:
            base += 0.35
        if prod.startswith("annuity"):
            base += 0.15
        if prod == "annuity_variable" and risk == "aggressive":
            base += 0.10
        if inflation:
            base += 0.10
        if age and age >= 70 and prod.startswith("annuity"):
            base += 0.05
        return {
            "premium_factor": round(base, 2),
            "notes": "Heuristic guidance only; use actuarial models for pricing & reserving.",
        }

    def ifrs17_hint(prod: str) -> Dict[str, str]:
        if prod in ["ltc", "hybrid_life_ltc"]:
            return {"measurement_model": "GMM", "notes": "Long-duration with significant insurance risk; check investment component split."}
        if prod.startswith("annuity") or prod in ["pension", "group_pension", "innovative_flex_drawdown"]:
            return {"measurement_model": "GMM", "notes": "Guarantee-heavy; assess discount rates, risk adjustment, and CSM amortization."}
        return {"measurement_model": "Assess", "notes": "Confirm contract boundary & renewability(PAA may apply if short-dur)."}

    def solvency_focus(prod: str) -> List[str]:
        f = ["Longevity risk", "Interest rate risk"]
        if prod in ["annuity_variable", "pension", "group_pension", "innovative_flex_drawdown"]:
            f.append("Market risk(equity spread)")
        if prod in ["ltc", "hybrid_life_ltc"]:
            f.append("Morbidity risk")
            f.append("Expense inflation risk")
        return f

    def distribution_suggestion(prod: str) -> List[str]:
        if prod in ["pension", "group_pension"]:
            return ["Bancassurance", "Corporate partnerships", "Digital workplace portals"]
        if prod.startswith("annuity"):
            return ["Financial advisors/brokers", "Direct-to-consumer with guided advice"]
        if prod in ["ltc", "hybrid_life_ltc"]:
            return ["Advisors/brokers", "Healthcare partnerships", "Insurer direct"]
        if prod == "innovative_flex_drawdown":
            return ["Robo-advice platforms", "Bancassurance", "Advisors"]
        return ["Advisors", "Bank channels"]

    def underwriting_hint(prod: str, health: str) -> str:
        if prod in ["ltc", "hybrid_life_ltc"]:
            return "Medical underwriting with focus on chronic conditions, ADLs, cognitive screening."
        if prod.startswith("annuity"):
            return "Light financial & mortality underwriting; impaired-life annuity route if applicable."
        if prod in ["pension", "group_pension", "innovative_flex_drawdown"]:
            return "Financial suitability & KYC/AML; typically non-medical."
        return "Standard KYC/AML and affordability checks."

    "color: #6b7280;"># Validation & normalization
    customer_type = customer_type.lower().replace(" ", "_")
    product_class = product_class.lower().replace(" ", "_")
    risk_profile = risk_profile.lower()
    valid_customers = {"pre-retiree", "retiree", "elderly_with_health_issues", "group/employer", "group_employer", "group"}
    valid_products = {
        "pension", "annuity_immediate", "annuity_deferred", "annuity_variable",
        "ltc", "hybrid_life_ltc", "group_pension", "innovative_flex_drawdown",
    }
    valid_risks = {"conservative", "moderate", "aggressive"}
    if customer_type in {"group/employer", "group_employer", "group"}:
        customer_type = "group_employer"
    errors = []
    if customer_type not in valid_customers:
        errors.append(f"Invalid customer_type: {customer_type}")
    if product_class not in valid_products:
        errors.append(f"Invalid product_class: {product_class}")
    if risk_profile not in valid_risks:
        errors.append(f"Invalid risk_profile: {risk_profile}")
    if errors:
        return json.dumps({"error": True, "messages": errors}, indent=2)

    "color: #6b7280;"># Build blueprint core
    age_range = {
        "pre-retiree": age_band(target_age, "45-60"),
        "retiree": age_band(target_age, "60-80"),
        "elderly_with_health_issues": age_band(target_age, "70-85"),
        "group_employer": "Workforce coverage(18-70)",
    }[customer_type]
    premium_type = default_premium_type(product_class, budget_level)
    guarantees = base_guarantees(product_class, longevity_risk_concern, inflation_protection)
    riders = suggest_riders(product_class, risk_profile, health_status, income_need)
    allocation = model_allocation(product_class, risk_profile)
    pricing_hint = indicative_pricing_hint(product_class, target_age, risk_profile, inflation_protection)
    ifrs17 = ifrs17_hint(product_class)
    solvency = solvency_focus(product_class)
    distribution = distribution_suggestion(product_class)
    underwriting = underwriting_hint(product_class, health_status)
    name_parts = {
        "pension": "Lifetime Pension Plan",
        "annuity_immediate": "Immediate Income Annuity",
        "annuity_deferred": "Deferred Income Annuity",
        "annuity_variable": "Participating/Variable Annuity",
        "ltc": "Comprehensive LTC Insurance",
        "hybrid_life_ltc": "Hybrid Life + LTC",
        "group_pension": "Employer DC/Hybrid Pension",
        "innovative_flex_drawdown": "Flexible Retirement Drawdown",
    }
    product_name = name_parts[product_class]
    coverage_map = {
        "pension": "Guaranteed lifetime income post-retirement",
        "annuity_immediate": "Immediate lifetime income starting at purchase",
        "annuity_deferred": "Lifetime income starting at selected deferral date",
        "annuity_variable": "Income linked to investment performance with floors",
        "ltc": "Daily/monthly benefit for home care, assisted living, nursing",
        "hybrid_life_ltc": "Life insurance with accelerated LTC benefits",
        "group_pension": "Employer-sponsored retirement accumulation & annuitization options",
        "innovative_flex_drawdown": "Systematic withdrawals with longevity rider options",
    }
    derisking = {
        "glidepath": "Age-based equity de-risking(e.g., equity -10% per decade post 55).",
        "hedging": "ALM with duration matching; optional longevity reinsurance for tails.",
        "inflation": "CPI-linked or capped escalation; mix of ILBs/TIPS where available.",
    }
    fees = {
        "management": "0.40%-1.20% p.a. depending on complexity",
        "rider": "0.10%-0.60% p.a. for add-on guarantees/riders",
        "surrender": "Declining surrender charge 5%→0% over 5 years(if applicable)",
    }
    surrender_rules = "Early surrender may reduce benefits; MVA may apply for interest rate shifts."
    kpis = [
        "NBM(New Business Margin)",
        "IRR(Internal Rate of Return)",
        "EV/VNB(Embedded Value / Value of New Business)",
        "Persistency(13m/25m/37m)",
        "Claims ratio(for LTC/hybrid)",
        "Capital strain(Solvency coverage ratio)",
    ]
    blueprint: Dict[str, Any] = {
        "meta": {
            "region": region,
            "customer_type": customer_type,
            "product_class": product_class,
            "risk_profile": risk_profile,
            "target_age_range": age_range,
            "objectives": objectives or ["income_stability", "capital_preservation"],
        },
        "product": {
            "product_id": None,
            "product_name": product_name,
            "category": product_class,
            "premium_type": premium_type,
            "coverage": coverage_map[product_class],
            "guarantees": guarantees,
            "optional_riders": riders,
            "investment_allocation": allocation,
            "de_risking": derisking,
            "fees": fees,
            "surrender_rules": surrender_rules,
        },
        "ops": {
            "underwriting": underwriting,
            "distribution": distribution,
            "policy_admin": [
                "Support long-duration contracts",
                "Benefit escalation logic(inflation/cap)",
                "Annuitization options & switch windows",
                "Claims workflows(for LTC/hybrid)",
            ],
        },
        "compliance": {
            "ifrs17": ifrs17,
            "solvency_focus": solvency,
            "consumer_protection": [
                "Clear disclosure of guarantees, escalation caps",
                "Transparent conversion/annuitization factors",
                "LTC exclusions, waiting periods, inflation adjustments",
            ],
        },
        "analytics": {
            "pricing_hint": pricing_hint,
            "sensitivity_levers": [
                "Interest rates / discount curve",
                "Longevity improvement",
                "Expense & claims inflation",
                "Equity/credit shocks(if participating/variable)",
            ],
            "target_kpis": kpis,
        },
        "versioning": {
            "status": "draft",
            "notes": "Auto-generated blueprint—use actuarial & compliance tools for validation.",
        },
    }
    return json.dumps(blueprint, indent=2)