aria-code 0.52.0__py3-none-any.whl

aria_code/packages/quant_engine/sports/__init__.py

@@ -0,0 +1,80 @@
+# 让本子包也能穿透到私有 Arthera 仓的同名子包。
+# 父层 (packages / quant_engine) 已经做了 __path__ 拼接，但 Python 找到
+# 常规子包后就停止查找，不会继续看父包 __path__ 的其它条目——所以每一层
+# 都得自己声明。规则：aria-code 自带的实现优先，Arthera 补齐缺口。
+# 详见 packages/quant_engine/_namespace.py 的模块文档。
+from .._namespace import extend as _extend_namespace
+_extend_namespace(__path__, "sports")
+
+"""
+packages/quant_engine/sports — 足球量化分析模块
+================================================
+v2.0.0 — 2026-06
+
+模块组成:
+  elo          — World Football Elo 动态评分系统（二次曲线攻防，GD K 因子）
+  dixon_coles  — Dixon-Coles 比分预测（NB 分布，大比分悬殊自动启用）
+  form         — 近期状态分析（指数衰减权重）
+  h2h          — 历史交锋分析与调整
+  predictor    — 统一预测引擎 v2（动态权重、赛事情境、ρ 校准）
+  tracker      — 预测追踪、Brier Score、自动 Elo 同步、动态场均进球
+
+快速使用:
+    from packages.quant_engine.sports import quick_predict, get_elo
+
+    # 预测（含 NB 分布 + 动态权重）
+    result = quick_predict("germany", "curacao", league="wc")
+    print(f"德国赢率: {result['home_win']*100:.1f}%")   # ~85%
+
+    # Elo 评分
+    elo = get_elo()
+    print(elo.get_rating("germany"))    # ~1912（赛后更新）
+
+    # 自动同步已结束 WC 比赛 Elo
+    from packages.quant_engine.sports import sync_elo_from_wc
+    sync_elo_from_wc(api_get_fn)
+"""
+
+from .elo          import EloRatingSystem, get_elo, ranking_to_elo
+from .dixon_coles  import (
+    compute_match_probabilities,
+    predict_scoreline_matrix,
+    tau_correction,
+    estimate_rho_from_results,
+    format_dc_result,
+)
+from .form         import analyze_form, parse_api_results, form_bar, momentum_label
+from .h2h          import analyze_h2h
+from .predictor    import FootballPredictor, get_predictor, quick_predict
+from .tracker      import (
+    record_prediction,
+    record_result,
+    get_accuracy_stats,
+    sync_elo_from_wc,
+    fetch_wc_league_avg,
+    fetch_wc_rho,
+    auto_calibrate,
+    backfill_score_metrics,
+)
+from .calibrator   import (
+    get_calibrated_params,
+    get_team_goal_bias,
+    get_all_team_biases,
+    calibration_summary,
+    save_calibration,
+)
+
+__all__ = [
+    "EloRatingSystem", "get_elo", "ranking_to_elo",
+    "compute_match_probabilities", "predict_scoreline_matrix",
+    "tau_correction", "estimate_rho_from_results", "format_dc_result",
+    "analyze_form", "parse_api_results", "form_bar", "momentum_label",
+    "analyze_h2h",
+    "FootballPredictor", "get_predictor", "quick_predict",
+    "record_prediction", "record_result", "get_accuracy_stats",
+    "sync_elo_from_wc", "fetch_wc_league_avg", "fetch_wc_rho", "auto_calibrate",
+    "get_calibrated_params", "get_team_goal_bias", "get_all_team_biases",
+    "calibration_summary", "save_calibration",
+]
+
+__version__ = "2.0.0"

aria_code/packages/quant_engine/sports/calibrator.py

@@ -0,0 +1,354 @@
+"""
+sports/calibrator.py — 模型参数自动优化
+=========================================
+基于历史预测 Brier Score 和实际进球，持续校准攻防斜率与 λ 偏差。
+
+自动优化流程（数据积累触发）:
+  ≥ 5 场已结算  → λ 偏差修正（实际进球 / 预测 λ 的指数移动平均）
+  ≥ 10 场已结算 → 攻防斜率网格搜索（最小化 Brier Score）
+  ≥ 3 场单队数据 → 队伍专属进球偏差修正
+
+持久化:
+  ~/.arthera/wc_calibrated_params.json  — 全局斜率 + λ 偏差
+  ~/.arthera/team_goal_bias.json        — 各队进球偏差 EMA
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+from aria_code.packages.aria_core.paths import aria_home
+
+_PARAMS_PATH    = aria_home() / "wc_calibrated_params.json"
+_TEAM_BIAS_PATH = aria_home() / "team_goal_bias.json"
+
+_DEFAULT_PARAMS = {
+    "a1": 1.05, "a2": 0.35,   # 攻击斜率（线性 + 二次）
+    "d1": -0.42, "d2": -0.10, # 防守斜率
+    "lambda_home_bias": 1.0,   # λ 偏差修正因子
+    "lambda_away_bias": 1.0,
+    "conf_temp": 1.0,          # 概率温度（<1 收敛过度自信的预测）
+    "calibrated_at": None,
+    "n_matches": 0,
+    "avg_brier": None,
+}
+
+
+# ── 持久化工具 ────────────────────────────────────────────────────────────────
+
+def _load_json(path: Path, default):
+    try:
+        if path.exists():
+            return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        pass
+    return default
+
+
+def _save_json(path: Path, data) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    except Exception:
+        pass
+
+
+# ── 1. λ 偏差修正 ─────────────────────────────────────────────────────────────
+
+def optimize_lambda_bias(settled_records: List[Dict]) -> Dict[str, float]:
+    """
+    从已结算预测计算主客队 λ 系统偏差。
+
+    每条记录需包含: actual_home_goals, actual_away_goals, lambda_home, lambda_away。
+    偏差 = mean(actual / predicted)；> 1.0 说明模型系统性低估进球。
+    需要 ≥ 5 条含实际进球的记录才修正。
+    """
+    home_ratios, away_ratios = [], []
+
+    for r in settled_records:
+        ah = r.get("actual_home_goals")
+        aa = r.get("actual_away_goals")
+        lh = r.get("lambda_home")
+        la = r.get("lambda_away")
+        if ah is not None and lh and lh > 0:
+            home_ratios.append(ah / lh)
+        if aa is not None and la and la > 0:
+            away_ratios.append(aa / la)
+
+    result = {"home_bias": 1.0, "away_bias": 1.0, "n_home": len(home_ratios), "n_away": len(away_ratios)}
+    if len(home_ratios) >= 5:
+        result["home_bias"] = round(sum(home_ratios) / len(home_ratios), 4)
+    if len(away_ratios) >= 5:
+        result["away_bias"] = round(sum(away_ratios) / len(away_ratios), 4)
+    return result
+
+
+# ── 2. 攻防斜率网格搜索 ───────────────────────────────────────────────────────
+
+def optimize_slopes_from_outcomes(settled_records: List[Dict]) -> Dict:
+    """
+    从已结算预测记录（需含 home_elo / away_elo / result）搜索最优攻防斜率。
+
+    策略：固定 d1 = -a1×0.40, d2 = -a2×0.29（对称性假设），
+    2D 网格搜索 a1 × a2，最小化平均 Brier Score。
+    需要 ≥ 10 条含 Elo 数据的记录。
+    """
+    records = [
+        r for r in settled_records
+        if r.get("home_elo") and r.get("away_elo") and r.get("result")
+    ]
+    if len(records) < 10:
+        return {**_DEFAULT_PARAMS, "status": "not_enough_data", "n": len(records)}
+
+    try:
+        from .dixon_coles import compute_match_probabilities
+    except ImportError:
+        return {**_DEFAULT_PARAMS, "status": "import_error"}
+
+    best_brier = float("inf")
+    best = {}
+
+    for a1 in [0.85, 0.95, 1.05, 1.15, 1.25, 1.35]:
+        for a2 in [0.20, 0.28, 0.35, 0.43, 0.50]:
+            d1 = round(-a1 * 0.40, 3)
+            d2 = round(-a2 * 0.29, 3)
+            total_brier = 0.0
+
+            for r in records:
+                h_elo = float(r["home_elo"])
+                a_elo = float(r["away_elo"])
+                si_h  = (h_elo - 1500) / 400.0
+                si_a  = (a_elo - 1500) / 400.0
+
+                h_atk = max(0.45, min(1.10 + si_h*a1 + max(0, si_h)*si_h*a2, 2.60))
+                a_atk = max(0.45, min(1.10 + si_a*a1 + max(0, si_a)*si_a*a2, 2.60))
+                h_def = max(0.40, min(0.95 + si_h*d1 + max(0, si_h)*si_h*d2, 1.25))
+                a_def = max(0.40, min(0.95 + si_a*d1 + max(0, si_a)*si_a*d2, 1.25))
+
+                league_avg = float(r.get("league_avg", 1.35))
+                lh = max(0.2, min(h_atk * a_def * league_avg, 8.0))
+                la = max(0.2, min(a_atk * h_def * league_avg, 8.0))
+                elo_diff = h_elo - a_elo
+
+                dc = compute_match_probabilities(lh, la, rho=-0.10, elo_diff=elo_diff)
+                res = r["result"]
+                ih = 1.0 if res == "home" else 0.0
+                id_ = 1.0 if res == "draw" else 0.0
+                ia  = 1.0 if res == "away" else 0.0
+                total_brier += (dc["home_win"]-ih)**2 + (dc["draw"]-id_)**2 + (dc["away_win"]-ia)**2
+
+            avg_brier = total_brier / len(records)
+            if avg_brier < best_brier:
+                best_brier = avg_brier
+                best = {
+                    "a1": a1, "a2": a2, "d1": d1, "d2": d2,
+                    "avg_brier": round(avg_brier, 4),
+                    "n": len(records),
+                    "status": "optimized",
+                }
+
+    return best
+
+
+# ── 2b. 概率温度校准（对抗过度自信）──────────────────────────────────────────
+
+def _apply_temp(ph: float, pd: float, pa: float, temp: float) -> Tuple[float, float, float]:
+    """Temperature-scale a 1X2 distribution: p_i ∝ p_i**temp, renormalized.
+
+    temp < 1 flattens (less confident); temp = 1 is a no-op. Guards against
+    zero/negative inputs.
+    """
+    if temp == 1.0:
+        return ph, pd, pa
+    eps = 1e-9
+    h = max(ph, eps) ** temp
+    d = max(pd, eps) ** temp
+    a = max(pa, eps) ** temp
+    s = h + d + a
+    return h / s, d / s, a / s
+
+
+def optimize_confidence_temp(settled_records: List[Dict]) -> Dict:
+    """Grid-search the probability temperature that minimizes Brier.
+
+    World-Cup favorites are systematically over-predicted (e.g. 88% → draw),
+    so the raw 1X2 distribution is too sharp. We find temp ∈ [0.55, 1.0] that
+    flattens predictions to best match observed outcomes.
+
+    Trains on RAW probabilities (raw_home_win/…) when present so it never
+    compounds a temperature already applied at output; falls back to the
+    stored home_win/… for legacy records. Needs ≥ 8 settled records.
+    """
+    rows = []
+    for r in settled_records:
+        if not r.get("result"):
+            continue
+        ph = r.get("raw_home_win", r.get("home_win"))
+        pd = r.get("raw_draw",     r.get("draw"))
+        pa = r.get("raw_away_win", r.get("away_win"))
+        if ph is None or pd is None or pa is None:
+            continue
+        rows.append((float(ph), float(pd), float(pa), r["result"]))
+
+    if len(rows) < 8:
+        return {"temp": 1.0, "status": "not_enough_data", "n": len(rows)}
+
+    def mean_brier(temp: float) -> float:
+        tot = 0.0
+        for ph, pd, pa, res in rows:
+            h, d, a = _apply_temp(ph, pd, pa, temp)
+            ih = 1.0 if res == "home" else 0.0
+            idr = 1.0 if res == "draw" else 0.0
+            ia = 1.0 if res == "away" else 0.0
+            tot += (h - ih) ** 2 + (d - idr) ** 2 + (a - ia) ** 2
+        return tot / len(rows)
+
+    base = mean_brier(1.0)
+    best_temp, best_brier = 1.0, base
+    t = 0.55
+    while t <= 1.001:
+        b = mean_brier(t)
+        if b < best_brier:
+            best_brier, best_temp = b, round(t, 2)
+        t += 0.05
+
+    return {
+        "temp": best_temp,
+        "status": "optimized",
+        "n": len(rows),
+        "brier_before": round(base, 4),
+        "brier_after": round(best_brier, 4),
+    }
+
+
+def get_confidence_temp() -> float:
+    return get_calibrated_params().get("conf_temp", 1.0)
+
+
+# ── 3. 队伍专属进球偏差（EMA）─────────────────────────────────────────────────
+
+def update_team_goal_bias(team: str, predicted_lambda: float, actual_goals: int) -> None:
+    """
+    更新队伍历史进球偏差（指数移动平均，alpha=0.3）。
+    bias_ema > 1 表示该队实际进球通常高于模型预测。
+    """
+    if predicted_lambda <= 0:
+        return
+
+    biases: Dict = _load_json(_TEAM_BIAS_PATH, {})
+    key   = team.lower().strip()
+    ratio = actual_goals / predicted_lambda
+
+    if key not in biases:
+        biases[key] = {"ema": round(ratio, 4), "n": 1, "updated": time.strftime("%Y-%m-%d")}
+    else:
+        alpha = 0.3
+        biases[key]["ema"] = round(alpha * ratio + (1 - alpha) * biases[key]["ema"], 4)
+        biases[key]["n"]  += 1
+        biases[key]["updated"] = time.strftime("%Y-%m-%d")
+
+    _save_json(_TEAM_BIAS_PATH, biases)
+
+
+def get_team_goal_bias(team: str) -> float:
+    """
+    返回队伍进球偏差修正因子。
+    < 3 场数据时返回 1.0（不修正，防止过拟合）。
+    """
+    biases = _load_json(_TEAM_BIAS_PATH, {})
+    entry  = biases.get(team.lower().strip(), {})
+    if entry.get("n", 0) < 3:
+        return 1.0
+    bias = entry.get("ema", 1.0)
+    # 限制修正幅度，防止极端值
+    return round(max(0.70, min(bias, 1.50)), 4)
+
+
+def get_all_team_biases() -> Dict[str, Dict]:
+    """返回所有有数据的队伍偏差记录。"""
+    return _load_json(_TEAM_BIAS_PATH, {})
+
+
+# ── 3b. λ 偏差：基于比分 MAE 的精化校准 ──────────────────────────────────────
+
+def optimize_lambda_bias_from_scores(settled_records: List[Dict]) -> Dict:
+    """
+    用实际比分优化 λ_home / λ_away 全局缩放因子，最小化总进球 MAE。
+
+    与 optimize_lambda_bias 的区别：
+      - 后者用 actual/predicted 比值的均值（易受极端值拉偏）
+      - 本函数网格搜索 bias_h × bias_a，最小化
+          mean(|bias_h * lambda_h - actual_h| + |bias_a * lambda_a - actual_a|)
+    需要 ≥ 8 条含实际进球记录才运行。
+
+    返回 {"home_bias": ..., "away_bias": ..., "goals_mae": ..., "n": ..., "status": ...}
+    """
+    rows = [
+        r for r in settled_records
+        if r.get("actual_home_goals") is not None
+        and r.get("actual_away_goals") is not None
+        and r.get("lambda_home") and r.get("lambda_away")
+    ]
+    if len(rows) < 8:
+        return {"home_bias": 1.0, "away_bias": 1.0, "status": "not_enough_data", "n": len(rows)}
+
+    best_mae = float("inf")
+    best_bh, best_ba = 1.0, 1.0
+
+    for bh in [0.70, 0.75, 0.80, 0.85, 0.90, 0.95, 1.00, 1.05, 1.10, 1.15, 1.20]:
+        for ba in [0.70, 0.75, 0.80, 0.85, 0.90, 0.95, 1.00, 1.05, 1.10, 1.15]:
+            total = 0.0
+            for r in rows:
+                pred_h = float(r["lambda_home"]) * bh
+                pred_a = float(r["lambda_away"]) * ba
+                total += abs(pred_h - float(r["actual_home_goals"]))
+                total += abs(pred_a - float(r["actual_away_goals"]))
+            mae = total / (2 * len(rows))
+            if mae < best_mae:
+                best_mae, best_bh, best_ba = mae, bh, ba
+
+    return {
+        "home_bias":  round(best_bh, 3),
+        "away_bias":  round(best_ba, 3),
+        "goals_mae":  round(best_mae, 4),
+        "n":          len(rows),
+        "status":     "optimized",
+    }
+
+
+# ── 4. 参数读写 ───────────────────────────────────────────────────────────────
+
+def get_calibrated_params() -> Dict:
+    """读取已保存的校准参数，不存在则返回默认值。"""
+    saved = _load_json(_PARAMS_PATH, {})
+    return {**_DEFAULT_PARAMS, **saved}
+
+
+def save_calibration(params: Dict) -> None:
+    """保存校准结果（追加 timestamp）。"""
+    params["calibrated_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    existing = _load_json(_PARAMS_PATH, {})
+    existing.update(params)
+    _save_json(_PARAMS_PATH, existing)
+
+
+def calibration_summary() -> str:
+    """打印可读的当前校准状态。"""
+    p = get_calibrated_params()
+    biases = get_all_team_biases()
+    lines = [
+        f"校准时间: {p.get('calibrated_at', '未校准')}",
+        f"攻击斜率: a1={p['a1']}  a2={p['a2']}",
+        f"防守斜率: d1={p['d1']}  d2={p['d2']}",
+        f"λ 偏差:   主队 ×{p['lambda_home_bias']}  客队 ×{p['lambda_away_bias']}",
+        f"平均 Brier: {p.get('avg_brier', 'N/A')}",
+        f"样本场次: {p.get('n_matches', 0)}",
+        "",
+        "队伍进球偏差 (≥3场数据):",
+    ]
+    for team, d in sorted(biases.items(), key=lambda x: -x[1].get("n", 0)):
+        if d.get("n", 0) >= 3:
+            lines.append(f"  {team:<20} EMA={d['ema']:.3f}  n={d['n']}")
+    return "\n".join(lines)

aria_code/packages/quant_engine/sports/dixon_coles.py

@@ -0,0 +1,234 @@
+"""
+sports/dixon_coles.py — Dixon-Coles 足球比分预测模型
+=====================================================
+实现 Dixon & Coles (1997) 经典论文的完整模型。
+
+核心改进 vs 纯泊松：
+1. τ (tau) 低比分修正：0-0 / 0-1 / 1-0 / 1-1 比分在现实中
+   比独立泊松分布出现频率更高，DC 模型用相关性项修正。
+2. ρ (rho) 参数：控制修正强度，典型值 -0.13 ~ -0.08。
+3. 时间权重：近期比赛权重更高（可选）。
+
+τ 修正矩阵:
+    τ(x, y, λ, μ, ρ) =
+        1 - λμρ         if x=0, y=0
+        1 + λρ          if x=0, y=1
+        1 + μρ          if x=1, y=0
+        1 - ρ           if x=1, y=1
+        1               otherwise
+
+参考文献: Dixon, M.J. & Coles, S.G. (1997).
+          "Modelling Association Football Scores and Inefficiencies in the
+          Football Betting Market." Applied Statistics, 46(2), 265-280.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Dict, List, Optional, Tuple
+
+
+def _poisson_pmf(k: int, lam: float) -> float:
+    if lam <= 0:
+        return 1.0 if k == 0 else 0.0
+    return (lam ** k) * math.exp(-lam) / math.factorial(k)
+
+
+def _nb_pmf(k: int, mu: float, r: float) -> float:
+    """
+    负二项分布 PMF，均值 mu，离散参数 r。
+
+    方差 = mu + mu²/r  >  mu（泊松）
+    当 r→∞ 时退化为泊松分布。
+    r 越小，尾部越重（大比分概率越高）。
+    """
+    if mu <= 0:
+        return 1.0 if k == 0 else 0.0
+    p = r / (r + mu)
+    log_pmf = (
+        math.lgamma(k + r) - math.lgamma(r) - math.lgamma(k + 1)
+        + r * math.log(p)
+        + k * math.log(1.0 - p)
+    )
+    return math.exp(log_pmf)
+
+
+def _auto_dispersion(elo_diff: float) -> float:
+    """
+    根据 Elo 差距自动选择负二项离散参数 r。
+    差距越大 → r 越小 → 尾部越重 → 大比分概率更高。
+
+    elo_diff=0   → r=80  (近似泊松)
+    elo_diff=200 → r=25
+    elo_diff=387 → r=13  (德国 vs 库拉索)
+    elo_diff=500 → r=10
+    """
+    r = max(6.0, 80.0 / (1.0 + abs(elo_diff) / 100.0))
+    return round(r, 1)
+
+
+def tau_correction(
+    x: int,
+    y: int,
+    lambda_home: float,
+    lambda_away: float,
+    rho: float = -0.10,
+) -> float:
+    """
+    Dixon-Coles τ 修正因子。
+
+    rho < 0 意味着低比分（含 0 的）出现频率比独立泊松预测的更低，
+    但 0-0 / 0-1 / 1-0 / 1-1 特别地有正相关（团队防守同进攻 jointly low）。
+    """
+    if x == 0 and y == 0:
+        return 1.0 - lambda_home * lambda_away * rho
+    if x == 0 and y == 1:
+        return 1.0 + lambda_home * rho
+    if x == 1 and y == 0:
+        return 1.0 + lambda_away * rho
+    if x == 1 and y == 1:
+        return 1.0 - rho
+    return 1.0
+
+
+def predict_scoreline_matrix(
+    lambda_home: float,
+    lambda_away: float,
+    rho: float = -0.10,
+    max_goals: int = 10,
+    elo_diff: float = 0.0,
+) -> Dict[Tuple[int, int], float]:
+    """
+    计算所有比分的概率矩阵。
+
+    当 |elo_diff| > 150 时自动切换到负二项分布以处理大比分场景，
+    否则使用标准泊松分布（DC 修正）。
+
+    Returns:
+        dict: {(home_goals, away_goals): probability}，归一化为 1.0
+    """
+    use_nb = abs(elo_diff) > 150
+    if use_nb:
+        r_home = _auto_dispersion(elo_diff)
+        r_away = _auto_dispersion(-elo_diff)
+
+    raw: Dict[Tuple[int, int], float] = {}
+    for hg in range(max_goals):
+        ph = _nb_pmf(hg, lambda_home, r_home) if use_nb else _poisson_pmf(hg, lambda_home)
+        for ag in range(max_goals):
+            pa = _nb_pmf(ag, lambda_away, r_away) if use_nb else _poisson_pmf(ag, lambda_away)
+            tau = tau_correction(hg, ag, lambda_home, lambda_away, rho)
+            raw[(hg, ag)] = ph * pa * tau
+
+    total = sum(raw.values())
+    if total <= 0:
+        return raw
+    return {k: v / total for k, v in raw.items()}
+
+
+def compute_match_probabilities(
+    lambda_home: float,
+    lambda_away: float,
+    rho: float = -0.10,
+    max_goals: int = 10,
+    elo_diff: float = 0.0,
+) -> Dict:
+    """
+    从期望进球计算比赛结果概率（含 D-C 修正）。
+
+    Returns:
+        {
+            "home_win": float,
+            "draw": float,
+            "away_win": float,
+            "btts": float,
+            "over_2_5": float,
+            "top_scorelines": [...],
+            "score_matrix": {...},
+        }
+    """
+    matrix = predict_scoreline_matrix(lambda_home, lambda_away, rho, max_goals, elo_diff)
+
+    home_win = draw = away_win = 0.0
+    btts = 0.0
+    over_2_5 = 0.0
+
+    for (hg, ag), p in matrix.items():
+        if hg > ag:
+            home_win += p
+        elif hg == ag:
+            draw += p
+        else:
+            away_win += p
+        if hg > 0 and ag > 0:
+            btts += p
+        if hg + ag > 2:
+            over_2_5 += p
+
+    top_scores = sorted(matrix.items(), key=lambda x: -x[1])[:8]
+
+    return {
+        "home_win":  round(home_win, 4),
+        "draw":      round(draw, 4),
+        "away_win":  round(away_win, 4),
+        "btts":      round(btts, 4),
+        "over_2_5":  round(over_2_5, 4),
+        "rho":       rho,
+        "top_scorelines": [
+            {"score": f"{hg}-{ag}", "prob": round(p * 100, 2)}
+            for (hg, ag), p in top_scores
+        ],
+        "implied_odds": {
+            "home": round(1 / home_win, 2) if home_win > 0.01 else 99,
+            "draw": round(1 / draw, 2)     if draw > 0.01 else 99,
+            "away": round(1 / away_win, 2) if away_win > 0.01 else 99,
+        },
+    }
+
+
+def estimate_rho_from_results(match_results: List[Tuple[int, int]]) -> float:
+    """
+    从历史赛果估计最优 ρ 参数（简化版 MLE 搜索）。
+
+    match_results: [(home_goals, away_goals), ...]
+    返回: 最优 ρ（范围 -0.3 ~ 0.0）
+    """
+    if len(match_results) < 20:
+        return -0.10  # 数据不足，用默认值
+
+    def log_likelihood(rho: float) -> float:
+        ll = 0.0
+        for hg, ag in match_results:
+            # 用平均进球作简化 λ
+            lh = sum(h for h, _ in match_results) / len(match_results)
+            la = sum(a for _, a in match_results) / len(match_results)
+            p_h = _poisson_pmf(hg, lh)
+            p_a = _poisson_pmf(ag, la)
+            tau = tau_correction(hg, ag, lh, la, rho)
+            p = p_h * p_a * tau
+            if p > 0:
+                ll += math.log(p)
+        return ll
+
+    best_rho = -0.10
+    best_ll = float("-inf")
+    for rho_int in range(-30, 1, 2):
+        rho = rho_int / 100.0
+        ll = log_likelihood(rho)
+        if ll > best_ll:
+            best_ll = ll
+            best_rho = rho
+
+    return round(best_rho, 3)
+
+
+def format_dc_result(result: Dict, home_cn: str, away_cn: str) -> str:
+    """格式化 Dixon-Coles 预测结果为 CLI 输出文本。"""
+    lines = [
+        f"  主队 {home_cn:<12} 获胜: {result['home_win']*100:5.1f}%   赔率: {result['implied_odds']['home']:5.2f}",
+        f"  平局              {result['draw']*100:5.1f}%   赔率: {result['implied_odds']['draw']:5.2f}",
+        f"  客队 {away_cn:<12} 获胜: {result['away_win']*100:5.1f}%   赔率: {result['implied_odds']['away']:5.2f}",
+        "",
+        f"  双方均进球 (BTTS): {result['btts']*100:.1f}%   大于2.5球: {result['over_2_5']*100:.1f}%",
+    ]
+    return "\n".join(lines)