Guides

Econ

The econ domain ships CPI, payrolls, GDP, and friends as vintage-stamped tables. Every row records when it became knowable, so revisions cannot leak into a backtest. Same schema discipline as weather, same composition surface.

from datetime import date
from mostlyright import econ

s = econ.series("cpi", date(2024, 1, 1), date(2025, 6, 1))

Real output (captured against the installed SDK):

  indicator series_id   period    value  units              vintage_date release_type  settlement_grade            knowledge_time
2       cpi  CPIAUCSL  2025-02  319.775  index 2025-03-12 00:00:00+00:00      advance              True 2025-03-12 00:00:00+00:00
3       cpi  CPIAUCSL  2025-03  319.615  index 2025-04-10 00:00:00+00:00      advance              True 2025-04-10 00:00:00+00:00
4       cpi  CPIAUCSL  2025-04  320.321  index 2025-05-13 00:00:00+00:00      advance              True 2025-05-13 00:00:00+00:00

Access

Econ ships with the SDK in both languages (in TypeScript it is the econ namespace on the meta barrel as of 1.18). Access to the SDK is currently by request: see Packages & versioning. The import name is mostlyright.econ in Python.

The surface

As of 1.18, mr.econ resolves at the root like every domain (earlier releases shipped econ without wiring it into the root map), and the domain speaks the uniform grammar: econ.pairs(entity, from_date, to_date) is the same one-liner shape as weather.pairs(), wrapping the research join verbatim.

Call	Returns
`pairs(entity, from_date, to_date, as_of=None, source=None)`	The quickstart frame for a contract entity
`series(indicator, from_date, to_date, vintages="settlement")`	Vintage-stamped rows per period
`snapshot(indicator, as_of=None)`	The indicator as it was knowable at `as_of`
`releases(indicator)`	The upcoming release calendar as typed events
`history(...)`	Full revision history for a period
`research_econ(series_or_contract, from_date, to_date)`	The composed research frame, contract-aware

Indicators shipped today: cpi, cpi_core, nfp, u3, gdp, jobless_claims, fed_funds, plus derived variants like cpi_yoy. The authoritative list is the installed package; the API surface carries the public map.

releases() returns real calendar events, not strings:

econ.releases("cpi")[0]
# ReleaseEvent(indicator='cpi', period='2026-05',
#              release_datetime=datetime(2026, 6, 10, 12, 30, tzinfo=UTC),
#              agency='BLS')

Vintages are the point

An economic number is revised repeatedly after first print. The vintages= axis decides which truth you get:

"settlement" (default): the first-print, settlement-grade value per period, stamped with its vintage_date and release_type (advance, and later revisions where applicable). This is what a prediction-market contract settles on.
"all": every vintage of every period, one row per revision, for revision-dynamics research.

Every row carries knowledge_time, which means the temporal toolkit applies directly:

from mostlyright.core import KnowledgeView, TimePoint

view = KnowledgeView(s, TimePoint("2025-04-01T00:00:00Z"))
knowable = view.dataframe()   # rows whose vintage existed by April 1

A backtest that reads value through a KnowledgeView cutoff can never train on a revision that had not been published yet. This is the same guard the weather frames get from mr.align; econ rows carry it natively because the vintage is the row.

Composing econ with everything else

Econ tables are sources like any other: lift your target with mr.spine, or align econ features onto a market spine alongside weather. Kalshi lists econ contracts (CPI, Fed funds) and the markets layer carries econ-aware catalog and trades modules; research_econ("<contract-or-series>", ...) composes the contract-aware frame in one call.

import mostlyright as mr

frame = mr.align(
    my_spine,                                   # your decision calendar
    econ.series("cpi", date(2024, 1, 1), date(2025, 6, 1)),
    econ.series("fed_funds", date(2024, 1, 1), date(2025, 6, 1)),
)

Credentials

The paths above run keyless. Two exceptions, both documented in Credentials: FRED_API_KEY unlocks settlement-grade ALFRED vintage queries at depth, and BEA_API_KEY covers latest-revised GDP. An indicator queried before its first release raises IndicatorNotYetReleasedError rather than returning a guess.