backcaster 0.3.0__py3-none-any.whl

backcaster/__init__.py

@@ -0,0 +1,4 @@
+"""backcaster package."""
+
+__all__ = ["__version__"]
+__version__ = "0.3.0"

backcaster/cli.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+import pandas as pd
+
+from backcaster.data import (
+    DataFetchError,
+    PlayerLookupError,
+    fetch_season_stats,
+    lookup_player_ids,
+    resolve_player_lookup,
+)
+from backcaster.marcel import ProjectionError, project_player, project_team
+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 _prior_years(year: int) -> tuple[int, int, int]:
+    return year - 1, year - 2, year - 3
+
+
+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 _require_columns(
+    df: pd.DataFrame, required: set[str], *, context: str, error_cls: type[Exception]
+) -> None:
+    missing = sorted(required - set(df.columns))
+    if missing:
+        cols = ", ".join(missing)
+        raise error_cls(f"{context} missing required column(s): {cols}.")
+
+
+def run_player(args: argparse.Namespace) -> int:
+    years = _prior_years(args.year)
+    pid_df = lookup_player_ids(args.name)
+    resolved = resolve_player_lookup(args.name, pid_df, years)
+    fg_key = resolved.get("key_fangraphs")
+    fg_key_numeric = pd.to_numeric(fg_key, errors="coerce") if pd.notna(fg_key) else None
+
+    frames = []
+    league_frames = []
+    for y in years:
+        df = fetch_season_stats(y, args.kind)
+        league = df.copy()
+        league["Season"] = y
+        league_frames.append(league)
+
+        row = pd.DataFrame()
+        if pd.notna(fg_key_numeric) and "IDfg" in league.columns:
+            idfg_numeric = pd.to_numeric(league["IDfg"], errors="coerce")
+            row = league[idfg_numeric == fg_key_numeric].copy()
+
+        if row.empty and pd.isna(fg_key_numeric):
+            _require_columns(
+                league,
+                {"Name"},
+                context=f"Season {y} {args.kind} stats for name fallback",
+                error_cls=ProjectionError,
+            )
+            row = league[league["Name"].astype(str).str.casefold() == args.name.casefold()].copy()
+        if row.empty:
+            raise ProjectionError(f"Missing season {y} for player '{args.name}'.")
+        frames.append(row)
+
+    prior = pd.concat(frames, ignore_index=True).sort_values("Season", ascending=False)
+    league_prior = pd.concat(league_frames, ignore_index=True)
+    proj = project_player(args.name, prior, args.kind, args.year, league_df=league_prior)
+    _render(proj, args.format, args.out)
+    return 0
+
+
+def run_team(args: argparse.Namespace) -> int:
+    years = _prior_years(args.year)
+    team_frames = []
+    league_frames = []
+    for y in years:
+        df = fetch_season_stats(y, args.kind)
+        _require_columns(
+            df, {"Team"}, context=f"Season {y} {args.kind} stats", error_cls=DataFetchError
+        )
+        league = df.copy()
+        league["Season"] = y
+        league_frames.append(league)
+
+        row = df[df["Team"] == args.team].copy()
+        if row.empty:
+            raise ProjectionError(f"Missing season {y} for team '{args.team}'.")
+        row["Season"] = y
+        team_frames.append(row)
+    all_team = pd.concat(team_frames, ignore_index=True)
+    all_league = pd.concat(league_frames, ignore_index=True)
+    proj = project_team(all_team, args.kind, args.year, baseline_df=all_league)
+    _render(proj, args.format, args.out)
+    return 0
+
+
+def run_batch(args: argparse.Namespace) -> int:
+    years = _prior_years(args.year)
+    frames = []
+    for y in years:
+        df = fetch_season_stats(y, args.kind)
+        df = df.copy()
+        df["Season"] = y
+        frames.append(df)
+    all_players = pd.concat(frames, ignore_index=True)
+    proj = project_team(all_players, args.kind, args.year)
+    _render(proj, args.format, args.out)
+    return 0
+
+
+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")
+
+    pp = sub.add_parser("player")
+    add_common(pp)
+    pp.add_argument("--name", required=True)
+    pp.set_defaults(func=run_player)
+
+    tp = sub.add_parser("team")
+    add_common(tp)
+    tp.add_argument("--team", required=True)
+    tp.set_defaults(func=run_team)
+
+    bp = sub.add_parser("batch")
+    add_common(bp)
+    bp.set_defaults(func=run_batch)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (DataFetchError, PlayerLookupError, ProjectionError, ValueError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

backcaster/data.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import logging
+import uuid
+from collections.abc import Callable, Iterable
+from numbers import Number
+from pathlib import Path
+from typing import SupportsInt, cast
+
+import pandas as pd
+
+from backcaster.schemas import Kind
+
+CACHE_ROOT = Path.home() / ".cache" / "backcaster"
+VALID_KINDS: tuple[Kind, ...] = ("batting", "pitching")
+
+LOGGER = logging.getLogger(__name__)
+
+
+class DataFetchError(RuntimeError):
+    pass
+
+
+class PlayerLookupError(RuntimeError):
+    pass
+
+
+def _normalize_name(value: str) -> str:
+    return " ".join(value.strip().lower().split())
+
+
+def _clean_name_value(row: pd.Series, key: str) -> str:
+    value = row.get(key)
+    return str(value).strip() if pd.notna(value) else ""
+
+
+def _candidate_full_names(row: pd.Series) -> set[str]:
+    names: set[str] = set()
+    first = _clean_name_value(row, "name_first")
+    last = _clean_name_value(row, "name_last")
+    given = _clean_name_value(row, "name_given")
+    if first and last:
+        names.add(_normalize_name(f"{first} {last}"))
+    if given:
+        names.add(_normalize_name(given))
+    return names
+
+
+def _to_int_or_none(value: object) -> int | None:
+    if value is None or value == "":
+        return None
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, (Number, str, bytes, bytearray)):
+        try:
+            return int(cast(SupportsInt | str | bytes | bytearray, value))
+        except (TypeError, ValueError):
+            return None
+    return None
+
+
+def _format_numeric_or_unknown(value: object) -> str:
+    as_int = _to_int_or_none(value)
+    return str(as_int) if as_int is not None else "?"
+
+
+def _filter_candidates_by_name(requested_name: str, lookup_df: pd.DataFrame) -> pd.DataFrame:
+    def _normalized_name_column(column_name: str) -> pd.Series:
+        if column_name not in lookup_df.columns:
+            return pd.Series("", index=lookup_df.index, dtype="object")
+        return lookup_df[column_name].astype("string").fillna("").str.strip()
+
+    first_names = _normalized_name_column("name_first")
+    last_names = _normalized_name_column("name_last")
+    given_names = _normalized_name_column("name_given")
+
+    full_names = (first_names + " " + last_names).str.strip().map(_normalize_name)
+    given_names = given_names.map(_normalize_name)
+
+    has_full_name = first_names.ne("") & last_names.ne("")
+    name_mask = (has_full_name & full_names.eq(requested_name)) | given_names.eq(requested_name)
+    return lookup_df[name_mask] if name_mask.any() else lookup_df
+
+
+def _overlaps_year_window(row: pd.Series, start_year: int, end_year: int) -> bool:
+    first = _to_int_or_none(row.get("mlb_played_first"))
+    last = _to_int_or_none(row.get("mlb_played_last"))
+    if first is None and last is None:
+        return True
+    if first is None:
+        # `last` cannot be None here because the both-None case returns above.
+        assert last is not None
+        return start_year <= last
+    if last is None:
+        return end_year >= first
+    return not (last < start_year or first > end_year)
+
+
+def _filter_candidates_by_years(candidates: pd.DataFrame, years: list[int]) -> pd.DataFrame:
+    has_year_cols = {"mlb_played_first", "mlb_played_last"}.issubset(candidates.columns)
+    if not years or not has_year_cols:
+        return candidates
+    start_year, end_year = min(years), max(years)
+    window_mask = candidates.apply(
+        lambda row: _overlaps_year_window(row, start_year, end_year), axis=1
+    )
+    return candidates[window_mask]
+
+
+def _format_candidate_detail(row: pd.Series) -> str:
+    given = _clean_name_value(row, "name_given")
+    first_name = _clean_name_value(row, "name_first")
+    last_name = _clean_name_value(row, "name_last")
+    label = given or f"{first_name} {last_name}".strip() or "Unknown Player"
+    fg = _format_numeric_or_unknown(row.get("key_fangraphs"))
+    start = _format_numeric_or_unknown(row.get("mlb_played_first"))
+    end = _format_numeric_or_unknown(row.get("mlb_played_last"))
+    return f"{label} (key_fangraphs={fg}, MLB={start}-{end})"
+
+
+def resolve_player_lookup(
+    name: str, lookup_df: pd.DataFrame, target_years: Iterable[int]
+) -> pd.Series:
+    if lookup_df.empty:
+        raise PlayerLookupError(f"No player found for '{name}'.")
+
+    requested = _normalize_name(name)
+    candidates = _filter_candidates_by_name(requested, lookup_df)
+
+    years = sorted({int(y) for y in target_years})
+    candidates = _filter_candidates_by_years(candidates, years)
+
+    if len(candidates) == 1:
+        return candidates.iloc[0]
+
+    if len(candidates) == 0:
+        raise PlayerLookupError(f"No player found for '{name}' in seasons {years}.")
+
+    details = [_format_candidate_detail(row) for _, row in candidates.iterrows()]
+
+    raise PlayerLookupError(
+        f"Duplicate player match for '{name}'. Candidates: " + "; ".join(details)
+    )
+
+
+def _cache_path(kind: Kind, year: int, ext: str = "csv") -> Path:
+    if kind not in VALID_KINDS:
+        expected = ", ".join(repr(value) for value in VALID_KINDS)
+        raise ValueError(f"Invalid kind {kind!r}. Expected one of: {expected}.")
+    CACHE_ROOT.mkdir(parents=True, exist_ok=True)
+    return CACHE_ROOT / f"{kind}_{year}.{ext}"
+
+
+def _read_cache(kind: Kind, year: int) -> pd.DataFrame | None:
+    parquet_path = _cache_path(kind, year, "parquet")
+    csv_path = _cache_path(kind, year, "csv")
+
+    if parquet_path.exists():
+        try:
+            return pd.read_parquet(parquet_path)
+        except Exception as exc:
+            LOGGER.warning(
+                "Parquet cache read failed for %s %s at %s; falling back to CSV if available: %s",
+                kind,
+                year,
+                parquet_path,
+                exc,
+            )
+
+    if csv_path.exists():
+        return pd.read_csv(csv_path)
+    return None
+
+
+def _atomic_write_frame(
+    df: pd.DataFrame,
+    target_path: Path,
+    writer: Callable[[pd.DataFrame, Path], None],
+) -> None:
+    tmp_path = target_path.with_suffix(f"{target_path.suffix}.{uuid.uuid4().hex}.tmp")
+    try:
+        writer(df, tmp_path)
+        tmp_path.replace(target_path)
+    finally:
+        if tmp_path.exists():
+            tmp_path.unlink()
+
+
+def _write_cache(kind: Kind, year: int, df: pd.DataFrame) -> None:
+    parquet_path = _cache_path(kind, year, "parquet")
+    csv_path = _cache_path(kind, year, "csv")
+
+    try:
+        _atomic_write_frame(
+            df, parquet_path, lambda frame, path: frame.to_parquet(path, index=False)
+        )
+    except Exception as exc:
+        LOGGER.warning(
+            "Parquet cache write failed for %s %s at %s; falling back to CSV: %s",
+            kind,
+            year,
+            parquet_path,
+            exc,
+        )
+        _atomic_write_frame(df, csv_path, lambda frame, path: frame.to_csv(path, index=False))
+
+
+def fetch_season_stats(year: int, kind: Kind, use_cache: bool = True) -> pd.DataFrame:
+    if not isinstance(kind, str) or kind not in ("batting", "pitching"):
+        raise DataFetchError(f"Invalid kind {kind!r}. Expected one of: 'batting', 'pitching'.")
+
+    cached = _read_cache(kind, year) if use_cache else None
+    if cached is not None:
+        return cached
+
+    try:
+        import pybaseball as pyb
+
+        if kind == "batting":
+            df = pyb.batting_stats(year)
+        else:
+            df = pyb.pitching_stats(year)
+    except Exception as exc:
+        raise DataFetchError(f"Unable to fetch {kind} stats for {year}: {exc}") from exc
+
+    if df is None or df.empty:
+        raise DataFetchError(f"No {kind} stats returned for {year}.")
+
+    _write_cache(kind, year, df)
+    return df
+
+
+def lookup_player_ids(name: str) -> pd.DataFrame:
+    parts = name.strip().split()
+    if len(parts) < 2:
+        raise PlayerLookupError("Provide both first and last name.")
+    first, last = parts[0], parts[-1]
+    try:
+        import pybaseball as pyb
+
+        df = pyb.playerid_lookup(last, first)
+    except Exception as exc:
+        raise PlayerLookupError(f"Failed player lookup for '{name}': {exc}") from exc
+    if df.empty:
+        raise PlayerLookupError(f"No player found for '{name}'.")
+    return df

backcaster/marcel.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import pandas as pd
+
+from backcaster.normalize import safe_divide
+from backcaster.schemas import MarcelConfig
+
+
+class ProjectionError(RuntimeError):
+    pass
+
+
+BATTING_COMPONENTS = ["PA", "AB", "H", "2B", "3B", "HR", "BB", "SO", "HBP", "SF"]
+PITCHING_COMPONENTS = ["IP", "ER", "H", "HR", "BB", "SO", "BF"]
+
+
+def _weighted_row(
+    rows: list[pd.Series], weights: tuple[float, float, float], cols: list[str]
+) -> pd.Series:
+    total_w = sum(weights[: len(rows)])
+    out = {}
+    for col in cols:
+        out[col] = (
+            sum(float(r.get(col, 0.0)) * w for r, w in zip(rows, weights)) / total_w
+            if total_w
+            else 0.0
+        )
+    return pd.Series(out)
+
+
+def _derive_batting_rates(s: pd.Series) -> pd.Series:
+    singles = s["H"] - s["2B"] - s["3B"] - s["HR"]
+    tb = singles + 2 * s["2B"] + 3 * s["3B"] + 4 * s["HR"]
+    avg = safe_divide(s["H"], s["AB"])
+    obp = safe_divide(
+        s["H"] + s["BB"] + s.get("HBP", 0), s["AB"] + s["BB"] + s.get("HBP", 0) + s.get("SF", 0)
+    )
+    slg = safe_divide(tb, s["AB"])
+    return pd.Series({"AVG": avg, "OBP": obp, "SLG": slg, "OPS": obp + slg})
+
+
+def _derive_pitching_rates(s: pd.Series) -> pd.Series:
+    era = safe_divide(s["ER"] * 9, s["IP"])
+    whip = safe_divide(s["H"] + s["BB"], s["IP"])
+    return pd.Series({"ERA": era, "WHIP": whip})
+
+
+def _compute_baseline_rates(df: pd.DataFrame, comps: list[str]) -> tuple[float, dict[str, float]]:
+    pt_col = comps[0]
+    present_cols = [c for c in comps if c in df.columns]
+    sums = df[present_cols].sum() if present_cols else pd.Series(dtype="float64")
+    league_pt = float(sums.get(pt_col, 0.0))
+    league_rates = {c: safe_divide(float(sums.get(c, 0.0)), league_pt) for c in comps[1:]}
+    return league_pt, league_rates
+
+
+def _validate_projection_kind(kind: str) -> str:
+    if kind not in {"batting", "pitching"}:
+        raise ProjectionError(f"Invalid kind {kind!r}. Expected one of: 'batting', 'pitching'.")
+    return kind
+
+
+def _projection_components(kind: str, config: MarcelConfig) -> tuple[list[str], float]:
+    if kind == "batting":
+        return BATTING_COMPONENTS, config.regression_pa
+    return PITCHING_COMPONENTS, config.regression_ip
+
+
+def _prepare_prior_df(
+    prior_three: pd.DataFrame, comps: list[str], optional_comps: set[str] | None = None
+) -> pd.DataFrame:
+    if "Season" not in prior_three.columns:
+        raise ProjectionError("Missing required Season column in prior seasons input.")
+
+    season_values = prior_three["Season"]
+    if season_values.isna().any():
+        raise ProjectionError("Season values must be non-missing in prior seasons input.")
+
+    try:
+        season_numeric = pd.to_numeric(season_values, errors="raise")
+    except (TypeError, ValueError) as exc:
+        raise ProjectionError("Season values must be numeric and consistently typed.") from exc
+
+    prior_df = (
+        prior_three.assign(Season=season_numeric)
+        .sort_values("Season", ascending=False, kind="mergesort")
+        .reset_index(drop=True)
+        .copy()
+    )
+
+    optional_comps = optional_comps or set()
+    missing_required = [c for c in comps if c not in prior_df.columns and c not in optional_comps]
+    if missing_required:
+        missing_required_str = ", ".join(sorted(missing_required))
+        raise ProjectionError(
+            f"Missing required component columns in prior seasons input: {missing_required_str}."
+        )
+
+    for c in optional_comps:
+        if c in comps and c not in prior_df.columns:
+            prior_df[c] = 0.0
+    return prior_df
+
+
+def project_player(
+    player_name: str,
+    prior_three: pd.DataFrame,
+    kind: str,
+    year: int,
+    config: MarcelConfig | None = None,
+    age: float = 29,
+    league_df: pd.DataFrame | None = None,
+    league_rates: dict[str, float] | None = None,
+) -> pd.DataFrame:
+    config = config or MarcelConfig()
+    if prior_three.empty:
+        raise ProjectionError("Expected at least one prior season for projection.")
+    if prior_three.shape[0] > 3:
+        raise ProjectionError("Expected at most three prior seasons for projection.")
+
+    kind = _validate_projection_kind(kind)
+    comps, reg_pt = _projection_components(kind, config)
+    optional_comps = {"HBP", "SF"} if kind == "batting" else set()
+    prior_df = _prepare_prior_df(prior_three, comps, optional_comps=optional_comps)
+
+    rows = [prior_df.iloc[i] for i in range(min(3, prior_df.shape[0]))]
+    weighted = _weighted_row(rows, config.season_weights, comps)
+
+    pt_col = comps[0]
+    weighted_pt = float(weighted[pt_col])
+    reliability = min(1.0, safe_divide(weighted_pt, config.reliability_scale))
+
+    if league_rates is None:
+        baseline_df = league_df if league_df is not None else prior_df
+        _, league_rates = _compute_baseline_rates(baseline_df, comps)
+
+    regressed = weighted.copy()
+    regressed[pt_col] = weighted_pt
+    for c in comps[1:]:
+        regressed_rate = safe_divide(
+            float(weighted[c]) + league_rates[c] * reg_pt, weighted_pt + reg_pt
+        )
+        regressed[c] = regressed_rate * weighted_pt
+
+    growth = config.default_pa_growth if kind == "batting" else config.default_ip_growth
+    age_adj = config.age_adjustment_fn(age)
+    projected_pt = weighted_pt * growth * age_adj
+    pt_scale = safe_divide(projected_pt, weighted_pt)
+    regressed *= pt_scale
+
+    if kind == "batting":
+        rates = _derive_batting_rates(regressed)
+    else:
+        rates = _derive_pitching_rates(regressed)
+
+    output = pd.concat([regressed, rates])
+    output["Reliability"] = reliability
+    output["Name"] = player_name
+    output["Year"] = year
+    return output.to_frame().T
+
+
+def project_team(
+    team_df: pd.DataFrame,
+    kind: str,
+    year: int,
+    config: MarcelConfig | None = None,
+    baseline_df: pd.DataFrame | None = None,
+) -> pd.DataFrame:
+    config = config or MarcelConfig()
+    if "Name" not in team_df.columns:
+        raise ProjectionError("Missing required Name column in team input.")
+    if "Season" not in team_df.columns:
+        raise ProjectionError("Missing required Season column in team input.")
+    kind = _validate_projection_kind(kind)
+    if kind == "batting":
+        comps = BATTING_COMPONENTS
+    else:
+        comps = PITCHING_COMPONENTS
+    baseline_source = baseline_df if baseline_df is not None else team_df
+    _, baseline_rates = _compute_baseline_rates(baseline_source, comps)
+    group_column = team_df["IDfg"].fillna(team_df["Name"]) if "IDfg" in team_df.columns else "Name"
+    grouped = team_df.groupby(group_column, dropna=False, sort=False)
+    projections: list[pd.DataFrame] = []
+    for _, grp in grouped:
+        sorted_grp = grp.sort_values("Season", ascending=False, kind="mergesort")
+        display_name = sorted_grp["Name"].iloc[0]
+        if not isinstance(display_name, str):
+            raise ProjectionError("Encountered non-string player name in team input.")
+        projections.append(
+            project_player(
+                display_name,
+                sorted_grp.head(3),
+                kind,
+                year,
+                config,
+                league_rates=baseline_rates,
+            )
+        )
+    if not projections:
+        raise ProjectionError("No players available to project for this team.")
+    return pd.concat(projections, ignore_index=True)

backcaster/normalize.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import pandas as pd
+
+
+def numeric_columns(df: pd.DataFrame, exclude: set[str] | None = None) -> list[str]:
+    return [
+        c for c in df.columns if c not in (exclude or ()) and pd.api.types.is_numeric_dtype(df[c])
+    ]
+
+
+def safe_divide(numerator: float, denominator: float) -> float:
+    return 0.0 if denominator == 0 else float(numerator) / float(denominator)

backcaster/outputs.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+
+def to_cli_table(df: pd.DataFrame) -> str:
+    return df.to_string(index=False)
+
+
+def to_csv(df: pd.DataFrame, out_path: str | Path) -> Path:
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    df.to_csv(out, index=False)
+    return out
+
+
+def to_html(df: pd.DataFrame, out_path: str | Path) -> Path:
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    html = df.to_html(index=False, border=0)
+    out.write_text(html, encoding="utf-8")
+    return out

backcaster/schemas.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Literal
+
+import pandas as pd
+
+Kind = Literal["batting", "pitching"]
+OutputFormat = Literal["cli", "csv", "html"]
+
+
+@dataclass(frozen=True)
+class MarcelConfig:
+    """Configuration knobs for Marcel-style projection."""
+
+    season_weights: tuple[float, float, float] = (5.0, 4.0, 3.0)
+    regression_pa: float = 1200.0
+    regression_ip: float = 200.0
+    age_adjustment_fn: Callable[[float], float] = lambda age: 1.0 + (0.006 if age <= 29 else -0.003)
+    reliability_scale: float = 1200.0
+    default_pa_growth: float = 1.0
+    default_ip_growth: float = 1.0
+
+
+@dataclass
+class ProjectionResult:
+    player_name: str
+    kind: Kind
+    year: int
+    projected: pd.DataFrame
+    source_years: tuple[int, int, int]
+    reliability: float
+    meta: dict[str, str] = field(default_factory=dict)

backcaster-0.3.0.dist-info/METADATA

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: backcaster
+Version: 0.3.0
+Summary: Marcel-style MLB projection CLI built on pybaseball
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jeffreywevans/backcaster
+Project-URL: Repository, https://github.com/jeffreywevans/backcaster
+Project-URL: Issues, https://github.com/jeffreywevans/backcaster/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: pybaseball>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.11.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pandas-stubs>=2.2; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+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`.
+
+It supports:
+- **Single player projections** (`player`)
+- **Single team projections** (`team`)
+- **League-wide batch projections** (`batch`)
+- Output as terminal table, CSV, or HTML
+
+---
+
+## Installation
+
+### Requirements
+- Python **3.13+**
+- Internet access for first-time stat fetches (data is cached locally afterward)
+
+### Install from source (recommended for contributors)
+
+```bash
+# from repo root
+uv sync
+```
+
+This installs runtime dependencies and the `backcaster` CLI entrypoint defined in `pyproject.toml`.
+
+### Install in editable/dev mode
+
+```bash
+uv sync --extra dev
+```
+
+This adds test/lint/type-check/build tooling (`pytest`, `pytest-cov`, `ruff`, `mypy`, `pandas-stubs`, `build`).
+
+### Build/install as a package
+
+```bash
+python -m build
+pip install dist/backcaster-*.whl
+```
+
+---
+
+## Quickstart CLI usage
+
+All commands require:
+- `--year` target projection year
+- `--kind` one of `batting` or `pitching`
+
+Subcommand-specific required options:
+- `player` requires `--name`
+- `team` requires `--team`
+- `batch` requires no additional required option
+
+```bash
+backcaster <player|team|batch> [subcommand-options] --year <YEAR> --kind <batting|pitching> [--format cli|csv|html] [--out PATH]
+```
+
+### 1) Player projection
+
+```bash
+backcaster player --name "Mookie Betts" --year 2026 --kind batting
+```
+
+### 2) Team projection
+
+```bash
+backcaster team --team LAD --year 2026 --kind pitching
+```
+
+### 3) Batch projection (all players returned by source data)
+
+```bash
+backcaster batch --year 2026 --kind batting
+```
+
+### File outputs
+
+```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
+```
+
+> `--out` is required for `csv` and `html` formats.
+
+---
+
+## Output examples
+
+### CLI table output (`--format cli`, default)
+
+Example shape (columns vary by batting vs pitching):
+
+```text
+   PA    AB     H   2B   3B    HR    BB    SO   HBP    SF    AVG    OBP    SLG    OPS  Reliability          Name  Year
+610.2 545.1 162.4 34.1  2.8  32.6  67.9 119.3   5.6   4.7  0.298  0.384  0.531  0.915        0.89  Mookie Betts  2026
+```
+
+### CSV output (`--format csv`)
+A single-row CSV for `player`; multi-row CSV for `team` and `batch`.
+
+### HTML output (`--format html`)
+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
+
+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.
+
+---
+
+## Dependency notes
+
+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`
+- `ruff`
+- `mypy`, `pandas-stubs`
+
+### Lockfile policy (`uv.lock`)
+
+`uv.lock` pins transitive versions for reproducible environments when working from a Git checkout.
+
+Release/source ZIP archives may not include `uv.lock`. If it is missing in your environment, regenerate it locally:
+
+```bash
+uv lock
+```
+
+Do not hand-edit `uv.lock`; regenerate it when dependencies change.
+
+---
+
+## What this projection does and does not claim
+
+### What it does
+- Implements a **Marcel-style** weighted/regressed projection over prior seasons.
+- Uses configurable reliability/regression/playing-time assumptions in code defaults.
+- Produces transparent, table-based outputs for downstream analysis.
+
+### What it does **not** claim
+- It is **not** an official MLB/club forecasting system.
+- It does **not** model injuries, role changes, park effects, coaching strategy, or transaction context in a comprehensive way.
+- It does **not** guarantee predictive superiority versus commercial/public projection systems.
+- It should be treated as a **baseline projection tool**, not a betting or financial decision engine.
+
+---
+
+## Development and quality checks
+
+For release preparation and PyPI Trusted Publishing, see [RELEASING.md](RELEASING.md).
+Changes for the next release are recorded in [CHANGELOG.md](CHANGELOG.md).
+
+### Run tests
+
+```bash
+pytest
+```
+
+### Coverage + JUnit reports
+
+```bash
+pytest --junitxml=pytest.xml --cov=src --cov-report=xml:coverage.xml
+```
+
+### Lint and types
+
+```bash
+ruff check .
+mypy
+```
+
+### SonarScanner
+
+```bash
+sonar-scanner -Dsonar.projectVersion=$(PYTHONPATH=src python -c "from backcaster import __version__; print(__version__)")
+```
+
+Sonar consumes:
+- `coverage.xml`
+- `pytest.xml`
+
+---
+
+## 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.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+backcaster/__init__.py,sha256=euTgnCilMbmN6lU2sTIDND4iY9W7tk_sCrcfBAP51JI,75
+backcaster/cli.py,sha256=Jv0lyC3JOkC5rogWOzRMND2M2KInAvvt9sch6ALYyXc,5315
+backcaster/data.py,sha256=ot5zTu-A5P6iFHmxbnrBgYO6GP6TUHlvsTDDLgJfn7o,8138
+backcaster/marcel.py,sha256=f9qpMRJ0u0NrCfDInIAgHQ-KW3SsydyQ1kA_n-Dhgks,7342
+backcaster/normalize.py,sha256=gJWS5uXCVgJWf456RdoWoZ9BII1IqfeyFdsRPvFcljc,405
+backcaster/outputs.py,sha256=RQQOUegTmeBqz3NkOH7QKR1pT2pUqifWvlw1Ccy3jbQ,589
+backcaster/schemas.py,sha256=jCsVixeJFQjHfqKFM24f6xg1emGUD-83-41p9xauTUo,925
+backcaster-0.3.0.dist-info/licenses/LICENSE,sha256=FwqY_Dpco13UKumXJCjQqeZastouwYyUyIz6_UBOa44,1080
+backcaster-0.3.0.dist-info/METADATA,sha256=Cg8hHrIbVKC0yHj3yjFDkBtJ8g-KJhFqdt6FnPPp0Gg,6597
+backcaster-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+backcaster-0.3.0.dist-info/entry_points.txt,sha256=rowOJPeGAsJbYR_64Y8wGSS6UszIMC7YxH-BnSqH77Y,51
+backcaster-0.3.0.dist-info/top_level.txt,sha256=gF7yELu88KPtSo1912jnCC4zVJ-ND7SuA-x1aijvDAI,11
+backcaster-0.3.0.dist-info/RECORD,,

backcaster-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

backcaster-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+backcaster = backcaster.cli:main

backcaster-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 backcaster contributors
+
+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.

backcaster-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+backcaster