mlb-statsapi-pydantic 0.0.1__tar.gz

mlb_statsapi_pydantic-0.0.1/.claude/CLAUDE.md

@@ -0,0 +1,11 @@
+# Overview
+
+This project is a Pydantic rewrite of [MLB-StatsAPI](https://github.com/toddrob99/MLB-StatsAPI) to take
+advantage of pydantics type system and rich libraries.
+
+Always use Pydantic best practices, preferring structured models over raw dictionaries.
+
+Document models in `docs/` and update docs when making model changes. When
+taking on a task, complete all steps and ensure verification methods pass
+before marking the task complete. A completed task should be marked as such in
+`mlb-statsapi-pydantic/.claude/tasks.md`

mlb_statsapi_pydantic-0.0.1/.claude/hooks/run_pytest.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+source .venv/bin/activate && python3 -m pytest tests/ -x -q >&2
+if [ $? -eq 1 ]; then
+  exit 2 # Exit code 2 tells Claude to treat as feedback/error
+else
+  exit 0 # Exit code 0 means success, continue
+fi

mlb_statsapi_pydantic-0.0.1/.claude/mlb-stats-memory.md

@@ -0,0 +1,135 @@
+# MLB Stats API — Research Reference
+
+## API Overview
+
+- **Base URL:** `https://statsapi.mlb.com/api/`
+- **Versions:** Most endpoints use `v1`; live game feed uses `v1.1`
+- **Auth:** None required for public data (some analytics/statcast endpoints need auth)
+- **Response format:** JSON; all responses include a `copyright` field
+
+---
+
+## Response Patterns
+
+### Common Root Structure
+Every response wraps data in a named array: `{"copyright": "...", "teams": [...]}`, `{"people": [...]}`, `{"dates": [...]}`, etc.
+
+### Reference Object Pattern — `{id, name, link}`
+Used everywhere for cross-references (teams, venues, leagues, divisions, people). Variations:
+- Minimal: `{id, link}` (e.g. `springVenue`)
+- Standard: `{id, name, link}`
+- Extended: `{id, name, link, abbreviation, ...}` (e.g. `springLeague`)
+
+### Code/Description Pattern — `{code, description}`
+Used for: `batSide`, `pitchHand`, `gameType`, position types.
+
+### Enum-like Fields
+| Field | Values |
+|-------|--------|
+| `abstractGameState` | Preview, Live, Final |
+| `codedGameState` | P, S, I, F, and others |
+| `gameType` | R (regular), S (spring), F (wild card), D (division), L (league), W (world series), C, P, A, E, I |
+| `batSide/pitchHand code` | L, R, S (switch) |
+| `dayNight` | day, night |
+| `positionType` | Pitcher, Catcher, Infielder, Outfielder, Hitter, Runner, etc. |
+
+---
+
+## Key Endpoint Response Structures
+
+### Sports (`/api/v1/sports`)
+Flat array. Fields: `id`, `code`, `link`, `name`, `abbreviation`, `sortOrder`, `activeStatus` (boolean).
+
+### Teams (`/api/v1/teams?sportId=1`)
+Rich objects. Notable fields:
+- Multiple name variants: `name`, `teamName`, `shortName`, `franchiseName`, `clubName`
+- Nested refs: `venue`, `springVenue`, `league`, `division`, `springLeague`, `sport`
+- `season` (int), `firstYearOfPlay` (string), `active` (boolean), `allStarStatus` (string)
+
+### Schedule (`/api/v1/schedule?sportId=1&date=MM/DD/YYYY`)
+Nested hierarchy: root → `dates[]` → `games[]` → `teams.{away,home}`
+- Root-level aggregates: `totalItems`, `totalEvents`, `totalGames`, `totalGamesInProgress`
+- Same aggregates repeated per date
+- Game fields: `gamePk`, `gameGuid`, `link`, `gameType`, `season`, `gameDate` (ISO 8601), `officialDate` (YYYY-MM-DD)
+- `status` object: `abstractGameState`, `codedGameState`, `detailedState`, `statusCode`, `startTimeTBD`
+- `venue` ref, `dayNight` field
+
+### People (`/api/v1/people/{id}`)
+Single person wrapped in `people[]` array. Notable fields:
+- `id`, `fullName`, `firstName`, `lastName`, `primaryNumber`
+- `birthDate` (YYYY-MM-DD), `currentAge`, `birthCity`, `birthCountry`
+- `height` (string, e.g. `6' 2"`), `weight` (int)
+- `primaryPosition` — has `code`, `name`, `type`, `abbreviation`
+- `batSide`, `pitchHand` — `{code, description}`
+- `strikeZoneTop`, `strikeZoneBottom` (floats)
+- `mlbDebutDate` (optional), `nickName` (optional)
+- Name variants: `useName`, `boxscoreName`, `nickName`
+
+### Standings
+Division-grouped. Structure: `records[]` → `teamRecords[]`
+- Team record fields: `wins`, `losses`, `winningPercentage`, `gamesBack`, `wildCardGamesBack`, `divisionRank`, `wildCardRank`, `eliminationNumber`
+- `streak` object, `leagueRecord`, `records` (splits)
+
+### Boxscore
+`teams.{away,home}` each with:
+- `teamStats.{batting,pitching,fielding}` — aggregate stats
+- `players` dict keyed by `"ID{playerId}"` — individual player stats
+- `battingOrder` array, `info` array, `note` strings
+
+### Linescore
+`innings[]` array with `home`/`away` each having `runs`, `hits`, `errors` per inning.
+Top-level `teams.{home,away}` with game totals.
+
+### Live Feed (`/api/v1.1/game/{gamePk}/feed/live`)
+Largest response. Top-level: `gameData`, `liveData`
+- `gameData`: datetime, status, teams, players, venue, weather, probablePitchers
+- `liveData.plays`: allPlays, currentPlay, scoringPlays
+- `liveData.linescore`: same as linescore endpoint
+- `liveData.boxscore`: same as boxscore endpoint
+
+---
+
+## Reference Library (toddrob99/MLB-StatsAPI)
+
+### 27 Public Functions
+**Schedule/Game:** `schedule`, `boxscore`, `boxscore_data`, `linescore`, `last_game`, `next_game`, `game_scoring_plays`, `game_scoring_play_data`, `game_highlights`, `game_highlight_data`, `game_pace`, `game_pace_data`
+
+**Player:** `player_stats`, `player_stat_data`, `lookup_player`, `latest_season`
+
+**Team:** `lookup_team`, `roster`, `team_leaders`, `team_leader_data`
+
+**League:** `league_leaders`, `league_leader_data`, `standings`, `standings_data`
+
+**Utility:** `meta`, `notes`, `get`
+
+### Endpoint System
+60+ endpoints defined in `endpoints.py` as a dict. Each has:
+- `url` — template with `{ver}` and `{param}` placeholders
+- `path_params` — dict with type, default, required, leading/trailing slash
+- `query_params` — list of allowed query param names
+- `required_params` — list of lists (OR combinations)
+- `note` — developer guidance (optional)
+
+### Key Details
+- Only dependency: `requests`
+- No type hints or Pydantic models
+- Returns formatted strings (display) or raw dicts (data variants)
+- Core `get()` function handles all HTTP, param validation, URL construction
+- Uses `datetime.now().year` as default season
+- Logger name: `"statsapi"`
+
+---
+
+## Meta Endpoint Types
+Valid types for `/api/v1/meta?type=X`:
+awards, baseballStats, eventTypes, freeGameTypes, gameStatus, gameTypes, hitTrajectories, jobTypes, languages, leagueLeaderTypes, logicalEvents, metrics, pitchCodes, pitchTypes, platforms, positions, reviewReasons, rosterTypes, runnerDetailTypes, scheduleTypes, scheduleEventTypes, situationCodes, sky, standingsTypes, statGroups, statTypes, violationTypes, windDirection
+
+---
+
+## Known Quirks
+- Some fields appear/disappear depending on game state or context
+- `springVenue` has only `{id, link}` — no `name`
+- Boxscore `players` dict uses string keys like `"ID660271"` instead of integer keys
+- Date formats vary: `gameDate` is ISO 8601, `officialDate` is YYYY-MM-DD, schedule query uses MM/DD/YYYY
+- `height` is a display string (`6' 2"`) not a numeric value
+- `firstYearOfPlay` on teams is a string, not int

mlb_statsapi_pydantic-0.0.1/.claude/refactor_tasks.md

@@ -0,0 +1,188 @@
+# Model Refactoring Tasks
+
+> Branch: `refactor-models`
+> Based on comprehensive code review of all 20 model files.
+
+---
+
+## Task 1: Consolidate shared models into `_base.py`
+**Status:** completed
+**Blocked by:** —
+
+Deduplicate models repeated across files:
+
+- **PersonRef** (6 duplicates): `PersonRef` (livefeed), `BoxscorePersonRef` (game), `TransactionPerson` (transactions), `JobPerson` (jobs), `LeaderPersonRef` (stats), `DraftPerson` (draft). Create single `PersonRef` in `_base.py` with `id: PersonId`, `full_name: str | None`, `link: str | None`.
+- **PositionRef** (3 duplicates): `PrimaryPosition` (people), `PositionRef` (livefeed), `BoxscorePosition` (game). Create single `PositionRef` in `_base.py` with `code: str`, `name: str | None`, `type: str | None`, `abbreviation: str | None`.
+- **WinLossRecord** (4 duplicates): `LeagueRecord` (schedule), `StandingsLeagueRecord` (standings), `GameDataTeamRecord` (livefeed), plus `SplitRecord` variant. Create single `WinLossRecord` in `_base.py`.
+- **GameStatus** (2 duplicates): `schedule.GameStatus`, `livefeed.GameDataStatus`. Consolidate into one in `_base.py` or `schedule.py`.
+
+Update all imports across models and tests.
+
+---
+
+## Task 2: Define custom ID types (NewType) for entity IDs
+**Status:** not started
+**Blocked by:** —
+
+Create `NewType` definitions in `_base.py` instead of bare `int`:
+
+- `PersonId = NewType("PersonId", int)` — `PersonRef.id`, `Person.id`, `BoxscoreTeam.batters/pitchers/bench/bullpen/batting_order` items
+- `TeamId = NewType("TeamId", int)` — `Team.id`, `GameDataTeam.id`, `BoxscorePlayer.parent_team_id`
+- `GamePk = NewType("GamePk", int)` — `LiveFeedResponse.game_pk`, `ScheduleGame.game_pk`, `AttendanceGame.game_pk`
+
+Keep `IdNameLink.id` as plain `int` since it's used generically across entity types.
+
+**Verified data patterns:**
+- `BoxscoreTeam.batters/pitchers/bench/bullpen/batting_order` contain **player IDs** (e.g., `608324`) that map to `players["ID608324"]`, NOT array indices.
+- `Plays.scoring_plays`, `Play.pitch_index/action_index/runner_index`, `InningPlays.top/bottom` are **array indices** into sibling lists.
+
+---
+
+## Task 3: Wire up enums to model fields
+**Status:** not started
+**Blocked by:** Task 1
+
+All four enums in `enums.py` are defined but never referenced by any model field:
+
+- `GameType` → `ScheduleGame.game_type`, attendance `game_type.id`
+- `AbstractGameState` → `GameStatus.abstract_game_state`
+- `HandCode` → bat_side/pitch_hand `code` fields
+- `PositionType` → `PositionRef.type`
+
+Since the API may return unexpected values, consider using the enum but keeping `extra="allow"` or using a validator that falls back to `str`.
+
+---
+
+## Task 4: Add index-to-object helper properties
+**Status:** not started
+**Blocked by:** Task 1, Task 2
+
+**Array index helpers** (indices into sibling arrays on the same object):
+- `Plays.scoring_plays: list[int]` → `@property scoring_play_objects -> list[Play]` (indices into `all_plays`)
+- `Play.pitch_index: list[int]` → `@property pitches -> list[PlayEvent]` (indices into `play_events`)
+- `Play.action_index: list[int]` → `@property actions -> list[PlayEvent]` (indices into `play_events`)
+- `Play.runner_index: list[int]` → `@property indexed_runners -> list[Runner]` (indices into `runners`)
+- `InningPlays.top/bottom: list[int]` — indices into parent `Plays.all_plays`; document clearly, consider if helper is feasible
+
+**Player ID lookup helpers** (PersonId → player object via `players` dict):
+- `BoxscoreTeam.batters/pitchers/bench/bullpen/batting_order: list[PersonId]` → `@property batter_players`, `pitcher_players`, `bench_players`, `bullpen_players`, `batting_order_players` that resolve against `players[f"ID{pid}"]`
+
+---
+
+## Task 5: Fix stringly-typed date/datetime fields
+**Status:** not started
+**Blocked by:** —
+
+Convert `str` date fields to proper types (following `seasons.py` and `people.py` pattern):
+
+**→ `datetime.date`:**
+- `ScheduleDate.date` (`"2024-07-01"`)
+- `Transaction.date`, `effective_date`, `resolution_date` (`"2024-03-01"`)
+- `DraftPerson.birth_date`
+
+**→ `datetime.datetime`:**
+- `ScheduleGame.game_date` (`"2024-07-01T19:07:00Z"`)
+- `TeamStanding.last_updated`, `StandingsRecord.last_updated` (`"2025-12-27T17:29:50Z"`)
+- `PlayEvent.start_time`, `end_time`
+- `PlayAbout.start_time`, `end_time`
+- `Play.play_end_time`
+- `AttendanceRecord.attendance_high_date`, `attendance_low_date`
+
+---
+
+## Task 6: Standardize season field type across models
+**Status:** not started
+**Blocked by:** —
+
+Inconsistent `season` typing across models:
+- `int | None` in `Team`
+- `str` in `Division`, `TeamStanding`, `LeaderEntry`, `Season.season_id`
+- `str | None` in `Venue`, `ScheduleGame`
+
+Standardize on `int` (more useful for comparisons). Add Pydantic validators to coerce `str → int` where the API returns strings.
+
+---
+
+## Task 7: Replace weak `MlbBaseModel`/`dict` catch-all types with proper models
+**Status:** not started
+**Blocked by:** Task 1
+
+17 fields use `MlbBaseModel` or `dict` as catch-alls. Replace with typed models:
+
+**game.py:**
+- `BoxscorePlayer.stats/season_stats` → `PlayerStats` model with batting/pitching/fielding
+- `BoxscoreTeamStats.batting/pitching/fielding` → typed stat models (`BattingStats`, `PitchingStats`, `FieldingStats`)
+- `BoxscoreTeam.info/note` → `BoxscoreInfo` model with `title` + `field_list: list[BoxscoreInfoField]`
+- `BoxscorePlayer.game_status/status` → typed models
+
+**livefeed.py:**
+- `GameData.game` → `GameInfo` model
+- `GameData.datetime` → `GameDateTime` model
+- `GameData.game_info` → `GameInfoDetails` model (attendance, firstPitch, gameDurationMinutes)
+- `GameData.review` → `ReviewInfo` model
+- `GameData.flags` → `GameFlags` model (noHitter, perfectGame)
+- `LiveData.linescore` → reuse `LinescoreResponse` (minus copyright) or create `Linescore` base
+- `LiveData.boxscore` → reuse `BoxscoreResponse` (minus copyright) or create `Boxscore` base
+- `Matchup.batter_hot_cold_zones/pitcher_hot_cold_zones` → `HotColdZone` model
+
+**draft.py:**
+- `DraftPick.draft_type` → `CodeDescription` from `_base.py`
+- `DraftPerson.primary_position` → shared `PositionRef`
+
+**attendance.py:**
+- `AttendanceRecord.game_type` → `GameTypeRef` from stats.py or shared model
+
+**stats.py:**
+- `StatSplit.stat` → typed stat dicts or keep `dict` with better type annotation
+
+---
+
+## Task 8: Add computed properties for derived data
+**Status:** not started
+**Blocked by:** Task 1, Task 5
+
+- `Person.height_inches -> int | None` — parse `"6' 2\""` → `74`
+- `WinLossRecord.win_pct -> float | None` — parse `".512"` → `0.512`
+- `TeamStanding.games_back_float -> float | None` — parse `"-"` → `0.0`, `"5.0"` → `5.0`
+- `DraftPick.pick_value_amount -> float | None` — parse `"9200000.00"` → `9200000.0`
+- `DraftPick.signing_bonus_amount -> float | None` — same pattern
+
+---
+
+## Task 9: Add commonly-accessed missing fields
+**Status:** not started
+**Blocked by:** Task 1, Task 2
+
+Fields currently hidden in `extra` that users would commonly access:
+
+**standings.py `TeamStanding`:**
+- `wins: int`, `losses: int`, `winning_percentage: str`
+- `runs_scored: int`, `runs_allowed: int`, `run_differential: int`
+- `division_champ: bool`, `division_leader: bool`, `clinched: bool`
+- `elimination_number: str | None`, `magic_number: str | None`
+- `wild_card_elimination_number: str | None`
+
+**livefeed.py `GameData`:**
+- `players: dict[str, PersonRef] | None` — full player dict keyed by `"ID{playerId}"`
+
+**schedule.py `ScheduleGame`:**
+- `series_description: str | None`, `games_in_series: int | None`, `series_game_number: int | None`
+
+**stats.py `LeaderEntry`:**
+- `num_teams: int | None`
+
+Update tests to cover new fields where fixture data exists.
+
+---
+
+## Task 10: Update all tests and verify everything passes
+**Status:** not started
+**Blocked by:** Tasks 1–9
+
+- Update all test imports to use consolidated models
+- Add tests for new helper properties (index-to-object, computed properties)
+- Add tests for new ID types
+- Run full test suite: `pytest tests/test_models/ tests/test_client/`
+- Run integration tests: `pytest tests/test_integration/ -m integration`
+- Run `mypy src/mlb_statsapi` — strict, 0 errors
+- Run `ruff check src/` — clean

mlb_statsapi_pydantic-0.0.1/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "Bash(git *)",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" && .claude/hooks/run_pytest.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

mlb_statsapi_pydantic-0.0.1/.claude/tasks.md

@@ -0,0 +1,233 @@
+# mlb-statsapi-pydantic — Implementation Tasks
+
+> Pydantic v2 typed client for the MLB Stats API.
+> Reference: [toddrob99/MLB-StatsAPI](https://github.com/toddrob99/MLB-StatsAPI)
+> Approach: TDD — write tests first, then implement until green.
+
+---
+
+## Design Decisions
+
+| Decision | Choice | Why |
+|----------|--------|-----|
+| `extra="allow"` on all models | Yes | MLB API adds fields without notice; strict breaks clients |
+| `alias_generator=to_camel` | Yes | Auto snake_case ↔ camelCase without per-field aliases |
+| httpx (not requests) | Yes | Native async support, modern API |
+| `src/` layout | Yes | Packaging best practice, avoids import shadowing |
+| Tiered endpoint coverage | Yes | Ship Tier 1 fast, expand incrementally |
+| `IdNameLink.name` optional | Yes | Some API refs omit `name` (e.g. `springVenue`) |
+
+## Package Structure
+
+```
+src/mlb_statsapi/
+├── __init__.py              # Public re-exports
+├── exceptions.py            # MlbApiError, MlbValidationError
+├── client/
+│   ├── __init__.py
+│   ├── _base.py             # Shared: URL building, param validation, response parsing
+│   ├── sync_client.py       # MlbClient (httpx sync)
+│   └── async_client.py      # AsyncMlbClient (httpx async)
+├── endpoints/
+│   ├── __init__.py
+│   └── registry.py          # EndpointDef dataclass + 60+ endpoint definitions
+└── models/
+    ├── __init__.py           # Re-exports
+    ├── _base.py              # MlbBaseModel, BaseResponse, IdNameLink, CodeDescription
+    ├── enums.py              # GameType, GameState, HandCode, PositionType, etc.
+    ├── sports.py             # Sport, SportsResponse
+    ├── divisions.py          # Division, DivisionsResponse
+    ├── leagues.py            # League, LeaguesResponse
+    ├── venues.py             # Venue, VenuesResponse
+    ├── seasons.py            # Season, SeasonsResponse
+    ├── teams.py              # Team, TeamsResponse, TeamRecord, Roster
+    ├── people.py             # Person, PeopleResponse, PrimaryPosition
+    ├── schedule.py           # ScheduleResponse, ScheduleDate, ScheduleGame, GameStatus
+    ├── standings.py          # StandingsResponse, StandingsRecord, TeamStanding
+    ├── game.py               # BoxscoreResponse, LinescoreResponse, LiveFeedResponse
+    ├── stats.py              # StatGroup, StatSplit, LeaderCategory, StatsResponse
+    ├── transactions.py
+    ├── draft.py
+    ├── awards.py
+    ├── attendance.py
+    ├── jobs.py
+    └── meta.py
+```
+
+---
+
+## Tasks
+
+### Task 1: Project Setup & TDD Foundation
+**Status:** not started
+**Goal:** Repo, tooling, deps, directory skeleton, and first test suite so every future task starts with red tests.
+
+**Steps:**
+1. `git init`, create GitHub repo via `gh repo create`
+2. Create `pyproject.toml` — hatchling build system
+   - deps: `pydantic>=2.0`, `httpx>=0.25`
+   - dev deps: `pytest`, `pytest-asyncio`, `respx`, `ruff`, `mypy`
+   - `requires-python = ">=3.10"`
+3. `.gitignore` (Python template), `LICENSE` (MIT)
+4. Create full directory skeleton (all `__init__.py` files, empty modules)
+5. Create Python venv, install deps in editable mode (`pip install -e ".[dev]"`)
+6. Write `src/mlb_statsapi/exceptions.py` — `MlbApiError`, `MlbValidationError`
+7. Write initial test stubs in `tests/`:
+   - `conftest.py` with fixture loading helper
+   - `tests/fixtures/` — fetch & save JSON from live API: sports, teams (sportId=1), schedule, people/660271, standings
+   - `tests/test_models/test_base.py` — tests for `MlbBaseModel`, `BaseResponse`, `IdNameLink`, `CodeDescription`
+   - `tests/test_models/test_enums.py` — tests for all enum types
+8. Run `pytest` — confirm tests exist and fail (red)
+9. Initial commit + push
+
+**Verification:** `pytest` runs, discovers tests, all fail (no implementations yet). `ruff check` clean. Venv works.
+
+---
+
+### Task 2: Base Models & Enums
+**Status:** not started
+**Depends on:** Task 1
+**Goal:** Implement foundation models until Task 1 tests go green.
+
+**Files to create:**
+- `src/mlb_statsapi/models/_base.py`
+  - `MlbBaseModel(BaseModel)` — `ConfigDict(populate_by_name=True, extra="allow", alias_generator=to_camel)`
+  - `BaseResponse(MlbBaseModel)` — `copyright: str`
+  - `IdNameLink(MlbBaseModel)` — `id: int, name: str | None = None, link: str`
+  - `CodeDescription(MlbBaseModel)` — `code: str, description: str`
+- `src/mlb_statsapi/models/enums.py`
+  - `GameType`, `AbstractGameState`, `HandCode`, `PositionType` as `StrEnum`
+- `src/mlb_statsapi/models/__init__.py` — re-exports
+
+**Verification:** `pytest tests/test_models/test_base.py tests/test_models/test_enums.py` all green.
+
+---
+
+### Task 3: Simple Domain Models (sports, divisions, leagues, venues, seasons)
+**Status:** completed
+**Depends on:** Task 2
+**Goal:** TDD the simplest response models — flat arrays with minimal nesting.
+
+**For each module:** write tests first using saved JSON fixtures, then implement.
+- `sports.py` — `Sport`, `SportsResponse`
+- `divisions.py` — `Division`, `DivisionsResponse`
+- `leagues.py` — `League`, `LeaguesResponse`
+- `venues.py` — `Venue`, `VenuesResponse`
+- `seasons.py` — `Season`, `SeasonsResponse`
+
+**Verification:** `pytest tests/test_models/` all green. Models validate against real API fixtures.
+
+---
+
+### Task 4: Teams & People Models
+**Status:** completed
+**Depends on:** Task 2
+**Goal:** TDD the team and player models with nested references.
+
+- `teams.py` — `Team`, `TeamsResponse`, `TeamRecord`, `Roster`, `RosterEntry`
+  - Nested: `IdNameLink` for venue, league, division, spring_league
+- `people.py` — `Person`, `PeopleResponse`, `PrimaryPosition`, `BatPitchSide`
+  - Nested: `CodeDescription` for bat_side, pitch_hand
+  - Date fields as `datetime.date`
+
+**Verification:** `pytest tests/test_models/test_teams.py tests/test_models/test_people.py` green.
+
+---
+
+### Task 5: Schedule & Standings Models
+**Status:** completed
+**Depends on:** Task 2
+**Goal:** TDD the most complex response hierarchies.
+
+- `schedule.py` — `ScheduleResponse`, `ScheduleDate`, `ScheduleGame`, `GameStatus`, `ScheduleTeam`
+  - Hierarchy: dates → games → teams.{away,home}
+  - Multiple status representations (abstract, coded, detailed)
+- `standings.py` — `StandingsResponse`, `StandingsRecord`, `TeamStanding`, `Streak`
+  - Division-grouped team records
+
+**Verification:** `pytest tests/test_models/test_schedule.py tests/test_models/test_standings.py` green.
+
+---
+
+### Task 6: Game Models (Boxscore, Linescore, Live Feed)
+**Status:** completed
+**Depends on:** Task 4 (reuses Team/Person models)
+**Goal:** TDD the deepest, most complex models.
+
+- `game.py` — `BoxscoreResponse`, `LinescoreResponse`, `LiveFeedResponse`
+  - Boxscore: `teams.{away,home}` with batting/pitching/fielding stats, players dict keyed by `"ID{playerId}"`
+  - Linescore: innings array with home/away runs/hits/errors
+  - LiveFeed: `game_data`, `live_data.plays`, `live_data.linescore`, `live_data.boxscore`
+- `stats.py` — `StatGroup`, `StatSplit`, `LeaderCategory`, `StatsResponse`
+
+**Verification:** `pytest tests/test_models/test_game.py tests/test_models/test_stats.py` green.
+
+---
+
+### Task 7: Endpoint Registry
+**Status:** completed
+**Depends on:** Tasks 2–6
+**Goal:** Define all 60+ MLB API endpoints in a typed registry.
+
+- `endpoints/registry.py`
+  - `EndpointDef` frozen dataclass: `url_template`, `path_params`, `query_params`, `required_params`, `default_version`, `response_model`
+  - Registry `dict[str, EndpointDef]` covering all endpoints
+  - Tier 1 (~15): full model — schedule, teams, people, standings, game, boxscore, linescore, stats_leaders, roster, seasons, sports
+  - Tier 2 (~15): model, no convenience method — divisions, leagues, venues, transactions, draft, awards
+  - Tier 3 (~30): `BaseResponse` — remaining endpoints accessible via `client.get()`
+- Tests: endpoint URL construction, required param validation
+
+**Verification:** `pytest tests/test_client/test_endpoint_registry.py` green.
+
+---
+
+### Task 8: Client Implementation (Sync + Async)
+**Status:** completed
+**Depends on:** Task 7
+**Goal:** Build the httpx-based client with typed convenience methods.
+
+- `client/_base.py` — `_ClientMixin`
+  - `_build_request(endpoint, **params) -> (url, query_params)`
+  - `_parse_response(endpoint, data) -> BaseResponse`
+  - Required param validation
+- `client/sync_client.py` — `MlbClient`
+  - Convenience methods: `schedule()`, `teams()`, `person()`, `standings()`, `boxscore()`, `linescore()`, `roster()`, `player_stats()`, `league_leaders()`, `get()`
+- `client/async_client.py` — `AsyncMlbClient` (same interface, `async def`)
+- Tests: mock httpx with `respx`, test URL building, param validation, error handling
+
+**Verification:** `pytest tests/test_client/` all green.
+
+---
+
+### Task 9: Remaining Models & Public API Polish
+**Status:** completed
+**Depends on:** Task 8
+**Goal:** Fill in Tier 2 models and finalize the package surface.
+
+- Implement remaining model files: `transactions.py`, `draft.py`, `awards.py`, `attendance.py`, `jobs.py`, `meta.py`
+- `src/mlb_statsapi/__init__.py` — export `MlbClient`, `AsyncMlbClient`, all response models
+- `src/mlb_statsapi/py.typed` — PEP 561 marker
+- `models/__init__.py` — complete re-exports
+
+**Verification:** `mypy src/mlb_statsapi/` passes. `ruff check src/` clean.
+
+---
+
+### Task 10: Integration Tests & Smoke Test
+**Status:** not started
+**Depends on:** Task 9
+**Goal:** Validate against the live MLB API.
+
+- `tests/test_integration/test_live_api.py` — marked `@pytest.mark.integration`
+  - Hit live API for key endpoints, validate parsing
+  - Sports, teams, schedule, person, standings, boxscore
+- Manual smoke test:
+  ```python
+  from mlb_statsapi import MlbClient
+  client = MlbClient()
+  schedule = client.schedule(date="03/27/2026")
+  print(schedule.dates[0].games[0].teams.home.team.name)
+  ```
+- `pyproject.toml` — add `[tool.pytest.ini_options]` markers config
+
+**Verification:** `pytest tests/ -m "not integration"` all green. `pytest tests/ -m integration` passes against live API.

mlb_statsapi_pydantic-0.0.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG] "
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

mlb_statsapi_pydantic-0.0.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,33 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened? What did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Minimal code or steps to reproduce the issue.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Package version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+    validations:
+      required: true

mlb_statsapi_pydantic-0.0.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[FEAT] "
+labels: enhancement
+assignees: ''
+
+---
+
+## Is your feature request related to a problem? Please describe.
+A clear description of the problem, including what prevents you from achieving your goal.
+
+## Describe the solution you'd like
+A clear description of the desired functionality and potential implementation details.
+
+## Describe alternatives you've considered
+Any alternative solutions or workarounds you've considered.
+
+## Additional context
+Add any other context, examples, or screenshots here.