aria-code 0.52.0__py3-none-any.whl

aria_code/packages/quant_engine/sports/ml_model.py

@@ -0,0 +1,377 @@
+"""
+sports/ml_model.py — 足球 XGBoost 预测模型
+=============================================
+从 tracker.py 积累的已结算预测记录中学习，
+与 Dixon-Coles 规则模型进行 A/B Brier Score 对比。
+
+触发逻辑（原始设计）:
+  - 首次训练: ≥20 条已结算记录（Elo + 实际结果）
+  - 自动重训: 每新增 10 条记录触发一次
+  - 预测时:   优先使用 ML 模型，数据不足则 fallback → DC
+
+⚠️ 现状：本模块目前**未接入预测路径，这是有意的**。
+predictor.py 只跑 Elo+DC+Form+H2H（见其 model_tag），从不调用
+get_football_ml()。2026-08-19 复查时一度把它当成"死代码"准备删除，查了
+训练产物才发现真相——它不是忘了接线，是 A/B 输给了基线：
+
+    ~/.arthera/football_ml_report.json  (trained_at 2026-06-15)
+      n_samples      25
+      cv_brier_mean  1.0446   ← 本模型
+      dc_brier       0.3251   ← Dixon-Coles 基线
+      improvement   -0.7196   ← 负数 = 更差
+
+Brier 越低越好，ML 比基线差约 3.2 倍。25 条样本喂 9 维特征的 XGBoost，
+1.04 的 CV Brier 正是过拟合的典型表现（3 分类 Brier 上界 2.0，随机猜测
+约 0.67，本模型比随机还差）。所以**不接入是正确决定**，不是遗漏。
+
+要重新评估的前提是样本量先上来（经验上 9 维特征至少需要几百条已结算记录，
+25 条差了一个数量级）。届时重跑 train() 看 improvement 是否转正，
+再决定要不要在 predictor.py 里接上。
+
+保留本文件的理由：删掉会一并丢失"ML 在此样本量下输给 DC"这个结论，
+下一个人只会重新实现一遍再重新发现一次。
+
+特征向量 (9维):
+  elo_diff, elo_home, elo_away,
+  lambda_home, lambda_away, lambda_ratio,
+  league_avg, elo_diff_abs_scaled, is_high_gap
+
+标签: 0=away, 1=draw, 2=home（XGBoost 多分类）
+
+持久化:
+  ~/.arthera/football_ml_model.pkl
+  ~/.arthera/football_ml_report.json
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import pickle
+import time
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+from aria_code.packages.aria_core.paths import aria_home
+
+logger = logging.getLogger(__name__)
+
+_MODEL_PATH  = aria_home() / "football_ml_model.pkl"
+_REPORT_PATH = aria_home() / "football_ml_report.json"
+_MIN_TRAIN   = 20
+_RETRAIN_EVERY = 10
+
+try:
+    from xgboost import XGBClassifier
+    _HAS_XGB = True
+except ImportError:
+    try:
+        import lightgbm as lgb
+        _HAS_XGB = False
+        _HAS_LGB = True
+    except ImportError:
+        _HAS_XGB = False
+        _HAS_LGB = False
+
+try:
+    from sklearn.preprocessing import StandardScaler
+    from sklearn.model_selection import cross_val_score, StratifiedKFold
+    _HAS_SK = True
+except ImportError:
+    _HAS_SK = False
+
+
+# ── 特征提取 ──────────────────────────────────────────────────────────────────
+
+_FEATURE_NAMES = [
+    "elo_diff", "elo_home", "elo_away",
+    "lambda_home", "lambda_away", "lambda_ratio",
+    "league_avg", "elo_gap_scaled", "is_high_gap",
+]
+
+
+def _extract_features(record: Dict) -> Optional[np.ndarray]:
+    """从一条预测记录提取特征向量，缺字段返回 None。"""
+    elo_h = record.get("home_elo")
+    elo_a = record.get("away_elo")
+    lh    = record.get("lambda_home")
+    la    = record.get("lambda_away")
+    avg   = record.get("league_avg", 1.35)
+
+    if any(v is None for v in [elo_h, elo_a, lh, la]):
+        return None
+
+    elo_h, elo_a, lh, la, avg = float(elo_h), float(elo_a), float(lh), float(la), float(avg)
+    diff = elo_h - elo_a
+
+    return np.array([
+        diff,                           # Elo 差
+        elo_h,                          # 主队 Elo
+        elo_a,                          # 客队 Elo
+        lh,                             # 主队期望进球
+        la,                             # 客队期望进球
+        lh / (la + 1e-6),              # λ 比值（反映实力差距）
+        avg,                            # 赛事场均进球
+        abs(diff) / 400.0,             # 标准化 Elo 差（400=1个标准差）
+        1.0 if abs(diff) > 200 else 0.0,  # 悬殊场次标志
+    ], dtype=np.float32)
+
+
+def _result_to_label(result: str) -> int:
+    """home=2, draw=1, away=0"""
+    return {"home": 2, "draw": 1, "away": 0}.get(result, -1)
+
+
+# ── 训练器 ────────────────────────────────────────────────────────────────────
+
+class FootballMLModel:
+    """
+    足球 XGBoost/LightGBM 预测器。
+
+    用法:
+        m = FootballMLModel.load_or_train()
+        if m.is_ready:
+            p = m.predict(record)   # {"home_win": 0.72, "draw": 0.18, "away_win": 0.10}
+    """
+
+    def __init__(self):
+        self._model   = None
+        self._scaler  = None
+        self._report: Dict = {}
+        self._n_trained = 0
+
+    @property
+    def is_ready(self) -> bool:
+        return self._model is not None
+
+    # ── 训练 ──────────────────────────────────────────────────────────────────
+
+    def train(self, records: Optional[List[Dict]] = None) -> Dict:
+        """
+        从 tracker 记录中训练。records 为 None 时自动从磁盘加载。
+        返回训练报告 dict。
+        """
+        if not (_HAS_XGB or _HAS_LGB):
+            return {"error": "pip install xgboost 或 lightgbm 后重试"}
+        if not _HAS_SK:
+            return {"error": "pip install scikit-learn 后重试"}
+
+        if records is None:
+            records = _load_settled_records()
+
+        # 过滤出含完整特征的记录
+        X_rows, y_rows = [], []
+        for r in records:
+            label = _result_to_label(r.get("result", ""))
+            if label == -1:
+                continue
+            feat = _extract_features(r)
+            if feat is None:
+                continue
+            X_rows.append(feat)
+            y_rows.append(label)
+
+        n = len(X_rows)
+        if n < _MIN_TRAIN:
+            return {"status": "waiting", "n": n, "need": _MIN_TRAIN,
+                    "message": f"需要 {_MIN_TRAIN} 条完整记录，当前 {n} 条"}
+
+        X = np.array(X_rows)
+        y = np.array(y_rows)
+
+        # 标准化
+        scaler = StandardScaler()
+        X_s = scaler.fit_transform(X)
+
+        # 模型
+        if _HAS_XGB:
+            model = XGBClassifier(
+                n_estimators=200, max_depth=4, learning_rate=0.05,
+                subsample=0.8, colsample_bytree=0.8,
+                reg_alpha=0.1, reg_lambda=0.5,
+                objective="multi:softprob", num_class=3,
+                eval_metric="mlogloss", use_label_encoder=False,
+                random_state=42, verbosity=0,
+            )
+        else:
+            import lightgbm as lgb
+            model = lgb.LGBMClassifier(
+                n_estimators=200, max_depth=4, learning_rate=0.05,
+                num_class=3, objective="multiclass",
+                feature_fraction=0.8, bagging_fraction=0.8,
+                reg_alpha=0.1, reg_lambda=0.5,
+                verbose=-1, random_state=42,
+            )
+
+        # 走步交叉验证（时序感知：按时间顺序分折）
+        cv_briers = _walk_forward_cv(model, X_s, y, n_splits=min(5, n // 4))
+
+        # 全量重训练
+        model.fit(X_s, y)
+
+        self._model   = model
+        self._scaler  = scaler
+        self._n_trained = n
+
+        # CV Brier vs DC Brier（走步验证，公平对比）
+        dc_brier   = _dc_brier_from_records(records[:n])
+        cv_mean    = float(np.mean(cv_briers)) if cv_briers else None
+        # improvement = DC - CV_ML（正值表示 ML 更准，使用 CV 避免训练集过拟合）
+        improvement = round(dc_brier - cv_mean, 4) if cv_mean is not None else None
+
+        lib = "XGBoost" if _HAS_XGB else "LightGBM"
+        self._report = {
+            "lib":           lib,
+            "n_samples":     int(n),
+            "cv_brier_mean": round(cv_mean, 4) if cv_mean is not None else None,
+            "cv_brier_std":  round(float(np.std(cv_briers)), 4) if cv_briers else None,
+            "dc_brier":      round(float(dc_brier), 4),
+            "improvement":   improvement,  # >0 = ML 更准（基于 CV，可信）
+            "trained_at":    time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "feature_names": _FEATURE_NAMES,
+        }
+
+        _save_model(self._model, self._scaler, self._report)
+        logger.info(
+            f"[FootballML] {lib} 训练完成 n={n}  "
+            f"CV Brier={self._report.get('cv_brier_mean')}  "
+            f"DC Brier={dc_brier:.4f}  提升={self._report['improvement']:+.4f}"
+        )
+        return self._report
+
+    # ── 预测 ──────────────────────────────────────────────────────────────────
+
+    def predict(self, record: Dict) -> Optional[Dict[str, float]]:
+        """
+        从预测记录（含 elo/lambda）输出 ML 概率。
+        返回 None 表示特征不完整，调用方应 fallback 到 DC。
+        """
+        if not self.is_ready:
+            return None
+        feat = _extract_features(record)
+        if feat is None:
+            return None
+
+        feat_s = self._scaler.transform(feat.reshape(1, -1))
+        proba  = self._model.predict_proba(feat_s)[0]  # [away, draw, home]
+        return {
+            "away_win": round(float(proba[0]), 4),
+            "draw":     round(float(proba[1]), 4),
+            "home_win": round(float(proba[2]), 4),
+            "model":    "XGB+Elo+λ",
+        }
+
+    @property
+    def report(self) -> Dict:
+        return self._report
+
+    # ── 加载/保存 ─────────────────────────────────────────────────────────────
+
+    @classmethod
+    def load_or_train(cls, force_train: bool = False) -> "FootballMLModel":
+        """加载已存模型，若不存在或需重训则自动训练。"""
+        m = cls()
+        if _MODEL_PATH.exists() and not force_train:
+            try:
+                payload = pickle.loads(_MODEL_PATH.read_bytes())
+                m._model   = payload["model"]
+                m._scaler  = payload["scaler"]
+                m._report  = payload.get("report", {})
+                m._n_trained = payload.get("n_trained", 0)
+
+                # 检查是否需要重训
+                records = _load_settled_records()
+                if len(records) >= m._n_trained + _RETRAIN_EVERY:
+                    logger.info("[FootballML] 新增 ≥10 条记录，触发重训")
+                    m.train(records)
+                return m
+            except Exception as e:
+                logger.warning(f"[FootballML] 加载失败: {e}，重新训练")
+
+        m.train()
+        return m
+
+
+# ── 工具函数 ──────────────────────────────────────────────────────────────────
+
+def _load_settled_records() -> List[Dict]:
+    """从 tracker 加载已结算预测记录。"""
+    try:
+        from .tracker import _PRED_PATH, _load_json
+        records = _load_json(_PRED_PATH, [])
+        return [r for r in records if r.get("result") and r.get("brier_score") is not None]
+    except Exception:
+        return []
+
+
+def _walk_forward_cv(model, X: np.ndarray, y: np.ndarray, n_splits: int = 5) -> List[float]:
+    """时序感知交叉验证，返回每折 Brier Score。"""
+    import copy
+    n = len(X)
+    fold_size = max(4, n // (n_splits + 1))
+    briers = []
+    for i in range(n_splits):
+        tr_end = (i + 1) * fold_size
+        te_end = tr_end + fold_size
+        if te_end > n:
+            break
+        y_tr = y[:tr_end]
+        # 跳过训练集类别不足的折（XGBoost 要求所有类别都出现）
+        if len(np.unique(y_tr)) < 3:
+            continue
+        try:
+            m_copy = copy.deepcopy(model)
+            m_copy.fit(X[:tr_end], y_tr)
+            proba = m_copy.predict_proba(X[tr_end:te_end])
+            if proba.shape[1] == 3:
+                briers.append(_brier_mc(proba, y[tr_end:te_end]))
+        except Exception:
+            continue
+    return briers
+
+
+def _brier_mc(proba: np.ndarray, y: np.ndarray) -> float:
+    """多分类 Brier Score。"""
+    total = 0.0
+    n_classes = proba.shape[1]
+    for i, yi in enumerate(y):
+        for c in range(n_classes):
+            total += (proba[i, c] - (1.0 if yi == c else 0.0)) ** 2
+    return total / max(len(y), 1)
+
+
+def _dc_brier_from_records(records: List[Dict]) -> float:
+    """用记录里已存的 brier_score（DC 模型）计算均值。"""
+    scores = [r["brier_score"] for r in records if r.get("brier_score") is not None]
+    return float(np.mean(scores)) if scores else 0.5
+
+
+def _save_model(model, scaler, report: Dict) -> None:
+    try:
+        n = report.get("n_samples", 0)
+        payload = {"model": model, "scaler": scaler, "report": report, "n_trained": n}
+        _MODEL_PATH.parent.mkdir(parents=True, exist_ok=True)
+        _MODEL_PATH.write_bytes(pickle.dumps(payload))
+        # JSON 序列化：将 numpy 类型转换为 Python 原生类型
+        def _to_native(obj):
+            if isinstance(obj, (np.floating, np.float32, np.float64)): return float(obj)
+            if isinstance(obj, (np.integer,)): return int(obj)
+            if isinstance(obj, np.ndarray): return obj.tolist()
+            return obj
+        safe_report = json.loads(json.dumps(report, default=_to_native))
+        _REPORT_PATH.write_text(json.dumps(safe_report, ensure_ascii=False, indent=2), encoding="utf-8")
+    except Exception as e:
+        logger.warning(f"[FootballML] 保存失败: {e}")
+
+
+# ── 单例 ─────────────────────────────────────────────────────────────────────
+
+_instance: Optional[FootballMLModel] = None
+
+
+def get_football_ml() -> FootballMLModel:
+    global _instance
+    if _instance is None:
+        _instance = FootballMLModel.load_or_train()
+    return _instance

aria_code/packages/quant_engine/sports/predictor.py

@@ -0,0 +1,312 @@
+"""
+sports/predictor.py — 统一足球比赛预测引擎 v2
+==============================================
+整合 Elo + Dixon-Coles(NB) + 近期状态 + H2H + 赛事情境 五个模块。
+
+v2 改进:
+  1. 负二项分布（大比分悬殊时自动启用，尾部更重）
+  2. 动态 DC×Elo 混合权重（form 数据越充足 DC 权重越高）
+  3. 赛事情境参数（必须赢/已出线保守/淘汰赛）
+  4. 动态 WC 场均进球（从 tracker 实时获取）
+  5. ρ 随赛果积累自动校准
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Dict, List, Optional, Tuple
+
+from .elo         import EloRatingSystem, get_elo
+from .dixon_coles import compute_match_probabilities, estimate_rho_from_results
+from .form        import analyze_form, parse_api_results
+from .h2h         import analyze_h2h, _neutral_h2h
+from aria_code.packages.aria_core.paths import aria_home
+
+
+# ── 联赛场均进球（每队每场，后备默认值）──────────────────────────────────────
+_LEAGUE_AVG_GOALS: Dict[str, float] = {
+    "wc":       1.35, "euro":    1.20, "copa":   1.28,
+    "pl":       1.51, "bl1":     1.56, "sa":     1.33,
+    "pd":       1.34, "fl1":     1.43, "cl":     1.40,
+    "friendly": 1.45, "default": 1.35,
+}
+
+# ── 赛事情境因子 ──────────────────────────────────────────────────────────────
+_CONTEXT: Dict[str, Dict[str, float]] = {
+    "normal":          {"lmult_h": 1.00, "lmult_a": 1.00, "draw_boost": 0.00},
+    "must_win":        {"lmult_h": 1.10, "lmult_a": 0.95, "draw_boost": -0.04},
+    "safe":            {"lmult_h": 0.88, "lmult_a": 0.88, "draw_boost":  0.06},
+    "knockout":        {"lmult_h": 1.00, "lmult_a": 1.00, "draw_boost":  0.12},
+    "knockout_attack": {"lmult_h": 1.08, "lmult_a": 1.00, "draw_boost":  0.05},
+}
+
+
+class FootballPredictor:
+    """
+    增强型足球比赛预测引擎 v2。
+
+    用法:
+        pred = FootballPredictor()
+        result = pred.predict("germany", "curacao", league="wc",
+                              tournament_context="normal")
+    """
+
+    def __init__(self, elo_system: Optional[EloRatingSystem] = None):
+        self._elo = elo_system or get_elo()
+
+    def predict(
+        self,
+        home_team: str,
+        away_team: str,
+        league: str = "default",
+        neutral_venue: bool = True,
+        form_home: Optional[List[Dict]] = None,
+        form_away: Optional[List[Dict]] = None,
+        h2h_matches: Optional[List[Dict]] = None,
+        historical_results: Optional[List[Tuple[int, int]]] = None,
+        tournament_context: str = "normal",
+        league_avg_override: Optional[float] = None,
+        home_attack_override: Optional[float] = None,
+        away_attack_override: Optional[float] = None,
+        home_defense_override: Optional[float] = None,
+        away_defense_override: Optional[float] = None,
+    ) -> Dict:
+        """
+        主预测函数。
+
+        tournament_context:
+          "normal"          — 小组赛正常（默认）
+          "must_win"        — 必须赢（全力进攻）
+          "safe"            — 已出线、可保守
+          "knockout"        — 淘汰赛（平局→加时）
+          "knockout_attack" — 淘汰赛落后方
+        """
+        # ── Step 0: 基础参数 ───────────────────────────────────────────────────
+        league_key = league.lower().replace("-", "").replace("_", "")
+        league_avg = league_avg_override or _LEAGUE_AVG_GOALS.get(
+            league_key, _LEAGUE_AVG_GOALS["default"]
+        )
+        ctx = _CONTEXT.get(tournament_context, _CONTEXT["normal"])
+
+        # ── Step 1: Elo → 攻防基础参数（二次曲线，更陡）─────────────────────
+        home_stats = self._elo.get_attack_defense(home_team, league_avg)
+        away_stats = self._elo.get_attack_defense(away_team, league_avg)
+
+        h_attack  = home_attack_override  or home_stats["attack"]
+        a_attack  = away_attack_override  or away_stats["attack"]
+        h_defense = home_defense_override or home_stats["defense"]
+        a_defense = away_defense_override or away_stats["defense"]
+
+        home_elo  = home_stats["elo"]
+        away_elo  = away_stats["elo"]
+        elo_diff  = home_elo - away_elo
+
+        # ── Step 2: 近期状态调整 ───────────────────────────────────────────────
+        home_form = _neutral_form_dict()
+        away_form = _neutral_form_dict()
+        form_matches_h = 0
+        form_matches_a = 0
+
+        if form_home:
+            parsed_h = parse_api_results(form_home, home_team)
+            if parsed_h:
+                home_form = analyze_form(parsed_h)
+                form_matches_h = home_form.get("matches_analyzed", 0)
+        if form_away:
+            parsed_a = parse_api_results(form_away, away_team)
+            if parsed_a:
+                away_form = analyze_form(parsed_a)
+                form_matches_a = away_form.get("matches_analyzed", 0)
+
+        h_attack  *= home_form["form_factor_attack"]
+        a_attack  *= away_form["form_factor_attack"]
+        h_defense *= home_form["form_factor_defense"]
+        a_defense *= away_form["form_factor_defense"]
+
+        # ── Step 3: 主场优势 + 赛事情境 ───────────────────────────────────────
+        home_adv_mult = 1.0 if neutral_venue else 1.12
+
+        # ── Step 4: 期望进球 ───────────────────────────────────────────────────
+        lambda_home = h_attack * a_defense * home_adv_mult * league_avg * ctx["lmult_h"]
+        lambda_away = a_attack * h_defense * league_avg * ctx["lmult_a"]
+
+        # H2H 微调（±8% 期望进球）
+        h2h_result = _neutral_h2h(home_team, away_team)
+        if h2h_matches:
+            h2h_result = analyze_h2h(h2h_matches, home_team, away_team)
+        h2h_adv = h2h_result.get("h2h_advantage", 0.0)
+        lambda_home *= (1.0 + h2h_adv)
+        lambda_away *= (1.0 - h2h_adv)
+
+        # ── Step 4b: 自动校准修正 ──────────────────────────────────────────────
+        # 全局 λ 偏差（实际进球 / 预测 λ 的历史 EMA）
+        # 队伍专属进球偏差（≥3 场数据才生效）
+        try:
+            from .calibrator import get_calibrated_params, get_team_goal_bias
+            cal = get_calibrated_params()
+            lambda_home *= cal.get("lambda_home_bias", 1.0)
+            lambda_away *= cal.get("lambda_away_bias", 1.0)
+            lambda_home *= get_team_goal_bias(home_team)
+            lambda_away *= get_team_goal_bias(away_team)
+        except Exception:
+            pass
+
+        lambda_home = max(0.20, min(lambda_home, 8.0))
+        lambda_away = max(0.20, min(lambda_away, 8.0))
+
+        # ── Step 5: 动态 ρ 校准 ────────────────────────────────────────────────
+        rho = _load_calibrated_rho()
+        if historical_results and len(historical_results) >= 20:
+            rho = estimate_rho_from_results(historical_results)
+
+        # ── Step 6: Dixon-Coles（NB 自动启用于悬殊场次）──────────────────────
+        dc_result = compute_match_probabilities(
+            lambda_home, lambda_away, rho, elo_diff=elo_diff
+        )
+
+        # ── Step 7: Elo 概率混合（动态权重）──────────────────────────────────
+        elo_probs = self._elo.win_probability(home_team, away_team, neutral_venue)
+
+        # form 数据越充足，DC 权重越高；数据稀少时 Elo 权重更保守
+        avg_form_matches = (form_matches_h + form_matches_a) / 2.0
+        w_dc  = min(0.78, 0.55 + avg_form_matches * 0.04)
+        w_elo = 1.0 - w_dc
+
+        mix_home = dc_result["home_win"] * w_dc + elo_probs["home_win"] * w_elo
+        mix_draw = dc_result["draw"]     * w_dc + elo_probs["draw"]     * w_elo
+        mix_away = dc_result["away_win"] * w_dc + elo_probs["away_win"] * w_elo
+
+        # 淘汰赛平局加成（反映加时/点球场景）
+        draw_boost = ctx["draw_boost"]
+        if draw_boost != 0:
+            mix_draw = max(0.02, mix_draw + draw_boost)
+
+        total = mix_home + mix_draw + mix_away
+        mix_home /= total
+        mix_draw /= total
+        mix_away /= total
+
+        # Raw (pre-temperature) probabilities — recorded for calibration so the
+        # temperature optimizer never compounds an already-applied shrink.
+        raw_home, raw_draw, raw_away = mix_home, mix_draw, mix_away
+
+        # ── Step 8: 概率温度校准（收敛过度自信的预测）────────────────────────
+        try:
+            from .calibrator import get_confidence_temp, _apply_temp
+            _temp = get_confidence_temp()
+            if _temp != 1.0:
+                mix_home, mix_draw, mix_away = _apply_temp(mix_home, mix_draw, mix_away, _temp)
+        except Exception:
+            pass
+
+        def impl_odds(p: float) -> float:
+            return round(1.0 / p, 2) if p > 0.01 else 99.0
+
+        use_nb = abs(elo_diff) > 150
+        model_tag = f"Elo+DC{'(NB)' if use_nb else ''}+Form+H2H"
+        if draw_boost:
+            model_tag += f"+{tournament_context}"
+
+        return {
+            "home_team":        home_team,
+            "away_team":        away_team,
+            "home_win":         round(mix_home, 4),
+            "draw":             round(mix_draw, 4),
+            "away_win":         round(mix_away, 4),
+            "raw_home_win":     round(raw_home, 4),
+            "raw_draw":         round(raw_draw, 4),
+            "raw_away_win":     round(raw_away, 4),
+            "btts":             dc_result["btts"],
+            "over_2_5":         dc_result["over_2_5"],
+            "lambda_home":      round(lambda_home, 2),
+            "lambda_away":      round(lambda_away, 2),
+            "league_avg_goals": round(league_avg, 2),
+            "top_scorelines":   dc_result["top_scorelines"],
+            "implied_odds": {
+                "home": impl_odds(mix_home),
+                "draw": impl_odds(mix_draw),
+                "away": impl_odds(mix_away),
+            },
+            "home_elo":          home_elo,
+            "away_elo":          away_elo,
+            "elo_diff":          round(elo_diff, 0),
+            "home_attack":       round(h_attack, 3),
+            "away_attack":       round(a_attack, 3),
+            "home_defense":      round(h_defense, 3),
+            "away_defense":      round(a_defense, 3),
+            "rho":               rho,
+            "dc_home_win":       dc_result["home_win"],
+            "dc_draw":           dc_result["draw"],
+            "dc_away_win":       dc_result["away_win"],
+            "elo_home_win":      elo_probs["home_win"],
+            "elo_draw":          elo_probs["draw"],
+            "elo_away_win":      elo_probs["away_win"],
+            "home_form":         home_form.get("form_string", "?????"),
+            "away_form":         away_form.get("form_string", "?????"),
+            "home_momentum":     home_form.get("momentum", "stable"),
+            "away_momentum":     away_form.get("momentum", "stable"),
+            "h2h_summary":       h2h_result.get("summary", ""),
+            "h2h_advantage":     h2h_adv,
+            "w_dc":              round(w_dc, 2),
+            "w_elo":             round(w_elo, 2),
+            "use_nb":            use_nb,
+            "tournament_context": tournament_context,
+            "model":             model_tag,
+        }
+
+
+def _neutral_form_dict() -> Dict:
+    return {
+        "form_factor_attack":  1.0,
+        "form_factor_defense": 1.0,
+        "form_string":         "?????",
+        "momentum":            "stable",
+        "matches_analyzed":    0,
+    }
+
+
+def _load_calibrated_rho() -> float:
+    """从 tracker 读取已校准的 ρ 值，不可用则返回默认 -0.10。"""
+    try:
+        from pathlib import Path
+        import json
+        p = aria_home() / "wc_rho.json"
+        if p.exists():
+            d = json.loads(p.read_text())
+            return d.get("rho", -0.10)
+    except Exception:
+        pass
+    return -0.10
+
+
+_predictor_instance: Optional[FootballPredictor] = None
+
+
+def get_predictor() -> FootballPredictor:
+    global _predictor_instance
+    if _predictor_instance is None:
+        _predictor_instance = FootballPredictor()
+    return _predictor_instance
+
+
+def quick_predict(
+    home_team: str,
+    away_team: str,
+    league: str = "wc",
+    neutral_venue: bool = True,
+    tournament_context: str = "normal",
+    league_avg_override: Optional[float] = None,
+) -> Dict:
+    """
+    一行调用接口。
+
+    示例:
+        from packages.quant_engine.sports.predictor import quick_predict
+        r = quick_predict("germany", "ivory coast", tournament_context="must_win")
+        print(f"德国赢: {r['home_win']*100:.1f}%")
+    """
+    return get_predictor().predict(
+        home_team, away_team, league, neutral_venue,
+        tournament_context=tournament_context,
+        league_avg_override=league_avg_override,
+    )