backcaster 0.3.2__tar.gz → 0.3.4__tar.gz

{backcaster-0.3.2/src/backcaster.egg-info → backcaster-0.3.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: backcaster
-Version: 0.3.2
-Summary: Marcel-style MLB projection CLI built on pybaseball
+Version: 0.3.4
+Summary: Marcel-style MLB projection CLI using local Lahman CSV data
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/jeffreywevans/backcaster
 Project-URL: Repository, https://github.com/jeffreywevans/backcaster
@@ -17,8 +17,9 @@ Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
 Requires-Dist: pandas>=2.0
-Requires-Dist: pybaseball>=2.2
+Requires-Dist: numpy>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
@@ -30,7 +31,7 @@ Dynamic: license-file
 
 # Backcaster
 
-Backcaster is a Python CLI that produces **Marcel-style MLB projections** from the prior three seasons of data using [`pybaseball`](https://github.com/jldbc/pybaseball) and `pandas`.
+Backcaster is a Python CLI that produces **Marcel-style MLB projections** from the prior three seasons of data using local Lahman CSV files and `pandas`.
 
 It supports:
 - **Single player projections** (`player`)
@@ -44,7 +45,8 @@ It supports:
 
 ### Requirements
 - Python **3.13+**
-- Internet access for first-time stat fetches (data is cached locally afterward)
+- An extracted Lahman CSV database covering the three prior seasons
+- Internet access for package installation only; projections run offline
 
 ### Update an installed package
 
@@ -54,10 +56,10 @@ Upgrade to the latest release available on PyPI:
 python -m pip install --upgrade backcaster
 ```
 
-To install a specific release, such as 0.3.2:
+To install a specific release, such as 0.3.4:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.3.2
+python -m pip install --upgrade backcaster==0.3.4
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -116,12 +118,21 @@ backcaster player --name "Mookie Betts" --year 2026 --kind batting
 
 ### Offline projections with Lahman CSVs
 
-Extract your Lahman CSV distribution into a local directory. Pass `--data-dir`
-to use it without any network requests, player-register downloads, or FanGraphs
-cache reads. The directory must contain `People.csv`, `Teams.csv`, and
-`Batting.csv` or `Pitching.csv` for the selected kind. Filenames are matched
+All projections use local Lahman CSVs. On Windows, the default directory is
+`C:\Baseball\lahman`; on other systems it is `~/Baseball/lahman`.
+Set the `LAHMAN_DATA_DIR` environment variable to change the default, or pass
+`--data-dir` to override it for one command. No network requests or online
+fallbacks are made. The directory must contain `People.csv`, `Teams.csv`, and
+`Batting.csv` or `Pitching.csv` for the selected kind. Batter projections also
+require `Appearances.csv` and a valid `birthYear` in `People.csv`. Filenames are matched
 without regard to case. The database is not bundled with Backcaster.
 
+For the default Windows directory, no additional flag is needed:
+
+```powershell
+backcaster player --name "Mookie Betts" --year 2024 --kind batting
+```
+
 See [Lahman database notes](docs/LAHMAN.md) for the supplied 1871–2025 edition's
 coverage, attribution, license, and historical-data caveats, with its original README.
 
@@ -134,8 +145,8 @@ backcaster batch --year 2022 --kind pitching --data-dir "C:\Baseball\lahman" --f
 Use Lahman's `teamID` values, such as `LAN` for the Dodgers (rather than the
 FanGraphs abbreviation `LAD`). A projection year needs the preceding three seasons:
 2022 requires 2019–2021. Missing seasons produce an error explaining which year
-is unavailable. Without `--data-dir`, the existing pybaseball source is used;
-FanGraphs may reject its automated requests with HTTP 403.
+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.
@@ -153,7 +164,10 @@ 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.
 
-Only qualified player-seasons enter projections and league regression baselines.
+Batter league regression and rebaselining use all non-pitcher player-seasons;
+qualification selects the displayed players. Pitching retains its qualified-only
+baseline. See [the batter model](docs/BATTER_MODEL.md) for the six-stage calculation,
+real-age adjustment, PA formula, and explicit rebaselining choices.
 Single-player projections require qualification in all three preceding seasons.
 Team and batch projections use each player's available qualified seasons within
 that window. For team selection, a traded player's full-season totals are assigned
@@ -162,7 +176,7 @@ to the team in their latest stint for that season; this is not a current-roster
 ### 2) Team projection
 
 ```bash
-backcaster team --team LAD --year 2026 --kind pitching
+backcaster team --team LAN --year 2026 --kind pitching
 ```
 
 ### 3) Batch projection (all players returned by source data)
@@ -175,7 +189,7 @@ backcaster batch --year 2026 --kind batting
 
 ```bash
 backcaster player --name "Mookie Betts" --year 2026 --kind batting --format csv --out ./out/mookie_2026.csv
-backcaster team --team LAD --year 2026 --kind pitching --format html --out ./out/lad_pitching_2026.html
+backcaster team --team LAN --year 2026 --kind pitching --format html --out ./out/lan_pitching_2026.html
 ```
 
 > `--out` is required for `csv` and `html` formats.
@@ -201,24 +215,11 @@ A basic HTML table (no custom CSS) suitable for quick sharing or embedding.
 
 ---
 
-## Cache behavior
-
-Backcaster caches season stat pulls under:
-
-```text
-~/.cache/backcaster/
-```
-
-Cache details:
-- Key pattern: `<kind>_<year>.parquet` (preferred) or `<kind>_<year>.csv` (fallback)
-- Read order: Parquet first, then CSV
-- Write behavior: atomic temp-file write + rename to reduce corruption risk
-- Parquet write failures automatically fall back to CSV
+## Local data updates
 
-Practical implications:
-- First run for a season may be slower (network fetch).
-- Re-runs are typically faster (local cache hit).
-- If upstream data changes and you need a refresh, delete the relevant cache file(s) and rerun.
+Backcaster reads the local CSV files for each command and does not use the old
+FanGraphs season cache. To refresh the data, replace the CSVs with a complete
+Lahman distribution from the same edition. Existing online caches are ignored.
 
 ---
 
@@ -226,7 +227,6 @@ Practical implications:
 
 Runtime dependencies are intentionally minimal:
 - `pandas` for tabular data processing and projection output
-- `pybaseball` for MLB player/team seasonal stat retrieval and player ID lookup
 
 Development dependencies (`--extra dev`) include:
 - `pytest`, `pytest-cov`
@@ -298,6 +298,20 @@ Sonar consumes:
 
 ---
 
+## Acknowledgments
+
+Thank you to **Tom Tango** for developing and publishing the Marcel system, and
+to **Ben Dilday** for [marcelR](https://github.com/bdilday/marcelR), whose open R
+implementation provides a valuable methodological reference for our Python work.
+We document the reviewed formulas, source revision, and implementation differences
+in [our reference notes](docs/MARCELR_REFERENCE.md). The complete marcelR MIT
+notice is preserved in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and shipped
+with our distributions.
+
+Thanks also to SABR, Sean Lahman, and the database contributors. See
+[Lahman attribution and licensing](docs/LAHMAN.md). These acknowledgments do not
+imply endorsement or exact agreement with another implementation's projections.
+
 ## Security and responsible use
 
 Please review `SECURITY.md` for reporting guidance. Backcaster is an analytical utility and should be validated independently before use in production pipelines.

{backcaster-0.3.2 → backcaster-0.3.4}/README.md

@@ -1,6 +1,6 @@
 # Backcaster
 
-Backcaster is a Python CLI that produces **Marcel-style MLB projections** from the prior three seasons of data using [`pybaseball`](https://github.com/jldbc/pybaseball) and `pandas`.
+Backcaster is a Python CLI that produces **Marcel-style MLB projections** from the prior three seasons of data using local Lahman CSV files and `pandas`.
 
 It supports:
 - **Single player projections** (`player`)
@@ -14,7 +14,8 @@ It supports:
 
 ### Requirements
 - Python **3.13+**
-- Internet access for first-time stat fetches (data is cached locally afterward)
+- An extracted Lahman CSV database covering the three prior seasons
+- Internet access for package installation only; projections run offline
 
 ### Update an installed package
 
@@ -24,10 +25,10 @@ Upgrade to the latest release available on PyPI:
 python -m pip install --upgrade backcaster
 ```
 
-To install a specific release, such as 0.3.2:
+To install a specific release, such as 0.3.4:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.3.2
+python -m pip install --upgrade backcaster==0.3.4
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -86,12 +87,21 @@ backcaster player --name "Mookie Betts" --year 2026 --kind batting
 
 ### Offline projections with Lahman CSVs
 
-Extract your Lahman CSV distribution into a local directory. Pass `--data-dir`
-to use it without any network requests, player-register downloads, or FanGraphs
-cache reads. The directory must contain `People.csv`, `Teams.csv`, and
-`Batting.csv` or `Pitching.csv` for the selected kind. Filenames are matched
+All projections use local Lahman CSVs. On Windows, the default directory is
+`C:\Baseball\lahman`; on other systems it is `~/Baseball/lahman`.
+Set the `LAHMAN_DATA_DIR` environment variable to change the default, or pass
+`--data-dir` to override it for one command. No network requests or online
+fallbacks are made. The directory must contain `People.csv`, `Teams.csv`, and
+`Batting.csv` or `Pitching.csv` for the selected kind. Batter projections also
+require `Appearances.csv` and a valid `birthYear` in `People.csv`. Filenames are matched
 without regard to case. The database is not bundled with Backcaster.
 
+For the default Windows directory, no additional flag is needed:
+
+```powershell
+backcaster player --name "Mookie Betts" --year 2024 --kind batting
+```
+
 See [Lahman database notes](docs/LAHMAN.md) for the supplied 1871–2025 edition's
 coverage, attribution, license, and historical-data caveats, with its original README.
 
@@ -104,8 +114,8 @@ backcaster batch --year 2022 --kind pitching --data-dir "C:\Baseball\lahman" --f
 Use Lahman's `teamID` values, such as `LAN` for the Dodgers (rather than the
 FanGraphs abbreviation `LAD`). A projection year needs the preceding three seasons:
 2022 requires 2019–2021. Missing seasons produce an error explaining which year
-is unavailable. Without `--data-dir`, the existing pybaseball source is used;
-FanGraphs may reject its automated requests with HTTP 403.
+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.
@@ -123,7 +133,10 @@ 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.
 
-Only qualified player-seasons enter projections and league regression baselines.
+Batter league regression and rebaselining use all non-pitcher player-seasons;
+qualification selects the displayed players. Pitching retains its qualified-only
+baseline. See [the batter model](docs/BATTER_MODEL.md) for the six-stage calculation,
+real-age adjustment, PA formula, and explicit rebaselining choices.
 Single-player projections require qualification in all three preceding seasons.
 Team and batch projections use each player's available qualified seasons within
 that window. For team selection, a traded player's full-season totals are assigned
@@ -132,7 +145,7 @@ to the team in their latest stint for that season; this is not a current-roster
 ### 2) Team projection
 
 ```bash
-backcaster team --team LAD --year 2026 --kind pitching
+backcaster team --team LAN --year 2026 --kind pitching
 ```
 
 ### 3) Batch projection (all players returned by source data)
@@ -145,7 +158,7 @@ backcaster batch --year 2026 --kind batting
 
 ```bash
 backcaster player --name "Mookie Betts" --year 2026 --kind batting --format csv --out ./out/mookie_2026.csv
-backcaster team --team LAD --year 2026 --kind pitching --format html --out ./out/lad_pitching_2026.html
+backcaster team --team LAN --year 2026 --kind pitching --format html --out ./out/lan_pitching_2026.html
 ```
 
 > `--out` is required for `csv` and `html` formats.
@@ -171,24 +184,11 @@ A basic HTML table (no custom CSS) suitable for quick sharing or embedding.
 
 ---
 
-## Cache behavior
-
-Backcaster caches season stat pulls under:
-
-```text
-~/.cache/backcaster/
-```
-
-Cache details:
-- Key pattern: `<kind>_<year>.parquet` (preferred) or `<kind>_<year>.csv` (fallback)
-- Read order: Parquet first, then CSV
-- Write behavior: atomic temp-file write + rename to reduce corruption risk
-- Parquet write failures automatically fall back to CSV
+## Local data updates
 
-Practical implications:
-- First run for a season may be slower (network fetch).
-- Re-runs are typically faster (local cache hit).
-- If upstream data changes and you need a refresh, delete the relevant cache file(s) and rerun.
+Backcaster reads the local CSV files for each command and does not use the old
+FanGraphs season cache. To refresh the data, replace the CSVs with a complete
+Lahman distribution from the same edition. Existing online caches are ignored.
 
 ---
 
@@ -196,7 +196,6 @@ Practical implications:
 
 Runtime dependencies are intentionally minimal:
 - `pandas` for tabular data processing and projection output
-- `pybaseball` for MLB player/team seasonal stat retrieval and player ID lookup
 
 Development dependencies (`--extra dev`) include:
 - `pytest`, `pytest-cov`
@@ -268,6 +267,20 @@ Sonar consumes:
 
 ---
 
+## Acknowledgments
+
+Thank you to **Tom Tango** for developing and publishing the Marcel system, and
+to **Ben Dilday** for [marcelR](https://github.com/bdilday/marcelR), whose open R
+implementation provides a valuable methodological reference for our Python work.
+We document the reviewed formulas, source revision, and implementation differences
+in [our reference notes](docs/MARCELR_REFERENCE.md). The complete marcelR MIT
+notice is preserved in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and shipped
+with our distributions.
+
+Thanks also to SABR, Sean Lahman, and the database contributors. See
+[Lahman attribution and licensing](docs/LAHMAN.md). These acknowledgments do not
+imply endorsement or exact agreement with another implementation's projections.
+
 ## Security and responsible use
 
 Please review `SECURITY.md` for reporting guidance. Backcaster is an analytical utility and should be validated independently before use in production pipelines.

backcaster-0.3.4/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# Third-party acknowledgments and notices
+
+## marcelR — Ben Dilday
+
+Backcaster is a Python implementation of Marcel-style baseball projections.
+[marcelR](https://github.com/bdilday/marcelR), by Ben Dilday, is an independent R
+implementation we reviewed as a methodological reference and source of inspiration.
+Thank you to Ben Dilday for sharing readable formulas, intermediate calculations,
+and historical comparison examples that help make this work reproducible.
+
+Reference revision: `13a1c7943f5a7317c9c812a28e299c2184060046` (March 1, 2020).
+See [reference and adaptation notes](docs/MARCELR_REFERENCE.md) for the files
+reviewed, formulas examined, current differences, and attribution practices.
+
+At the time this notice was added, marcelR source had been inspected, but no R
+source had been copied or translated into Backcaster, and its datasets had not
+been bundled. Backcaster does not depend on R or marcelR. The notice is retained
+for acknowledgment and to accompany future attributed adaptations. Neither the
+review nor the acknowledgment implies endorsement or verified numerical parity.
+
+The following is marcelR's MIT license notice, reproduced without changes:
+
+```text
+MIT License
+
+Copyright (c) 2017 Ben Dilday
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## Method and data credits
+
+Tom Tango developed the Marcel projection system. We thank him for publishing
+its methodology. SABR, Sean Lahman, and the contributors to the Lahman database
+provide the historical data on which local projections rely. The Lahman data
+license is separate; see [database attribution and caveats](docs/LAHMAN.md).

{backcaster-0.3.2 → backcaster-0.3.4}/pyproject.toml

@@ -5,10 +5,10 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "backcaster"
 dynamic = ["version"]
-description = "Marcel-style MLB projection CLI built on pybaseball"
+description = "Marcel-style MLB projection CLI using local Lahman CSV data"
 readme = "README.md"
 license = "MIT"
-license-files = ["LICENSE"]
+license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
 classifiers = [
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.13",
@@ -22,7 +22,7 @@ classifiers = [
 requires-python = ">=3.13"
 dependencies = [
   "pandas>=2.0",
-  "pybaseball>=2.2",
+  "numpy>=2.0",
 ]
 
 [project.urls]
@@ -85,5 +85,5 @@ no_implicit_optional = true
 check_untyped_defs = true
 
 [[tool.mypy.overrides]]
-module = ["pandas", "pandas.*", "pybaseball", "pybaseball.*"]
+module = ["pandas", "pandas.*"]
 ignore_missing_imports = true

{backcaster-0.3.2 → backcaster-0.3.4}/src/backcaster/__init__.py

@@ -1,4 +1,4 @@
 """backcaster package."""
 
 __all__ = ["__version__"]
-__version__ = "0.3.2"
+__version__ = "0.3.4"

backcaster-0.3.4/src/backcaster/batters.py

@@ -0,0 +1,118 @@
+"""Population-level batter projections; no projected-year statistics are read."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from backcaster.marcel import BATTING_COMPONENTS, ProjectionError
+
+EVENTS = ["1B", "2B", "3B", "HR", "BB", "HBP", "SO", "SH", "SF", "OUT"]
+
+
+def _events(frame: pd.DataFrame) -> pd.DataFrame:
+    events = frame.reindex(columns=EVENTS, fill_value=0).astype(float)
+    events["1B"] = frame["H"] - frame["2B"] - frame["3B"] - frame["HR"]
+    events["OUT"] = frame["AB"] - frame["H"] - frame["SO"]
+    if not np.isfinite(events.to_numpy()).all() or (events < 0).any().any():
+        raise ProjectionError(
+            "Batter counts must be finite and consistent (H <= AB, SO <= AB - H)."
+        )
+    return events
+
+
+def _rebaseline(events: pd.DataFrame, pa: pd.Series, target: pd.Series) -> pd.DataFrame:
+    """Rake mutually exclusive events to fixed player PA and league event totals."""
+    desired = target * float(pa.sum())
+    # Positive league outcomes must be reachable, including a historically absent
+    # event in the projected population. Seed only those cells, then rake.
+    values = events.clip(lower=1e-12).mul(desired.gt(0), axis=1)
+    for _ in range(200):
+        values = values.mul(desired.div(values.sum()).fillna(0), axis=1)
+        values = values.mul(pa.div(values.sum(axis=1)).fillna(0), axis=0)
+        if np.allclose(values.sum(), desired, rtol=1e-10, atol=1e-8):
+            return values
+    raise ProjectionError("Batter league rebaselining did not converge.")
+
+
+def project_batters(seasons: pd.DataFrame, year: int) -> pd.DataFrame:
+    """Use all non-pitcher seasons for both regression and rebaselining."""
+    history = seasons[seasons["Season"].isin([year - 1, year - 2, year - 3])].copy()
+    if history.empty:
+        raise ProjectionError("No non-pitcher batting history in the three prior seasons.")
+    history = history[history["PA"] > 0].copy()
+    counts = _events(history)
+    weights = history["Season"].map({year - 1: 5.0, year - 2: 4.0, year - 3: 3.0})
+    history["EvidencePA"] = history["PA"] * weights
+    league_counts = counts.groupby(history["Season"]).sum()
+    league_pa = history.groupby("Season")["PA"].sum()
+    if year - 1 not in league_pa:
+        raise ProjectionError("Latest completed season has no non-pitcher batting PA.")
+    league_rates = league_counts.div(league_pa, axis=0)
+    # Each player's exposure to each season determines their league average.
+    expected = (
+        league_rates.reindex(history["Season"])
+        .set_axis(history.index)
+        .mul(history["EvidencePA"], axis=0)
+    )
+    evidence = counts.mul(weights, axis=0).groupby(history["PlayerID"]).sum()
+    evidence_pa = history.groupby("PlayerID")["EvidencePA"].sum()
+    baseline = expected.groupby(history["PlayerID"]).sum().div(evidence_pa, axis=0)
+    rates = (evidence + 1200 * baseline).div(evidence_pa + 1200, axis=0)
+    prior_pa = (
+        history.pivot_table(index="PlayerID", columns="Season", values="PA", aggfunc="sum")
+        .reindex(columns=[year - 1, year - 2], fill_value=0)
+        .fillna(0)
+    )
+    pa = 0.5 * prior_pa[year - 1] + 0.1 * prior_pa[year - 2] + 200
+    people = (
+        history.sort_values("Season")
+        .drop_duplicates("PlayerID", keep="last")
+        .set_index("PlayerID")
+        .reindex(rates.index)
+    )
+    birth = pd.to_numeric(people["birthYear"], errors="coerce")
+    age = year - birth
+    if birth.isna().any() or not np.isfinite(age).all() or ((age < 15) | (age > 70)).any():
+        raise ProjectionError(
+            "Valid birthYear is required for every batter in the projection population."
+        )
+    adjustment = (age - 29) * np.where(age > 29, 0.003, 0.006)
+    rates[["1B", "2B", "3B", "HR", "BB", "HBP"]] = rates[["1B", "2B", "3B", "HR", "BB", "HBP"]].mul(
+        1 - adjustment, axis=0
+    )
+    rates[["SO", "OUT"]] = rates[["SO", "OUT"]].mul(1 + adjustment, axis=0)
+    rates = rates.div(rates.sum(axis=1), axis=0)
+    projected = _rebaseline(rates.mul(pa, axis=0), pa, league_rates.loc[[year - 1]].iloc[0])
+    out = projected.copy()
+    out["H"] = projected[["1B", "2B", "3B", "HR"]].sum(axis=1)
+    out["AB"] = out["H"] + projected["SO"] + projected["OUT"]
+    out["PA"] = pa
+    out["AVG"] = out["H"] / out["AB"].replace(0, np.nan)
+    out["OBP"] = (out["H"] + out["BB"] + out["HBP"]) / (
+        out["AB"] + out["BB"] + out["HBP"] + out["SF"]
+    ).replace(0, np.nan)
+    out["SLG"] = (projected["1B"] + 2 * out["2B"] + 3 * out["3B"] + 4 * out["HR"]) / out[
+        "AB"
+    ].replace(0, np.nan)
+    out["OPS"] = out["OBP"] + out["SLG"]
+    out["Reliability"] = evidence_pa / (evidence_pa + 1200)
+    out["Age"] = age
+    out["Name"] = people["Name"]
+    out["Year"] = year
+    out = out.fillna(0).drop(columns=["1B", "OUT"]).reset_index()
+    return out[
+        [
+            "PlayerID",
+            *BATTING_COMPONENTS,
+            "SH",
+            "AVG",
+            "OBP",
+            "SLG",
+            "OPS",
+            "Reliability",
+            "Age",
+            "Name",
+            "Year",
+        ]
+    ]

backcaster-0.3.4/src/backcaster/cli.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+from backcaster.data import DataFetchError, PlayerLookupError
+from backcaster.lahman import LahmanSource
+from backcaster.marcel import ProjectionError
+from backcaster.outputs import to_cli_table, to_csv, to_html
+
+_FILE_RENDERERS = {"csv": to_csv, "html": to_html}
+_OUTPUT_FORMAT_CHOICES = ("cli", *_FILE_RENDERERS.keys())
+
+
+def _default_data_dir() -> str:
+    default = (
+        "C:/Baseball/lahman"
+        if sys.platform == "win32"
+        else str(Path.home() / "Baseball" / "lahman")
+    )
+    return os.environ.get("LAHMAN_DATA_DIR", default)
+
+
+def _render(df: pd.DataFrame, output_format: str, out: str | None) -> None:
+    if output_format == "cli":
+        print(to_cli_table(df))
+    elif output_format in _FILE_RENDERERS:
+        if not out:
+            raise ValueError(f"--out is required for {output_format} output")
+        _FILE_RENDERERS[output_format](df, out)
+    else:
+        raise ValueError(f"Unsupported format: {output_format}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="backcaster")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    def add_common(sp: argparse.ArgumentParser) -> None:
+        sp.add_argument("--year", type=int, required=True)
+        sp.add_argument("--kind", choices=["batting", "pitching"], required=True)
+        sp.add_argument("--format", choices=_OUTPUT_FORMAT_CHOICES, default="cli")
+        sp.add_argument("--out")
+        sp.add_argument(
+            "--data-dir",
+            default=_default_data_dir(),
+            help="Lahman CSV directory (default: LAHMAN_DATA_DIR, C:/Baseball/lahman on Windows, or ~/Baseball/lahman)",
+        )
+
+    pp = sub.add_parser("player")
+    add_common(pp)
+    pp.add_argument("--name", required=True)
+
+    tp = sub.add_parser("team")
+    add_common(tp)
+    tp.add_argument("--team", required=True)
+
+    bp = sub.add_parser("batch")
+    add_common(bp)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        result = LahmanSource(args.data_dir).project(
+            args.command,
+            args.year,
+            args.kind,
+            name=getattr(args, "name", None),
+            team=getattr(args, "team", None),
+        )
+        _render(result, args.format, args.out)
+        return 0
+    except (DataFetchError, PlayerLookupError, ProjectionError, ValueError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

backcaster-0.3.4/src/backcaster/data.py

@@ -0,0 +1,9 @@
+"""Errors reported when local source data cannot be loaded or resolved."""
+
+
+class DataFetchError(RuntimeError):
+    pass
+
+
+class PlayerLookupError(RuntimeError):
+    pass