Orchestration API

`FetchRunSummary`

Bases: BaseModel

Compact terminal summary returned by one Prefect season fetch flow.

`GameFetchTaskError`

Bases: RuntimeError

Carries a durable failure record through Prefect retry handling.

`should_retry_fetch(_task, _task_run, state)`

Retry only failures marked transient by the direct NBA client.

`fetch_raw_game_task(game, run_id, raw_dir, refresh, min_request_interval_seconds, request_interval_jitter_seconds, access_denial_cooldown_seconds)`

Prefect task wrapper around the framework-independent raw fetcher.

`fetch_season_raw_flow(season, *, catalog_path='data/catalog/games.parquet', raw_dir='data/raw', manifest_path='data/manifests/fetches.parquet', season_types=None, game_ids=None, limit=None, refresh=False, run_id=None, min_request_interval_seconds=1.0, request_interval_jitter_seconds=0.25, access_denial_cooldown_seconds=DEFAULT_ACCESS_DENIAL_COOLDOWN_SECONDS)`

Fetch raw game feeds concurrently for one cataloged NBA season.

`StatsHistoryFetchSummary`

Bases: BaseModel

Terminal summary for one multi-season NBA Stats acquisition flow.

`StatsFetchTaskError`

Bases: RuntimeError

Carries a terminal endpoint record through Prefect retry handling.

`fetch_stats_endpoint_task(game, endpoint, run_id, stats_raw_dir, refresh, min_request_interval_seconds, request_interval_jitter_seconds, access_denial_cooldown_seconds)`

Prefect wrapper for one independently resumable source response.

`fetch_stats_history_flow(seasons, *, catalog_path='data/catalog/games.parquet', raw_dir='data/raw', manifest_path='data/manifests/stats_fetches.parquet', season_types=None, game_ids=None, endpoints=None, limit=None, cdn_missing_only=False, refresh=False, run_id=None, min_request_interval_seconds=1.0, request_interval_jitter_seconds=0.25, access_denial_cooldown_seconds=DEFAULT_STATS_ACCESS_DENIAL_COOLDOWN_SECONDS, max_retries=3)`

Retain raw NBA Stats game responses across one or more seasons.

`ProcessRunSummary`

Bases: BaseModel

Compact terminal summary returned by one season processing flow.

`GameProcessTaskError`

Bases: RuntimeError

Carries a terminal process outcome through Prefect task failure handling.

`should_retry_process(_task, _task_run, state)`

Retry only game failures classified as local infrastructure errors.

`process_game_task(game, run_id, raw_dir, processed_dir, code_version, prior_success, prior_quality, force)`

Prefect task wrapper around the framework-independent game processor.

`process_season_flow(season, *, catalog_path='data/catalog/games.parquet', raw_dir='data/raw', processed_dir='data/processed', ledger_path='data/manifests/builds.parquet', quality_games_path='data/quality/games.parquet', quality_summary_path='data/quality/summary.parquet', season_types=None, game_ids=None, limit=None, sample_per_stratum=None, random_seed=0, force=False, checkpoint_size=25, code_version=None, run_id=None)`

Process and quality-gate final catalog games from the local raw cache.

`CompactSeasonRunSummary`

Bases: BaseModel

Terminal summary for one curated season compaction flow.

`CompactSeasonRunManifest`

Bases: BaseModel

Durable flow summary plus every partition outcome.

`should_retry_compaction(_task, _task_run, state)`

Retry only local I/O failures.

`compact_partition_task(partition, sources, run_id, processed_dir, curated_dir, games_per_part, force, curation_code_version)`

Prefect wrapper around framework-independent partition compaction.

`compact_season_flow(season, *, catalog_path='data/catalog/games.parquet', processed_dir='data/processed', curated_dir='data/curated', ledger_path='data/manifests/builds.parquet', quality_games_path='data/quality/games.parquet', season_types=None, game_ids=None, games_per_part=100, force=False, quality_eligible_only=False, curation_code_version=None, run_id=None)`

Compact all quality-gated final games into curated season partitions.

`HistoricalBackfillStageRecord`

Bases: BaseModel

One terminal stage within a resumable historical backfill.

`HistoricalBackfillManifest`

Bases: BaseModel

Checkpointed parent record for a serial multi-season backfill.

run_historical_backfill(seasons=DEFAULT_HISTORY_SEASONS, *, from_stage='discover', through_stage='rapm', catalog_path=Path('data/catalog/games.parquet'), raw_dir=Path('data/raw'), processed_dir=Path('data/processed'), curated_dir=Path('data/curated'), analytical_dir=Path('data/analytical'), artifacts_dir=Path('artifacts/models'), fetch_manifest_path=Path('data/manifests/fetches.parquet'), build_ledger_path=Path('data/manifests/builds.parquet'), quality_games_path=Path('data/quality/games.parquet'), quality_summary_path=Path('data/quality/summary.parquet'), run_manifest_dir=Path('data/manifests/history_backfill'), max_workers=2, checkpoint_size=25, games_per_part=100, min_request_interval_seconds=1.0, request_interval_jitter_seconds=0.25, access_denial_cooldown_seconds=DEFAULT_ACCESS_DENIAL_COOLDOWN_SECONDS, refresh=False, force=False, quality_eligible_only=False, run_id=None)

Run existing resumable season stages serially across historical seasons.