mostlyright.discovery

mostlyright.discovery

Phase 3.6 — Discovery API + public settlement + DataVersion.

Phase 3.6 v0.1.0 scope: ergonomic surface quants hit on day one.

• availability(station)() — “what do I have for KNYC?”
• climate_gaps(station, from_date, to_date)() — missing-CLI-date scan.
• describe(schema_id)() — pretty-print a registered schema.
• feature_catalog() — list every available transform.
• settlement_date_for(station, ts)() — top-level wrapper.
• settlement_window_utc(station, settlement_date)() — top-level wrapper.
• DataVersion — reproducibility token stamping every research() call.

Functions

availability(station)	Return a summary of what mostlyright has cached for station.
climate_gaps(station, from_date, to_date)	Return ISO-8601 dates in [from_date, to_date] with no CLI cache.
describe(schema_id)	Return a human-readable description of a registered schema.
feature_catalog()	List every available transform in mostlyright.transforms.
settlement_date_for(station, ts)	Top-level wrapper around mostlyright.snapshot.settlement_date_for().
settlement_window_utc(station, settlement_date)	Top-level wrapper around mostlyright.snapshot.settlement_window_utc().

Classes

DataVersion(sdk_version, schema_ids, …)	Reproducibility token stamping a research() call.

class mostlyright.discovery.DataVersion(sdk_version, schema_ids, sources, code_sha, data_sha, token)

Bases: object

Reproducibility token stamping a research() call.

Carries enough metadata to re-run the same query against the same code + same data and get byte-identical output. token is a deterministic SHA-256 hash; components keeps the inputs for debugging.

• Parameters:
  • sdk_version (str)
  • schema_ids (tuple [str , … ])
  • sources (tuple [str , … ])
  • code_sha (str)
  • data_sha (str)
  • token (str)

code_sha : str

data_sha : str

classmethod for_research(, station, from_date, to_date, sdk_version=None)

Build a DataVersion for a research() call.

Hashes the current SDK version + the (station, from_date, to_date) triple + a deterministic data-cache fingerprint so two callers running the same query against the same cache get the same token.

Note: the sources tuple is the SDK’s source-priority contract, not the per-call subset that actually returned rows. v0.1.0 has no source-filter kwarg, so the contract matches reality; v0.2 with explicit source toggles should narrow this to the actually- consulted set.

• Return type: DataVersion
• Parameters:
  • station (str)
  • from_date (str)
  • to_date (str)
  • sdk_version (str | None)

classmethod from_components(, sdk_version, schema_ids, sources, code_sha, data_sha)

• Return type: DataVersion
• Parameters:
  • sdk_version (str)
  • schema_ids (tuple [str , … ])
  • sources (tuple [str , … ])
  • code_sha (str)
  • data_sha (str)

schema_ids : tuple[str, ...]

sdk_version : str

sources : tuple[str, ...]

token : str

mostlyright.discovery.availability(station)

Return a summary of what mostlyright has cached for station.

• Return type: dict
• Parameters: station (str)

mostlyright.discovery.climate_gaps(station, from_date, to_date)

Return ISO-8601 dates in [from_date, to_date] with no CLI cache.

Coarse signal: iterates every calendar day in the inclusive range and checks whether the climate-year parquet for that date’s year exists. A year being cached does NOT prove every day within it was actually in the upstream response. For row-level gap detection, read the parquet directly and diff against the date range.

• Return type: list[str]
• Parameters:
  • station (str)
  • from_date (str)
  • to_date (str)

mostlyright.discovery.describe(schema_id)

Return a human-readable description of a registered schema.

• Return type: str
• Parameters: schema_id (str)

mostlyright.discovery.feature_catalog()

List every available transform in mostlyright.transforms.

• Return type: list[str]

mostlyright.discovery.settlement_date_for(station, ts)

Top-level wrapper around mostlyright.snapshot.settlement_date_for().

• Parameters:
  • station (str) – ICAO or NWS code.
  • ts (datetime) – A timezone-aware datetime (UTC or any aware tz; converted via the station’s LST offset by the snapshot layer).
• Return type: str
• Returns: YYYY-MM-DD station-local settlement date.

mostlyright.discovery.settlement_window_utc(station, settlement_date)

Top-level wrapper around mostlyright.snapshot.settlement_window_utc().

• Parameters:
  • station (str) – ICAO or NWS code.
  • settlement_date (str) – YYYY-MM-DD in LST.
• Return type: tuple[datetime, datetime]
• Returns: (window_start_utc, window_end_utc) aware UTC datetimes.