aria-code 4.1.3__py3-none-any.whl

packages/quant_engine/sports/elo.py

@@ -0,0 +1,299 @@
+"""
+sports/elo.py — World Football Elo Rating System
+=================================================
+动态 Elo 评分系统，替代静态 FIFA 排名表。
+
+特性：
+- 初始评分基于 FIFA 排名（幂律映射，斜率更陡）
+- 每场赛果后自动更新
+- K 因子按赛事重要性调整（世界杯 > 洲际杯 > 友谊赛）
+- 主场优势 +100 Elo 加成（中性场地为 0）
+- 支持从本地 JSON 持久化加载/保存
+
+Elo 公式:
+    E = 1 / (1 + 10^((Rb - Ra - home_adv) / 400))
+    R' = R + K * (W - E)
+
+参考: World Football Elo Ratings (eloratings.net) 方法论
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+from pathlib import Path
+from typing import Dict, Optional, Tuple
+
+# ── 默认初始 Elo（基于 FIFA 排名，幂律映射）──────────────────────────────────
+# 公式: elo = BASE - SCALE * (ranking ^ POWER)
+# 经验参数：阿根廷#1→2050, 德国#11→1850, 库拉索#70→1520, 菲律宾#134→1280
+_ELO_BASE  = 2100.0
+_ELO_SCALE = 50.0
+_ELO_POWER = 0.58
+
+_DEFAULT_ELO = 1500.0  # 未知队伍
+
+
+def ranking_to_elo(ranking: int) -> float:
+    """FIFA 排名 → 初始 Elo 评分（幂律映射）。"""
+    if ranking <= 0:
+        return _DEFAULT_ELO
+    raw = _ELO_BASE - _ELO_SCALE * (ranking ** _ELO_POWER)
+    return max(900.0, round(raw, 1))
+
+
+# K 因子（赛事权重）
+_K_FACTORS: Dict[str, float] = {
+    "wc_final":       60,
+    "wc_semifinal":   56,
+    "wc_quarterfinal":52,
+    "wc_r16":         48,
+    "wc_group":       40,
+    "confederation":  35,
+    "euro_final":     40,
+    "euro":           35,
+    "copa_america":   35,
+    "afcon":          30,
+    "qualifier":      25,
+    "friendly":       15,
+    "default":        20,
+}
+
+# 内置 FIFA 排名表（覆盖主要队伍）
+_FIFA_RANKING: Dict[str, int] = {
+    "argentina": 1, "france": 2, "england": 3, "brazil": 4,
+    "portugal": 5, "belgium": 6, "spain": 7, "netherlands": 8,
+    "croatia": 9, "italy": 10, "germany": 11, "colombia": 12,
+    "united states": 13, "usa": 13, "mexico": 14, "morocco": 16,
+    "uruguay": 20, "denmark": 22, "switzerland": 23, "serbia": 24,
+    "austria": 25, "norway": 26, "ukraine": 27, "turkey": 28,
+    "senegal": 19, "japan": 18, "iran": 21, "south korea": 23,
+    "egypt": 33, "nigeria": 35, "cameroon": 37, "ghana": 60,
+    "australia": 23, "new zealand": 90, "canada": 47,
+    "costa rica": 53, "panama": 55, "jamaica": 60,
+    "curacao": 70, "haiti": 80, "trinidad": 85,
+    "china": 87, "thailand": 111, "philippines": 134,
+    "india": 124, "vietnam": 95, "indonesia": 130,
+    "saudi arabia": 58, "iraq": 62, "uae": 68, "bahrain": 80,
+    "romania": 45, "slovakia": 48, "hungary": 50,
+    "greece": 46, "albania": 66, "north macedonia": 70,
+    "sweden": 30, "finland": 43, "russia": 26,
+    "bolivia": 79, "venezuela": 75, "paraguay": 65,
+    "chile": 55, "ecuador": 45, "peru": 69,
+    "tunisia": 30, "algeria": 32, "mali": 56, "guinea": 64,
+    "ivory coast": 51, "south africa": 70, "zimbabwe": 120,
+}
+
+
+class EloRatingSystem:
+    """
+    World Football Elo 评分引擎。
+
+    用法:
+        elo = EloRatingSystem()
+        p = elo.win_probability("germany", "curacao")
+        # → {'home_win': 0.74, 'draw': 0.16, 'away_win': 0.10}
+    """
+
+    _STORE_PATH = Path.home() / ".arthera" / "football_elo.json"
+
+    def __init__(self, load_from_disk: bool = True):
+        self._ratings: Dict[str, float] = {}
+        self._match_log: list = []
+        if load_from_disk:
+            self._load()
+        # 如果没有持久化数据，用 FIFA 排名初始化
+        if not self._ratings:
+            self._init_from_rankings()
+
+    # ── 初始化 ────────────────────────────────────────────────────────────────
+
+    def _init_from_rankings(self) -> None:
+        for team, rank in _FIFA_RANKING.items():
+            self._ratings[team] = ranking_to_elo(rank)
+
+    # ── 核心 Elo 计算 ─────────────────────────────────────────────────────────
+
+    def get_rating(self, team: str) -> float:
+        key = team.lower().strip()
+        if key in self._ratings:
+            return self._ratings[key]
+        # 尝试 FIFA 排名推算
+        for stored_key, rank in _FIFA_RANKING.items():
+            if stored_key in key or key in stored_key:
+                return ranking_to_elo(rank)
+        return _DEFAULT_ELO
+
+    def expected_score(
+        self,
+        rating_a: float,
+        rating_b: float,
+        home_advantage: float = 100.0,
+    ) -> float:
+        """E_A = 1 / (1 + 10^((Rb - Ra - home_adv) / 400))"""
+        return 1.0 / (1.0 + 10.0 ** ((rating_b - rating_a - home_advantage) / 400.0))
+
+    def update(
+        self,
+        home_team: str,
+        away_team: str,
+        home_goals: int,
+        away_goals: int,
+        match_type: str = "default",
+        neutral_venue: bool = False,
+    ) -> Tuple[float, float]:
+        """
+        用一场赛果更新双方 Elo 评分。
+        返回 (home_delta, away_delta)。
+        """
+        k = _K_FACTORS.get(match_type, _K_FACTORS["default"])
+        home_adv = 0.0 if neutral_venue else 100.0
+
+        ra = self.get_rating(home_team)
+        rb = self.get_rating(away_team)
+
+        ea = self.expected_score(ra, rb, home_adv)
+        eb = 1.0 - ea
+
+        if home_goals > away_goals:
+            wa, wb = 1.0, 0.0
+        elif home_goals == away_goals:
+            wa, wb = 0.5, 0.5
+        else:
+            wa, wb = 0.0, 1.0
+
+        # 进球差加成（World Football Elo 标准公式）
+        # GD=1→×1.0, GD=2→×1.5, GD=3→×1.75, GD=6→×2.125, 上限 2.5
+        goal_diff = abs(home_goals - away_goals)
+        if goal_diff <= 1:
+            gd_mult = 1.0
+        elif goal_diff == 2:
+            gd_mult = 1.5
+        else:
+            gd_mult = min(2.5, (11 + goal_diff) / 8.0)
+
+        da = round(k * gd_mult * (wa - ea), 2)
+        db = round(k * gd_mult * (wb - eb), 2)
+
+        h_key = home_team.lower().strip()
+        a_key = away_team.lower().strip()
+        self._ratings[h_key] = round(ra + da, 1)
+        self._ratings[a_key] = round(rb + db, 1)
+
+        self._match_log.append({
+            "home": h_key, "away": a_key,
+            "score": f"{home_goals}-{away_goals}",
+            "type": match_type, "da": da, "db": db,
+        })
+        return da, db
+
+    def win_probability(
+        self,
+        home_team: str,
+        away_team: str,
+        neutral_venue: bool = True,
+    ) -> Dict[str, float]:
+        """
+        基于 Elo 差距计算胜/平/负概率。
+        使用 Dixon & Robinson (1998) 的转换公式。
+        """
+        home_adv = 0.0 if neutral_venue else 100.0
+        ra = self.get_rating(home_team)
+        rb = self.get_rating(away_team)
+
+        e_home = self.expected_score(ra, rb, home_adv)
+        diff = ra + home_adv - rb
+
+        # 平局概率：差距越大平局越少
+        # 经验公式：draw_prob ≈ 0.30 * exp(-|diff| / 720)
+        draw_base = 0.295 * math.exp(-abs(diff) / 720.0)
+        draw_base = max(0.04, min(draw_base, 0.295))
+
+        home_win = e_home * (1.0 - draw_base / 2)
+        away_win = (1.0 - e_home) * (1.0 - draw_base / 2)
+        draw = 1.0 - home_win - away_win
+        draw = max(0.04, draw)
+
+        total = home_win + draw + away_win
+        return {
+            "home_win": round(home_win / total, 4),
+            "draw":     round(draw / total, 4),
+            "away_win": round(away_win / total, 4),
+            "home_elo": round(ra, 0),
+            "away_elo": round(rb, 0),
+            "elo_diff": round(ra + home_adv - rb, 0),
+        }
+
+    def get_attack_defense(self, team: str, base_avg: float = 1.35) -> Dict[str, float]:
+        """
+        从 Elo 评分推导 attack / defense 参数供泊松模型使用。
+        斜率参数优先从 calibrator 读取（自动优化），不存在则用默认值。
+
+        标定默认目标:
+          Elo 2050 (阿根廷) → attack≈2.50, defense≈0.42
+          Elo 1912 (德国)   → attack≈3.01, defense≈0.42
+          Elo 1800 (日本)   → attack≈1.75, defense≈0.65
+          Elo 1500 (平均)   → attack≈1.10, defense≈0.95
+          Elo 1200 (弱队)   → attack≈0.62, defense≈1.22
+        """
+        elo = self.get_rating(team)
+        si  = (elo - 1500) / 400.0
+
+        # 读取自动校准斜率（若无则用默认值）
+        a1, a2, d1, d2 = 1.05, 0.35, -0.42, -0.10
+        try:
+            from .calibrator import get_calibrated_params
+            p  = get_calibrated_params()
+            a1 = p.get("a1", a1)
+            a2 = p.get("a2", a2)
+            d1 = p.get("d1", d1)
+            d2 = p.get("d2", d2)
+        except Exception:
+            pass
+
+        attack  = 1.10 + si * a1 + max(0, si) * si * a2
+        defense = 0.95 + si * d1 + max(0, si) * si * d2
+
+        attack  = max(0.45, min(attack,  2.60))
+        defense = max(0.40, min(defense, 1.25))
+        return {
+            "attack":  round(attack, 3),
+            "defense": round(defense, 3),
+            "elo":     round(elo, 0),
+        }
+
+    # ── 持久化 ────────────────────────────────────────────────────────────────
+
+    def save(self) -> None:
+        try:
+            self._STORE_PATH.parent.mkdir(parents=True, exist_ok=True)
+            with open(self._STORE_PATH, "w", encoding="utf-8") as f:
+                json.dump({
+                    "ratings": self._ratings,
+                    "match_count": len(self._match_log),
+                }, f, ensure_ascii=False, indent=2)
+        except Exception:
+            pass
+
+    def _load(self) -> None:
+        try:
+            if self._STORE_PATH.exists():
+                data = json.loads(self._STORE_PATH.read_text(encoding="utf-8"))
+                self._ratings = data.get("ratings", {})
+        except Exception:
+            self._ratings = {}
+
+    def top_n(self, n: int = 10) -> list:
+        """返回评分最高的 n 支队伍。"""
+        return sorted(self._ratings.items(), key=lambda x: -x[1])[:n]
+
+
+_elo_instance: Optional[EloRatingSystem] = None
+
+
+def get_elo() -> EloRatingSystem:
+    global _elo_instance
+    if _elo_instance is None:
+        _elo_instance = EloRatingSystem()
+    return _elo_instance

packages/quant_engine/sports/form.py

@@ -0,0 +1,188 @@
+"""
+sports/form.py — 球队近期状态分析
+===================================
+用指数衰减权重分析近 N 场比赛，
+动态调整攻守参数，捕捉球队当前状态。
+
+状态因子 (form_factor) 定义:
+    - 近5场全胜 → 1.12（上调 12%）
+    - 近5场全败 → 0.88（下调 12%）
+    - 近5场持平 → 1.00
+    - 中间值线性插值
+
+影响方式:
+    attack_adjusted  = attack_base  * form_factor_attack
+    defense_adjusted = defense_base * form_factor_defense
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Dict, List, Optional, Tuple
+
+
+def _decay_weight(match_index: int, total: int, decay: float = 0.85) -> float:
+    """
+    越近期的比赛权重越高。
+    match_index=0 是最新一场，match_index=total-1 是最早一场。
+    """
+    return decay ** match_index
+
+
+def analyze_form(
+    results: List[Dict],
+    n: int = 6,
+    decay: float = 0.85,
+) -> Dict:
+    """
+    分析球队近期状态。
+
+    Args:
+        results: 近期比赛结果列表，每项格式:
+                 {"is_win": bool, "is_draw": bool, "goals_for": int,
+                  "goals_against": int, "is_home": bool}
+                 按时间倒序（最新在前）。
+        n:       分析最近 n 场（默认6场）。
+        decay:   指数衰减系数（0.85 → 最新权重是最早的 0.85^5 ≈ 44%）。
+
+    Returns:
+        {
+            "form_string": "WWDLW",
+            "weighted_win_rate": float,
+            "form_factor_attack": float,
+            "form_factor_defense": float,
+            "avg_goals_for": float,
+            "avg_goals_against": float,
+            "momentum": str,  # "rising" | "declining" | "stable"
+        }
+    """
+    recent = results[:n]
+    if not recent:
+        return _neutral_form()
+
+    total_weight = 0.0
+    weighted_wins = 0.0
+    weighted_draws = 0.0
+    weighted_gf = 0.0
+    weighted_ga = 0.0
+    form_chars = []
+
+    for i, m in enumerate(recent):
+        w = _decay_weight(i, len(recent), decay)
+        total_weight += w
+        if m.get("is_win"):
+            weighted_wins += w
+            form_chars.append("W")
+        elif m.get("is_draw"):
+            weighted_draws += w
+            form_chars.append("D")
+        else:
+            form_chars.append("L")
+        weighted_gf += w * m.get("goals_for", 1.0)
+        weighted_ga += w * m.get("goals_against", 1.0)
+
+    if total_weight <= 0:
+        return _neutral_form()
+
+    w_win_rate  = weighted_wins  / total_weight
+    avg_gf      = weighted_gf    / total_weight
+    avg_ga      = weighted_ga    / total_weight
+
+    # 攻击状态因子：进球越多上调越多
+    # 基准：1.35进球/场=1.0，每±0.35调整±0.08
+    gf_baseline = 1.35
+    form_attack = 1.0 + (avg_gf - gf_baseline) / gf_baseline * 0.12
+    form_attack = max(0.82, min(form_attack, 1.18))
+
+    # 防守状态因子：失球越少上调越多
+    # 注意：defense 参数越小代表越强（对手进球少），失球少→factor下调（防守更好）
+    ga_baseline = 1.20
+    form_defense = 1.0 - (avg_ga - ga_baseline) / ga_baseline * 0.10
+    form_defense = max(0.85, min(form_defense, 1.15))
+
+    # 势头分析（对比前半段 vs 后半段胜率）
+    half = max(1, len(recent) // 2)
+    recent_half_wins  = sum(1 for m in recent[:half] if m.get("is_win"))
+    earlier_half_wins = sum(1 for m in recent[half:] if m.get("is_win"))
+    if recent_half_wins > earlier_half_wins:
+        momentum = "rising"
+    elif recent_half_wins < earlier_half_wins:
+        momentum = "declining"
+    else:
+        momentum = "stable"
+
+    return {
+        "form_string":         "".join(form_chars),
+        "weighted_win_rate":   round(w_win_rate, 3),
+        "form_factor_attack":  round(form_attack, 3),
+        "form_factor_defense": round(form_defense, 3),
+        "avg_goals_for":       round(avg_gf, 2),
+        "avg_goals_against":   round(avg_ga, 2),
+        "momentum":            momentum,
+        "matches_analyzed":    len(recent),
+    }
+
+
+def _neutral_form() -> Dict:
+    return {
+        "form_string":         "?????",
+        "weighted_win_rate":   0.5,
+        "form_factor_attack":  1.0,
+        "form_factor_defense": 1.0,
+        "avg_goals_for":       1.35,
+        "avg_goals_against":   1.20,
+        "momentum":            "stable",
+        "matches_analyzed":    0,
+    }
+
+
+def parse_api_results(matches: List[Dict], team_name: str) -> List[Dict]:
+    """
+    将 football-data.org API 返回的比赛记录转换为 form 分析格式。
+
+    team_name: 用于判断主客队角色（小写）
+    """
+    parsed = []
+    for m in matches:
+        ft = m.get("score", {}).get("fullTime", {})
+        home_team = (m.get("homeTeam") or {}).get("name", "").lower()
+        away_team = (m.get("awayTeam") or {}).get("name", "").lower()
+        home_goals = ft.get("home")
+        away_goals = ft.get("away")
+        if home_goals is None or away_goals is None:
+            continue
+
+        team_low = team_name.lower()
+        is_home = team_low in home_team
+
+        if is_home:
+            gf, ga = int(home_goals), int(away_goals)
+        else:
+            gf, ga = int(away_goals), int(home_goals)
+
+        is_win  = gf > ga
+        is_draw = gf == ga
+
+        parsed.append({
+            "is_win":          is_win,
+            "is_draw":         is_draw,
+            "is_home":         is_home,
+            "goals_for":       gf,
+            "goals_against":   ga,
+            "date":            m.get("utcDate", ""),
+        })
+
+    # 按日期倒序（最新在前）
+    parsed.sort(key=lambda x: x.get("date", ""), reverse=True)
+    return parsed
+
+
+def form_bar(form_string: str) -> str:
+    """近期状态可视化条。"""
+    _MAP = {"W": "●", "D": "◑", "L": "○"}
+    return " ".join(_MAP.get(c, "?") for c in form_string[:6])
+
+
+def momentum_label(momentum: str) -> str:
+    _LABELS = {"rising": "↑ 上升", "declining": "↓ 下滑", "stable": "→ 平稳"}
+    return _LABELS.get(momentum, "?")

packages/quant_engine/sports/h2h.py

@@ -0,0 +1,195 @@
+"""
+sports/h2h.py — 历史交锋 (Head-to-Head) 分析与调整
+===================================================
+分析两队历史对阵记录，提供调整系数。
+
+理论依据：
+  某些队伍存在"心理/战术克制"效应，超出 Elo 差距能解释的范围。
+  H2H 调整系数在实际市场定价中通常权重约 8-12%。
+
+调整范围：
+  h2h_advantage: -0.08 ~ +0.08（相对于主队/队1）
+  代入预测公式：lambda_home *= (1 + h2h_advantage)
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Dict, List, Optional, Tuple
+
+
+def analyze_h2h(
+    matches: List[Dict],
+    team1: str,
+    team2: str,
+    max_matches: int = 10,
+    decay: float = 0.90,
+) -> Dict:
+    """
+    分析两队历史交锋记录。
+
+    Args:
+        matches:     比赛记录列表（football-data.org 格式）
+        team1:       队1名称（通常是"主队"或查询方）
+        team2:       队2名称
+        max_matches: 最多分析 N 场
+        decay:       时间衰减系数
+
+    Returns:
+        {
+            "total_matches": int,
+            "team1_wins": int,
+            "draws": int,
+            "team2_wins": int,
+            "team1_goals": int,
+            "team2_goals": int,
+            "h2h_advantage": float,   # team1 相对优势 (-0.08 ~ +0.08)
+            "win_rate_team1": float,
+            "dominant_team": str,
+            "summary": str,
+        }
+    """
+    if not matches:
+        return _neutral_h2h(team1, team2)
+
+    t1_low = team1.lower()
+    t2_low = team2.lower()
+
+    results = []
+    for m in matches[:max_matches]:
+        ht = (m.get("homeTeam") or {}).get("name", "").lower()
+        at = (m.get("awayTeam") or {}).get("name", "").lower()
+        ft = m.get("score", {}).get("fullTime", {})
+        hg = ft.get("home")
+        ag = ft.get("away")
+        if hg is None or ag is None:
+            continue
+
+        t1_is_home = t1_low in ht
+        if t1_is_home:
+            t1g, t2g = int(hg), int(ag)
+        else:
+            t1g, t2g = int(ag), int(hg)
+
+        results.append({
+            "t1_goals": t1g, "t2_goals": t2g,
+            "date": m.get("utcDate", ""),
+        })
+
+    if not results:
+        return _neutral_h2h(team1, team2)
+
+    results.sort(key=lambda x: x.get("date", ""), reverse=True)
+
+    total_w   = 0.0
+    t1_win_w  = 0.0
+    draw_w    = 0.0
+    t2_win_w  = 0.0
+    t1_goals  = 0
+    t2_goals  = 0
+    t1_wins = draws = t2_wins = 0
+
+    for i, r in enumerate(results):
+        w = decay ** i
+        total_w += w
+        t1g, t2g = r["t1_goals"], r["t2_goals"]
+        t1_goals += t1g
+        t2_goals += t2g
+        if t1g > t2g:
+            t1_win_w += w
+            t1_wins += 1
+        elif t1g == t2g:
+            draw_w += w
+            draws += 1
+        else:
+            t2_win_w += w
+            t2_wins += 1
+
+    if total_w <= 0:
+        return _neutral_h2h(team1, team2)
+
+    t1_wr = t1_win_w / total_w
+    t2_wr = t2_win_w / total_w
+
+    # H2H 优势调整系数：偏离0.5的部分映射到 ±0.08
+    # t1_wr=1.0 → +0.08, t1_wr=0.5 → 0.0, t1_wr=0.0 → -0.08
+    h2h_adv = (t1_wr - 0.5) * 0.16
+    h2h_adv = max(-0.08, min(h2h_adv, 0.08))
+
+    n = len(results)
+    if t1_wins > t2_wins + 1:
+        dominant = team1
+    elif t2_wins > t1_wins + 1:
+        dominant = team2
+    else:
+        dominant = "平分秋色"
+
+    summary = (
+        f"{team1} {t1_wins}胜 {draws}平 {t2_wins}负 "
+        f"({t1_goals}:{t2_goals}) "
+        f"近{n}场"
+    )
+
+    return {
+        "total_matches":  n,
+        "team1_wins":     t1_wins,
+        "draws":          draws,
+        "team2_wins":     t2_wins,
+        "team1_goals":    t1_goals,
+        "team2_goals":    t2_goals,
+        "h2h_advantage":  round(h2h_adv, 4),
+        "win_rate_team1": round(t1_wr, 3),
+        "dominant_team":  dominant,
+        "summary":        summary,
+    }
+
+
+def _neutral_h2h(team1: str, team2: str) -> Dict:
+    return {
+        "total_matches":  0,
+        "team1_wins":     0,
+        "draws":          0,
+        "team2_wins":     0,
+        "team1_goals":    0,
+        "team2_goals":    0,
+        "h2h_advantage":  0.0,
+        "win_rate_team1": 0.5,
+        "dominant_team":  "数据不足",
+        "summary":        f"{team1} vs {team2} — 无历史数据",
+    }
+
+
+def fetch_h2h_from_api(
+    home_team: str,
+    away_team: str,
+    api_get_fn,
+    limit: int = 10,
+) -> List[Dict]:
+    """
+    从 football-data.org API 获取历史交锋数据（需要 API key）。
+    api_get_fn: 封装好的 GET 函数，如 football_data_client._get()
+    """
+    try:
+        data = api_get_fn("/teams", {"name": home_team})
+        if not data:
+            return []
+        teams = data.get("teams", [])
+        if not teams:
+            return []
+        team_id = teams[0]["id"]
+
+        h2h_data = api_get_fn(f"/teams/{team_id}/matches", {
+            "competitions": "WC,CL,PL,BL1,SA,FL1,PD",
+            "limit": str(limit),
+        })
+        if not h2h_data:
+            return []
+        matches = h2h_data.get("matches", [])
+        at_low = away_team.lower()
+        return [
+            m for m in matches
+            if at_low in (m.get("homeTeam") or {}).get("name", "").lower()
+            or at_low in (m.get("awayTeam") or {}).get("name", "").lower()
+        ]
+    except Exception:
+        return []