import pandas as pd
import numpy as np

def explain_kpi_model(
    X: pd.DataFrame,
    y: pd.Series,
    coef_series: pd.Series,
    top: int = 5
):
    """
    Explica el modelo usando:
    - coeficientes desescalados
    - betas estandarizados
    - correlación con target
    - varianza de cada feature

    Devuelve un DataFrame con columnas:
    ['feature','coef','beta_std','abs_beta','rank']
    """

    if not isinstance(coef_series, pd.Series):
        raise ValueError("coef_series debe ser un pd.Series con coeficientes.")

    # Asegurar que features y coeficientes alineen
    coefs = coef_series.reindex(X.columns).fillna(0)

    # Estandarización para betas
    X_std = (X - X.mean()) / X.std(ddof=0)
    y_std = (y - y.mean()) / y.std(ddof=0)

    beta_std = (X_std.mul(coefs, axis=1)).corrwith(y_std)

    df_out = pd.DataFrame({
        "feature": X.columns,
        "coef": coefs.values,
        "beta_std": beta_std.values,
    })

    df_out["abs_beta"] = df_out["beta_std"].abs()
    df_out = df_out.sort_values("abs_beta", ascending=False).reset_index(drop=True)
    df_out["rank"] = df_out.index + 1

    return df_out.head(top)

