mostlyright.snapshot

mostlyright.snapshot

Historical data snapshot — all data available at a given UTC moment.

Snapshot answers: “What would an AI agent have known at time T for station X?”

Key concepts:

• LOCAL STANDARD TIME (LST): station’s standard UTC offset, DST ignored.

Kalshi NHIGH/NLOW contracts define the settlement window in LST.

• Settlement window: midnight-midnight LST for a given date. During US daylight saving, the clock window is 1:00 AM-1:00 AM next day (EDT), but the UTC bounds are the same year-round.
• CLI publication delay: NWS issues the overnight final CLI ~04:00-10:00 UTC (midnight-5 AM ET) the day after observation. Default assumption: 10 AM ET = 10 h after midnight LST. Climate record is withheld from the snapshot until as_of is past that threshold.
• as_of: observations are filtered to [window_start_utc, as_of] (both bounds).

NOTE: forecasts field stubs to None. Full support requires the sprint2/forecast-backfill branch to be merged into main.

Functions

build_snapshot(station, as_of, observations, …)	Build a DataSnapshot from pre-fetched observations and climate records.
cli_available_at(date_str, station[, …])	Return the UTC time at which the NWS CLI for a date is expected to be available.
settlement_date_for(as_of, station[, …])	Return the Kalshi settlement date (YYYY-MM-DD LST) for a UTC moment.
settlement_window_utc(date_str, station[, …])	Return UTC start/end of the Kalshi settlement window for a date.

Classes

DataSnapshot(station, as_of, …)	All data available at a historical moment for a station.

class mostlyright.snapshot.DataSnapshot(station, as_of, settlement_date, window_start_utc, window_end_utc, observations, climate, climate_unavailable_reason, cli_publication_delay_hours, forecasts, version)

Bases: object

All data available at a historical moment for a station.

Used for AI-native data access: reproducible, temporally honest, settlement-window-aware.

• Parameters:
  • station (str)
  • as_of (str)
  • settlement_date (str)
  • window_start_utc (str)
  • window_end_utc (str)
  • observations (list *[*Observation ])
  • climate (dict [str , Any ] | None)
  • climate_unavailable_reason (str | None)
  • cli_publication_delay_hours (float)
  • forecasts (list [dict [str , Any ] ] | None)
  • version (DataVersion)

station

Station code (normalized, e.g. “NYC”).

as_of

Query timestamp (UTC ISO 8601 string).

settlement_date

Kalshi settlement date (YYYY-MM-DD in LST).

window_start_utc

UTC start of the settlement window (midnight LST).

window_end_utc

UTC end of the settlement window (midnight LST + 24h).

observations

METAR/SPECI observations within [window_start_utc, as_of].

climate

NWS CLI climate record for settlement_date. None if not yet published at as_of (CLI expected ~10 AM ET next day).

climate_unavailable_reason

Explanation when climate is None. Either a data gap message or a publication delay message with expected time. None when climate is available.

cli_publication_delay_hours

Hours assumed for CLI publication delay.

forecasts

Placeholder for forecast data. Always None until sprint2/forecast-backfill is merged into main.

version

DataVersion for this snapshot. Deterministic hash of station + sorted observation timestamps. as_of stored as metadata only.

as_of : str

cli_publication_delay_hours : float

climate : dict[str, Any] | None

climate_unavailable_reason : str | None

forecasts : list[dict[str, Any]] | None

observations : list[Observation]

settlement_date : str

station : str

to_dict()

Serialize to JSON-compatible dict (matches specs/snapshot.json).

• Return type: dict[str, Any]

to_toon()

Encode as TOON v3.0 string for LLM/AI agent consumption.

• Return type: str

version : DataVersion

window_end_utc : str

window_start_utc : str

mostlyright.snapshot.build_snapshot(station, as_of, observations, all_climate, cli_publication_delay_hours=10.0, tz_override=None)

Build a DataSnapshot from pre-fetched observations and climate records.

Filters observations to [window_start_utc, as_of] (both bounds inclusive). Filters climate to what was available at as_of per publication delay. Called by MostlyRightClient.snapshot() after fetching from API.

• Parameters:
  • station (str) – Station code.
  • as_of (str | datetime) – Query timestamp.
  • observations (list[Observation]) – All observations for the station (caller may pre-filter by date range; this function applies the settlement window lower bound).
  • all_climate (list[dict[str, Any]]) – Climate records for the station/date (may be empty).
  • cli_publication_delay_hours (float) – Hours after midnight LST for CLI publication.
  • tz_override (str | None) – IANA timezone name override for unknown stations.
• Return type: DataSnapshot
• Returns: DataSnapshot with temporally-honest data.
• Raises: ValueError – If station is not in the known timezone map and tz_override is not provided.

mostlyright.snapshot.cli_available_at(date_str, station, delay_hours=10.0, tz_override=None)

Return the UTC time at which the NWS CLI for a date is expected to be available.

NWS overnight final CLI is issued approximately 10 hours after midnight LST (i.e., 10 AM local standard time the following day).

• Parameters:
  • date_str (str) – Settlement date (YYYY-MM-DD in LST).
  • station (str) – Station code.
  • delay_hours (float) – Hours after midnight LST when CLI is published. Default 10.
  • tz_override (str | None) – IANA timezone name override for unknown stations.
• Return type: datetime
• Returns: Aware UTC datetime when CLI is expected.

mostlyright.snapshot.settlement_date_for(as_of, station, tz_override=None)

Return the Kalshi settlement date (YYYY-MM-DD LST) for a UTC moment.

Kalshi NHIGH/NLOW contracts cover midnight-midnight LOCAL STANDARD TIME. DST is ignored: the window is always fixed to the standard UTC offset.

• Parameters:
  • as_of (str | datetime) – UTC moment (ISO string or aware datetime).
  • station (str) – Station code (e.g. “NYC”, “ATL”, “KORD”).
  • tz_override (str | None) – IANA timezone name override for unknown stations.
• Return type: str
• Returns: ISO date string (YYYY-MM-DD) representing the settlement date in LST.

Examples

>>> settlement_date_for("2024-07-04T03:00:00Z", "NYC")
'2024-07-03'  # 03:00 UTC = 22:00 EDT = 22:00 LST (UTC-5) → July 3

mostlyright.snapshot.settlement_window_utc(date_str, station, tz_override=None)

Return UTC start/end of the Kalshi settlement window for a date.

The window is midnight-midnight LST, expressed in UTC.

• Parameters:
  • date_str (str) – ISO date string (YYYY-MM-DD) in LST.
  • station (str) – Station code.
  • tz_override (str | None) – IANA timezone name override for unknown stations.
• Return type: tuple[datetime, datetime]
• Returns: (window_start_utc, window_end_utc) as timezone-aware UTC datetimes.