Predicción de cruce en reporte pre-partido: bloque defensivo + pasillo de ataque + xT

Agrega modelos LightGBM (bloque defensivo, pasillo de ataque, xT por pasillo) al
reporte pre-partido: para A y B dibuja la cancha de ataque por pasillos y la de
bloque defensivo (bajo/medio/alto) + un insight del cruce. Inferencia con features
rolling 'a la fecha' precalculadas. No rompe el reporte si faltan datos.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitignore

@@ -34,3 +34,9 @@ vendor/data/processed/
 !vendor/data/modeling/attack_prediction_dataset.parquet
 !vendor/data/modeling/attack_matchup_gnn_bundle.pt
 !vendor/data/modeling/pv_distribution_gnn_bundle.pt
+# Modelos de cruce (bloque defensivo · pasillo de ataque · xT) + features para inferencia
+!vendor/data/modeling/model_bloques__*.txt
+!vendor/data/modeling/model_pasillos__*.txt
+!vendor/data/modeling/model_peligro_pasillo__*.txt
+!vendor/data/modeling/team_features_latest.parquet
+!vendor/data/modeling/matchup_feat_cols.json

scripts/build_matchup_features.py

@@ -0,0 +1,51 @@
+"""Precalcula, por equipo (liga, temporada), su vector de features rolling 'a la fecha'
+(la última fila disponible) para alimentar la predicción de cruce A-vs-B en el reporte
+pre-partido, sin tener que re-correr todo el pipeline en runtime.
+
+Sale:
+  vendor/data/modeling/team_features_latest.parquet  (1 fila por equipo-temporada)
+  vendor/data/modeling/matchup_feat_cols.json        (orden exacto de features del modelo)
+
+Uso: python scripts/build_matchup_features.py
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+from pathlib import Path
+
+import pandas as pd
+
+ROOT = Path(__file__).resolve().parents[1]
+spec = importlib.util.spec_from_file_location("tm", ROOT / "scripts" / "train_models.py")
+tm = importlib.util.module_from_spec(spec); spec.loader.exec_module(tm)
+OUT = ROOT / "vendor" / "data" / "modeling"
+
+
+def main() -> None:
+    df = pd.read_parquet(tm.DATA)
+    blk = df.assign(_b=df[tm.DEF].sum(axis=1) > 0).groupby("Competencia")["_b"].mean()
+    df = df[df["Competencia"].isin(blk[blk > 0.5].index)].copy()
+    m, feat = tm._assemble(df)
+    m = m.merge(df[["matchId", "teamId", "fecha", "TeamName"]].drop_duplicates(),
+                on=["matchId", "teamId"], how="left")
+
+    # columnas que definen el "estado a la fecha" de un equipo (lado propio)
+    self_cols = [c for c in m.columns if c.startswith(("self_", "selfH_", "selfA_"))]
+    keep = ["Competencia", "Temporada", "teamId", "TeamName", "fecha", "formation"] + self_cols
+    keep = [c for c in keep if c in m.columns]
+
+    # última fila por (liga, temporada, equipo) — su forma más reciente
+    m = m.sort_values(["Competencia", "Temporada", "teamId", "fecha", "matchId"])
+    latest = m[keep].dropna(subset=["self_def_H"]).groupby(
+        ["Competencia", "Temporada", "teamId"], as_index=False).last()
+
+    latest.to_parquet(OUT / "team_features_latest.parquet", index=False)
+    (OUT / "matchup_feat_cols.json").write_text(json.dumps(feat, ensure_ascii=False))
+    print(f"team_features_latest: {len(latest)} equipos-temporada | self_cols={len(self_cols)} | feat={len(feat)}")
+    print("ligas:", latest['Competencia'].nunique(), "| ej:",
+          latest[latest.Competencia.eq('Liga Profesional Argentina')]['TeamName'].dropna().unique()[:6].tolist())
+
+
+if __name__ == "__main__":
+    main()

scripts/train_models.py

@@ -0,0 +1,206 @@
+"""Entrena los dos modelos (bloque defensivo y pasillos) sobre el dataset RICO
+matchteam_dataset.parquet. Arma features SIN leakage:
+  - ELO propio por (liga,temporada), pre-partido (de los resultados).
+  - Rolling "hasta la fecha" (promedio expandido de partidos PREVIOS) del equipo y del
+    rival, y splits LOCAL / VISITA (cómo juega/resulta de local vs visitante).
+  - Resultados rolling (win%, goles a favor/en contra) all/home/away.
+  - One-hot de la formación del partido (info pre-partido).
+LightGBM por componente, normalizado a simplex; baseline = promedio propio.
+
+Uso: python scripts/train_models.py
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+import lightgbm as lgb
+import numpy as np
+import pandas as pd
+
+DATA = Path(__file__).resolve().parents[1] / "vendor" / "data" / "modeling" / "matchteam_dataset.parquet"
+OUTDIR = DATA.parent
+DEF = ["def_H", "def_M", "def_L"]
+ATK = ["atk_Der", "atk_Centro", "atk_Izq"]
+OFFXT = [f"offxt_{b}_{l}" for b in "HML" for l in ["Der", "Centro", "Izq"]]
+DEFXT = [f"defxt_{b}_{l}" for b in "HML" for l in ["Der", "Centro", "Izq"]]
+XTLANE = ["xt_lane_Der", "xt_lane_Centro", "xt_lane_Izq"]  # xT absoluto por pasillo (objetivo Modelo 2-b)
+DIST_GROUPS = {"def": DEF, "atk": ATK, "offxt": OFFXT, "defxt": DEFXT}
+SCALARS = ["sh_buildup", "sh_counter", "sh_direct", "sh_setpiece", "sh_recovery", "sh_progr",
+           "cross_pct", "pct_long", "pct_short", "pct_pass_ok", "n_attacks", "xt_total",
+           "xg_total", "xt_per_attack", "n_seq", "n_pass", "n_shots", "avg_x", "avg_y",
+           "share_opp_half", "recovery_height", "n_progr", "goals_for", "goals_against", "win"] + XTLANE
+RNG = np.random.default_rng(7)
+
+
+def _norm_df(df, cols):
+    s = df[cols].sum(axis=1)
+    out = df[cols].div(s.where(s > 0), axis=0)
+    return out, s
+
+
+def _elo(df: pd.DataFrame) -> pd.Series:
+    """ELO pre-partido por (liga,temporada). Devuelve serie alineada al índice de df."""
+    K, HOME = 24.0, 60.0
+    elo = pd.Series(np.nan, index=df.index)
+    for _, g in df.groupby(["Competencia", "Temporada"], sort=False):
+        rating: dict = {}
+        # ordenar por fecha y partido; procesar cada partido (2 filas) una vez
+        g = g.sort_values(["fecha", "matchId"])
+        for mid, mm in g.groupby("matchId", sort=False):
+            if len(mm) != 2:
+                for i in mm.index:
+                    elo.loc[i] = rating.get(mm.loc[i, "teamId"], 1500.0)
+                continue
+            i1, i2 = mm.index
+            t1, t2 = mm.loc[i1, "teamId"], mm.loc[i2, "teamId"]
+            r1, r2 = rating.get(t1, 1500.0), rating.get(t2, 1500.0)
+            elo.loc[i1], elo.loc[i2] = r1, r2  # pre-partido
+            h1 = HOME if mm.loc[i1, "is_home"] else 0.0
+            h2 = HOME if mm.loc[i2, "is_home"] else 0.0
+            e1 = 1.0 / (1.0 + 10 ** ((r2 - r1 - h1 + h2) / 400.0))
+            gf1, ga1 = mm.loc[i1, "goals_for"], mm.loc[i1, "goals_against"]
+            s1 = 0.5 if pd.isna(gf1) or pd.isna(ga1) or gf1 == ga1 else (1.0 if gf1 > ga1 else 0.0)
+            gd = 1.0 if pd.isna(gf1) or pd.isna(ga1) else max(1.0, abs(gf1 - ga1)) ** 0.5
+            rating[t1] = r1 + K * gd * (s1 - e1)
+            rating[t2] = r2 + K * gd * ((1 - s1) - (1 - e1))
+    return elo
+
+
+def _prep(df: pd.DataFrame) -> pd.DataFrame:
+    df = df.copy()
+    df["win"] = np.where(df["goals_for"] > df["goals_against"], 1.0,
+                         np.where(df["goals_for"] < df["goals_against"], 0.0, 0.5))
+    # xT absoluto por pasillo = suma del xT por bloque en cada pasillo
+    for ln in ["Der", "Centro", "Izq"]:
+        df[f"xt_lane_{ln}"] = df[[f"offxt_{b}_{ln}" for b in "HML"]].sum(axis=1)
+    # normalizar grupos distribucionales a shares (para features de estilo/peligro)
+    feat = {}
+    for name, cols in DIST_GROUPS.items():
+        nd, _ = _norm_df(df, cols)
+        for c in cols:
+            feat["f_" + c] = nd[c]
+    for c in SCALARS:
+        feat["f_" + c] = pd.to_numeric(df[c], errors="coerce")
+    F = pd.DataFrame(feat, index=df.index)
+    df = pd.concat([df, F], axis=1)
+    df["elo"] = _elo(df)
+    return df
+
+
+def _rolling(df: pd.DataFrame) -> pd.DataFrame:
+    fcols = [c for c in df.columns if c.startswith("f_")]
+    df = df.sort_values(["Competencia", "Temporada", "teamId", "fecha", "matchId"]).copy()
+    keys = ["Competencia", "Temporada", "teamId"]
+
+    def _prior(frame):  # expanding mean de partidos previos
+        return frame.groupby([df[k] for k in keys], group_keys=False).apply(lambda x: x.shift(1).expanding().mean())
+
+    roll_all = _prior(df[fcols]); roll_all.columns = ["self_" + c[2:] for c in fcols]
+    # splits local/visita: expanding sobre el subconjunto, luego ffill al resto
+    def _split(is_home_val):
+        sub = df[fcols].where(df["is_home"] == is_home_val)
+        r = sub.groupby([df[k] for k in keys], group_keys=False).apply(lambda x: x.shift(1).expanding().mean())
+        r = r.groupby([df[k] for k in keys], group_keys=False).ffill()
+        return r
+    rh = _split(True); rh.columns = ["selfH_" + c[2:] for c in fcols]
+    ra = _split(False); ra.columns = ["selfA_" + c[2:] for c in fcols]
+    eloprior = df.groupby(keys, group_keys=False)["elo"].apply(lambda x: x)  # ya es pre-partido
+    out = pd.concat([df[keys + ["matchId", "rival_teamId", "is_home", "formation"] + DEF + ATK + XTLANE],
+                     df["elo"].rename("self_elo"), roll_all, rh, ra], axis=1)
+    return out
+
+
+def _assemble(df: pd.DataFrame):
+    df = _prep(df)
+    roll = _rolling(df)
+    selfcols = [c for c in roll.columns if c.startswith(("self_", "selfH_", "selfA_"))]
+    oppmap = roll[["matchId", "teamId"] + selfcols].rename(
+        columns={"teamId": "rival_teamId", **{c: "opp_" + c for c in selfcols}})
+    m = roll.merge(oppmap, on=["matchId", "rival_teamId"], how="left")
+    m["is_home"] = m["is_home"].astype(float)
+    m["elo_diff"] = m["self_elo"] - m["opp_self_elo"]
+    # one-hot formación (top 12 + otras)
+    top = m["formation"].astype(str).value_counts().head(12).index
+    for f in top:
+        m[f"form_{f}"] = (m["formation"].astype(str) == f).astype(float)
+    feat_cols = (selfcols + [c for c in m.columns if c.startswith("opp_")]
+                 + ["is_home", "elo_diff"] + [f"form_{f}" for f in top])
+    return m, feat_cols
+
+
+def _kl(a, b):
+    a = np.clip(a, 1e-9, None); b = np.clip(b, 1e-9, None)
+    return float(np.mean(np.sum(a * (np.log(a) - np.log(b)), 1)))
+
+
+def _train_one(m, feat_cols, target_cols, name):
+    sub = m.dropna(subset=["self_" + c for c in target_cols]).copy()  # con historial rolling
+    tgt, tot = _norm_df(sub, target_cols)
+    keep = tot.values > 0
+    sub = sub[keep]; Y = tgt[keep].to_numpy(dtype=np.float32)
+    base = sub[["self_" + c for c in target_cols]].to_numpy(dtype=np.float32)
+    base = base / np.clip(base.sum(1, keepdims=True), 1e-9, None)
+    n = len(sub); idx = RNG.permutation(n); cut = int(n * 0.8); tr, te = idx[:cut], idx[cut:]
+    Xtr, Xte = sub[feat_cols].iloc[tr], sub[feat_cols].iloc[te]
+    vm = np.zeros(len(tr), bool); vm[RNG.permutation(len(tr))[:int(len(tr) * 0.12)]] = True
+    print(f"\n=== Modelo {name}: {n} (test {len(te)}) | {len(feat_cols)} features ===")
+    preds = []
+    for j in range(Y.shape[1]):
+        mdl = lgb.LGBMRegressor(n_estimators=700, learning_rate=0.025, num_leaves=31,
+                                subsample=0.8, colsample_bytree=0.5, min_child_samples=40, verbose=-1)
+        mdl.fit(Xtr[~vm], Y[tr][~vm, j], eval_set=[(Xtr[vm], Y[tr][vm, j])],
+                callbacks=[lgb.early_stopping(50, verbose=False)])
+        preds.append(np.clip(mdl.predict(Xte), 0, None))
+        mdl.booster_.save_model(str(OUTDIR / f"model_{name}__{target_cols[j]}.txt"))
+    P = np.vstack(preds).T; P = P / np.clip(P.sum(1, keepdims=True), 1e-9, None)
+    mae = lambda a, b: float(np.mean(np.abs(a - b)))
+    print(f"  modelo  : MAE={mae(Y[te], P):.4f}  KL={_kl(Y[te], P):.4f}")
+    print(f"  baseline: MAE={mae(Y[te], base[te]):.4f}  KL={_kl(Y[te], base[te]):.4f}")
+
+
+def _train_abs(m, feat_cols, target_cols, name):
+    """Regresión de VALORES ABSOLUTOS (no shares). Eval MAE/RMSE vs promedio propio."""
+    sub = m.dropna(subset=["self_" + c for c in target_cols]).copy()
+    Y = sub[target_cols].to_numpy(dtype=np.float32)
+    base = sub[["self_" + c for c in target_cols]].to_numpy(dtype=np.float32)
+    n = len(sub); idx = RNG.permutation(n); cut = int(n * 0.8); tr, te = idx[:cut], idx[cut:]
+    Xtr, Xte = sub[feat_cols].iloc[tr], sub[feat_cols].iloc[te]
+    vm = np.zeros(len(tr), bool); vm[RNG.permutation(len(tr))[:int(len(tr) * 0.12)]] = True
+    print(f"\n=== Modelo {name} (xT absoluto): {n} (test {len(te)}) ===")
+    preds = []
+    for j in range(Y.shape[1]):
+        mdl = lgb.LGBMRegressor(n_estimators=700, learning_rate=0.025, num_leaves=31,
+                                subsample=0.8, colsample_bytree=0.5, min_child_samples=40, verbose=-1)
+        mdl.fit(Xtr[~vm], Y[tr][~vm, j], eval_set=[(Xtr[vm], Y[tr][vm, j])],
+                callbacks=[lgb.early_stopping(50, verbose=False)])
+        preds.append(np.clip(mdl.predict(Xte), 0, None))
+        mdl.booster_.save_model(str(OUTDIR / f"model_{name}__{target_cols[j]}.txt"))
+    P = np.vstack(preds).T
+    mae = lambda a, b: float(np.mean(np.abs(a - b)))
+    rmse = lambda a, b: float(np.sqrt(np.mean((a - b) ** 2)))
+    print(f"  modelo  : MAE={mae(Y[te], P):.4f}  RMSE={rmse(Y[te], P):.4f}")
+    print(f"  baseline: MAE={mae(Y[te], base[te]):.4f}  RMSE={rmse(Y[te], base[te]):.4f}")
+    print(f"  (xT medio real por pasillo: {np.round(Y[te].mean(0), 3)})")
+
+
+def main():
+    import argparse
+    ap = argparse.ArgumentParser(); ap.add_argument("--leagues", nargs="*", default=None); a = ap.parse_args()
+    df = pd.read_parquet(DATA)
+    if a.leagues:
+        df = df[df["Competencia"].isin(a.leagues)].copy()
+    blk = (df.assign(_b=df[DEF].sum(axis=1) > 0).groupby("Competencia")["_b"].mean())
+    df = df[df["Competencia"].isin(blk[blk > 0.5].index)].copy()
+    print("dataset:", len(df), "filas |", df["Competencia"].nunique(), "ligas |", df["matchId"].nunique(), "partidos")
+    m, feat = _assemble(df)
+    _train_one(m, feat, DEF, "bloques")
+    _train_one(m, feat, ATK, "pasillos")
+    _train_abs(m, feat, XTLANE, "peligro_pasillo")
+
+
+if __name__ == "__main__":
+    main()

src/racing_reports/reports/matchup_models.py

@@ -0,0 +1,129 @@
+"""Predicción de cruce A-vs-B a partir de los modelos LightGBM entrenados
+(bloque defensivo, pasillo de ataque y xT por pasillo).
+
+Para cada equipo usa su vector de features rolling 'a la fecha' (precalculado en
+``team_features_latest.parquet``) y arma la fila del enfrentamiento: lado propio del
+equipo + lado rival del oponente. Devuelve, para A y para B:
+  - dist. de bloque defensivo  (alto / medio / bajo)   — cómo va a defender
+  - dist. de ataque por pasillo (izq / centro / der)    — por dónde va a atacar
+  - xT absoluto por pasillo      (izq / centro / der)    — peligro esperado por pasillo
+"""
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from racing_reports import vendor_env
+
+_MODELDIR = vendor_env.DATA_DIR / "modeling"
+_FEATS = _MODELDIR / "team_features_latest.parquet"
+_FEATCOLS = _MODELDIR / "matchup_feat_cols.json"
+
+DEF = ["def_H", "def_M", "def_L"]            # alto, medio, bajo
+ATK = ["atk_Der", "atk_Centro", "atk_Izq"]   # derecha, centro, izquierda
+XT = ["xt_lane_Der", "xt_lane_Centro", "xt_lane_Izq"]
+LANES = ["Izq", "Centro", "Der"]
+
+_LOCK = threading.Lock()
+_CACHE: dict = {}
+
+
+def _load():
+    with _LOCK:
+        if _CACHE:
+            return _CACHE
+        if not _FEATS.exists() or not _FEATCOLS.exists():
+            _CACHE["ok"] = False
+            return _CACHE
+        import lightgbm as lgb
+        feats = pd.read_parquet(_FEATS)
+        feat_cols = json.loads(_FEATCOLS.read_text(encoding="utf-8"))
+        boosters = {}
+        for name, cols in (("bloques", DEF), ("pasillos", ATK), ("peligro_pasillo", XT)):
+            paths = [_MODELDIR / f"model_{name}__{c}.txt" for c in cols]
+            if all(p.exists() for p in paths):
+                boosters[name] = [lgb.Booster(model_file=str(p)) for p in paths]
+        _CACHE.update(ok=bool(boosters) and len(feats) > 0, feats=feats,
+                      feat_cols=feat_cols, boosters=boosters)
+        return _CACHE
+
+
+def available() -> bool:
+    return bool(_load().get("ok"))
+
+
+def _row_for(feats: pd.DataFrame, league: str, season: str | None, team: str):
+    """Última fila de features del equipo (por nombre) en la liga/temporada."""
+    q = feats[feats["Competencia"].astype(str) == str(league)]
+    q = q[q["TeamName"].astype(str).str.casefold() == str(team).casefold()]
+    if season:
+        qs = q[q["Temporada"].astype(str) == str(season)]
+        q = qs if not qs.empty else q
+    if q.empty:
+        return None
+    return q.sort_values("fecha").iloc[-1]
+
+
+def _build_feature_row(self_r, opp_r, is_home: bool, feat_cols: list[str]) -> np.ndarray:
+    """Arma el vector en el orden exacto de feat_cols para un equipo (self) vs su rival (opp)."""
+    vals = {}
+    for c in feat_cols:
+        if c == "is_home":
+            vals[c] = 1.0 if is_home else 0.0
+        elif c == "elo_diff":
+            vals[c] = float(self_r.get("self_elo", 1500.0)) - float(opp_r.get("self_elo", 1500.0))
+        elif c.startswith("form_"):
+            vals[c] = 1.0 if str(self_r.get("formation")) == c[len("form_"):] else 0.0
+        elif c.startswith("opp_"):
+            base = c[len("opp_"):]
+            vals[c] = float(opp_r.get(base)) if pd.notna(opp_r.get(base)) else np.nan
+        else:  # self / selfH / selfA
+            vals[c] = float(self_r.get(c)) if pd.notna(self_r.get(c)) else np.nan
+    return np.array([vals[c] for c in feat_cols], dtype=np.float64).reshape(1, -1)
+
+
+def _predict_side(boosters, X, dist: bool):
+    p = np.array([b.predict(X)[0] for b in boosters], dtype=float)
+    p = np.clip(p, 0, None)
+    if dist:
+        s = p.sum()
+        p = p / s if s > 0 else np.full_like(p, 1 / len(p))
+    return p
+
+
+def predict_matchup(league: str, season: str | None, team_a: str, team_b: str,
+                    a_is_home: bool = True) -> dict | None:
+    """Predicción del enfrentamiento. Devuelve dict con A y B, o None si faltan modelos
+    o no se encuentra alguno de los equipos."""
+    c = _load()
+    if not c.get("ok"):
+        return None
+    feats, feat_cols, B = c["feats"], c["feat_cols"], c["boosters"]
+    if not all(k in B for k in ("bloques", "pasillos", "peligro_pasillo")):
+        return None
+    ra = _row_for(feats, league, season, team_a)
+    rb = _row_for(feats, league, season, team_b)
+    if ra is None or rb is None:
+        return {"error": f"Sin datos del modelo para "
+                + (team_a if ra is None else team_b) + f" en {league} {season or ''}".strip()}
+
+    def side(self_r, opp_r, is_home):
+        X = _build_feature_row(self_r, opp_r, is_home, feat_cols)
+        defb = _predict_side(B["bloques"], X, dist=True)      # H, M, L
+        atk = _predict_side(B["pasillos"], X, dist=True)      # Der, Centro, Izq
+        xt = _predict_side(B["peligro_pasillo"], X, dist=False)
+        return {
+            "bloque": {"alto": float(defb[0]), "medio": float(defb[1]), "bajo": float(defb[2])},
+            "pasillo": {"Der": float(atk[0]), "Centro": float(atk[1]), "Izq": float(atk[2])},
+            "xt": {"Der": float(xt[0]), "Centro": float(xt[1]), "Izq": float(xt[2])},
+        }
+
+    return {
+        "league": league, "season": season, "team_a": team_a, "team_b": team_b,
+        "a": side(ra, rb, a_is_home),
+        "b": side(rb, ra, not a_is_home),
+    }

src/racing_reports/reports/matchup_render.py

@@ -0,0 +1,95 @@
+"""Dibujo de la predicción de cruce sobre canchas:
+  - Ataque por pasillo: media cancha con 3 pasillos (Izq/Centro/Der), % y xT.
+  - Bloque defensivo: el 75% defensivo dividido en bajo (verde, cerca del arco propio),
+    medio (naranja) y alto (rojo), sombreado según el % previsto.
+Devuelve figuras de matplotlib (una por cancha)."""
+from __future__ import annotations
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+from mplsoccer import VerticalPitch
+
+PITCH = dict(pitch_type="opta", line_color="#cdd6e6", linewidth=1.2)
+GREEN, ORANGE, RED = "#2bb673", "#f5912b", "#e0392b"
+LANE_C = "#2E74D6"
+TEXT = "#10243f"
+
+
+def _pitch(ax, half=False):
+    p = VerticalPitch(half=half, pad_top=2, pitch_color="none", **PITCH)
+    p.draw(ax=ax)
+    return p
+
+
+def attack_fig(side: dict, team: str) -> plt.Figure:
+    """Media cancha de ataque con los 3 pasillos sombreados por % y rotulados con % y xT."""
+    fig, ax = plt.subplots(figsize=(4.2, 5.2))
+    fig.patch.set_facecolor("white")
+    p = _pitch(ax, half=True)
+    pas, xt = side["pasillo"], side["xt"]
+    mx = max(pas.values()) or 1.0
+    # x = ancho (0-100). Izquierda a la izquierda del espectador.
+    bounds = [(0, 33.33, "Der"), (33.33, 66.67, "Centro"), (66.67, 100, "Izq")]
+    for x0, x1, lane in bounds:
+        frac = pas[lane]
+        ax.fill_betweenx([50, 100], x0, x1, color=LANE_C, alpha=0.12 + 0.55 * frac / mx, zorder=0.5)
+        ax.plot([x0, x0], [50, 100], color="#9fb0c9", lw=1, ls="--", zorder=1)
+        ax.text((x0 + x1) / 2, 88, f"{frac*100:.0f}%", ha="center", va="center",
+                fontsize=17, fontweight="bold", color=TEXT, zorder=3)
+        ax.text((x0 + x1) / 2, 79, lane, ha="center", va="center", fontsize=10.5, color="#42546e", zorder=3)
+        ax.text((x0 + x1) / 2, 73, f"xT {xt[lane]:.2f}", ha="center", va="center",
+                fontsize=9, color="#5a6b85", zorder=3)
+    ax.set_title(f"{team}\nPor dónde ataca", fontsize=12.5, fontweight="bold", color=TEXT, pad=6)
+    fig.tight_layout()
+    return fig
+
+
+def defense_fig(side: dict, team: str) -> plt.Figure:
+    """Cancha con el 75% defensivo en 3 bandas: bajo (verde) cerca del arco propio,
+    medio (naranja) y alto (rojo); sombreado por % previsto."""
+    fig, ax = plt.subplots(figsize=(4.2, 5.2))
+    fig.patch.set_facecolor("white")
+    _pitch(ax, half=False)
+    blo = side["bloque"]
+    mx = max(blo.values()) or 1.0
+    # arco propio abajo (y=0). Bandas a lo largo: bajo [0-25], medio [25-50], alto [50-75].
+    bands = [(0, 25, "bajo", GREEN), (25, 50, "medio", ORANGE), (50, 75, "alto", RED)]
+    for y0, y1, name, col in bands:
+        frac = blo[name]
+        ax.fill_between([0, 100], y0, y1, color=col, alpha=0.18 + 0.6 * frac / mx, zorder=0.5)
+        ax.plot([0, 100], [y1, y1], color="#9fb0c9", lw=0.8, ls="--", zorder=1)
+        ax.text(50, (y0 + y1) / 2 + 3.5, f"{frac*100:.0f}%", ha="center", va="center",
+                fontsize=16, fontweight="bold", color=TEXT, zorder=3)
+        ax.text(50, (y0 + y1) / 2 - 4, f"Bloque {name}", ha="center", va="center",
+                fontsize=10.5, color="#33455f", zorder=3)
+    ax.annotate("arco propio", (50, 1.5), ha="center", va="bottom", fontsize=8.5,
+                color="#7a889e", zorder=3)
+    ax.set_title(f"{team}\nCómo defiende", fontsize=12.5, fontweight="bold", color=TEXT, pad=6)
+    fig.tight_layout()
+    return fig
+
+
+def insight(pred: dict) -> str:
+    """Lectura breve del cruce a partir de las predicciones de A y B."""
+    a, b = pred["a"], pred["b"]
+    ta, tb = pred["team_a"], pred["team_b"]
+    lane_es = {"Izq": "izquierda", "Centro": "el centro", "Der": "derecha"}
+    blo_max = lambda s: max(s["bloque"], key=s["bloque"].get)
+    xt_max = lambda s: max(s["xt"], key=s["xt"].get)
+    out = []
+    # quién genera más peligro
+    xa, xb = sum(a["xt"].values()), sum(b["xt"].values())
+    mas, men = (ta, tb) if xa >= xb else (tb, ta)
+    out.append(f"El modelo espera más peligro total de <b>{mas}</b> ({max(xa,xb):.2f} vs {min(xa,xb):.2f} de xT).")
+    # pasillo principal de cada uno
+    out.append(f"<b>{ta}</b> apuntaría sobre todo por {lane_es[xt_max(a)]} "
+               f"(xT {a['xt'][xt_max(a)]:.2f}); <b>{tb}</b>, por {lane_es[xt_max(b)]} "
+               f"(xT {b['xt'][xt_max(b)]:.2f}).")
+    # bloque defensivo de cada uno
+    out.append(f"Defensivamente, <b>{ta}</b> se pararía mayormente en bloque {blo_max(a)} "
+               f"y <b>{tb}</b> en bloque {blo_max(b)}.")
+    # coincidencia de pasillo (ambos cargan el mismo lado)
+    if xt_max(a) == xt_max(b) and xt_max(a) != "Centro":
+        out.append(f"Ojo: ambos cargan el mismo sector ({lane_es[xt_max(a)]}), va a ser una zona disputada.")
+    return " ".join(out)

src/racing_reports/reports/pre_match.py

@@ -191,6 +191,53 @@ def generate(
             output_path=out_path,
         )
 
+    # --- Predicción de cruce (modelos LightGBM): canchas de ataque/defensa + insight ---
+    try:
+        from racing_reports.reports import matchup_models, matchup_render
+        from racing_reports.reports.common import save_figure
+
+        if matchup_models.available():
+            pred = matchup_models.predict_matchup(league, season, home_name, away_name, a_is_home=True)
+            if pred and "error" not in pred:
+                sec = "Predicción del modelo (cruce)"
+                fig_specs = [
+                    ("modelo_ataque_home", f"Por dónde ataca — {home_name}", matchup_render.attack_fig(pred["a"], home_name)),
+                    ("modelo_defensa_home", f"Cómo defiende — {home_name}", matchup_render.defense_fig(pred["a"], home_name)),
+                    ("modelo_ataque_away", f"Por dónde ataca — {away_name}", matchup_render.attack_fig(pred["b"], away_name)),
+                    ("modelo_defensa_away", f"Cómo defiende — {away_name}", matchup_render.defense_fig(pred["b"], away_name)),
+                ]
+                for nm, ttl, fig in fig_specs:
+                    png_path, svg_path = save_figure(fig, out_path.parent, nm)
+                    figures.append(FigureArtifact(name=nm, title=ttl, section=sec,
+                                                  png_path=png_path, svg_path=svg_path))
+                # tabla resumen con números + insight
+                rows = []
+                for side, team in ((pred["a"], home_name), (pred["b"], away_name)):
+                    rows.append({
+                        "Equipo": team,
+                        "Bloque alto %": round(side["bloque"]["alto"] * 100),
+                        "Bloque medio %": round(side["bloque"]["medio"] * 100),
+                        "Bloque bajo %": round(side["bloque"]["bajo"] * 100),
+                        "Ataque Izq %": round(side["pasillo"]["Izq"] * 100),
+                        "Ataque Centro %": round(side["pasillo"]["Centro"] * 100),
+                        "Ataque Der %": round(side["pasillo"]["Der"] * 100),
+                        "xT Izq": round(side["xt"]["Izq"], 3),
+                        "xT Centro": round(side["xt"]["Centro"], 3),
+                        "xT Der": round(side["xt"]["Der"], 3),
+                    })
+                df_pred = pd.DataFrame(rows)
+                csv_path = out_path.parent / "modelo_cruce.csv"
+                df_pred.to_csv(csv_path, index=False)
+                preview = (f"<p style='margin-bottom:.6rem'>{matchup_render.insight(pred)}</p>"
+                           + df_pred.to_html(index=False, escape=True))
+                tables.append(TableArtifact(
+                    name="modelo_cruce", title="Predicción del modelo — resumen del cruce",
+                    section=sec, csv_path=csv_path, preview_html=preview))
+            elif pred and "error" in pred:
+                warnings.append("Modelo de cruce: " + str(pred["error"]))
+    except Exception as exc:  # nunca romper el reporte por la predicción
+        warnings.append(f"Predicción del modelo no disponible: {exc}")
+
     return ReportBundle(
         report_type="pre_match",
         html_path=Path(result_path),

vendor/data/modeling/matchup_feat_cols.json

@@ -0,0 +1 @@
+["self_elo", "self_def_H", "self_def_M", "self_def_L", "self_atk_Der", "self_atk_Centro", "self_atk_Izq", "self_offxt_H_Der", "self_offxt_H_Centro", "self_offxt_H_Izq", "self_offxt_M_Der", "self_offxt_M_Centro", "self_offxt_M_Izq", "self_offxt_L_Der", "self_offxt_L_Centro", "self_offxt_L_Izq", "self_defxt_H_Der", "self_defxt_H_Centro", "self_defxt_H_Izq", "self_defxt_M_Der", "self_defxt_M_Centro", "self_defxt_M_Izq", "self_defxt_L_Der", "self_defxt_L_Centro", "self_defxt_L_Izq", "self_sh_buildup", "self_sh_counter", "self_sh_direct", "self_sh_setpiece", "self_sh_recovery", "self_sh_progr", "self_cross_pct", "self_pct_long", "self_pct_short", "self_pct_pass_ok", "self_n_attacks", "self_xt_total", "self_xg_total", "self_xt_per_attack", "self_n_seq", "self_n_pass", "self_n_shots", "self_avg_x", "self_avg_y", "self_share_opp_half", "self_recovery_height", "self_n_progr", "self_goals_for", "self_goals_against", "self_win", "self_xt_lane_Der", "self_xt_lane_Centro", "self_xt_lane_Izq", "selfH_def_H", "selfH_def_M", "selfH_def_L", "selfH_atk_Der", "selfH_atk_Centro", "selfH_atk_Izq", "selfH_offxt_H_Der", "selfH_offxt_H_Centro", "selfH_offxt_H_Izq", "selfH_offxt_M_Der", "selfH_offxt_M_Centro", "selfH_offxt_M_Izq", "selfH_offxt_L_Der", "selfH_offxt_L_Centro", "selfH_offxt_L_Izq", "selfH_defxt_H_Der", "selfH_defxt_H_Centro", "selfH_defxt_H_Izq", "selfH_defxt_M_Der", "selfH_defxt_M_Centro", "selfH_defxt_M_Izq", "selfH_defxt_L_Der", "selfH_defxt_L_Centro", "selfH_defxt_L_Izq", "selfH_sh_buildup", "selfH_sh_counter", "selfH_sh_direct", "selfH_sh_setpiece", "selfH_sh_recovery", "selfH_sh_progr", "selfH_cross_pct", "selfH_pct_long", "selfH_pct_short", "selfH_pct_pass_ok", "selfH_n_attacks", "selfH_xt_total", "selfH_xg_total", "selfH_xt_per_attack", "selfH_n_seq", "selfH_n_pass", "selfH_n_shots", "selfH_avg_x", "selfH_avg_y", "selfH_share_opp_half", "selfH_recovery_height", "selfH_n_progr", "selfH_goals_for", "selfH_goals_against", "selfH_win", "selfH_xt_lane_Der", "selfH_xt_lane_Centro", "selfH_xt_lane_Izq", "selfA_def_H", "selfA_def_M", "selfA_def_L", "selfA_atk_Der", "selfA_atk_Centro", "selfA_atk_Izq", "selfA_offxt_H_Der", "selfA_offxt_H_Centro", "selfA_offxt_H_Izq", "selfA_offxt_M_Der", "selfA_offxt_M_Centro", "selfA_offxt_M_Izq", "selfA_offxt_L_Der", "selfA_offxt_L_Centro", "selfA_offxt_L_Izq", "selfA_defxt_H_Der", "selfA_defxt_H_Centro", "selfA_defxt_H_Izq", "selfA_defxt_M_Der", "selfA_defxt_M_Centro", "selfA_defxt_M_Izq", "selfA_defxt_L_Der", "selfA_defxt_L_Centro", "selfA_defxt_L_Izq", "selfA_sh_buildup", "selfA_sh_counter", "selfA_sh_direct", "selfA_sh_setpiece", "selfA_sh_recovery", "selfA_sh_progr", "selfA_cross_pct", "selfA_pct_long", "selfA_pct_short", "selfA_pct_pass_ok", "selfA_n_attacks", "selfA_xt_total", "selfA_xg_total", "selfA_xt_per_attack", "selfA_n_seq", "selfA_n_pass", "selfA_n_shots", "selfA_avg_x", "selfA_avg_y", "selfA_share_opp_half", "selfA_recovery_height", "selfA_n_progr", "selfA_goals_for", "selfA_goals_against", "selfA_win", "selfA_xt_lane_Der", "selfA_xt_lane_Centro", "selfA_xt_lane_Izq", "opp_self_elo", "opp_self_def_H", "opp_self_def_M", "opp_self_def_L", "opp_self_atk_Der", "opp_self_atk_Centro", "opp_self_atk_Izq", "opp_self_offxt_H_Der", "opp_self_offxt_H_Centro", "opp_self_offxt_H_Izq", "opp_self_offxt_M_Der", "opp_self_offxt_M_Centro", "opp_self_offxt_M_Izq", "opp_self_offxt_L_Der", "opp_self_offxt_L_Centro", "opp_self_offxt_L_Izq", "opp_self_defxt_H_Der", "opp_self_defxt_H_Centro", "opp_self_defxt_H_Izq", "opp_self_defxt_M_Der", "opp_self_defxt_M_Centro", "opp_self_defxt_M_Izq", "opp_self_defxt_L_Der", "opp_self_defxt_L_Centro", "opp_self_defxt_L_Izq", "opp_self_sh_buildup", "opp_self_sh_counter", "opp_self_sh_direct", "opp_self_sh_setpiece", "opp_self_sh_recovery", "opp_self_sh_progr", "opp_self_cross_pct", "opp_self_pct_long", "opp_self_pct_short", "opp_self_pct_pass_ok", "opp_self_n_attacks", "opp_self_xt_total", "opp_self_xg_total", "opp_self_xt_per_attack", "opp_self_n_seq", "opp_self_n_pass", "opp_self_n_shots", "opp_self_avg_x", "opp_self_avg_y", "opp_self_share_opp_half", "opp_self_recovery_height", "opp_self_n_progr", "opp_self_goals_for", "opp_self_goals_against", "opp_self_win", "opp_self_xt_lane_Der", "opp_self_xt_lane_Centro", "opp_self_xt_lane_Izq", "opp_selfH_def_H", "opp_selfH_def_M", "opp_selfH_def_L", "opp_selfH_atk_Der", "opp_selfH_atk_Centro", "opp_selfH_atk_Izq", "opp_selfH_offxt_H_Der", "opp_selfH_offxt_H_Centro", "opp_selfH_offxt_H_Izq", "opp_selfH_offxt_M_Der", "opp_selfH_offxt_M_Centro", "opp_selfH_offxt_M_Izq", "opp_selfH_offxt_L_Der", "opp_selfH_offxt_L_Centro", "opp_selfH_offxt_L_Izq", "opp_selfH_defxt_H_Der", "opp_selfH_defxt_H_Centro", "opp_selfH_defxt_H_Izq", "opp_selfH_defxt_M_Der", "opp_selfH_defxt_M_Centro", "opp_selfH_defxt_M_Izq", "opp_selfH_defxt_L_Der", "opp_selfH_defxt_L_Centro", "opp_selfH_defxt_L_Izq", "opp_selfH_sh_buildup", "opp_selfH_sh_counter", "opp_selfH_sh_direct", "opp_selfH_sh_setpiece", "opp_selfH_sh_recovery", "opp_selfH_sh_progr", "opp_selfH_cross_pct", "opp_selfH_pct_long", "opp_selfH_pct_short", "opp_selfH_pct_pass_ok", "opp_selfH_n_attacks", "opp_selfH_xt_total", "opp_selfH_xg_total", "opp_selfH_xt_per_attack", "opp_selfH_n_seq", "opp_selfH_n_pass", "opp_selfH_n_shots", "opp_selfH_avg_x", "opp_selfH_avg_y", "opp_selfH_share_opp_half", "opp_selfH_recovery_height", "opp_selfH_n_progr", "opp_selfH_goals_for", "opp_selfH_goals_against", "opp_selfH_win", "opp_selfH_xt_lane_Der", "opp_selfH_xt_lane_Centro", "opp_selfH_xt_lane_Izq", "opp_selfA_def_H", "opp_selfA_def_M", "opp_selfA_def_L", "opp_selfA_atk_Der", "opp_selfA_atk_Centro", "opp_selfA_atk_Izq", "opp_selfA_offxt_H_Der", "opp_selfA_offxt_H_Centro", "opp_selfA_offxt_H_Izq", "opp_selfA_offxt_M_Der", "opp_selfA_offxt_M_Centro", "opp_selfA_offxt_M_Izq", "opp_selfA_offxt_L_Der", "opp_selfA_offxt_L_Centro", "opp_selfA_offxt_L_Izq", "opp_selfA_defxt_H_Der", "opp_selfA_defxt_H_Centro", "opp_selfA_defxt_H_Izq", "opp_selfA_defxt_M_Der", "opp_selfA_defxt_M_Centro", "opp_selfA_defxt_M_Izq", "opp_selfA_defxt_L_Der", "opp_selfA_defxt_L_Centro", "opp_selfA_defxt_L_Izq", "opp_selfA_sh_buildup", "opp_selfA_sh_counter", "opp_selfA_sh_direct", "opp_selfA_sh_setpiece", "opp_selfA_sh_recovery", "opp_selfA_sh_progr", "opp_selfA_cross_pct", "opp_selfA_pct_long", "opp_selfA_pct_short", "opp_selfA_pct_pass_ok", "opp_selfA_n_attacks", "opp_selfA_xt_total", "opp_selfA_xg_total", "opp_selfA_xt_per_attack", "opp_selfA_n_seq", "opp_selfA_n_pass", "opp_selfA_n_shots", "opp_selfA_avg_x", "opp_selfA_avg_y", "opp_selfA_share_opp_half", "opp_selfA_recovery_height", "opp_selfA_n_progr", "opp_selfA_goals_for", "opp_selfA_goals_against", "opp_selfA_win", "opp_selfA_xt_lane_Der", "opp_selfA_xt_lane_Centro", "opp_selfA_xt_lane_Izq", "is_home", "elo_diff", "form_4231", "form_4231.0", "form_433", "form_442", "form_3421", "form_433.0", "form_442.0", "form_3421.0", "form_352", "form_4141.0", "form_343", "form_4141"]

vendor/data/modeling/team_features_latest.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d5a3e60860e442bab0870bad04bebfded42d96dd9a039d64bcabc3b28f759703
+size 1604608