korb 0.3.1__tar.gz → 0.3.2__tar.gz

{korb-0.3.1 → korb-0.3.2}/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.3.2] — 2026-10-25
+
+### Added
+
+- `backtest` command with chronological winner accuracy, Brier score,
+  score MAE, and score RMSE.
+- Per-game win probabilities in text and JSON predictions.
+- Opponent-adjusted offensive and defensive ratings via weighted ridge
+  regression.
+- Fitted home advantage with a 3% prior and fitted score volatility.
+
+### Changed
+
+- Prediction ratings are now additive strength coefficients converted
+  to the multiplicative score model.
+- Recent form uses opponent-adjusted residuals instead of raw scoring.
+- Removed the hard three-game rating cutoff; ridge regularization
+  handles thin samples.
+- Split the prediction code into `model.py`, `predict.py`, and
+  `backtest.py`.
+
 ## [0.3.1] — 2026-10-25
 
 ### Changed

{korb-0.3.1 → korb-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: korb
-Version: 0.3.1
+Version: 0.3.2
 Summary: A CLI toolkit for DBB basketball league analysis
 Project-URL: Homepage, https://github.com/malvavisc0/korb
 Project-URL: Repository, https://github.com/malvavisc0/korb
@@ -47,8 +47,10 @@ platform and provides standings, results, schedules, predictions, and more.
 - 🏀 **Team** — game-by-game results, sparklines, quality metrics
 - 📋 **Ergebnisse** — all completed game results with optional team filter
 - 📅 **Schedule** — with back-to-back detection, filtering, pending games
-- 🔮 **Predict** — efficiency-model-based final standings forecast
+- 🔮 **Predict** — opponent-adjusted final standings forecast with
+  win probabilities
 - 🥇 **Top** — quick leaderboard with ASCII bar chart
+- 🧪 **Backtest** — chronological holdout metrics for the prediction model
 - 📥 **Download** — fetch fresh HTML data directly from basketball-bund.net
 - 🔧 **`--json`** — machine-readable output for data commands (not `download`)
 
@@ -131,8 +133,19 @@ uv run korb --ligaid 12345 schedule --team "Hawks" --pending --b2b
 
 ```bash
 uv run korb --ligaid 12345 predict
+uv run korb --ligaid 12345 --json predict
 ```
 
+### `backtest` — Evaluate the prediction model
+
+```bash
+uv run korb --ligaid 12345 backtest
+uv run korb --ligaid 12345 backtest --min-train 10
+```
+
+Trains on each game's prior results only and reports winner accuracy,
+Brier score, score MAE, and score RMSE.
+
 ### `top` — Quick leaderboard
 
 ```bash
@@ -152,18 +165,22 @@ uv run korb --ligaid 12345 top -n 5
 
 ## How Predictions Work
 
-The `predict` command estimates final standings using a **multiplicative efficiency model**:
+The `predict` command fits opponent-adjusted ratings and converts them
+into a **multiplicative efficiency model**:
 
 | Factor | How it works |
 |---|---|
-| **Offensive rating** | Team's scored points vs. league average (>1.0 = above avg) |
-| **Defensive rating** | Points allowed vs. league average (>1.0 = worse defense) |
+| **Opponent adjustment** | Weighted ridge regression on point differentials |
+| **Offensive rating** | Adjusted scoring strength relative to league average (>1.0 = above avg) |
+| **Defensive rating** | Adjusted points allowed relative to league average (>1.0 = worse defense) |
 | **Recency weighting** | 60-day half-life — recent games count more |
-| **Recent form** | Last 5 games blended at 30% weight into ratings |
-| **Home advantage** | 3% scoring boost applied symmetrically |
+| **Recent form** | Last 5 opponent-adjusted residuals blended at 30% weight |
+| **Regularization** | Ridge shrinkage replaces the hard 3-game cutoff |
+| **Home advantage** | Fitted from results with a 3% prior |
+| **Win probability** | Normal margin model using fitted score volatility |
 | **B2B fatigue** | ≤36h between games → 5% offense/defense penalty |
-| **New teams** | <3 games → ratings blended toward league average |
-| **No draws** | Ties broken by home advantage (basketball has OT) |
+| **No draws** | The higher win probability decides ties |
+| **Backtest** | `backtest` evaluates the model chronologically |
 
 ## Data Notes
 
@@ -177,10 +194,12 @@ The `predict` command estimates final standings using a **multiplicative efficie
 korb/
 ├── __init__.py      # Package marker & version
 ├── __main__.py      # CLI entry point & command handlers
+├── backtest.py      # Chronological model evaluation
 ├── core.py          # Shared models, HTML parsing, utilities
 ├── download.py      # HTTP downloader, headers, rate limiting
 ├── ergebnisse.py    # Game results viewer & filter
-├── predict.py       # Multiplicative efficiency prediction model
+├── model.py         # Opponent-adjusted ratings & score model
+├── predict.py       # Final standings orchestration & output
 ├── schedule.py      # HTML schedule parser & filters
 ├── standings.py     # Standings calculator
 └── team.py          # Team results viewer & metrics

{korb-0.3.1 → korb-0.3.2}/README.md

@@ -21,8 +21,10 @@ platform and provides standings, results, schedules, predictions, and more.
 - 🏀 **Team** — game-by-game results, sparklines, quality metrics
 - 📋 **Ergebnisse** — all completed game results with optional team filter
 - 📅 **Schedule** — with back-to-back detection, filtering, pending games
-- 🔮 **Predict** — efficiency-model-based final standings forecast
+- 🔮 **Predict** — opponent-adjusted final standings forecast with
+  win probabilities
 - 🥇 **Top** — quick leaderboard with ASCII bar chart
+- 🧪 **Backtest** — chronological holdout metrics for the prediction model
 - 📥 **Download** — fetch fresh HTML data directly from basketball-bund.net
 - 🔧 **`--json`** — machine-readable output for data commands (not `download`)
 
@@ -105,8 +107,19 @@ uv run korb --ligaid 12345 schedule --team "Hawks" --pending --b2b
 
 ```bash
 uv run korb --ligaid 12345 predict
+uv run korb --ligaid 12345 --json predict
 ```
 
+### `backtest` — Evaluate the prediction model
+
+```bash
+uv run korb --ligaid 12345 backtest
+uv run korb --ligaid 12345 backtest --min-train 10
+```
+
+Trains on each game's prior results only and reports winner accuracy,
+Brier score, score MAE, and score RMSE.
+
 ### `top` — Quick leaderboard
 
 ```bash
@@ -126,18 +139,22 @@ uv run korb --ligaid 12345 top -n 5
 
 ## How Predictions Work
 
-The `predict` command estimates final standings using a **multiplicative efficiency model**:
+The `predict` command fits opponent-adjusted ratings and converts them
+into a **multiplicative efficiency model**:
 
 | Factor | How it works |
 |---|---|
-| **Offensive rating** | Team's scored points vs. league average (>1.0 = above avg) |
-| **Defensive rating** | Points allowed vs. league average (>1.0 = worse defense) |
+| **Opponent adjustment** | Weighted ridge regression on point differentials |
+| **Offensive rating** | Adjusted scoring strength relative to league average (>1.0 = above avg) |
+| **Defensive rating** | Adjusted points allowed relative to league average (>1.0 = worse defense) |
 | **Recency weighting** | 60-day half-life — recent games count more |
-| **Recent form** | Last 5 games blended at 30% weight into ratings |
-| **Home advantage** | 3% scoring boost applied symmetrically |
+| **Recent form** | Last 5 opponent-adjusted residuals blended at 30% weight |
+| **Regularization** | Ridge shrinkage replaces the hard 3-game cutoff |
+| **Home advantage** | Fitted from results with a 3% prior |
+| **Win probability** | Normal margin model using fitted score volatility |
 | **B2B fatigue** | ≤36h between games → 5% offense/defense penalty |
-| **New teams** | <3 games → ratings blended toward league average |
-| **No draws** | Ties broken by home advantage (basketball has OT) |
+| **No draws** | The higher win probability decides ties |
+| **Backtest** | `backtest` evaluates the model chronologically |
 
 ## Data Notes
 
@@ -151,10 +168,12 @@ The `predict` command estimates final standings using a **multiplicative efficie
 korb/
 ├── __init__.py      # Package marker & version
 ├── __main__.py      # CLI entry point & command handlers
+├── backtest.py      # Chronological model evaluation
 ├── core.py          # Shared models, HTML parsing, utilities
 ├── download.py      # HTTP downloader, headers, rate limiting
 ├── ergebnisse.py    # Game results viewer & filter
-├── predict.py       # Multiplicative efficiency prediction model
+├── model.py         # Opponent-adjusted ratings & score model
+├── predict.py       # Final standings orchestration & output
 ├── schedule.py      # HTML schedule parser & filters
 ├── standings.py     # Standings calculator
 └── team.py          # Team results viewer & metrics

{korb-0.3.1 → korb-0.3.2}/docs/coding-standard.md

@@ -126,9 +126,9 @@ Write the simplest correct solution. Delete anything that isn't needed.
   `set_defaults(func=cmd_<name>)`. Global flags are `--results`,
   `--schedule`, `--json`, `--ligaid`, `--download`.
 - Feature modules sit next to the CLI (`standings.py`, `team.py`,
-  `schedule.py`, `predict.py`, `ergebnisse.py`, `download.py`); shared
-  models, HTML parsing, date/score helpers, and output headers live in
-  `core.py`.
+  `schedule.py`, `model.py`, `predict.py`, `backtest.py`,
+  `ergebnisse.py`, `download.py`); shared models, HTML parsing,
+  date/score helpers, and output headers live in `core.py`.
 - HTML parsing extends the shared public `DBBRowParser`
   (`<td>`/`<tr>`/`<strike>` state machine). Parser changes need a
   fixture in `tests/fixtures/` and a test; cover cancelled rows
@@ -136,8 +136,8 @@ Write the simplest correct solution. Delete anything that isn't needed.
 - Parsers return `(data, LeagueInfo)`. Every data command's `--json`
   response is a wrapped object built with `_liga_meta(...)` plus a
   named data key: `standings`, `results` (team), `ergebnisse`,
-  `schedule`, `predictions`, and `top`. `download` is a side-effect
-  command and emits no JSON.
+  `schedule`, `predictions`, `backtest`, and `top`. `download` is a
+  side-effect command and emits no JSON.
 - Data paths resolve as `files/<ligaid>/ergebnisse.html` and
   `files/<ligaid>/spielplan.html`; explicit `--results` / `--schedule`
   win. Use `_resolve_results` / `_resolve_schedule`, not ad hoc paths.

{korb-0.3.1 → korb-0.3.2}/korb/__init__.py

@@ -3,4 +3,4 @@
 Target: DBB Version ≤12.01.1-f733da5 (legacy JSP platform).
 """
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"

{korb-0.3.1 → korb-0.3.2}/korb/__main__.py

@@ -10,10 +10,17 @@ import sys
 from pathlib import Path
 
 from . import __version__
+from .backtest import DEFAULT_MIN_TRAIN, backtest, print_backtest
 from .core import LeagueInfo, read_games
 from .download import discover_league_ids, download_league, wait_between_requests
 from .ergebnisse import filter_ergebnisse, print_ergebnisse
-from .predict import predict_standings, print_predicted_standings, print_predictions
+from .predict import (
+    PredictionError,
+    format_prediction,
+    predict_standings,
+    print_predicted_standings,
+    print_predictions,
+)
 from .schedule import b2b_flags, filter_schedule, parse_schedule, print_schedule
 from .standings import Standing, calculate_standings, print_table
 from .team import get_team_results, print_bars, print_metrics, print_results
@@ -174,7 +181,11 @@ def cmd_predict(args: argparse.Namespace) -> None:
     rp = _resolve_results(args, "prediction results")
     sp = _resolve_schedule(args, "prediction schedule")
 
-    standings, preds, league_info = predict_standings(rp, sp)
+    try:
+        standings, preds, league_info = predict_standings(rp, sp)
+    except PredictionError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
     if not preds:
         print(
             "Error: Season is finalized (no pending games). "
@@ -186,16 +197,7 @@ def cmd_predict(args: argparse.Namespace) -> None:
         _json_out(
             {
                 **_liga_meta(league_info, args.ligaid),
-                "predictions": [
-                    {
-                        "home": g.home,
-                        "away": g.away,
-                        "winner": w,
-                        "home_score": hs,
-                        "away_score": aws,
-                    }
-                    for g, w, hs, aws in preds
-                ],
+                "predictions": [format_prediction(pred) for pred in preds],
                 "standings": [s.to_dict() for s in standings],
             }
         )
@@ -204,6 +206,21 @@ def cmd_predict(args: argparse.Namespace) -> None:
         print_predicted_standings(standings)
 
 
+def cmd_backtest(args: argparse.Namespace) -> None:
+    """Handle 'backtest' subcommand."""
+    fp = _resolve_results(args, "backtest")
+    result, league_info = backtest(fp, min_train_games=args.min_train)
+    if args.json:
+        _json_out(
+            {
+                **_liga_meta(league_info, args.ligaid),
+                "backtest": result.to_dict(),
+            }
+        )
+    else:
+        print_backtest(result)
+
+
 def _blocks(value: int, scale: int) -> str:
     return "█" * max(0, value // scale)
 
@@ -404,6 +421,18 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     p_pr.set_defaults(func=cmd_predict)
 
+    p_bt = subs.add_parser(
+        "backtest",
+        help="Backtest the prediction model on completed games",
+    )
+    p_bt.add_argument(
+        "--min-train",
+        type=_positive_int,
+        default=DEFAULT_MIN_TRAIN,
+        help=f"Minimum prior games before evaluating (default: {DEFAULT_MIN_TRAIN})",
+    )
+    p_bt.set_defaults(func=cmd_backtest)
+
     p_top = subs.add_parser(
         "top",
         help="Show top teams from standings",

korb-0.3.2/korb/backtest.py

@@ -0,0 +1,150 @@
+"""Chronological backtesting for the prediction model."""
+
+from dataclasses import dataclass
+from math import sqrt
+
+from korb.core import Game, LeagueInfo, read_games
+from korb.model import (
+    FATIGUE_THRESHOLD_H,
+    Winner,
+    fatigue,
+    fit_model,
+    game_times,
+    predict_game,
+)
+
+DEFAULT_MIN_TRAIN = 5
+
+
+@dataclass(frozen=True)
+class BacktestResult:
+    """Chronological holdout metrics for the prediction model."""
+
+    games: int
+    winner_games: int
+    winner_accuracy: float
+    brier: float
+    score_mae: float
+    score_rmse: float
+
+    def to_dict(self) -> dict[str, object]:
+        """Serializable metrics."""
+        return {
+            "games": self.games,
+            "winner_games": self.winner_games,
+            "winner_accuracy": round(self.winner_accuracy, 4),
+            "brier": round(self.brier, 4),
+            "score_mae": round(self.score_mae, 2),
+            "score_rmse": round(self.score_rmse, 2),
+        }
+
+
+def _actual_home_win(game: Game) -> float | None:
+    if game.home_score > game.away_score:
+        return 1.0
+    if game.home_score < game.away_score:
+        return 0.0
+    return None
+
+
+def _predict_historical(
+    game: Game, prior: list[Game]
+) -> tuple[Winner, int, int, float] | None:
+    model = fit_model(prior)
+    if game.home not in model.ratings or game.away not in model.ratings:
+        return None
+    times = game_times(prior)
+    timestamp = game.date.timestamp()
+    threshold_s = FATIGUE_THRESHOLD_H * 3600
+    return predict_game(
+        game.home,
+        game.away,
+        model.ratings,
+        model.league_avg,
+        home_fatigue=fatigue(game.home, timestamp, times, threshold_s),
+        away_fatigue=fatigue(game.away, timestamp, times, threshold_s),
+        home_advantage=model.home_advantage,
+        sigma=model.sigma,
+    )
+
+
+def backtest(
+    results_path: str,
+    min_train_games: int = DEFAULT_MIN_TRAIN,
+) -> tuple[BacktestResult, LeagueInfo]:
+    """Evaluate the model chronologically on completed games."""
+    games, league_info = read_games(results_path)
+    games = sorted(
+        (game for game in games if not game.forfeit),
+        key=lambda game: game.date,
+    )
+
+    evaluated = 0
+    winner_games = 0
+    correct = 0
+    brier = 0.0
+    absolute_errors: list[float] = []
+    squared_errors: list[float] = []
+
+    for index, game in enumerate(games):
+        prior = games[:index]
+        if len(prior) < min_train_games:
+            continue
+        prediction = _predict_historical(game, prior)
+        if prediction is None:
+            continue
+        winner, home_score, away_score, home_probability = prediction
+
+        evaluated += 1
+        absolute_errors.extend(
+            [
+                abs(home_score - game.home_score),
+                abs(away_score - game.away_score),
+            ]
+        )
+        squared_errors.extend(
+            [
+                float((home_score - game.home_score) ** 2),
+                float((away_score - game.away_score) ** 2),
+            ]
+        )
+
+        actual_home = _actual_home_win(game)
+        if actual_home is not None:
+            winner_games += 1
+            correct += int((winner == "home") == (actual_home == 1.0))
+            brier += (home_probability - actual_home) ** 2
+
+    if not evaluated:
+        return BacktestResult(0, 0, 0.0, 0.0, 0.0, 0.0), league_info
+
+    return (
+        BacktestResult(
+            games=evaluated,
+            winner_games=winner_games,
+            winner_accuracy=correct / winner_games if winner_games else 0.0,
+            brier=brier / winner_games if winner_games else 0.0,
+            score_mae=sum(absolute_errors) / len(absolute_errors),
+            score_rmse=sqrt(sum(squared_errors) / len(squared_errors)),
+        ),
+        league_info,
+    )
+
+
+def print_backtest(result: BacktestResult) -> None:
+    """Print backtest metrics."""
+    print("\n" + "=" * 70)
+    print("  Prediction Backtest")
+    print("=" * 70)
+
+    if result.games == 0:
+        print("  Not enough completed games to backtest.")
+        return
+
+    print(f"  Games evaluated: {result.games}")
+    print(
+        f"  Winner accuracy: {result.winner_accuracy:.1%} ({result.winner_games} games)"
+    )
+    print(f"  Brier score: {result.brier:.4f}")
+    print(f"  Score MAE: {result.score_mae:.2f}")
+    print(f"  Score RMSE: {result.score_rmse:.2f}")