Migration

Upgrade guide

One page, newest first, actions only. Every 1.x release is additive-plus-shims: existing calls keep returning the same bytes, deprecations warn for at least two minors, removals happen at 2.0. The changelog has the full detail per release; this page has what to do.

1.18: the domain-first map

A curation release finishing 1.17’s move. Zero call-site changes required; names re-map, bytes never change (live parity stays byte-green against the 0.14.1 fixtures).

The root is the product now. sorted(mostlyright.__all__) is exactly ["ContractError", "LeakageError", "NoDataError", "__version__", "align", "econ", "markets", "spine", "weather"]. mr.econ finally resolves at the root (it shipped in 1.16 but was never wired in), and it speaks the uniform grammar: econ.pairs(entity, from_date, to_date).
Stray root modules went private behind a runtime finder. mostlyright.research / dataset / live / stations / snapshot / qc / international / forecasts / mode2 / discovery all keep working through 1.x with a once-per-session DeprecationWarning naming the new home (mostly mostlyright.weather.*). Static tooling (pyright, IDE auto-import) stops offering the legacy paths immediately: that pressure is by design.
Transforms and preprocessing are exiting with NO replacement. mostlyright.transforms (lag/diff/rolling/heat_index/…), mostlyright.preprocessing (clip_outliers/PHYSICS_BOUNDS/…), and contracts.feature_catalog are removed at 2.0 and nothing replaces them: pandas/polars own transforms, features are user-land. Migrate to .shift/.diff/.rolling and your own winsorize.
discovery dissolved into its domains: climate_gaps, availability, settlement_date_for, settlement_window_utc now live on mostlyright.weather; describe/DataVersion on mostlyright.contracts.
Markets curated its surface: markets.__all__ is ["__version__", "econ_trades", "kalshi", "polymarket"]; the standalone trade-history modules were privatized (no shim; they had no external importers). Trades enter via pairs(include_trades=True) and markets.econ_trades.
discover, provenance, registry, contracts stay importable and documented but leave dir(mr): reference-tier machinery, no deprecation.
TypeScript: the meta barrel exports the domain namespaces (import { weather, econ, markets, core } from "mostlyright"), fixing the missing econ dependency; the ~70 flat machinery re-exports are @deprecated (reach them via the namespaces), while dataset and research stay exported untouched in 1.x.
Frozen apps (PyInstaller and friends): legacy names resolve via a MetaPathFinder, not on-disk files; either migrate off legacy imports or add the private impls (mostlyright._legacy_finder, mostlyright._research, …) as hidden imports.

1.17: compose with align and spine

The composition redesign. Nothing you run today breaks.

Move off root shims. from mostlyright import research, dataset, Station, CATALOG and mostlyright.live now emit DeprecationWarning and are removed at 2.0. New homes: weather.pairs() for the quickstart one-liner, mr.align/mr.spine for composition, mostlyright.weather.stations for the registry, from mostlyright.weather import live for live.
Markets naming: markets.kalshi.dataset() and markets.polymarket.dataset() are shims for .pairs().
The D-22 label warning is gone in Python. The planned “label default flips at 2.0” was cancelled: pairs(..., label="cli") is an explicit, stable default with no deprecation path. Only the TypeScript dataset() still fires the D-22 notice.
features=[...] has no equivalent on the new surface: the sources you pass to align are the feature list. Migrating a pinned feature set is a retrain event, not a find-replace.
Full mapping of all 26 old dataset() kwargs to their new homes: Compose a dataset.

1.16: floors and packaging

Node 20+ is the floor for all TypeScript packages (was 18). Python stays 3.11+.
The econ domain began landing across 1.16 and 1.17; see the Econ guide for the shipped surface.
No API changes requiring action.

1.15: the label axis and markets delegators

dataset() gained the explicit label= axis ("cli", "daily_extremes", None, or a BYO frame). Passing it explicitly was and remains the right call; at 1.17 the explicit form became the only teaching.
include_forecast / include_satellite / include_cwop / include_trades became deprecated aliases of features=[...] (and features itself retired at 1.17 in favor of align sources; skip straight to the current form).
contract= / contracts= on core dataset() deprecated toward the markets layer: use markets.kalshi.pairs(ticker) today.
Multi-station panels (stations=[...]) and the experimental contributor registry landed here; panels are now a list entity on pairs().

1.14: additive granularity

granularity="observation" arrived on dataset()/obs() (per-report rows; the schema changes with granularity). Daily output stayed byte-identical to 1.13.
settlement_date appeared on per-report obs() rows. If you cross-validate on sub-daily rows, group folds by settlement_date so one settlement day never spans train and test.

1.13: dataset() era begins

dataset() became the primary composer with research() as its alias (both are shims as of 1.17: compose with pairs/align in new code).
Per-report obs() grain, standalone climate(), covariate columns, and the numbered-mode deprecation train landed.
If you run -W error in production, allowlist DeprecationWarning from mostlyright.* during any migration window instead of muting warnings globally.

Older

Coming from the decommissioned 0.14.1 hosted client (pip install mostlyright, the Client object, client.pairs()): that is a different product generation with its own page: Legacy 0.14.1 migration.