Guides

Economy

The economy domain returns macro data with publication vintages intact. A revision is a new row with a new knowledge time, so research can use the value that was actually available before a decision instead of today’s revised history.

from datetime import date
from mostlyright import economy

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

In 2.0 the domain is economy everywhere. The old econ import, research_econ(), and economy.history() are gone.

Install and import

The meta package includes every domain:

pip install mostlyrightmd

For an economy-only installation:

pip install mostlyrightmd-economy

from mostlyright import economy

TypeScript uses the economy namespace and the @mostlyrightmd/economy scoped package.

Public methods

Call	Returns
`series(indicator, from_date, to_date, vintages="settlement", source=None, delivery="live")`	Vintage-stamped observations for an indicator
`snapshot(indicator, as_of=None, source=None, delivery="live")`	Latest first-print value available by a cutoff
`releases(indicator)`	Typed release-calendar events
`training_table(entity, from_date, to_date, as_of=None, source=None)`	Contract/indicator settlement example with cutoff fields

The domain covers CPI (headline, core, and YoY), PPI, nonfarm payrolls and revisions, U3 unemployment, initial jobless claims, GDP, and Fed funds decisions. Query the installed API reference for the current indicator catalog.

Vintages are the feature

series() defaults to vintages="settlement": the first print selected by the SDK’s settlement policy for each period.

first_prints = economy.series(
    "cpi",
    "2024-01-01",
    "2025-06-01",
)

all_revisions = economy.series(
    "cpi",
    "2024-01-01",
    "2025-06-01",
    vintages="all",
)

Rows carry the period being described and the knowledge_time at which that vintage became available. Later revisions never overwrite the first print.

snapshot() answers a different question: which qualifying first print was available at one cutoff?

from datetime import datetime, timezone

then = economy.snapshot(
    "cpi",
    as_of=datetime(2025, 4, 1, tzinfo=timezone.utc),
)

If no qualifying first-print vintage existed by the cutoff, the call raises IndicatorNotYetReleasedError; it does not return a guessed value.

Release calendars

releases() returns typed events, not formatted strings:

for event in economy.releases("nfp"):
    print(event.period, event.release_datetime, event.agency)

Each event includes indicator, period, a timezone-aware UTC release_datetime, and agency.

Training-table example

from datetime import date
from mostlyright import economy
from mostlyright.core import TimePoint

table = economy.training_table(
    "KXCPIYOY",
    date(2026, 5, 1),
    date(2026, 6, 30),
)

as_of_table = economy.training_table(
    "KXCPIYOY",
    date(2026, 5, 1),
    date(2026, 6, 30),
    as_of=TimePoint("2026-06-01T00:00:00Z"),
)

training_table() resolves the market entity to its indicator, selects a qualifying first print, and checks the knowledge cutoff. A row that violates as_of raises LeakageError.

Some market series settle against values the SDK cannot license directly. Those rows are marked settlement_grade=False and emit DivergenceWarning rather than pretending an agency value is the contractual settlement value.

Source and delivery

source= names provenance: fred, bls, bea, dol, or fed, depending on the indicator. The default selects the relevant authority.

delivery="live" calls public agency APIs from your runtime. Hosted economy delivery is not implemented; delivery="hosted" raises SourceUnavailableError.

Credentials

The common reads are keyless. FRED_API_KEY unlocks deeper ALFRED vintage access, BEA_API_KEY covers latest-revised GDP from BEA, and BLS_API_KEY raises BLS rate limits. See Credentials for the full matrix.