app.py

# Streamlit Dashboard for Soccer ML Analytics
import streamlit as st
import pandas as pd
import numpy as np
import plotly.express as px
import plotly.graph_objects as go
import joblib
from plotly.colors import qualitative
from sklearn.metrics import (
    mean_squared_error,
    r2_score,
    accuracy_score,
    precision_score,
    recall_score,
)

from src.config import (
    PLAYER_SNAPSHOT_CSV,
    AGING_CURVES_CSV,
    TRANSFER_MODEL_CSV,
    TRANSFER_FEE_MODEL_PATH,
    VALUE_GROWTH_MODEL_PATH,
    TRANSFER_OUTCOME_MODEL_PATH,
    BREAKOUT_MODEL_PATH,
    BREAKOUT_MODEL_CSV,
    REPORTS_DIR,
)

HIGH_CONTRAST_SEQUENCE = [
    "#0B60B0",  # royal blue
    "#E63946",  # crimson
    "#FFB703",  # amber
    "#2A9D8F",  # teal
    "#8D5B4C",  # brown
    "#6A4C93",  # violet
    "#1D3557",  # deep navy
    "#F3722C",  # orange-red
    "#43AA8B",  # jade
    "#4D908E",  # muted teal
    "#F94144",  # bright red
    "#277DA1",  # blue teal
]
LEAGUE_COLOR_SEQUENCE = qualitative.Dark24
PRIMARY_BLUE = "#0057B7"
ACCENT_ORANGE = "#F06449"
BAND_PRIMARY = "rgba(0, 87, 183, 0.45)"
BAND_SECONDARY = "rgba(0, 87, 183, 0.15)"
HOVERLABEL_STYLE = dict(bgcolor="#F5F9FF", font_size=12, font_color="#111111", bordercolor="#90CAF9")
POSITION_COLOR_ORDER = ["GK", "DEF", "DF", "CB", "FB", "WB", "DM", "CM", "MID", "AM", "WF", "FW", "ST"]
POSITION_COLOR_BASE = {pos: HIGH_CONTRAST_SEQUENCE[i % len(HIGH_CONTRAST_SEQUENCE)] for i, pos in enumerate(POSITION_COLOR_ORDER)}
GOAL_BAR_COLOR = PRIMARY_BLUE
ASSIST_BAR_COLOR = ACCENT_ORANGE


def ensure_color_map(values, base_map=None, palette=None):
    """Return a consistent categorical color map using a safe palette."""
    palette = palette or HIGH_CONTRAST_SEQUENCE
    mapping = dict(base_map) if base_map else {}
    unique_values = []
    for val in pd.Series(values).dropna():
        if isinstance(val, str) and not val.strip():
            continue
        if val not in unique_values:
            unique_values.append(val)
    for val in unique_values:
        if val not in mapping:
            mapping[val] = palette[len(mapping) % len(palette)]
    return mapping

def format_currency(value: float) -> str:
    if value is None or pd.isna(value):
        return "€0"
    return f"€{value:,.0f}"


def format_percent(value: float, decimals: int = 1) -> str:
    if value is None or pd.isna(value):
        return "0%"
    return f"{value:.{decimals}%}"


def describe_value_gap(row) -> str:
    gap = row.get("undervaluation", 0)
    name = row.get("name", "Player")
    league = row.get("current_league_name", "unknown league")
    return f"{name} ({league}) is priced {format_currency(gap)} below the model estimate."

VALUE_MODEL_NUMERIC_FEATURES = [
    # Basic player info
    "age",
    "age_sq",
    "height_in_cm",
    # Career stats
    "career_minutes",
    "career_goals",
    "career_assists",
    "career_goals_per_90",
    "career_assists_per_90",
    # Recent form
    "last_season_minutes",
    "last_season_goals",
    "last_season_assists",
    "last_season_goals_per_90",
    "last_season_assists_per_90",
    # Club & league context
    "current_club_total_market_value",
    "current_league_strength",
    "contract_months_remaining",
    # Transfer history (NEW)
    "transfer_count",
    "avg_transfer_fee",
    "years_since_last_transfer",
    "transfer_frequency",
    # Discipline (NEW)
    "yellow_cards_per_90",
    "red_cards_per_90",
    "discipline_score",
    # International experience (NEW)
    "has_international_caps",
    "international_minutes",
    "international_goals",
    "international_appearances",
    # Value trajectory (NEW)
    "value_to_peak_ratio",
    "is_at_peak_value",
    "value_momentum_6mo",
    # Agent effect (NEW)
    "has_top_agent",
]
VALUE_MODEL_CATEGORICAL_FEATURES = ["position", "foot", "nationality", "current_league_name"]

BREAKOUT_NUMERIC_FEATURES = [
    # Basic info
    "age",
    "current_market_value",
    # Career stats
    "career_minutes",
    "career_goals",
    "career_assists",
    "career_goals_per_90",
    "career_assists_per_90",
    "career_goals_per90_pct_rank",
    "career_assists_per90_pct_rank",
    # Recent form
    "last_season_minutes",
    "last_season_goals",
    "last_season_assists",
    "last_season_goals_per_90",
    "last_season_assists_per_90",
    "last_season_minutes_pct_rank",
    # Value indicators
    "value_1yr_growth_pct",
    "value_vs_age_pos_ratio",
    # League context
    "current_league_strength",
    "current_league_is_big5",
    # International experience (NEW)
    "has_international_caps",
    "international_appearances",
    # Value momentum (NEW)
    "value_momentum_6mo",
    "is_at_peak_value",
    # Discipline (NEW)
    "discipline_score",
]
BREAKOUT_CATEGORICAL_FEATURES = [
    "position",
    "foot",
    "value_trend",
    "current_league_name",
    "nationality",
]

TRANSFER_NUMERIC_FEATURES = [
    # Basic transfer context
    "age_at_transfer",
    "market_value_at_transfer",
    "fee_to_value_ratio",
    # Recent performance
    "recent_minutes",
    "recent_goals",
    "recent_assists",
    "recent_goals_per_90",
    "recent_assists_per_90",
    # League & club context
    "from_league_strength",
    "to_league_strength",
    "league_step",
    "is_step_up",
    "from_club_market_value",
    "to_club_market_value",
    "contract_months_remaining",
    "days_since_last_transfer",
    # International experience (NEW)
    "has_international_caps",
    "international_minutes",
    "international_goals",
    "international_appearances",
    # Transfer history (NEW)
    "transfer_count",
    "avg_transfer_fee",
    "transfer_frequency",
    # Value trajectory (NEW)
    "value_to_peak_ratio",
    "is_at_peak_value",
    "value_momentum_6mo",
    # Agent effect (NEW)
    "has_top_agent",
    # Discipline (NEW)
    "discipline_score",
]
TRANSFER_CATEGORICAL_FEATURES = [
    "position",
    "foot",
    "nationality",
    "from_league_name",
    "to_league_name",
]
TRANSFER_OUTCOME_NUMERIC_FEATURES = [
    # Basic transfer context
    "age_at_transfer",
    "market_value_at_transfer",
    "fee_to_value_ratio",
    "transfer_year",
    # Recent performance
    "recent_minutes",
    "recent_goals",
    "recent_assists",
    "recent_goals_per_90",
    "recent_assists_per_90",
    # League & club context
    "from_league_strength",
    "to_league_strength",
    "league_step",
    "is_step_up",
    "from_club_market_value",
    "to_club_market_value",
    "contract_months_remaining",
    "days_since_last_transfer",
    # Discipline (NEW - critical for success!)
    "yellow_cards_per_90",
    "red_cards_per_90",
    "discipline_score",
    # Transfer history (NEW)
    "transfer_count",
    "transfer_frequency",
    # International experience (NEW)
    "has_international_caps",
    "international_appearances",
    # Value trajectory (NEW)
    "value_to_peak_ratio",
    "value_momentum_6mo",
]

SHAP_FILES = {
    "M1 Transfer Fee": REPORTS_DIR / "shap_m1_transfer_fee.csv",
    "M2 Value Growth": REPORTS_DIR / "shap_m2_value_growth.csv",
    "M3 Transfer Outcome": REPORTS_DIR / "shap_m3_transfer_outcome.csv",
}



@st.cache_data
def load_player_snapshot():
    return pd.read_csv(PLAYER_SNAPSHOT_CSV)


@st.cache_data
def load_aging_curves():
    return pd.read_csv(AGING_CURVES_CSV)


@st.cache_data
def load_transfer_dataset():
    return pd.read_csv(TRANSFER_MODEL_CSV)


@st.cache_data
def load_shap_summary(model_label: str):
    path = SHAP_FILES.get(model_label)
    if path is None or not path.exists():
        return None
    return pd.read_csv(path)


def prettify_feature_name(raw: str) -> str:
    if not isinstance(raw, str):
        return str(raw)
    base = raw.split("__", 1)[-1]
    base = base.replace("pct", "%").replace("per90", " per 90")
    base = base.replace("_", " ")
    return base.strip().title()


def render_shap_importance(model_label: str, title: str, description: str):
    st.subheader(title)
    df = load_shap_summary(model_label)
    if df is None or df.empty:
        st.info("Train the pipeline (run `run_all_valuation_models`) to generate SHAP summaries.")
        return
    top = df.head(12).copy()
    top["feature_label"] = top["feature"].apply(prettify_feature_name)
    top = top.sort_values("mean_abs_shap", ascending=False)
    fig = px.bar(
        top,
        x="mean_abs_shap",
        y="feature_label",
        orientation="h",
        labels={"mean_abs_shap": "Mean |SHAP| impact", "feature_label": "Feature"},
        color="mean_abs_shap",
        color_continuous_scale="Blues",
        template="plotly_white",
    )
    fig.update_layout(
        height=420,
        hoverlabel=HOVERLABEL_STYLE,
        margin=dict(l=0, r=0, t=40, b=0),
        yaxis=dict(autorange="reversed"),
    )
    st.plotly_chart(fig, use_container_width=True)
    st.caption(description)


def load_model_metrics() -> dict:
    metrics_path = REPORTS_DIR / "model_metrics.json"
    if metrics_path.exists():
        import json
        with open(metrics_path, "r", encoding="utf-8") as f:
            return json.load(f)
    return {}
def compute_value_model_metrics(df_snapshot: pd.DataFrame, model) -> dict | None:
    df_eval = df_snapshot[df_snapshot["latest_market_value"] > 1_000_000].copy()
    if df_eval.empty:
        return None
    df_eval = df_eval.sort_values("valuation_date").tail(5000)  # focus on most recent valuations
    X = prepare_feature_frame(df_eval, VALUE_MODEL_NUMERIC_FEATURES, VALUE_MODEL_CATEGORICAL_FEATURES)
    preds = np.expm1(model.predict(X))
    actual = df_eval["latest_market_value"].values
    return {
        "rmse": np.sqrt(mean_squared_error(actual, preds)),
        "r2": r2_score(actual, preds),
    }


def compute_transfer_fee_metrics(df_transfers: pd.DataFrame, model) -> dict | None:
    df_eval = df_transfers[df_transfers["transfer_fee"] > 0].copy()
    if df_eval.empty:
        return None
    X = prepare_feature_frame(df_eval, TRANSFER_NUMERIC_FEATURES, TRANSFER_CATEGORICAL_FEATURES)
    preds = np.expm1(model.predict(X))
    actual = df_eval["transfer_fee"].values
    return {
        "rmse": np.sqrt(mean_squared_error(actual, preds)),
        "r2": r2_score(actual, preds),
    }


def compute_transfer_outcome_metrics(df_transfers: pd.DataFrame, model) -> dict | None:
    df_eval = df_transfers[df_transfers["transfer_outcome"].isin([0, 1])].copy()
    if df_eval.empty:
        return None
    X = prepare_feature_frame(df_eval, TRANSFER_OUTCOME_NUMERIC_FEATURES, TRANSFER_CATEGORICAL_FEATURES)
    preds = model.predict(X)
    actual = df_eval["transfer_outcome"].values
    return {
        "accuracy": accuracy_score(actual, preds),
        "precision": precision_score(actual, preds, zero_division=0),
        "recall": recall_score(actual, preds, zero_division=0),
    }


def compute_breakout_metrics(model) -> dict | None:
    df = pd.read_csv(BREAKOUT_MODEL_CSV)
    if not {"breakout"}.issubset(df.columns):
        return None
    X = prepare_feature_frame(df, BREAKOUT_NUMERIC_FEATURES, BREAKOUT_CATEGORICAL_FEATURES)
    preds = model.predict(X)
    actual = df["breakout"].values
    return {
        "accuracy": accuracy_score(actual, preds),
        "precision": precision_score(actual, preds, zero_division=0),
        "recall": recall_score(actual, preds, zero_division=0),
    }


def render_metric_block(metrics: dict | None, kind: str):
    if not metrics:
        return
    if kind == "regression":
        c1, c2 = st.columns(2)
        c1.metric("RMSE", format_currency(metrics["rmse"]))
        c2.metric("R²", f"{metrics['r2']:.2f}")
    elif kind == "classification":
        c1, c2, c3 = st.columns(3)
        c1.metric("Accuracy", f"{metrics['accuracy']:.1%}")
        c2.metric("Precision", f"{metrics['precision']:.1%}")
        c3.metric("Recall", f"{metrics['recall']:.1%}")


@st.cache_resource
def load_models():
    transfer_fee_model = joblib.load(TRANSFER_FEE_MODEL_PATH)
    value_model = joblib.load(VALUE_GROWTH_MODEL_PATH)
    outcome_model = joblib.load(TRANSFER_OUTCOME_MODEL_PATH)
    breakout_model = joblib.load(BREAKOUT_MODEL_PATH)
    return transfer_fee_model, value_model, outcome_model, breakout_model


def prepare_feature_frame(df: pd.DataFrame, numeric_cols, categorical_cols):
    """Ensure a feature matrix aligned with model training columns."""
    data = df.copy()
    for col in numeric_cols:
        if col not in data.columns:
            data[col] = 0
        data[col] = data[col].fillna(0)
    for col in categorical_cols:
        if col not in data.columns:
            data[col] = "UNKNOWN"
        data[col] = data[col].fillna("UNKNOWN").astype(str)
    return data[list(numeric_cols) + list(categorical_cols)]


def score_breakout_candidates_local(df_snapshot: pd.DataFrame, breakout_model) -> pd.DataFrame:
    """Score current youth players without reloading models."""
    df_youth = df_snapshot[df_snapshot["age"] <= 22].copy()
    df_youth["current_market_value"] = df_youth["latest_market_value"].fillna(0)
    features = prepare_feature_frame(df_youth, BREAKOUT_NUMERIC_FEATURES, BREAKOUT_CATEGORICAL_FEATURES)
    df_youth["breakout_probability"] = breakout_model.predict_proba(features)[:, 1]
    return df_youth


def render_value_scenario(df_snapshot: pd.DataFrame, value_model, value_metrics) -> None:
    """Interactive what-if tool for player market value."""
    st.subheader("Value Scenario Simulator")
    with st.expander("Simulate a player's valuation"):
        players = sorted(df_snapshot["name"].dropna().unique().tolist())
        if not players:
            st.info("Player snapshot not available for simulation.")
            return
        base_player = st.selectbox("Template Player", players)
        base_row = df_snapshot[df_snapshot["name"] == base_player].iloc[0]

        col1, col2, col3 = st.columns(3)
        age = col1.slider("Age", 16, 40, int(base_row["age"]))
        minutes = col1.number_input("Career Minutes", min_value=0, value=int(base_row.get("career_minutes", 0)), step=500)
        goals = col2.number_input("Career Goals", min_value=0, value=int(base_row.get("career_goals", 0)), step=5)
        assists = col2.number_input("Career Assists", min_value=0, value=int(base_row.get("career_assists", 0)), step=5)
        contract = col3.slider(
            "Contract Months Remaining",
            min_value=0,
            max_value=72,
            value=int(base_row.get("contract_months_remaining", 0)),
            step=3,
        )
        league_series = df_snapshot["current_league_name"].dropna().astype(str)
        league_options = sorted([val for val in league_series.unique().tolist() if val.strip()])
        if not league_options:
            league_options = ["UNKNOWN"]
        default_league = base_row.get("current_league_name")
        if pd.isna(default_league) or not str(default_league).strip():
            default_league = "UNKNOWN"
        if default_league not in league_options:
            league_options = ["UNKNOWN"] + [opt for opt in league_options if opt != "UNKNOWN"]
            league_index = 0
        else:
            league_index = league_options.index(default_league)
        league_choice = col3.selectbox("League", league_options, index=league_index)

        position_series = df_snapshot["position"].dropna().astype(str)
        position_options = sorted([val for val in position_series.unique().tolist() if val.strip()])
        if not position_options:
            position_options = ["UNKNOWN"]
        default_pos = base_row.get("position")
        if pd.isna(default_pos) or default_pos not in position_options:
            default_pos = position_options[0]
        position_choice = col1.selectbox("Position Group", position_options, index=position_options.index(default_pos))

        feature_payload = {col: float(base_row.get(col, 0)) for col in VALUE_MODEL_NUMERIC_FEATURES}
        feature_payload.update(
            {
                "age": age,
                "age_sq": age ** 2,
                "career_minutes": minutes,
                "career_goals": goals,
                "career_assists": assists,
                "contract_months_remaining": contract,
            }
        )
        cat_payload = {}
        for col in VALUE_MODEL_CATEGORICAL_FEATURES:
            raw_value = base_row.get(col, "UNKNOWN")
            if pd.isna(raw_value) or not str(raw_value).strip():
                raw_value = "UNKNOWN"
            cat_payload[col] = str(raw_value)
        cat_payload["current_league_name"] = str(league_choice)
        cat_payload["position"] = str(position_choice)

        features_df = prepare_feature_frame(
            pd.DataFrame([{**feature_payload, **cat_payload}]),
            VALUE_MODEL_NUMERIC_FEATURES,
            VALUE_MODEL_CATEGORICAL_FEATURES,
        )
        predicted_value = float(np.expm1(value_model.predict(features_df))[0])
        delta = predicted_value - base_row.get("latest_market_value", 0)
        rmse_val = value_metrics.get("rmse") if value_metrics else None
        if rmse_val:
            lower = max(predicted_value - rmse_val, 0)
            upper = predicted_value + rmse_val
        else:
            lower = upper = None

        st.metric(
            "Predicted Market Value",
            f"€{predicted_value:,.0f}",
            delta=f"{delta:,.0f}",
            delta_color="normal",
        )
        if rmse_val:
            st.caption(
                f"Confidence band (±RMSE): €{lower:,.0f} to €{upper:,.0f}. Adjust sliders to understand how performance, age, and context impact model valuation."
            )
        else:
            st.caption("Adjust sliders to understand how performance, age, and context impact model valuation.")
        st.info(
            "• Start with a known player to keep inputs realistic.\n"
            "• Raise the minutes/goals sliders to see how performance lifts value.\n"
            "• Try moving the player to a stronger league to gauge market impact."
        )


def render_transfer_scenario(df_transfers: pd.DataFrame, transfer_fee_model, outcome_model, fee_metrics) -> None:
    """Interactive scenario tool for transfer fees and success probability."""
    st.subheader("Transfer Scenario Studio")
    with st.expander("Estimate transfer fee & success likelihood"):
        if df_transfers.empty:
            st.info("Transfer dataset unavailable.")
            return
        template_options = df_transfers["scenario_label"].tolist()
        template_choice = st.selectbox("Template Transfer", template_options)
        base_row = df_transfers[df_transfers["scenario_label"] == template_choice].iloc[0]

        col1, col2, col3 = st.columns(3)
        market_value = col1.number_input(
            "Market Value at Transfer (€)",
            min_value=0,
            value=int(base_row.get("market_value_at_transfer", 0)),
            step=500000,
        )
        recent_minutes = col1.number_input(
            "Minutes Last Season",
            min_value=0,
            value=int(base_row.get("recent_minutes", 0)),
            step=250,
        )
        recent_goals = col2.number_input(
            "Goals Last Season",
            min_value=0,
            value=int(base_row.get("recent_goals", 0)),
            step=2,
        )
        recent_assists = col2.number_input(
            "Assists Last Season",
            min_value=0,
            value=int(base_row.get("recent_assists", 0)),
            step=2,
        )
        is_step_up = col3.selectbox("League Move", ["Step Up", "Lateral", "Step Down"])
        contract = col3.slider(
            "Contract Months Remaining",
            min_value=0,
            max_value=72,
            value=int(base_row.get("contract_months_remaining", 0)),
            step=3,
        )
        transfer_year = col3.slider(
            "Transfer Year",
            min_value=int(df_transfers["transfer_year"].min()),
            max_value=int(df_transfers["transfer_year"].max()),
            value=int(base_row.get("transfer_year", 2023)),
        )

        input_row = base_row.copy()
        input_row["market_value_at_transfer"] = market_value
        input_row["recent_minutes"] = recent_minutes
        input_row["recent_goals"] = recent_goals
        input_row["recent_assists"] = recent_assists
        input_row["contract_months_remaining"] = contract
        input_row["transfer_year"] = transfer_year
        input_row["league_step"] = (
            1 if is_step_up == "Step Up" else -1 if is_step_up == "Step Down" else 0
        )
        input_row["is_step_up"] = int(is_step_up == "Step Up")

        features_fee = prepare_feature_frame(
            pd.DataFrame([input_row]),
            TRANSFER_NUMERIC_FEATURES,
            TRANSFER_CATEGORICAL_FEATURES,
        )
        predicted_fee = float(np.expm1(transfer_fee_model.predict(features_fee))[0])

        features_outcome = prepare_feature_frame(
            pd.DataFrame([input_row]),
            TRANSFER_OUTCOME_NUMERIC_FEATURES,
            TRANSFER_CATEGORICAL_FEATURES,
        )
        success_probability = outcome_model.predict_proba(features_outcome)[0, 1]

        st.metric("Predicted Transfer Fee", format_currency(predicted_fee))
        st.metric("Success Probability", format_percent(success_probability, decimals=0))
        rmse_fee = fee_metrics.get("rmse") if fee_metrics else None
        if rmse_fee:
            lower = max(predicted_fee - rmse_fee, 0)
            upper = predicted_fee + rmse_fee
            st.caption(
                f"Use this sandbox to benchmark negotiations or run 'what-if' transfer ideas. Confidence range: {format_currency(lower)} – {format_currency(upper)}."
            )
        else:
            st.caption("Use this sandbox to benchmark negotiations or run 'what-if' transfer ideas.")
        st.info(
            "Guidance:\n"
            "- Step-up moves typically increase the projected fee and lower success probability.\n"
            "- Longer remaining contracts raise fees; experiment with the slider before entering talks.\n"
            "- Keep recent minutes/goals grounded in reality—the model expects last season’s stats."
        )


def show_undervalued(df_snapshot, value_model, value_metrics):
    st.header("Undervalued Players")
    st.write("Identifies players whose model-predicted fair value exceeds their current market value, with rich league filters.")
    st.caption(
        "Use the filters to find bargains by role, league, budget, and age. Filtering only zero-valued youngsters will naturally show dots above the parity line because the model still assigns them a positive value."
    )
    render_metric_block(value_metrics, "regression")
    
    col1, col2, col3 = st.columns(3)
    
    with col1:
        positions = ["All"] + sorted(df_snapshot["position"].unique().tolist())
        selected_pos = st.multiselect("Filter by Position", positions, default=["All"])
    
    with col2:
        leagues = ["All"] + sorted(df_snapshot["current_league_name"].dropna().unique().tolist())
        selected_leagues = st.multiselect("Filter by League", leagues, default=["All"])
    
    with col3:
        min_value = st.number_input("Minimum Market Value (EUR)", value=0, step=100000)
    
    max_age = st.slider("Maximum Age", 16, 40, 32)
    
    df_filtered = df_snapshot.copy()
    
    if "All" not in selected_pos and len(selected_pos) > 0:
        df_filtered = df_filtered[df_filtered["position"].isin(selected_pos)]
    
    if "All" not in selected_leagues and len(selected_leagues) > 0:
        df_filtered = df_filtered[df_filtered["current_league_name"].isin(selected_leagues)]
    
    df_filtered = df_filtered[df_filtered["age"] <= max_age]
    
    if min_value > 0:
        df_filtered = df_filtered[df_filtered["latest_market_value"] >= min_value]
    
    X = prepare_feature_frame(
        df_filtered,
        VALUE_MODEL_NUMERIC_FEATURES,
        VALUE_MODEL_CATEGORICAL_FEATURES,
    )
    df_filtered["model_value_eur"] = np.expm1(value_model.predict(X))
    rmse_val = value_metrics.get("rmse") if value_metrics else None
    if rmse_val:
        df_filtered["model_value_lower"] = np.clip(df_filtered["model_value_eur"] - rmse_val, 0, None)
        df_filtered["model_value_upper"] = df_filtered["model_value_eur"] + rmse_val
    
    df_filtered["undervaluation"] = df_filtered["model_value_eur"] - df_filtered["latest_market_value"]
    
    df_sorted = df_filtered.sort_values("undervaluation", ascending=False).head(50)
    
    display_cols = [
        "player_id",
        "name",
        "position",
        "age",
        "current_league_name",
        "latest_market_value",
        "model_value_eur",
        "model_value_lower",
        "model_value_upper",
        "undervaluation",
        "value_vs_age_pos_ratio",
        "value_1yr_growth_pct",
        "value_trend",
    ]
    display_cols = [c for c in display_cols if c in df_sorted.columns]
    
    st.dataframe(
        df_sorted[display_cols].style.format({
            "latest_market_value": "{:,.0f}",
            "model_value_eur": "{:,.0f}",
            "model_value_lower": "{:,.0f}",
            "model_value_upper": "{:,.0f}",
            "undervaluation": "{:,.0f}",
            "value_vs_age_pos_ratio": "{:.2f}",
            "value_1yr_growth_pct": "{:.1f}%"
        }),
        height=600
    )

    st.subheader("Actual vs Predicted Value")
    chart_df = df_filtered.sort_values("undervaluation", ascending=False).head(500)
    if not chart_df.empty:
        highlight_options = ["(none)"] + chart_df["name"].dropna().head(200).tolist()
        highlight_player = st.selectbox("Highlight Player", highlight_options)
        pos_color_map = ensure_color_map(chart_df["position"], POSITION_COLOR_BASE)
        fig = px.scatter(
            chart_df,
            x="latest_market_value",
            y="model_value_eur",
            color="position",
            size="career_minutes",
            custom_data=[
                "name",
                "position",
                "current_league_name",
                "undervaluation",
                "age",
                "career_minutes",
                "value_1yr_growth_pct",
            ],
            labels={"latest_market_value": "Current Value (€)", "model_value_eur": "Model Value (€)"},
            color_discrete_map=pos_color_map,
            template="plotly_white",
        )
        fig.update_traces(
            hovertemplate="<b>%{customdata[0]}</b> · %{customdata[1]}<br>"
            "League: %{customdata[2]}<br>"
            "Current value: €%{x:,.0f}<br>"
            "Model value: €%{y:,.0f}<br>"
            "Undervaluation: €%{customdata[3]:,.0f}<br>"
            "Age: %{customdata[4]:.0f} · Minutes: %{customdata[5]:,.0f}<br>"
            "1Y growth: %{customdata[6]:.1f}%<extra></extra>"
        )
        if rmse_val and "model_value_upper" in chart_df.columns and "model_value_lower" in chart_df.columns:
            fig.update_traces(
                error_y=dict(
                    type="data",
                    array=(chart_df["model_value_upper"] - chart_df["model_value_eur"]).clip(lower=0),
                    arrayminus=(chart_df["model_value_eur"] - chart_df["model_value_lower"]).clip(lower=0),
                    visible=True,
                    color="rgba(150,150,150,0.4)",
                    thickness=1.2,
                )
            )
        if highlight_player and highlight_player != "(none)":
            selected = chart_df[chart_df["name"] == highlight_player]
            if not selected.empty:
                fig.add_trace(
                    go.Scatter(
                        x=selected["latest_market_value"],
                        y=selected["model_value_eur"],
                        mode="markers+text",
                        text=selected["name"],
                        textposition="top center",
                        marker=dict(color="gold", size=20, symbol="star"),
                        name=f"Highlighted: {highlight_player}",
                    )
                )
        fig.add_trace(
            go.Scatter(
                x=[chart_df["latest_market_value"].min(), chart_df["latest_market_value"].max()],
                y=[chart_df["latest_market_value"].min(), chart_df["latest_market_value"].max()],
                mode="lines",
                name="Parity Line",
                line=dict(color="gray", dash="dash"),
            )
        )
        fig.update_layout(
            height=500,
            legend_title_text="Position",
            hoverlabel=HOVERLABEL_STYLE,
            hovermode="closest",
            margin=dict(l=0, r=0, t=50, b=0),
        )
        st.plotly_chart(fig, use_container_width=True)

        # Clear visual encoding explanation
        st.info(
            "📊 **How to Read This Plot:**\n\n"
            "• **Bubble Size** = Career Minutes Played (larger = more experienced, more reliable predictions)\n"
            "• **Color** = Position (GK = Blue, DEF = Green, MID = Orange, FWD = Red)\n"
            "• **Vertical Error Bars** = Prediction Uncertainty (±RMSE = ±€6M)\n"
            "• **Parity Line** (diagonal) = Where actual = predicted (fair value)\n"
            "• **Above Parity Line** = Undervalued (model predicts higher value)\n"
            "• **Below Parity Line** = Overvalued (model predicts lower value)\n\n"
            "**Best Opportunities**: Large bubbles far above the parity line (proven players, massively underpriced)"
        )
    else:
        st.info("Adjust filters to view the scatter chart.")

    if not df_sorted.empty:
        top_pick = df_sorted.iloc[0]
        st.metric(
            "Top opportunity",
            top_pick["name"],
            delta=f"{format_currency(top_pick['undervaluation'])} undervalued",
        )
        narrative = [describe_value_gap(row) for _, row in df_sorted.head(3).iterrows()]
        st.markdown("**Quick scouting narrative:**")
        for bullet in narrative:
            st.write(f"- {bullet}")

    render_value_scenario(df_snapshot, value_model, value_metrics)
    render_shap_importance(
        "M2 Value Growth",
        "Value Model — Top Drivers (SHAP)",
        "Bars show how much each feature swings the valuation on average. Minutes, age curve, and league strength are the dominant drivers behind the undervaluation rankings.",
    )


def show_breakout_candidates(df_snapshot: pd.DataFrame, breakout_model, breakout_metrics):
    st.header("Breakout Candidates")
    st.write("Young players (age ≤ 22) ranked by breakout probability with contextual performance metrics.")
    st.caption("High probability means the player’s value historically tends to surge within the next two seasons.")
    render_metric_block(breakout_metrics, "classification")

    df_breakout = score_breakout_candidates_local(df_snapshot, breakout_model)
    df_breakout = df_breakout[df_breakout["career_minutes"] >= 300].copy()

    col1, col2 = st.columns(2)
    min_prob = col1.slider("Minimum Breakout Probability", 0.0, 1.0, 0.6, 0.05)
    position_filter = col2.multiselect(
        "Positions",
        sorted(df_breakout["position"].dropna().unique().tolist()),
        default=sorted(df_breakout["position"].dropna().unique().tolist()),
    )

    df_filtered = df_breakout[df_breakout["breakout_probability"] >= min_prob]
    if position_filter:
        df_filtered = df_filtered[df_filtered["position"].isin(position_filter)]

    st.write(f"Found {len(df_filtered)} breakout prospects after filtering.")
    if not df_filtered.empty:
        best = df_filtered.sort_values("breakout_probability", ascending=False).head(3)
        stat_cols = st.columns(len(best))
        for col, (_, row) in zip(stat_cols, best.iterrows()):
            col.metric(
                row["name"],
                format_percent(row["breakout_probability"]),
                help=f"{row['position']} | {row['current_league_name'] or 'Unknown league'}",
            )

    display_cols = [
        "player_id",
        "name",
        "position",
        "age",
        "current_league_name",
        "current_market_value",
        "career_minutes",
        "career_goals",
        "career_assists",
        "career_goals_per_90",
        "career_assists_per_90",
        "career_goals_per90_pct_rank",
        "value_1yr_growth_pct",
        "value_vs_age_pos_ratio",
        "breakout_probability",
    ]
    display_cols = [c for c in display_cols if c in df_filtered.columns]

    st.dataframe(
        df_filtered[display_cols].style.format({
            "current_market_value": "{:,.0f}",
            "career_goals_per_90": "{:.2f}",
            "career_assists_per_90": "{:.2f}",
            "career_goals_per90_pct_rank": "{:.1f}",
            "value_1yr_growth_pct": "{:.1f}%",
            "value_vs_age_pos_ratio": "{:.2f}",
            "breakout_probability": "{:.2%}"
        }),
        height=450
    )

    if not df_filtered.empty:
        st.subheader("Probability vs Current Value")
        pos_color_map = ensure_color_map(df_filtered["position"], POSITION_COLOR_BASE)
        scatter = px.scatter(
            df_filtered,
            x="current_market_value",
            y="breakout_probability",
            color="position",
            size="career_minutes",
            custom_data=[
                "name",
                "position",
                "current_league_name",
                "career_minutes",
                "value_1yr_growth_pct",
                "career_goals_per_90",
            ],
            labels={
                "current_market_value": "Current Value (€)",
                "breakout_probability": "Breakout Probability"
            },
            color_discrete_map=pos_color_map,
            template="plotly_white",
        )
        scatter.update_traces(
            hovertemplate="<b>%{customdata[0]}</b> · %{customdata[1]}<br>"
            "League: %{customdata[2]}<br>"
            "Current value: €%{x:,.0f}<br>"
            "Breakout probability: %{y:.1%}<br>"
            "Minutes: %{customdata[3]:,.0f} · 1Y growth: %{customdata[4]:.1f}%<br>"
            "Goals/90: %{customdata[5]:.2f}<extra></extra>"
        )
        scatter.update_layout(
            height=500,
            legend_title_text="Position",
            hoverlabel=HOVERLABEL_STYLE,
            hovermode="closest",
            margin=dict(l=0, r=0, t=40, b=0),
        )
        st.plotly_chart(scatter, use_container_width=True)
        st.caption(
            "Markers scale with minutes (availability), color tracks position, and hover cards explain why the model is confident—this lets scouts balance upside vs. exposure at a glance."
        )

        selected_player = st.selectbox(
            "Explore player profile",
            df_filtered["name"].tolist(),
        )
        detail = df_filtered[df_filtered["name"] == selected_player].iloc[0]
        st.metric("Breakout Probability", f"{detail['breakout_probability']:.1%}")
        st.metric("Value vs Age Curve", f"{detail['value_vs_age_pos_ratio']:.2f}x")
    else:
        st.info("Adjust filters to see breakout visualizations.")


def show_development_curves(df_aging: pd.DataFrame, df_snapshot: pd.DataFrame):
    st.header("Player Development & Aging Curves")
    st.write("Average market value by age for each position.")
    st.caption("Solid blue line = mean value at each age; dashed orange = median; shaded band = interquartile range. Use this to benchmark whether a player is ahead (above band) or behind (below band) their positional peers.")
    
    positions = sorted(df_aging["position"].unique().tolist())
    selected_position = st.selectbox("Select Position", positions)
    
    df_pos = df_aging[df_aging["position"] == selected_position].sort_values("age")
    
    band_fig = go.Figure()
    band_fig.add_trace(go.Scatter(
        x=df_pos["age"],
        y=df_pos["p75_market_value"],
        name="75th Percentile",
        line=dict(color=BAND_PRIMARY),
        hovertemplate="Age %{x}: 75th percentile = €%{y:,.0f}<extra></extra>",
    ))
    band_fig.add_trace(go.Scatter(
        x=df_pos["age"],
        y=df_pos["p25_market_value"],
        name="25th Percentile",
        fill="tonexty",
        line=dict(color=BAND_SECONDARY),
        hovertemplate="Age %{x}: 25th percentile = €%{y:,.0f}<extra></extra>",
    ))
    band_fig.add_trace(go.Scatter(
        x=df_pos["age"],
        y=df_pos["mean_market_value"],
        name="Mean Market Value",
        line=dict(color=PRIMARY_BLUE, width=3),
        hovertemplate="Age %{x}: Mean value = €%{y:,.0f}<extra></extra>",
    ))
    band_fig.add_trace(go.Scatter(
        x=df_pos["age"],
        y=df_pos["median_market_value"],
        name="Median Market Value",
        line=dict(color=ACCENT_ORANGE, width=2, dash="dash"),
        hovertemplate="Age %{x}: Median value = €%{y:,.0f}<extra></extra>",
    ))
    band_fig.update_layout(
        title=f"Aging Curve with Percentile Bands ({selected_position})",
        xaxis_title="Age",
        yaxis_title="Market Value (EUR)",
        height=550,
        template="plotly_white",
        hoverlabel=HOVERLABEL_STYLE,
    )
    st.plotly_chart(band_fig, use_container_width=True)
    
    st.subheader("Data Table")
    st.dataframe(
        df_pos.style.format({
            "mean_market_value": "{:,.0f}",
            "median_market_value": "{:,.0f}",
            "p25_market_value": "{:,.0f}",
            "p75_market_value": "{:,.0f}",
            "count": "{:,}"
        }),
        height=400
    )

    peak_age = df_pos.loc[df_pos["mean_market_value"].idxmax(), "age"]
    st.caption(f"Players in this role typically reach peak value around age {int(peak_age)}.")

    st.subheader("Players relative to aging curve")
    df_players = df_snapshot[df_snapshot["position"] == selected_position].copy()
    df_players = df_players[df_players["value_vs_age_pos_ratio"].notna()]
    if not df_players.empty:
        league_color_map = ensure_color_map(df_players["current_league_name"], palette=LEAGUE_COLOR_SEQUENCE)
        scatter = px.scatter(
            df_players,
            x="age",
            y="value_vs_age_pos_ratio",
            color="current_league_name",
            custom_data=["name", "latest_market_value", "value_1yr_growth_pct"],
            labels={
                "age": "Age",
                "value_vs_age_pos_ratio": "Actual vs Expected Value",
                "current_league_name": "League"
            },
            color_discrete_map=league_color_map,
            template="plotly_white",
        )
        scatter.add_hline(y=1.0, line_dash="dash", line_color="gray")
        scatter.update_traces(
            hovertemplate="<b>%{customdata[0]}</b><br>"
            "Age: %{x}<br>"
            "Value vs curve: %{y:.2f}x<br>"
            "Current value: €%{customdata[1]:,.0f}<br>"
            "1Y value growth: %{customdata[2]:.1f}%<extra></extra>"
        )
        scatter.update_layout(
            height=500,
            legend_title_text="League",
            hoverlabel=HOVERLABEL_STYLE,
            hovermode="closest",
        )
        st.plotly_chart(scatter, use_container_width=True)
        st.caption("Values above 1.0 sit above the positional benchmark; color indicates competition strength so analysts know if a player is ahead because of league context or genuine outlier growth.")

        top_outliers = df_players.sort_values("value_vs_age_pos_ratio", ascending=False).head(5)
        lagging = df_players.sort_values("value_vs_age_pos_ratio", ascending=True).head(5)
        st.markdown("**Aging gracefully (top 5):** " + ", ".join(top_outliers["name"].tolist()))
        st.markdown("**Lagging peers (bottom 5):** " + ", ".join(lagging["name"].tolist()))
        st.caption("Dots above 1.0 mean the player is worth more than the average peer at the same age; below 1.0 indicates underperforming development.")
    else:
        st.info("No player snapshots available for this position.")


def show_player_lookup(df_snapshot):
    st.header("Player Lookup")
    st.write("Search for players by name.")
    st.caption("Helpful for internal scouting meetings: type part of a name to review every stat the models use.")
    
    search_query = st.text_input("Enter player name (partial match)")
    
    if search_query:
        mask = df_snapshot["name"].str.contains(search_query, case=False, na=False)
        df_results = df_snapshot[mask]
        
        st.write(f"Found {len(df_results)} matches")
        
        display_cols = [
            "player_id",
            "name",
            "position",
            "age",
            "current_league_name",
            "latest_market_value",
            "career_goals",
            "career_assists",
            "career_minutes",
            "career_goals_per_90",
            "career_assists_per_90",
            "value_vs_age_pos_ratio",
            "value_1yr_growth_pct",
            "contract_months_remaining",
        ]
        display_cols = [c for c in display_cols if c in df_results.columns]
        
        st.dataframe(
            df_results[display_cols].style.format({
                "latest_market_value": "{:,.0f}",
                "career_goals_per_90": "{:.2f}",
                "career_assists_per_90": "{:.2f}",
                "value_vs_age_pos_ratio": "{:.2f}",
                "value_1yr_growth_pct": "{:.1f}%",
                "contract_months_remaining": "{:.0f}"
            }),
            height=600
        )

        focus_player = st.selectbox("Visualize player details", df_results["name"].tolist())
        focus_row = df_results[df_results["name"] == focus_player].iloc[0]
        bar = go.Figure()
        bar.add_trace(go.Bar(
            x=["Goals/90", "Assists/90"],
            y=[focus_row.get("career_goals_per_90", 0), focus_row.get("career_assists_per_90", 0)],
            marker_color=[GOAL_BAR_COLOR, ASSIST_BAR_COLOR]
        ))
        bar.update_layout(
            title=f"Per 90 Contribution - {focus_player}",
            yaxis_title="Per 90 Contribution",
            height=350,
            template="plotly_white",
            hoverlabel=HOVERLABEL_STYLE,
        )
        bar.update_traces(hovertemplate="%{x}: %{y:.2f}<extra></extra>")
        st.plotly_chart(bar, use_container_width=True)
        st.metric("Value vs Expected Curve", f"{focus_row.get('value_vs_age_pos_ratio', 0):.2f}x")
    else:
        st.info("Enter a player name to search")


def show_transfer_insights(
    df_snapshot: pd.DataFrame,
    df_transfers: pd.DataFrame,
    transfer_fee_model,
    outcome_model,
    fee_metrics,
    outcome_metrics,
):
    st.header("Transfer Insights")
    st.write("Analyze historical transfers to spot bargains, risky moves, and success probabilities.")
    st.caption("Designed for club execs: quickly benchmark fees and see which deals the model considered overpriced or risky.")
    render_metric_block(fee_metrics, "regression")
    render_metric_block(outcome_metrics, "classification")

    if df_transfers.empty:
        st.info("Transfer dataset unavailable. Run feature engineering first.")
        return

    df = df_transfers.merge(
        df_snapshot[["player_id", "name"]],
        on="player_id",
        how="left",
    )
    df["scenario_label"] = df.apply(
        lambda row: f"{row.get('name', 'Unknown')} ({int(row.get('transfer_year', 0))})", axis=1
    )

    fee_features = prepare_feature_frame(df, TRANSFER_NUMERIC_FEATURES, TRANSFER_CATEGORICAL_FEATURES)
    df["predicted_fee"] = np.expm1(transfer_fee_model.predict(fee_features))

    outcome_features = prepare_feature_frame(df, TRANSFER_OUTCOME_NUMERIC_FEATURES, TRANSFER_CATEGORICAL_FEATURES)
    df["success_probability"] = outcome_model.predict_proba(outcome_features)[:, 1]
    df["fee_gap"] = df["transfer_fee"] - df["predicted_fee"]

    min_year = int(df["transfer_year"].min())
    max_year = int(df["transfer_year"].max())
    default_start = max(min_year, max_year - 4)
    year_range = st.slider("Transfer Year Range", min_year, max_year, (default_start, max_year))
    league_move = st.selectbox("League Change", ["All", "Step Up", "Lateral", "Step Down"])

    df_filtered = df[(df["transfer_year"] >= year_range[0]) & (df["transfer_year"] <= year_range[1])]
    if league_move == "Step Up":
        df_filtered = df_filtered[df_filtered["league_step"] > 0]
    elif league_move == "Step Down":
        df_filtered = df_filtered[df_filtered["league_step"] < 0]
    elif league_move == "Lateral":
        df_filtered = df_filtered[df_filtered["league_step"] == 0]

    st.metric("Average Actual Fee", format_currency(df_filtered["transfer_fee"].mean()))
    st.metric("Average Model Fee", format_currency(df_filtered["predicted_fee"].mean()))
    st.metric("Avg Success Probability", format_percent(df_filtered["success_probability"].mean()))

    display_cols = [
        "transfer_year",
        "name",
        "position",
        "from_league_name",
        "to_league_name",
        "transfer_fee",
        "predicted_fee",
        "fee_gap",
        "success_probability",
    ]
    display_cols = [col for col in display_cols if col in df_filtered.columns]
    st.dataframe(
        df_filtered[display_cols].head(200).style.format({
            "transfer_fee": "{:,.0f}",
            "predicted_fee": "{:,.0f}",
            "fee_gap": "{:,.0f}",
            "success_probability": "{:.1%}"
        }),
        height=350
    )

    if not df_filtered.empty:
        pos_color_map = ensure_color_map(df_filtered["position"], POSITION_COLOR_BASE)
        scatter = px.scatter(
            df_filtered,
            x="transfer_fee",
            y="predicted_fee",
            color="position",
            custom_data=[
                "name",
                "position",
                "from_league_name",
                "to_league_name",
                "success_probability",
            ],
            labels={"transfer_fee": "Actual Fee (€)", "predicted_fee": "Model Fee (€)"},
            color_discrete_map=pos_color_map,
            template="plotly_white",
        )
        scatter.update_traces(
            hovertemplate="<b>%{customdata[0]}</b> · %{customdata[1]}<br>"
            "From: %{customdata[2]} → To: %{customdata[3]}<br>"
            "Actual fee: €%{x:,.0f}<br>"
            "Model fee: €%{y:,.0f}<br>"
            "Success probability: %{customdata[4]:.1%}<extra></extra>"
        )
        scatter.add_trace(
            go.Scatter(
                x=[df_filtered["transfer_fee"].min(), df_filtered["transfer_fee"].max()],
                y=[df_filtered["transfer_fee"].min(), df_filtered["transfer_fee"].max()],
                mode="lines",
                name="Parity",
                line=dict(color="gray", dash="dash"),
            )
        )
        scatter.update_layout(
            height=500,
            legend_title_text="Position",
            hoverlabel=HOVERLABEL_STYLE,
            hovermode="closest",
        )
        st.plotly_chart(scatter, use_container_width=True)
        st.caption("Dots above the grey parity line indicate deals where the club likely overpaid. Rich hover cards mix source/destination leagues, success probability, and both fees for immediate negotiation context.")

        top_bargains = df_filtered.sort_values("fee_gap").head(10)
        bargains_fig = px.bar(
            top_bargains,
            x="fee_gap",
            y="name",
            orientation="h",
            title="Top Bargains (Actual - Predicted)",
            labels={"fee_gap": "Fee Gap (€)", "name": "Player"},
        )
        bargains_fig.update_traces(marker_color=PRIMARY_BLUE)
        bargains_fig.update_layout(template="plotly_white", hoverlabel=HOVERLABEL_STYLE)
        st.plotly_chart(bargains_fig, use_container_width=True)
        st.caption("Bars extending further left indicate bigger savings versus the model fee; all numbers are shown in today’s euros for apples-to-apples benchmarking.")
        st.caption("Negative bars indicate fees below the model estimate (potential bargains).")

        success_hist = px.histogram(
            df_filtered,
            x="success_probability",
            nbins=20,
            title="Distribution of Success Probability",
        )
        st.plotly_chart(success_hist, use_container_width=True)
    else:
        st.info("No transfers match the filters.")

    render_shap_importance(
        "M1 Transfer Fee",
        "Fee Model — Top Drivers (SHAP)",
        "These drivers move the predicted fee up or down; market value, contract runway, and usable minutes dominate.",
    )
    render_shap_importance(
        "M3 Transfer Outcome",
        "Transfer Success Model — Top Drivers (SHAP)",
        "Features with higher mean |SHAP| swing the success probability most. Age, fee inflation, and league step are key risk levers.",
    )

    render_transfer_scenario(df, transfer_fee_model, outcome_model, fee_metrics)


def show_model_guide():
    st.header("Guide & Explainability")
    st.write("Everything on the dashboard is tied to a reproducible ML pipeline. Use this walkthrough in diligence meetings or hackathon pitches.")

    with st.expander("1️⃣ Data foundation", expanded=True):
        st.markdown(
            "- **Sources**: Kaggle Player Scores bundle (`players`, `player_valuations`, `appearances`, `transfers`, `competitions`).\n"
            "- **IDs & joins**: We standardize on `player_id`, `game_id`, and `competition_id` so snapshots, transfers, and league context stay aligned.\n"
            "- **Date handling**: Valuation dates, appearances, transfers, and contracts are all parsed as `datetime` so age, momentum, and contract runway are accurate.\n"
            "- **Season table**: `appearances + games` → player-season aggregates (minutes, goals, assists, cards) → per-90 + minutes ratio with a 300-minute filter to remove noise.\n"
            "- **Snapshot**: Latest valuation + latest season stats + age + contract info per player. This powers undervaluation, breakout scoring, and the lookup tab.\n"
            "- **Confounder controls**: League tier, club strength proxy, log-transform of monetary targets, and age² are added to every modeling dataset."
        )

    with st.expander("2️⃣ Modeling stack", expanded=True):
        st.markdown(
            "**M1 · Transfer Fee (XGBoost regressor)**\n"
            "- Target: log-transformed actual transfer fee.\n"
            "- Inputs: market value at transfer, contract months, recent minutes/goals/assists, fee-to-value ratio, league strength delta, \"step up/down\" encoding.\n"
            "- Use case: benchmarking negotiations, highlighting bargains/overpays, fueling the scenario widget.\n\n"
            "**M2 · Value Growth / Undervaluation (XGBoost regressor)**\n"
            "- Target: log future valuation; predictions compared to current market value to compute undervaluation.\n"
            "- Inputs: snapshot metrics (career & last-season per-90), age & age², league tier, club strength, contract runway, foot/position.\n"
            "- Use case: surfaces players priced below model fair value, feeds the what-if simulator.\n\n"
            "**M3 · Transfer Outcome (XGBoost classifier)**\n"
            "- Target: categorical success label (over/meet/under), evaluated as binary success probability in the dashboard.\n"
            "- Inputs: same temporal boundary as the fee model plus value delta label engineered ~24 months post-transfer.\n"
            "- Use case: risk screening, success score on the Transfer tab, scenario studio probability readout.\n\n"
            "**M4 · Breakout Classifier (LightGBM)**\n"
            "- Target: probability under-23 player will increase value >50% within ~2 seasons.\n"
            "- Inputs: youth subset of snapshots, metrics like growth momentum, percentile ranks, league strength, per-90 output.\n"
            "- Use case: ranking emerging talent, guiding youth recruitment shortlists."
        )

    with st.expander("3️⃣ Evaluation & validation", expanded=False):
        st.markdown(
            "- **Train/validation splits**: time-based to mimic future predictions (e.g., value model trained ≤2018, validated 2019, tested ≥2020).\n"
            "- **Metrics**: RMSE/R² for regressors; accuracy/precision/recall for classifiers. Results are persisted in `reports/model_metrics.json` and shown on each tab.\n"
            "- **Testing**: `tests/` covers feature engineering utilities; unit tests run via `python -m unittest discover -s tests`."
        )

    with st.expander("4️⃣ Explainability & UX", expanded=False):
        st.markdown(
            "- **SHAP summaries**: Each model tab shows top feature drivers (mean |SHAP|) so decision makers know *why* a player is flagged.\n"
            "- **Scenario tools**: Sliders/numeric inputs let analysts test “what if we sign a 24-year-old winger with 3000 minutes?” instantly.\n"
            "- **Visualization principles**: Color-blind-safe palette, hover cards with context, confidence bands (±RMSE) for model curves, and narrative captions for every chart.\n"
            "- **Accessibility**: Tooltips, parity lines, and textual scouting narratives help non-technical staff interpret ML outputs."
        )

    st.caption(
        "Together, the pipeline converts raw match events and market data into explainable ML insights: undervalued assets, breakout bets, aging benchmarks, and transfer risk analysis—all in a single Streamlit console for club leadership."
    )

    st.caption("Model-specific SHAP explanations now live inside each tab so you can interpret drivers in context (e.g., fee drivers under Transfer Insights).")


def main():
    st.set_page_config(page_title="Soccer ML Analytics", layout="wide")
    st.title("Club Intelligence Console")
    st.write(
        "A single pane of glass for recruitment, player development, and transfer strategy. "
        "Every insight is powered by the Kaggle player-scores dataset."
    )
    st.sidebar.title("How to Use")
    st.sidebar.markdown(
        "- **Pick a tab** to explore undervalued players, youth prospects, development curves, or transfers.\n"
        "- **Filter first**, then review the charts and narratives for actionable takeaways.\n"
        "- **Scenario tools** on each tab let you run quick 'what-if' analyses for negotiation prep."
    )
    
    try:
        df_snapshot = load_player_snapshot()
        df_aging = load_aging_curves()
        df_transfers = load_transfer_dataset()
        transfer_fee_model, value_model, outcome_model, breakout_model = load_models()
    except Exception as e:
        st.error(f"Error loading data or models: {e}")
        st.stop()
    
    metrics_store = load_model_metrics()

    value_metrics = metrics_store.get("M2_value_growth") or compute_value_model_metrics(df_snapshot, value_model)
    fee_metrics = metrics_store.get("M1_transfer_fee") or compute_transfer_fee_metrics(df_transfers, transfer_fee_model)
    outcome_metrics = metrics_store.get("M3_transfer_outcome") or compute_transfer_outcome_metrics(df_transfers, outcome_model)
    breakout_metrics = metrics_store.get("M4_breakout") or compute_breakout_metrics(breakout_model)

    tab1, tab2, tab3, tab4, tab5, tab6 = st.tabs([
        "Undervalued Players",
        "Breakout Candidates",
        "Player Development",
        "Player Lookup",
        "Transfer Insights",
        "Guide & Explainability",
    ])
    
    with tab1:
        show_undervalued(df_snapshot, value_model, value_metrics)
    
    with tab2:
        show_breakout_candidates(df_snapshot, breakout_model, breakout_metrics)
    
    with tab3:
        show_development_curves(df_aging, df_snapshot)
    
    with tab4:
        show_player_lookup(df_snapshot)

    with tab5:
        show_transfer_insights(
            df_snapshot,
            df_transfers,
            transfer_fee_model,
            outcome_model,
            fee_metrics,
            outcome_metrics,
        )

    with tab6:
        show_model_guide()


if __name__ == "__main__":
    main()