Provisioning & Evaluation of Provisions Agent

@tool(
    name="calculate_chain_ladder_reserve",
    description="Basic Chain Ladder on a cumulative claims triangle with optional tail; returns ultimates, IBNR, and link ratios.",
    show_result=True,
)
def calculate_chain_ladder_reserve(
    cumulative_triangle: List[List[Optional[float]]],
    tail_factor: float = 1.00
) -> Dict[str, Any]:
    """
    Run a simple Chain Ladder on a cumulative triangle(origin rows x dev columns).
    None indicates missing cells(i.e., to be projected).

    Args:
        cumulative_triangle: 2D list of cumulative claims(origin x dev). Use None for missing cells.
        tail_factor: Additional tail factor applied to remaining LDF product.

    Returns:
        Dict with selected age-to-age factors, LDFs, ultimates, IBNR by origin, and totals.
    """
    n_origin = len(cumulative_triangle)
    if n_origin == 0:
        return {"error": "Empty triangle."}
    n_dev = max(len(row) for row in cumulative_triangle)

    "color: #6b7280;"># Compute age-to-age(link) ratios per column(j -> j+1), volume-weighted
    link_factors: List[float] = []
    for j in range(n_dev - 1):
        numer = 0.0
        denom = 0.0
        for i in range(n_origin):
            row = cumulative_triangle[i]
            if j + 1 < len(row) and row[j] is not None and row[j + 1] is not None:
                numer += float(row[j + 1])
                denom += float(row[j])
        link_factors.append((numer / denom) if denom > 0 else 1.0)

    "color: #6b7280;"># Build cumulative LDFs from each col to ultimate
    ldfs: List[float] = [1.0] * n_dev
    prod = tail_factor
    for j in range(n_dev - 2, -1, -1):
        prod *= link_factors[j]
        ldfs[j] = prod

    ultimate_by_origin: List[float] = []
    ibnr_by_origin: List[float] = []
    latest_cumulative: List[float] = []
    latest_col_index: List[int] = []

    for i in range(n_origin):
        row = cumulative_triangle[i]
        "color: #6b7280;"># find last observed dev col k
        k = -1
        last_val = None
        for j in range(len(row) - 1, -1, -1):
            if row[j] is not None:
                k = j
                last_val = float(row[j])
                break
        if k == -1 or last_val is None:
            ultimate_by_origin.append(0.0)
            ibnr_by_origin.append(0.0)
            latest_cumulative.append(0.0)
            latest_col_index.append(-1)
            continue

        ld = ldfs[k] if k < len(ldfs) else tail_factor
        ultimate = last_val * ld
        ibnr = max(0.0, ultimate - last_val)

        ultimate_by_origin.append(round(ultimate, 2))
        ibnr_by_origin.append(round(ibnr, 2))
        latest_cumulative.append(round(last_val, 2))
        latest_col_index.append(k)

    result = {
        "age_to_age_factors": [round(f, 6) for f in link_factors],
        "ldfs_to_ultimate": [round(x, 6) for x in ldfs],
        "tail_factor": tail_factor,
        "latest_cumulative_by_origin": latest_cumulative,
        "latest_column_index_by_origin": latest_col_index,
        "ultimate_by_origin": ultimate_by_origin,
        "ibnr_by_origin": ibnr_by_origin,
        "totals": {
            "ultimate_total": round(sum(ultimate_by_origin), 2),
            "latest_cumulative_total": round(sum(latest_cumulative), 2),
            "ibnr_total": round(sum(ibnr_by_origin), 2),
        },
    }
    return result

@tool(
    name="discount_cashflows_present_value",
    description="Discount annual cashflows with a simple zero-coupon curve: PV = sum(amount/(1+r_year)^year).",
    show_result=True,
)
def discount_cashflows_present_value(
    cashflows_by_year: Dict[int, float],
    zero_rates_by_year: Dict[int, float]
) -> Dict[str, Any]:
    """
    Present value cashflows using annual zero-coupon rates.

    Args:
        cashflows_by_year: {year_offset: cash_amount}, e.g., {1: -100.0, 2: -80.0, 3: 50.0}
        zero_rates_by_year: {year_offset: annual_rate}, e.g., {1: 0.02, 2: 0.025, 3: 0.03}

    Returns:
        Dict with PV by year and total PV.
    """
    pv_by_year: Dict[int, float] = {}
    total_pv = 0.0
    for t, amt in cashflows_by_year.items():
        r = zero_rates_by_year.get(t, 0.0)
        pv = amt / ((1.0 + r) ** t)
        pv_by_year[t] = round(pv, 2)
        total_pv += pv
    return {
        "present_value_by_year": pv_by_year,
        "present_value_total": round(total_pv, 2),
    }

@tool(
    name="backtest_reserve_adequacy",
    description="Simple actual-vs-expected back-test for prior IBNR.",
    show_result=True,
)
def backtest_reserve_adequacy(
    prior_ibnr_estimate: float,
    actual_paid_on_prior_year: float
) -> Dict[str, Any]:
    """
    Compare last year's IBNR estimate against actual cash emergence.

    Args:
        prior_ibnr_estimate: Last valuation's IBNR for the cohort.
        actual_paid_on_prior_year: Cash paid over the subsequent year for that cohort.

    Returns:
        Dict with adequacy, redundancy/deficiency, and percentages.
    """
    diff = prior_ibnr_estimate - actual_paid_on_prior_year
    status = "adequate" if abs(diff) <= 0.01 * max(1.0, prior_ibnr_estimate) else("redundant" if diff > 0 else "deficient")
    pct = (diff / prior_ibnr_estimate) if prior_ibnr_estimate != 0 else 0.0
    return {
        "prior_ibnr_estimate": round(prior_ibnr_estimate, 2),
        "actual_paid_on_prior_year": round(actual_paid_on_prior_year, 2),
        "difference": round(diff, 2),
        "adequacy_status": status,
        "difference_pct_of_prior": round(pct, 4)
    }