mostlyright

mostlyright — local-first SDK for prediction-market weather settlement research.

Sprint 0 v0.1.0 ships:

mostlyright.dataset(station, from_date, to_date, ...) — the v0.14.1 pairs() join,

lifted from monorepo-v0.14.1, calling AWC + IEM + GHCNh + NWS CLI directly. mostlyright.research remains a fully working alias of dataset (Phase 30 D-02).

mostlyright.snapshot — settlement-window math (LST, market_close_utc).

Adjacent surfaces:

mostlyright.weather — observations + climate + forecasts (sibling package mostlyrightmd-weather).
mostlyright.markets — Kalshi + Polymarket metadata (sibling package mostlyrightmd-markets,

ships v0.1.0 in Sprint 0.5).

Namespace note: mostlyright is a split-distribution namespace package. Core owns this __init__.py; sibling distributions mostlyrightmd-weather and mostlyrightmd-markets ship subdirectories (mostlyright/weather/, mostlyright/markets/) WITHOUT their own namespace-root __init__.py. The pkgutil declaration below extends __path__ so Python’s import machinery finds those subpackages from whichever site-packages location installed them.

mostlyright.Station

alias of StationInfo

class mostlyright.StationCatalog(stations=None)

Bases: object

Read-only view over the station registry with venue/country filters.

Lookups accept either the registry key (3-letter NWS code for US stations, ICAO for international) or the 4-letter ICAO directly, so get("NYC"), get("KNYC"), and get("EGLL") all resolve.

Parameters: stations (dict [str , Station ] | None)

filter_by_country(country)

Return stations whose ISO 3166-1 alpha-2 country matches, sorted by ICAO.

Return type: list[StationInfo]
Parameters: country (str)

filter_by_venue(venue)

Return stations tagged with venue (e.g. "kalshi"), sorted by ICAO.

Return type: list[StationInfo]
Parameters: venue (str)

get(code)

Return the station for code (registry key or ICAO).

Raises: KeyError – when no station matches.
Return type: StationInfo
Parameters: code (str)

venues()

Return the union of all venue tags present in the catalog.

Return type: frozenset[str]

mostlyright.dataset(station=None, from_date=None, to_date=None, *, label=, labels_as_known=‘settled’, city=None, stations=None, contract=None, contracts=None, station_override=None, sources=None, source=None, include_trades=False, include_forecast=False, forecast_model=None, forecast_models=None, forecast_source=‘iem_mos’, as_dataframe=None, tz_override=None, qc=False, granularity=‘daily’, include_satellite=False, include_cwop=False, features=None, backend=‘pandas’, return_type=‘dataframe’)

The canonical venue-free composition surface (Phase 30 D-02 / 32 charter).

See _dataset_impl() for the full pipeline. label= routes the settlement target (Phase 32 32-02):

a named recipe "cli" (today’s climate join, byte-identical) or "daily_extremes" (the WU/NOAA-WRH extremes Polymarket resolves on);
None — features-only (no label columns);
a user DataFrame — the BYO aligner (settlement-calendar bucketing, LEFT- join preservation, collision guards, optional publication discipline via labels_as_known="publication_lag").

Multi-station panels (Phase 32 32-04): pass stations=["KNYC","KLAX",...] (mutually exclusive with station=/city=/contract=/contracts=) for a long-format panel — station column first, per-station settlement calendars, per-station label-recipe resolution (mixed-venue OK). The row/ column data equals the concat of the per-station single calls; the frame adds nested attrs["stations"] per-station provenance.

D-22 bridge: calling dataset() WITHOUT an explicit label still returns cli_* bytes but emits a FutureWarning (the default flips to None at 2.0). Pass label="cli" to keep settlement labels, or label=None to silence and get the pure feature table. research() (the legacy alias) keeps implicit cli with no warning.

Return type: Any
Parameters:
- station (str | None)
- from_date (str | None)
- to_date (str | None)
- label (str | Any | None)
- labels_as_known (str)
- city (str | None)
- stations (list [str ] | tuple [str , … ] | None)
- contract (str | None)
- contracts (list [str ] | tuple [str , … ] | None)
- station_override (str | None)
- sources (list [str ] | tuple [str , … ] | None)
- source (str | None)
- include_trades (bool)
- include_forecast (bool)
- forecast_model (str | None)
- forecast_models (list [str ] | None)
- forecast_source (str | list [str ] | tuple [str , … ])
- as_dataframe (bool | None)
- tz_override (str | None)
- qc (bool)
- granularity (str)
- include_satellite (bool)
- include_cwop (bool)
- features (list [str ] | tuple [str , … ] | None)
- backend (str)
- return_type (str)

mostlyright.discover(, city)

Return per-station discovery table for city.

Each row shows one settlement station + the list of "<issuer>:<ticker>" markers that resolve against it. Stations in the per-city Polymarket denylist also appear (with empty settles_for) so quants see the full station neighborhood before deciding whether to use station_override=.

Parameters: city (str) – city slug ("NYC" for Kalshi, "nyc" for Polymarket; both forms are normalized).
Returns:
- city (str): the input city, echoed.
- station (str): 4-char K-prefix ICAO.
- settles_for (list[str]): ["kalshi:NYC"] / ["polymarket:nyc"] / [] (denylist backstop).
Return type: pd.DataFrame with columns
Raises:
- ValueError – city not in either catalog.
- SourceUnavailableError – pandas not installed.

mostlyright.research(station=None, from_date=None, to_date=None, *, label=, labels_as_known=‘settled’, city=None, stations=None, contract=None, contracts=None, station_override=None, sources=None, source=None, include_trades=False, include_forecast=False, forecast_model=None, forecast_models=None, forecast_source=‘iem_mos’, as_dataframe=None, tz_override=None, qc=False, granularity=‘daily’, include_satellite=False, include_cwop=False, features=None, backend=‘pandas’, return_type=‘dataframe’)

Legacy alias of dataset() — implicit cli label, NO new warning.

research() is the v0.14.1 name kept working byte-for-byte. Unlike dataset(), calling it WITHOUT an explicit label does NOT emit the D-22 bridge FutureWarning (this name is deprecated toward 2.0 regardless, so a second warning would be noise). An explicit label= is honored the same as on dataset().

Return type: Any
Parameters:
- station (str | None)
- from_date (str | None)
- to_date (str | None)
- label (str | Any | None)
- labels_as_known (str)
- city (str | None)
- stations (list [str ] | tuple [str , … ] | None)
- contract (str | None)
- contracts (list [str ] | tuple [str , … ] | None)
- station_override (str | None)
- sources (list [str ] | tuple [str , … ] | None)
- source (str | None)
- include_trades (bool)
- include_forecast (bool)
- forecast_model (str | None)
- forecast_models (list [str ] | None)
- forecast_source (str | list [str ] | tuple [str , … ])
- as_dataframe (bool | None)
- tz_override (str | None)
- qc (bool)
- granularity (str)
- include_satellite (bool)
- include_cwop (bool)
- features (list [str ] | tuple [str , … ] | None)
- backend (str)
- return_type (str)

Modules

`core`	mostlyright.core — temporal safety + schema + format primitives.
`discover`(*, city)	Return per-station discovery table for `city`.
`discovery`	Phase 3.6 — Discovery API + public settlement + DataVersion.
`experimental`	`mostlyright.experimental` — public-experimental, semver-exempt surfaces.
`forecasts`	Phase 3.2 — Multi-forecast live path (HRRR + GFS + NBM via NOAA BDP).
`international`	Phase 3.1 — International station expansion + daily_extremes rollup.
`live`	mostlyright.live — single-source ticker surface.
`mode2`	Source-pinned observation dispatch (DEPRECATED module — Phase 30 D-04).
`preprocessing`	Phase 3.5 — preprocessing primitives.
`qc`	Phase 3.4 — QC Engine Alpha + sidecar + crosscheck.
`research`([station, from_date, to_date, …])	Legacy alias of `dataset()` — implicit `cli` label, NO new warning.
`snapshot`	Historical data snapshot — all data available at a given UTC moment.
`stations`	Venue-agnostic station catalog (Phase 22).
`transforms`	Phase 3.5 — Transforms DSL + preprocessing primitives.
`markets`	mostlyright.markets — prediction market data (Kalshi, Polymarket).
`weather`	mostlyright.weather — direct public-API access for AWC, IEM, GHCNh, NWS CLI.