backcaster 0.4.2__tar.gz → 0.4.3__tar.gz

{backcaster-0.4.2/src/backcaster.egg-info → backcaster-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backcaster
-Version: 0.4.2
+Version: 0.4.3
 Summary: Marcel-style MLB projection CLI using local Lahman CSV data
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/jeffreywevans/backcaster
@@ -41,6 +41,7 @@ It supports:
 - **Single team projections** (`team`)
 - **League-wide projections** (`hitters`, `pitchers`, or `batch`)
 - Output as terminal table, CSV, or HTML
+- Historical comparisons against actual results in HTML reports (`--compare-actuals`)
 
 ---
 
@@ -59,10 +60,10 @@ Upgrade to the latest release available on PyPI:
 python -m pip install --upgrade backcaster
 ```
 
-To install a specific release, such as 0.4.2:
+To install a specific release, such as 0.4.3:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.4.2
+python -m pip install --upgrade backcaster==0.4.3
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -110,8 +111,8 @@ Subcommand-specific required options:
 - `batch`, `hitters`, and `pitchers` require no player or team option
 
 ```bash
-backcaster <player|team|batch> [subcommand-options] --year <YEAR> --kind <batting|pitching> [--format cli|csv|html] [--out PATH]
-backcaster <hitters|pitchers> --year <YEAR> [--data-dir PATH] [--format cli|csv|html] [--out PATH]
+backcaster <player|team|batch> [subcommand-options] --year <YEAR> --kind <batting|pitching> [--format cli|csv|html] [--compare-actuals] [--out PATH]
+backcaster <hitters|pitchers> --year <YEAR> [--data-dir PATH] [--format cli|csv|html] [--compare-actuals] [--out PATH]
 ```
 
 ### Pre-offseason league projections
@@ -131,7 +132,8 @@ backcaster hitters --year 2026 --format csv --out hitters_2026.csv
 backcaster pitchers --year 2026 --format csv --out pitchers_2026.csv
 ```
 
-`--year 2026` projects 2026 from 2023–2025; it never reads 2026 statistics.
+`--year 2026` projects 2026 from 2023–2025. It reads 2026 statistics only when
+`--compare-actuals` is selected for a historical HTML report.
 Both commands support `--data-dir`, `--format cli|csv|html`, and `--out`.
 They are shortcuts for `batch --kind batting` and `batch --kind pitching`.
 For a different data directory, add `--data-dir "C:\Baseball\lahman"`.
@@ -140,13 +142,21 @@ File formats require `--out`; the CLI format prints to the terminal and rejects
 `--out`. Invalid output options fail before data is loaded. Unwritable output
 paths report an error on stderr and exit with status 2.
 
-Players qualify for selection by meeting the existing PA/IP threshold in at least
-one of those three seasons. This is a historical eligibility list, not an active
-roster; pitchers who never reach the qualifying innings threshold (including most
-relievers) remain excluded. Qualification selects players without removing their
-other seasons from the calculation. Trades are combined into one player-season
-before qualification, and all teams' statistics contribute once. The output is
-one row per selected player, ready for comparison with reference projections.
+Exports must stay within the current working directory or its subdirectories.
+Relative paths and absolute paths within that directory are accepted; paths that
+escape it through `..` or symbolic links are rejected before data is loaded.
+To export elsewhere, run Backcaster from the intended output directory.
+
+Hitters receive a projection with any positive PA in the preceding three seasons,
+subject to usable ages and the existing non-pitcher classification. There is no
+minimum-PA or reliability gate. `ConfidenceTier` labels reliability at least 0.50
+as `core` and lower values as `low-sample`; both tiers appear in every output.
+Pitchers receive a projection with any recorded outs or batters faced in the
+lookback window, including relievers and appearances without an out. They use
+the same confidence labels, with no innings or reliability gate. All selected
+players use their available three-year history.
+Without a dated eligibility snapshot, this is a historical candidate population,
+including potentially retired or otherwise unavailable players.
 
 ### 1) Player projection
 
@@ -186,18 +196,24 @@ FanGraphs abbreviation `LAD`). A projection year needs the preceding three seaso
 is unavailable. If the directory or required files are missing, the command
 reports the missing file and directory; it never attempts an online fetch.
 
-Offline qualification uses a consistent modern rule across historical seasons:
-at least **3.1 PA per game** for hitters and **one inning per game** for pitchers.
-The season's game count is the maximum `G` in that year's `Teams.csv` records,
-so shortened seasons have lower thresholds. The PA threshold is rounded to the
-nearest integer (502 PA for 162 games, 186 PA for 60 games). This is an analytical filter, not a
-reconstruction of historical award eligibility or batting-title exceptions.
-Relievers generally do not qualify under this pitching rule.
+Batting inclusion requires positive lookback PA; pitching requires recorded outs
+or batters faced. Neither has a minimum seasonal workload or reliability cutoff.
+`season(..., qualified=True)` still exposes the historical PA/IP analytical filters
+for Python callers; projection commands do not apply them.
 
-Player stints are summed before qualification. Plate appearances are calculated
+Player stints are summed before projection. Plate appearances are calculated
 as `AB + BB + HBP + SF + SH`; missing/blank HBP, SF, and SH values count as zero.
 Blank numeric counting-stat cells are also treated as zero; use a dataset with
 complete records for the seasons you intend to project.
+
+Historical batting and pitching records with missing or invalid birth years are excluded with
+a stderr warning identifying the count and sample player IDs. Remaining players
+are still projected; no default age is substituted. An entirely unusable
+population produces a clear error. See [historical data caveats](docs/LAHMAN.md).
+Pitcher playing time is `0.5 × last-year IP + 0.1 × two-years-ago IP + 60`,
+with missing calendar years contributing zero. The third prior season still
+contributes to regression and reliability. See [the pitcher model](docs/PITCHER_MODEL.md).
+
 Pitching `IPouts` is divided by three for decimal innings, and `BFP` supplies
 batters faced. Lahman player IDs keep different players with the same name separate;
 ambiguous name lookups report the matching IDs. Select one with `--player-id`
@@ -207,18 +223,56 @@ instead of `--name`, for example:
 backcaster player --player-id bettsmo01 --year 2026 --kind batting
 ```
 
-IDs match Lahman `People.csv.playerID` exactly and retain the same qualification
+IDs match Lahman `People.csv.playerID` exactly and retain the same inclusion
 rules as name lookups.
 
-Batter league regression and rebaselining use all non-pitcher player-seasons;
-qualification selects the displayed players. Pitching retains its qualified-only
-baseline, with real-age performance adjustments documented in
-[the pitcher model](docs/PITCHER_MODEL.md). See [the batter model](docs/BATTER_MODEL.md) for the six-stage calculation,
-real-age adjustment, PA formula, and explicit rebaselining choices.
-Eligibility means qualifying in at least one of the three preceding seasons.
-For every selected player, projections use all available seasons in that window,
-including nonqualified seasons and seasons spent with other teams. For team selection, a traded player's full-season totals are assigned
-to the team in their latest stint for that season; this is not a current-roster forecast.
+Batter league regression and rebaselining use all positive-PA non-pitcher
+player-seasons. Output selection, including status snapshots, does not change
+that calculation. Pitcher regression likewise uses the full historical sample
+population, independently of roster, player, or team selection. See [the batter model](docs/BATTER_MODEL.md) and
+[the pitcher model](docs/PITCHER_MODEL.md).
+
+For every selected player, projections use all available seasons in the window,
+including seasons spent with other teams. Without a status snapshot, team
+selection uses historical last-stint membership for each season.
+
+### Dated player eligibility
+
+For a roster/status comparison, supply an explicit eligibility snapshot and date:
+
+```bash
+backcaster hitters --year 2025 --eligibility-file eligibility_2025.csv --as-of 2025-01-14 --format csv --out mlb_hitting_2025.csv
+```
+
+The CSV uses Lahman IDs and explicit inclusion decisions:
+
+```csv
+PlayerID,Year,AsOf,Eligible,Team
+troutmi01,2025,2025-01-14,true,ANA
+bettsmo01,2025,2025-01-14,true,LAN
+```
+
+Create these decisions from a roster/organization/free-agent/retirement source
+as of the stated date. `Eligible` must be true or false. Unlisted players and
+false rows are excluded; listed players still need a lookback sample (PA for
+hitters, outs or batters faced for pitchers) and a usable birth year. Eligibility
+never depends on reliability. The file can contain
+multiple years and dates; only the exact `Year` and `AsOf` match is used, with
+unique PlayerID values within that snapshot.
+
+Both flags are required together and apply to batting and pitching. For pitchers,
+use `backcaster pitchers` (or `--kind pitching`) with the same flags. Use separate
+snapshot files if inclusion decisions differ between hitting and pitching roles.
+`Team` is optional for league/player output and required for team output; it represents
+membership at the snapshot date, with blanks allowed for unassigned players.
+With a snapshot, team selection uses this membership rather than historical teams.
+Exports include `EligibilityAsOf`. The snapshot filters output only; league
+regression and rebaselining continue to use the full historical population.
+
+For the January 14, 2025 Baseball Reference comparison, supply a snapshot actually
+frozen to that date. Lahman history cannot reconstruct roster status on that date,
+and later performance or final career dates are not used to guess it. Matching
+504 benchmark rows requires the right status population as well as model inputs.
 
 ### 2) Team projection
 
@@ -285,7 +339,7 @@ true innings rather than the displayed notation.
 ### Tracked statistics and order
 
 All outputs put available Name, Year, Player ID, and Age metadata first, followed
-by these statistics in order and then Reliability:
+by these statistics in order and then Reliability and ConfidenceTier; snapshot-filtered output appends EligibilityAsOf:
 
 ```text
 Batters:  PA,AB,R,H,2B,3B,HR,RBI,SB,CS,BB,SO,BA,OBP,SLG,OPS,TB,GDP,HBP,SH,SF,IBB
@@ -314,6 +368,7 @@ or share as one file. No server, CDN, fonts, or internet connection are required
 ```powershell
 backcaster hitters --year 2025 --format html --out hitters_2025.html
 backcaster pitchers --year 2025 --format html --out pitchers_2025.html
+backcaster hitters --year 2025 --format html --compare-actuals --out hitters_accuracy_2025.html
 ```
 
 The first four columns are **Name, Year, Player ID, Age**, followed by counting
@@ -322,6 +377,7 @@ statistics and batting/pitching rates in a consistent order. The report includes
 - A player-count, projection-year, and projection-type summary.
 - Search across player names, IDs, and statistics.
 - Sortable column headings, with numeric sorting for statistics.
+- Optional historical accuracy rows with a per-player expand/collapse control.
 - A sticky name column/header and horizontal scrolling on narrow screens.
 - A reset control and print layout for browser printing or saving as PDF.
 
@@ -331,6 +387,43 @@ Search filters the visible rows; printing respects that current view. Without
 JavaScript, the complete table is still readable. See
 [HTML report customization](docs/HTML_REPORTS.md) for theme and column constants.
 
+### Compare projections with actual results (new in 0.4.3)
+
+Add `--compare-actuals` to a historical HTML report for either batters or pitchers:
+
+```powershell
+backcaster hitters --year 2025 --format html --compare-actuals --out hitters_accuracy_2025.html
+backcaster pitchers --year 2025 --format html --compare-actuals --out pitchers_accuracy_2025.html
+```
+
+For these examples, the local Lahman files must cover **2022–2024** for the
+projection and **2025** for the actual results, including target-year game counts
+in `Teams.csv`. Use `--data-dir` to select the dataset. The 1871–2025 edition can
+support a 2025 comparison; it cannot provide actual results for 2026.
+The option also works with `player`, `team`, and `batch`; it requires
+`--format html` and `--out` and is rejected for terminal or CSV output.
+
+Projection calculations use only the three preceding seasons. Target-season
+results are loaded afterward and matched by Lahman PlayerID, combining trade
+stints without requiring the player to meet a seasonal qualification threshold.
+Each projected player has two additional rows:
+
+- **Actual** shows the player's recorded target-season results.
+- **Variance** shows `actual - projected`, calculated before display rounding.
+  For example, 25 actual HR against 20 projected HR displays `+5`.
+
+Positive differences are green and negative differences are red. These colors
+indicate direction: a positive ERA variance means more earned runs per nine
+innings than projected. IP differences use signed baseball innings notation;
+`+1.2` means one inning and two outs.
+
+Rows start expanded. Use the control beside each player name to collapse or
+expand them; the rows stay with their player when sorting or filtering, and
+printing preserves the current view. A projected player without a target-season
+record is labeled `Actual (no recorded stats)` and has blank variance cells.
+Players absent from the projection population are not added from the actuals.
+ConfidenceTier and Reliability describe the projection, not the actual results.
+
 ---
 
 ## Local data updates
@@ -361,7 +454,9 @@ Development dependencies (`--extra dev`) include:
 
 ### Lockfile policy (`uv.lock`)
 
-`uv.lock` is committed and pins runtime, development, and build dependencies. CI uses
+`uv.lock` is committed and pins runtime, development, and build dependencies. CI
+installs uv 0.12.23 with a SHA-pinned `astral-sh/setup-uv` action, whose embedded
+checksums verify the downloaded uv archive. CI uses
 `uv sync --locked --extra dev` and fails if the lockfile is out of date. CI first
 installs the locked tools with `--no-install-project`, then installs Backcaster
 with `--no-build-isolation` to keep build dependencies pinned. CI builds
@@ -408,7 +503,7 @@ pytest
 ### Coverage + JUnit reports
 
 ```bash
-pytest --junitxml=pytest.xml --cov=src --cov-report=xml:coverage.xml
+pytest --junitxml=pytest.xml --cov=src --cov-branch --cov-report=xml:coverage.xml --cov-fail-under=100
 ```
 
 ### Lint and types

{backcaster-0.4.2 → backcaster-0.4.3}/README.md

@@ -7,6 +7,7 @@ It supports:
 - **Single team projections** (`team`)
 - **League-wide projections** (`hitters`, `pitchers`, or `batch`)
 - Output as terminal table, CSV, or HTML
+- Historical comparisons against actual results in HTML reports (`--compare-actuals`)
 
 ---
 
@@ -25,10 +26,10 @@ Upgrade to the latest release available on PyPI:
 python -m pip install --upgrade backcaster
 ```
 
-To install a specific release, such as 0.4.2:
+To install a specific release, such as 0.4.3:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.4.2
+python -m pip install --upgrade backcaster==0.4.3
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -76,8 +77,8 @@ Subcommand-specific required options:
 - `batch`, `hitters`, and `pitchers` require no player or team option
 
 ```bash
-backcaster <player|team|batch> [subcommand-options] --year <YEAR> --kind <batting|pitching> [--format cli|csv|html] [--out PATH]
-backcaster <hitters|pitchers> --year <YEAR> [--data-dir PATH] [--format cli|csv|html] [--out PATH]
+backcaster <player|team|batch> [subcommand-options] --year <YEAR> --kind <batting|pitching> [--format cli|csv|html] [--compare-actuals] [--out PATH]
+backcaster <hitters|pitchers> --year <YEAR> [--data-dir PATH] [--format cli|csv|html] [--compare-actuals] [--out PATH]
 ```
 
 ### Pre-offseason league projections
@@ -97,7 +98,8 @@ backcaster hitters --year 2026 --format csv --out hitters_2026.csv
 backcaster pitchers --year 2026 --format csv --out pitchers_2026.csv
 ```
 
-`--year 2026` projects 2026 from 2023–2025; it never reads 2026 statistics.
+`--year 2026` projects 2026 from 2023–2025. It reads 2026 statistics only when
+`--compare-actuals` is selected for a historical HTML report.
 Both commands support `--data-dir`, `--format cli|csv|html`, and `--out`.
 They are shortcuts for `batch --kind batting` and `batch --kind pitching`.
 For a different data directory, add `--data-dir "C:\Baseball\lahman"`.
@@ -106,13 +108,21 @@ File formats require `--out`; the CLI format prints to the terminal and rejects
 `--out`. Invalid output options fail before data is loaded. Unwritable output
 paths report an error on stderr and exit with status 2.
 
-Players qualify for selection by meeting the existing PA/IP threshold in at least
-one of those three seasons. This is a historical eligibility list, not an active
-roster; pitchers who never reach the qualifying innings threshold (including most
-relievers) remain excluded. Qualification selects players without removing their
-other seasons from the calculation. Trades are combined into one player-season
-before qualification, and all teams' statistics contribute once. The output is
-one row per selected player, ready for comparison with reference projections.
+Exports must stay within the current working directory or its subdirectories.
+Relative paths and absolute paths within that directory are accepted; paths that
+escape it through `..` or symbolic links are rejected before data is loaded.
+To export elsewhere, run Backcaster from the intended output directory.
+
+Hitters receive a projection with any positive PA in the preceding three seasons,
+subject to usable ages and the existing non-pitcher classification. There is no
+minimum-PA or reliability gate. `ConfidenceTier` labels reliability at least 0.50
+as `core` and lower values as `low-sample`; both tiers appear in every output.
+Pitchers receive a projection with any recorded outs or batters faced in the
+lookback window, including relievers and appearances without an out. They use
+the same confidence labels, with no innings or reliability gate. All selected
+players use their available three-year history.
+Without a dated eligibility snapshot, this is a historical candidate population,
+including potentially retired or otherwise unavailable players.
 
 ### 1) Player projection
 
@@ -152,18 +162,24 @@ FanGraphs abbreviation `LAD`). A projection year needs the preceding three seaso
 is unavailable. If the directory or required files are missing, the command
 reports the missing file and directory; it never attempts an online fetch.
 
-Offline qualification uses a consistent modern rule across historical seasons:
-at least **3.1 PA per game** for hitters and **one inning per game** for pitchers.
-The season's game count is the maximum `G` in that year's `Teams.csv` records,
-so shortened seasons have lower thresholds. The PA threshold is rounded to the
-nearest integer (502 PA for 162 games, 186 PA for 60 games). This is an analytical filter, not a
-reconstruction of historical award eligibility or batting-title exceptions.
-Relievers generally do not qualify under this pitching rule.
+Batting inclusion requires positive lookback PA; pitching requires recorded outs
+or batters faced. Neither has a minimum seasonal workload or reliability cutoff.
+`season(..., qualified=True)` still exposes the historical PA/IP analytical filters
+for Python callers; projection commands do not apply them.
 
-Player stints are summed before qualification. Plate appearances are calculated
+Player stints are summed before projection. Plate appearances are calculated
 as `AB + BB + HBP + SF + SH`; missing/blank HBP, SF, and SH values count as zero.
 Blank numeric counting-stat cells are also treated as zero; use a dataset with
 complete records for the seasons you intend to project.
+
+Historical batting and pitching records with missing or invalid birth years are excluded with
+a stderr warning identifying the count and sample player IDs. Remaining players
+are still projected; no default age is substituted. An entirely unusable
+population produces a clear error. See [historical data caveats](docs/LAHMAN.md).
+Pitcher playing time is `0.5 × last-year IP + 0.1 × two-years-ago IP + 60`,
+with missing calendar years contributing zero. The third prior season still
+contributes to regression and reliability. See [the pitcher model](docs/PITCHER_MODEL.md).
+
 Pitching `IPouts` is divided by three for decimal innings, and `BFP` supplies
 batters faced. Lahman player IDs keep different players with the same name separate;
 ambiguous name lookups report the matching IDs. Select one with `--player-id`
@@ -173,18 +189,56 @@ instead of `--name`, for example:
 backcaster player --player-id bettsmo01 --year 2026 --kind batting
 ```
 
-IDs match Lahman `People.csv.playerID` exactly and retain the same qualification
+IDs match Lahman `People.csv.playerID` exactly and retain the same inclusion
 rules as name lookups.
 
-Batter league regression and rebaselining use all non-pitcher player-seasons;
-qualification selects the displayed players. Pitching retains its qualified-only
-baseline, with real-age performance adjustments documented in
-[the pitcher model](docs/PITCHER_MODEL.md). See [the batter model](docs/BATTER_MODEL.md) for the six-stage calculation,
-real-age adjustment, PA formula, and explicit rebaselining choices.
-Eligibility means qualifying in at least one of the three preceding seasons.
-For every selected player, projections use all available seasons in that window,
-including nonqualified seasons and seasons spent with other teams. For team selection, a traded player's full-season totals are assigned
-to the team in their latest stint for that season; this is not a current-roster forecast.
+Batter league regression and rebaselining use all positive-PA non-pitcher
+player-seasons. Output selection, including status snapshots, does not change
+that calculation. Pitcher regression likewise uses the full historical sample
+population, independently of roster, player, or team selection. See [the batter model](docs/BATTER_MODEL.md) and
+[the pitcher model](docs/PITCHER_MODEL.md).
+
+For every selected player, projections use all available seasons in the window,
+including seasons spent with other teams. Without a status snapshot, team
+selection uses historical last-stint membership for each season.
+
+### Dated player eligibility
+
+For a roster/status comparison, supply an explicit eligibility snapshot and date:
+
+```bash
+backcaster hitters --year 2025 --eligibility-file eligibility_2025.csv --as-of 2025-01-14 --format csv --out mlb_hitting_2025.csv
+```
+
+The CSV uses Lahman IDs and explicit inclusion decisions:
+
+```csv
+PlayerID,Year,AsOf,Eligible,Team
+troutmi01,2025,2025-01-14,true,ANA
+bettsmo01,2025,2025-01-14,true,LAN
+```
+
+Create these decisions from a roster/organization/free-agent/retirement source
+as of the stated date. `Eligible` must be true or false. Unlisted players and
+false rows are excluded; listed players still need a lookback sample (PA for
+hitters, outs or batters faced for pitchers) and a usable birth year. Eligibility
+never depends on reliability. The file can contain
+multiple years and dates; only the exact `Year` and `AsOf` match is used, with
+unique PlayerID values within that snapshot.
+
+Both flags are required together and apply to batting and pitching. For pitchers,
+use `backcaster pitchers` (or `--kind pitching`) with the same flags. Use separate
+snapshot files if inclusion decisions differ between hitting and pitching roles.
+`Team` is optional for league/player output and required for team output; it represents
+membership at the snapshot date, with blanks allowed for unassigned players.
+With a snapshot, team selection uses this membership rather than historical teams.
+Exports include `EligibilityAsOf`. The snapshot filters output only; league
+regression and rebaselining continue to use the full historical population.
+
+For the January 14, 2025 Baseball Reference comparison, supply a snapshot actually
+frozen to that date. Lahman history cannot reconstruct roster status on that date,
+and later performance or final career dates are not used to guess it. Matching
+504 benchmark rows requires the right status population as well as model inputs.
 
 ### 2) Team projection
 
@@ -251,7 +305,7 @@ true innings rather than the displayed notation.
 ### Tracked statistics and order
 
 All outputs put available Name, Year, Player ID, and Age metadata first, followed
-by these statistics in order and then Reliability:
+by these statistics in order and then Reliability and ConfidenceTier; snapshot-filtered output appends EligibilityAsOf:
 
 ```text
 Batters:  PA,AB,R,H,2B,3B,HR,RBI,SB,CS,BB,SO,BA,OBP,SLG,OPS,TB,GDP,HBP,SH,SF,IBB
@@ -280,6 +334,7 @@ or share as one file. No server, CDN, fonts, or internet connection are required
 ```powershell
 backcaster hitters --year 2025 --format html --out hitters_2025.html
 backcaster pitchers --year 2025 --format html --out pitchers_2025.html
+backcaster hitters --year 2025 --format html --compare-actuals --out hitters_accuracy_2025.html
 ```
 
 The first four columns are **Name, Year, Player ID, Age**, followed by counting
@@ -288,6 +343,7 @@ statistics and batting/pitching rates in a consistent order. The report includes
 - A player-count, projection-year, and projection-type summary.
 - Search across player names, IDs, and statistics.
 - Sortable column headings, with numeric sorting for statistics.
+- Optional historical accuracy rows with a per-player expand/collapse control.
 - A sticky name column/header and horizontal scrolling on narrow screens.
 - A reset control and print layout for browser printing or saving as PDF.
 
@@ -297,6 +353,43 @@ Search filters the visible rows; printing respects that current view. Without
 JavaScript, the complete table is still readable. See
 [HTML report customization](docs/HTML_REPORTS.md) for theme and column constants.
 
+### Compare projections with actual results (new in 0.4.3)
+
+Add `--compare-actuals` to a historical HTML report for either batters or pitchers:
+
+```powershell
+backcaster hitters --year 2025 --format html --compare-actuals --out hitters_accuracy_2025.html
+backcaster pitchers --year 2025 --format html --compare-actuals --out pitchers_accuracy_2025.html
+```
+
+For these examples, the local Lahman files must cover **2022–2024** for the
+projection and **2025** for the actual results, including target-year game counts
+in `Teams.csv`. Use `--data-dir` to select the dataset. The 1871–2025 edition can
+support a 2025 comparison; it cannot provide actual results for 2026.
+The option also works with `player`, `team`, and `batch`; it requires
+`--format html` and `--out` and is rejected for terminal or CSV output.
+
+Projection calculations use only the three preceding seasons. Target-season
+results are loaded afterward and matched by Lahman PlayerID, combining trade
+stints without requiring the player to meet a seasonal qualification threshold.
+Each projected player has two additional rows:
+
+- **Actual** shows the player's recorded target-season results.
+- **Variance** shows `actual - projected`, calculated before display rounding.
+  For example, 25 actual HR against 20 projected HR displays `+5`.
+
+Positive differences are green and negative differences are red. These colors
+indicate direction: a positive ERA variance means more earned runs per nine
+innings than projected. IP differences use signed baseball innings notation;
+`+1.2` means one inning and two outs.
+
+Rows start expanded. Use the control beside each player name to collapse or
+expand them; the rows stay with their player when sorting or filtering, and
+printing preserves the current view. A projected player without a target-season
+record is labeled `Actual (no recorded stats)` and has blank variance cells.
+Players absent from the projection population are not added from the actuals.
+ConfidenceTier and Reliability describe the projection, not the actual results.
+
 ---
 
 ## Local data updates
@@ -327,7 +420,9 @@ Development dependencies (`--extra dev`) include:
 
 ### Lockfile policy (`uv.lock`)
 
-`uv.lock` is committed and pins runtime, development, and build dependencies. CI uses
+`uv.lock` is committed and pins runtime, development, and build dependencies. CI
+installs uv 0.12.23 with a SHA-pinned `astral-sh/setup-uv` action, whose embedded
+checksums verify the downloaded uv archive. CI uses
 `uv sync --locked --extra dev` and fails if the lockfile is out of date. CI first
 installs the locked tools with `--no-install-project`, then installs Backcaster
 with `--no-build-isolation` to keep build dependencies pinned. CI builds
@@ -374,7 +469,7 @@ pytest
 ### Coverage + JUnit reports
 
 ```bash
-pytest --junitxml=pytest.xml --cov=src --cov-report=xml:coverage.xml
+pytest --junitxml=pytest.xml --cov=src --cov-branch --cov-report=xml:coverage.xml --cov-fail-under=100
 ```
 
 ### Lint and types

{backcaster-0.4.2 → backcaster-0.4.3}/src/backcaster/__init__.py

@@ -1,4 +1,4 @@
 """backcaster package."""
 
 __all__ = ["__version__"]
-__version__ = "0.4.2"
+__version__ = "0.4.3"

{backcaster-0.4.2 → backcaster-0.4.3}/src/backcaster/batters.py

@@ -170,6 +170,7 @@ def project_batters(seasons: pd.DataFrame, year: int) -> pd.DataFrame:
     context = _project_context(rates, pa, target, projected)
     out = _summarize(projected.join(context), pa)
     out["Reliability"] = evidence_pa / (evidence_pa + 1200)
+    out["ConfidenceTier"] = np.where(out["Reliability"] >= 0.5, "core", "low-sample")
     out["Age"], out["Name"], out["Year"] = age, people["Name"], year
     out = out.reset_index()
-    return out[[*IDENTITY_COLUMNS, *BATTING_STAT_COLUMNS, "Reliability"]]
+    return out[[*IDENTITY_COLUMNS, *BATTING_STAT_COLUMNS, "Reliability", "ConfidenceTier"]]

{backcaster-0.4.2 → backcaster-0.4.3}/src/backcaster/cli.py

@@ -10,7 +10,7 @@ import pandas as pd
 from backcaster.data import DataLoadError, PlayerLookupError
 from backcaster.lahman import LahmanSource
 from backcaster.marcel import ProjectionError
-from backcaster.outputs import to_cli_table, to_csv, to_html
+from backcaster.outputs import to_cli_table, to_csv, to_html, validate_output_path
 
 _FILE_RENDERERS = {"csv": to_csv, "html": to_html}
 _OUTPUT_FORMAT_CHOICES = ("cli", *_FILE_RENDERERS.keys())
@@ -25,20 +25,34 @@ def _default_data_dir() -> str:
     return os.environ.get("LAHMAN_DATA_DIR", default)
 
 
-def _validate_output_options(output_format: str, out: str | None) -> None:
+def _validate_output_options(
+    output_format: str, out: str | None, compare_actuals: bool = False
+) -> None:
     if output_format == "cli" and out is not None:
         raise ValueError("--out cannot be used with --format cli; choose --format csv or html")
     if output_format in _FILE_RENDERERS and not out:
         raise ValueError(f"--out is required for {output_format} output")
-
-
-def _render(df: pd.DataFrame, output_format: str, out: str | None) -> None:
-    _validate_output_options(output_format, out)
+    if compare_actuals and output_format != "html":
+        raise ValueError("--compare-actuals requires --format html")
+    if output_format in _FILE_RENDERERS and out:
+        validate_output_path(out)
+
+
+def _render(
+    df: pd.DataFrame,
+    output_format: str,
+    out: str | None,
+    actuals: pd.DataFrame | None = None,
+) -> None:
     if output_format == "cli":
         print(to_cli_table(df))
     elif output_format in _FILE_RENDERERS:
-        assert out is not None
-        _FILE_RENDERERS[output_format](df, out)
+        if not out:
+            raise ValueError(f"--out is required for {output_format} output")
+        if output_format == "html" and actuals is not None:
+            to_html(df, out, actuals)
+        else:
+            _FILE_RENDERERS[output_format](df, out)
     else:
         raise ValueError(f"Unsupported format: {output_format}")
 
@@ -54,7 +68,21 @@ def build_parser() -> argparse.ArgumentParser:
         else:
             sp.set_defaults(kind=kind)
         sp.add_argument("--format", choices=_OUTPUT_FORMAT_CHOICES, default="cli")
-        sp.add_argument("--out", help="Output path (required for csv/html; invalid with cli)")
+        sp.add_argument(
+            "--eligibility-file", help="Target-season eligibility CSV keyed by Lahman PlayerID"
+        )
+        sp.add_argument(
+            "--as-of", help="Eligibility snapshot date (YYYY-MM-DD; requires --eligibility-file)"
+        )
+        sp.add_argument(
+            "--out",
+            help="Output path within the current working directory (required for csv/html; invalid with cli)",
+        )
+        sp.add_argument(
+            "--compare-actuals",
+            action="store_true",
+            help="Add expandable actual and variance rows to a historical HTML report",
+        )
         sp.add_argument(
             "--data-dir",
             default=_default_data_dir(),
@@ -64,7 +92,7 @@ def build_parser() -> argparse.ArgumentParser:
     pp = sub.add_parser("player")
     add_common(pp)
     player_selector = pp.add_mutually_exclusive_group(required=True)
-    player_selector.add_argument("--name", help="Player name (must identify one qualified player)")
+    player_selector.add_argument("--name", help="Player name (must identify one eligible player)")
     player_selector.add_argument(
         "--player-id", help="Exact Lahman player ID (for example, bettsmo01)"
     )
@@ -86,16 +114,24 @@ def main(argv: list[str] | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)
     try:
-        _validate_output_options(args.format, args.out)
-        result = LahmanSource(args.data_dir).project(
+        _validate_output_options(args.format, args.out, args.compare_actuals)
+        source = LahmanSource(args.data_dir)
+        result = source.project(
             args.command,
             args.year,
             args.kind,
             name=getattr(args, "name", None),
             team=getattr(args, "team", None),
             player_id=getattr(args, "player_id", None),
+            eligibility_file=args.eligibility_file,
+            as_of=args.as_of,
+        )
+        actuals = (
+            source.actuals(args.year, args.kind, result["PlayerID"])
+            if args.compare_actuals
+            else None
         )
-        _render(result, args.format, args.out)
+        _render(result, args.format, args.out, actuals)
         return 0
     except (DataLoadError, PlayerLookupError, ProjectionError, ValueError, OSError) as exc:
         print(f"Error: {exc}", file=sys.stderr)