nfl-data-mcp 0.1.2__py3-none-any.whl

nfl_data_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""NFL data services and MCP adapter."""
+
+__version__ = "0.1.2"

nfl_data_mcp/cli.py

@@ -0,0 +1,63 @@
+"""Command-line entry points for synchronization and diagnostics."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Sequence
+
+from nfl_data_mcp import __version__
+from nfl_data_mcp.config import get_settings
+from nfl_data_mcp.ingestion.sync import SUPPORTED_DATASETS, sync_datasets
+from nfl_data_mcp.storage.catalog import Catalog
+
+
+def _sync_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nfl-data-sync",
+        description="Explicitly synchronize nflverse datasets into the local DuckDB catalog.",
+    )
+    parser.add_argument(
+        "--datasets",
+        nargs="+",
+        choices=SUPPORTED_DATASETS,
+        default=list(SUPPORTED_DATASETS),
+    )
+    parser.add_argument("--season", type=int, required=True)
+    parser.add_argument(
+        "--allow-network",
+        action="store_true",
+        help="Required confirmation that the command may download nflverse data.",
+    )
+    return parser
+
+
+def sync_main(argv: Sequence[str] | None = None) -> int:
+    args = _sync_parser().parse_args(argv)
+    if not args.allow_network:
+        raise SystemExit("Refusing to download data without --allow-network.")
+    settings = get_settings()
+    statuses = sync_datasets(
+        Catalog(settings.catalog_path),
+        datasets=args.datasets,
+        season=args.season,
+    )
+    print(json.dumps([status.model_dump(mode="json") for status in statuses], indent=2))
+    return 0
+
+
+def doctor_main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="nfl-data-doctor",
+        description="Validate that the local catalog is readable and report coverage.",
+    )
+    parser.parse_args(argv)
+    settings = get_settings()
+    catalog = Catalog(settings.catalog_path)
+    result = {
+        **catalog.health(),
+        "server_version": __version__,
+        "datasets": [status.model_dump(mode="json") for status in catalog.list_statuses()],
+    }
+    print(json.dumps(result, indent=2))
+    return 0

nfl_data_mcp/config.py

@@ -0,0 +1,52 @@
+"""Application configuration."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from pathlib import Path
+
+from platformdirs import user_data_path
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class RuntimeMode(StrEnum):
+    AUTO = "auto"
+    OFFLINE = "offline"
+    SNAPSHOT = "snapshot"
+
+
+class Settings(BaseSettings):
+    """Validated runtime settings loaded from NFL_MCP_* variables."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="NFL_MCP_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    data_dir: Path = Field(
+        default_factory=lambda: user_data_path("nfl-data-mcp", ensure_exists=False)
+    )
+    log_level: str = "INFO"
+    max_results: int = Field(default=200, ge=1, le=1_000)
+    mode: RuntimeMode = RuntimeMode.AUTO
+    refresh_ttl_players_hours: int = Field(default=24, ge=1)
+    refresh_ttl_schedules_hours: int = Field(default=6, ge=1)
+    refresh_ttl_player_stats_hours: int = Field(default=6, ge=1)
+    refresh_ttl_team_stats_hours: int = Field(default=6, ge=1)
+    refresh_ttl_rosters_hours: int = Field(default=6, ge=1)
+    refresh_ttl_injuries_hours: int = Field(default=2, ge=1)
+    refresh_ttl_depth_charts_hours: int = Field(default=6, ge=1)
+    refresh_ttl_snap_counts_hours: int = Field(default=12, ge=1)
+
+    @property
+    def catalog_path(self) -> Path:
+        return self.data_dir / "catalog.duckdb"
+
+
+def get_settings() -> Settings:
+    """Build settings at the application boundary."""
+
+    return Settings()

nfl_data_mcp/domain/__init__.py

@@ -0,0 +1,21 @@
+"""Public domain contracts."""
+
+from nfl_data_mcp.domain.models import (
+    AsOfStatus,
+    DataEnvelope,
+    DatasetStatus,
+    Game,
+    PageInfo,
+    Player,
+    ResponseMeta,
+)
+
+__all__ = [
+    "AsOfStatus",
+    "DataEnvelope",
+    "DatasetStatus",
+    "Game",
+    "PageInfo",
+    "Player",
+    "ResponseMeta",
+]

nfl_data_mcp/domain/models.py

@@ -0,0 +1,184 @@
+"""Stable models returned by services and MCP tools."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.types import JsonValue
+
+
+class AsOfStatus(StrEnum):
+    CURRENT_SNAPSHOT = "current_snapshot"
+    WEEK_KEYED_NOT_KNOWLEDGE_TIME = "week_keyed_not_knowledge_time"
+    ARCHIVED_AS_OF = "archived_as_of"
+    DERIVED_PRIOR_ONLY = "derived_prior_only"
+
+
+class CacheStatus(StrEnum):
+    HIT = "hit"
+    REFRESHED = "refreshed"
+    STALE = "stale"
+
+
+class DomainModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class Player(DomainModel):
+    player_id: str
+    display_name: str
+    first_name: str | None = None
+    last_name: str | None = None
+    position: str | None = None
+    team: str | None = None
+    status: str | None = None
+    gsis_id: str | None = None
+    espn_id: str | None = None
+    pfr_id: str | None = None
+    rookie_season: int | None = None
+    last_season: int | None = None
+
+
+class StatSnapshot(DomainModel):
+    entity_id: str
+    entity_name: str
+    team: str
+    season: int | None
+    week: int | None
+    season_type: str
+    aggregation: str = "game"
+    game_id: str | None = None
+    opponent_team: str | None = None
+    position: str | None = None
+    offense: dict[str, JsonValue] = Field(default_factory=dict)
+    defense: dict[str, JsonValue] = Field(default_factory=dict)
+    special_teams: dict[str, JsonValue] = Field(default_factory=dict)
+    miscellaneous: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class Game(DomainModel):
+    game_id: str
+    season: int
+    week: int
+    season_type: str
+    home_team: str
+    away_team: str
+    kickoff: datetime | None = None
+    home_score: int | None = None
+    away_score: int | None = None
+
+
+class Team(DomainModel):
+    team: str
+    name: str
+    nickname: str
+    conference: str | None = None
+    division: str | None = None
+    primary_color: str | None = None
+    secondary_color: str | None = None
+    logo_url: str | None = None
+
+
+class RosterEntry(DomainModel):
+    season: int
+    week: int
+    team: str
+    player_id: str
+    full_name: str
+    position: str | None = None
+    depth_chart_position: str | None = None
+    jersey_number: int | None = None
+    status: str | None = None
+    status_description: str | None = None
+
+
+class InjuryReport(DomainModel):
+    season: int
+    week: int
+    team: str
+    player_id: str
+    full_name: str
+    position: str | None = None
+    primary_injury: str | None = None
+    secondary_injury: str | None = None
+    report_status: str | None = None
+    practice_status: str | None = None
+    modified_at: datetime | None = None
+
+
+class DepthChartEntry(DomainModel):
+    season: int
+    week: int
+    team: str
+    player_id: str
+    full_name: str
+    position: str | None = None
+    formation: str | None = None
+    depth_position: str | None = None
+    depth_rank: int | None = None
+
+
+class SnapCount(DomainModel):
+    game_id: str
+    season: int
+    week: int
+    team: str
+    opponent_team: str | None = None
+    player_id: str
+    player_name: str
+    position: str | None = None
+    offense_snaps: int = 0
+    offense_pct: float = 0
+    defense_snaps: int = 0
+    defense_pct: float = 0
+    special_teams_snaps: int = 0
+    special_teams_pct: float = 0
+
+
+class StatLeader(DomainModel):
+    rank: int
+    entity_id: str
+    entity_name: str
+    team: str
+    stat: str
+    value: float
+
+
+class DatasetStatus(DomainModel):
+    dataset: str
+    source: str
+    source_version: str
+    ingested_at: datetime
+    row_count: int = Field(ge=0)
+    season_min: int | None = None
+    season_max: int | None = None
+    week_min: int | None = None
+    week_max: int | None = None
+    as_of_status: AsOfStatus
+
+
+class ResponseMeta(DomainModel):
+    request_id: str = Field(default_factory=lambda: str(uuid4()))
+    dataset: str
+    source: str = "nflverse"
+    source_version: str
+    ingested_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    as_of_status: AsOfStatus
+    mode: str = "offline"
+    cache_status: CacheStatus = CacheStatus.HIT
+    freshness: str = "cached"
+    warnings: tuple[str, ...] = ()
+
+
+class PageInfo(DomainModel):
+    limit: int = Field(ge=1)
+    next_cursor: str | None = None
+
+
+class DataEnvelope[T](DomainModel):
+    data: T
+    meta: ResponseMeta
+    page: PageInfo | None = None

nfl_data_mcp/domain/provenance.py

@@ -0,0 +1,26 @@
+"""Helpers for producing consistent response provenance."""
+
+from __future__ import annotations
+
+from nfl_data_mcp.domain.models import CacheStatus, DatasetStatus, ResponseMeta
+
+
+def response_meta(
+    status: DatasetStatus,
+    *,
+    mode: str = "offline",
+    cache_status: CacheStatus = CacheStatus.HIT,
+    freshness: str = "cached",
+    warnings: tuple[str, ...] = (),
+) -> ResponseMeta:
+    return ResponseMeta(
+        dataset=status.dataset,
+        source=status.source,
+        source_version=status.source_version,
+        ingested_at=status.ingested_at,
+        as_of_status=status.as_of_status,
+        mode=mode,
+        cache_status=cache_status,
+        freshness=freshness,
+        warnings=warnings,
+    )

nfl_data_mcp/domain/resolution.py

@@ -0,0 +1,102 @@
+"""Resolve human-friendly team and season references."""
+
+from __future__ import annotations
+
+from datetime import date
+
+from nfl_data_mcp.errors import InvalidArgumentError
+
+SeasonRef = int | str
+
+TEAM_ALIASES = {
+    "ARI": ("arizona", "arizona cardinals", "cardinals"),
+    "ATL": ("atlanta", "atlanta falcons", "falcons"),
+    "BAL": ("baltimore", "baltimore ravens", "ravens"),
+    "BUF": ("buffalo", "buffalo bills", "bills"),
+    "CAR": ("carolina", "carolina panthers", "panthers"),
+    "CHI": ("chicago", "chicago bears", "bears"),
+    "CIN": ("cincinnati", "cincinnati bengals", "bengals"),
+    "CLE": ("cleveland", "cleveland browns", "browns"),
+    "DAL": ("dallas", "dallas cowboys", "cowboys"),
+    "DEN": ("denver", "denver broncos", "broncos"),
+    "DET": ("detroit", "detroit lions", "lions"),
+    "GB": ("green bay", "green bay packers", "packers"),
+    "HOU": ("houston", "houston texans", "texans"),
+    "IND": ("indianapolis", "indianapolis colts", "colts"),
+    "JAX": ("jacksonville", "jacksonville jaguars", "jaguars", "jac"),
+    "KC": ("kansas city", "kansas city chiefs", "chiefs"),
+    "LA": ("los angeles rams", "la rams", "rams", "lar"),
+    "LAC": ("los angeles chargers", "la chargers", "chargers"),
+    "LV": ("las vegas", "las vegas raiders", "raiders", "oak"),
+    "MIA": ("miami", "miami dolphins", "dolphins"),
+    "MIN": ("minnesota", "minnesota vikings", "vikings"),
+    "NE": ("new england", "new england patriots", "patriots"),
+    "NO": ("new orleans", "new orleans saints", "saints"),
+    "NYG": ("new york giants", "ny giants", "giants"),
+    "NYJ": ("new york jets", "ny jets", "jets"),
+    "PHI": ("philadelphia", "philadelphia eagles", "eagles"),
+    "PIT": ("pittsburgh", "pittsburgh steelers", "steelers"),
+    "SEA": ("seattle", "seattle seahawks", "seahawks"),
+    "SF": ("san francisco", "san francisco 49ers", "49ers", "niners"),
+    "TB": ("tampa bay", "tampa bay buccaneers", "buccaneers", "bucs"),
+    "TEN": ("tennessee", "tennessee titans", "titans"),
+    "WAS": ("washington", "washington commanders", "commanders", "wsh"),
+}
+
+_TEAM_LOOKUP = {
+    alias.casefold(): abbreviation
+    for abbreviation, aliases in TEAM_ALIASES.items()
+    for alias in (abbreviation, *aliases)
+}
+
+
+def resolve_team(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = " ".join(value.strip().casefold().replace(".", "").split())
+    team = _TEAM_LOOKUP.get(normalized)
+    if team is None:
+        raise InvalidArgumentError(
+            f"Unknown NFL team {value!r}.",
+            hint="Use a team abbreviation, city, nickname, or full name.",
+        )
+    return team
+
+
+def football_season(today: date | None = None) -> int:
+    """Return the NFL season currently in progress, including Jan/Feb playoffs."""
+
+    resolved = today or date.today()
+    return resolved.year - 1 if resolved.month <= 2 else resolved.year
+
+
+def latest_stat_season(today: date | None = None) -> int:
+    """Return the latest season expected to have weekly stat files."""
+
+    resolved = today or date.today()
+    return resolved.year - 1 if resolved.month <= 8 else resolved.year
+
+
+def resolve_season(value: SeasonRef, *, today: date | None = None) -> int:
+    if isinstance(value, int):
+        season = value
+    else:
+        normalized = value.strip().casefold()
+        current = football_season(today)
+        aliases = {
+            "current": current,
+            "upcoming": (today or date.today()).year,
+            "previous": current - 1,
+        }
+        if normalized.isdigit():
+            season = int(normalized)
+        elif normalized in aliases:
+            season = aliases[normalized]
+        else:
+            raise InvalidArgumentError(
+                f"Unknown season reference {value!r}.",
+                hint="Use a four-digit year, current, upcoming, or previous.",
+            )
+    if not 1999 <= season <= 2100:
+        raise InvalidArgumentError("season must be between 1999 and 2100.")
+    return season

nfl_data_mcp/errors.py

@@ -0,0 +1,52 @@
+"""Stable public error types."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class ErrorCode(StrEnum):
+    INVALID_ARGUMENT = "INVALID_ARGUMENT"
+    NOT_FOUND = "NOT_FOUND"
+    DATASET_NOT_SYNCED = "DATASET_NOT_SYNCED"
+    SOURCE_UNAVAILABLE = "SOURCE_UNAVAILABLE"
+
+
+class NflDataError(Exception):
+    """An expected error safe to translate at public boundaries."""
+
+    def __init__(self, code: ErrorCode, message: str, *, hint: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.hint = hint
+
+
+class InvalidArgumentError(NflDataError):
+    def __init__(self, message: str, *, hint: str | None = None) -> None:
+        super().__init__(ErrorCode.INVALID_ARGUMENT, message, hint=hint)
+
+
+class NotFoundError(NflDataError):
+    def __init__(self, message: str, *, hint: str | None = None) -> None:
+        super().__init__(ErrorCode.NOT_FOUND, message, hint=hint)
+
+
+class DatasetNotSyncedError(NflDataError):
+    def __init__(self, dataset: str) -> None:
+        super().__init__(
+            ErrorCode.DATASET_NOT_SYNCED,
+            f"The {dataset!r} dataset has not been synchronized.",
+            hint=f"Run `nfl-data-sync --datasets {dataset} --season <year>` first.",
+        )
+
+
+class SourceUnavailableError(NflDataError):
+    def __init__(self, dataset: str, *, cached: bool = False) -> None:
+        message = f"The upstream source for {dataset!r} is currently unavailable."
+        hint = (
+            "A stale cached copy was not available; retry when network access is restored."
+            if not cached
+            else "A stale cached copy is available."
+        )
+        super().__init__(ErrorCode.SOURCE_UNAVAILABLE, message, hint=hint)

nfl_data_mcp/ingestion/__init__.py

@@ -0,0 +1,5 @@
+"""nflverse ingestion and normalization."""
+
+from nfl_data_mcp.ingestion.sync import sync_datasets
+
+__all__ = ["sync_datasets"]