Season Data API
NbaScheduleError
Bases: RuntimeError
Raised when an NBA season schedule cannot be fetched or normalized.
ScheduleResponse
Bases: BaseModel
One direct response from the NBA Stats season schedule endpoint.
ScheduleCacheMetadata
Bases: BaseModel
Provenance sidecar for one byte-preserved schedule response.
SeasonScheduleCache
Byte-preserving cache for season-addressable NBA schedule responses.
NbaScheduleClient
Direct client for the season-parameterized NBA Stats schedule endpoint.
catalog_from_schedule(response)
Normalize one NBA schedule response into the canonical game catalog.
replace_catalog_season(existing, discovered)
Replace one discovered season while retaining every other catalog season.
RawArtifactEvidence
dataclass
Validated cache evidence for one exact raw response body.
fetch_game_raw(game, *, run_id, raw_dir=Path('data/raw'), refresh=False, attempt_number=1, prefect_flow_run_id=None, prefect_task_run_id=None, started_at=None, client=None, min_request_interval_seconds=0.0, request_interval_jitter_seconds=0.0, access_denial_cooldown_seconds=DEFAULT_ACCESS_DENIAL_COOLDOWN_SECONDS)
Fetch and validate both raw game documents without Prefect dependencies.
failed_fetch_record(game, *, run_id, started_at, error, raw_dir=Path('data/raw'), refresh=False, attempt_number=1, prefect_flow_run_id=None, prefect_task_run_id=None)
Build a terminal failure record while retaining valid partial artifacts.
artifact_evidence(cache, endpoint, game_id)
Read and hash one valid cached artifact.
require_artifact_evidence(cache, endpoint, game_id)
Require a valid raw artifact after a successful client fetch.
is_transient_fetch_error(error)
Return whether a failure should be retried by an orchestration layer.
select_catalog_games(catalog, *, season, season_types=None, game_ids=None, limit=None)
Select deterministic, final-only game work from the canonical catalog.
StatsArtifactEvidence
dataclass
Validated exact-byte evidence for one NBA Stats response.
StatsFetchRecord
Bases: BaseModel
Terminal outcome for one game and NBA Stats endpoint.
StatsFetchManifest
Bases: BaseModel
Append-oriented terminal history for NBA Stats endpoint work.
fetch_stats_endpoint_raw(game, endpoint, *, run_id, raw_dir=Path('data/raw/stats'), refresh=False, attempt_number=1, prefect_flow_run_id=None, prefect_task_run_id=None, started_at=None, client=None, min_request_interval_seconds=0.0, request_interval_jitter_seconds=0.0, access_denial_cooldown_seconds=DEFAULT_STATS_ACCESS_DENIAL_COOLDOWN_SECONDS)
Fetch one endpoint without requiring Prefect.
stats_play_by_play_final_score(payload)
Return the last valid home and away score from a V3 play-by-play payload.
failed_stats_fetch_record(game, endpoint, *, run_id, started_at, error, raw_dir=Path('data/raw/stats'), refresh=False, attempt_number=1, prefect_flow_run_id=None, prefect_task_run_id=None)
Create a durable endpoint failure while retaining prior valid evidence.
stats_artifact_evidence(cache, endpoint, game_id)
Read, validate, and hash one retained Stats response.
is_transient_stats_fetch_error(error)
Return whether Prefect should retry a Stats endpoint failure.
GameSourceError
Bases: RuntimeError
Raised when no processable raw document exists for a game endpoint.
SelectedRawArtifact
dataclass
One selected raw artifact and its processing-boundary payload.
GameSourceDocuments
dataclass
Selected play-by-play, box-score, and optional rotation documents.
load_game_source_documents(game_id, *, raw_dir=Path('data/raw'))
Prefer Stats V3 per endpoint and fall back to liveData.
Historical liveData can represent substitutions with only the outgoing player. Stats V3 retains both sides of each transaction.
GameProcessOutcome
dataclass
Terminal build and quality evidence returned by one game processor.
process_catalog_game(game, *, run_id, code_version, raw_dir=Path('data/raw'), processed_dir=Path('data/processed'), prior_success=None, prior_quality=None, force=False, attempt_number=1, prefect_flow_run_id=None, prefect_task_run_id=None, started_at=None)
Build one catalog game from validated local raw documents only.
quality_record_for_outcome(outcome)
Attach build provenance to a game's audit result.
failed_process_outcome(game, *, run_id, code_version, started_at, error, attempt_number=1, prefect_flow_run_id=None, prefect_task_run_id=None)
Build a terminal record for an unexpected orchestration failure.
processing_code_fingerprint(package_root=None, *, source_entries=None)
Hash processing-owned Python sources so algorithm changes invalidate resume.
latest_successful_builds(ledger)
Return the latest successful build for each game.
sample_processing_games(games, *, games_per_stratum, random_seed=0)
Sample deterministically by season type and overtime status.
processed_output_paths(game_id, processed_dir=Path('data/processed'))
Return all conventional per-game processed output paths.
require_processed_outputs(game_id, processed_dir=Path('data/processed'))
Require six readable, non-empty Parquet tables for the expected game.
processed_outputs_valid(game_id, processed_dir=Path('data/processed'))
Return whether all expected processed outputs pass preflight checks.
CatalogGame
Bases: BaseModel
One canonical NBA game catalog row.
GameCatalog
Bases: BaseModel
Versioned, unique collection of canonical NBA games.
GameFetchRecord
Bases: BaseModel
Terminal outcome of fetching both raw source documents for one game.
FetchManifest
Bases: BaseModel
Append-oriented history of terminal raw game fetch outcomes.
GameBuildRecord
Bases: BaseModel
Terminal outcome of one attempt to process a catalog game.
BuildLedger
Bases: BaseModel
Versioned collection of immutable game build outcomes.
GameQualityRecord
QualityReport
Bases: BaseModel
Canonical latest quality result for each processed game.
catalog_frame(catalog)
Return a deterministically ordered, typed catalog frame.
catalog_from_frame(frame)
Validate a canonical catalog frame without lossy identifier coercion.
write_game_catalog(catalog, path)
Atomically write a canonical game catalog to Parquet.
read_game_catalog(path)
Read and validate a canonical game catalog from Parquet.
fetch_manifest_frame(manifest)
Return a typed fetch manifest ordered by run and game.
fetch_manifest_from_frame(frame)
Validate a raw fetch manifest frame.
write_fetch_manifest(manifest, path)
Atomically write the append-oriented raw fetch manifest.
read_fetch_manifest(path)
Read a raw fetch manifest, returning an empty manifest when absent.
append_fetch_records(records, path)
Append a batch of terminal fetch records through one atomic writer.
build_ledger_frame(ledger)
Return a typed build ledger frame ordered by attempt start time.
build_ledger_from_frame(frame)
Validate a build ledger frame.
write_build_ledger(ledger, path)
Atomically write a build ledger to Parquet.
read_build_ledger(path)
Read a build ledger, returning an empty ledger when it does not exist.
append_build_record(record, path)
Append one terminal record using an atomic single-writer rewrite.
append_build_records(records, path)
Append terminal build records using one atomic single-writer rewrite.
quality_report_frame(report)
Return a typed canonical game-quality frame.
quality_report_from_frame(frame)
Validate a canonical game-quality frame.
write_quality_report(report, games_path, *, summary_path=None)
Atomically write canonical game quality and its aggregate summary.
read_quality_report(path)
Read canonical game quality, returning an empty report when absent.
merge_quality_records(records, games_path, *, summary_path=None)
Replace canonical quality rows by game ID and write the merged report.
CuratedPartition
Bases: BaseModel
One season and season-type partition of a curated table.
CuratedDatasetLayout
dataclass
Construct deterministic plain-directory curated Parquet paths.
CuratedGameSource
Bases: BaseModel
Catalog, successful-build, and quality evidence for one curated game.
CuratedPartRecord
Bases: BaseModel
Integrity evidence for one curated Parquet shard.
CuratedPartitionManifest
Bases: BaseModel
Versioned, lossless-compaction contract for one curated partition.
PartitionCompactionOutcome
Bases: BaseModel
Terminal outcome of compacting one curated table partition.
curation_code_fingerprint(source_paths=None)
Hash curation sources so implementation changes invalidate resume.
curated_input_fingerprint(partition, sources, processed_dir=Path('data/processed'))
Hash exact source files and metadata selected for one partition.
compact_curated_partition(partition, sources, *, run_id, processed_dir=Path('data/processed'), curated_dir=Path('data/curated'), games_per_part=100, force=False, curation_code_version=None, prefect_flow_run_id=None, prefect_task_run_id=None)
Compact validated per-game Parquet into one atomic curated partition.
read_curated_partition_manifest(partition, curated_dir=Path('data/curated'))
Read the manifest for one curated partition.
validate_curated_partition(manifest, curated_dir=Path('data/curated'))
Require exact files, hashes, schemas, game IDs, and row conservation.