mostlyright.economy

mostlyright.economy — economic-indicator data for prediction-market settlement.

Macro releases — CPI (headline / core / YoY), PPI, nonfarm payrolls (NFP) and revisions, U3 unemployment, initial jobless claims, GDP, and Fed funds decisions — sourced from FRED/ALFRED + BLS/BEA/DOL/Federal Reserve and joined to Kalshi and Polymarket economy markets for leakage-free settlement pairs.

This vertical is deliberately ISOLATED from the four weather parity files (research(), _internal/merge/observations.py’s SOURCE_PRIORITY, _internal/merge/climate.py’s policies, _live/_sources.py) — the same firewall discipline CWOP uses. Economy carries its OWN schema.economy.observations.v1, its OWN per-release cache namespace (~/.mostlyright/cache/v1/economy/…), and its OWN error taxonomy (IndicatorNotYetReleasedError). A macro release must never be routed through the weather settlement join, and the weather merge layer must never see an economy row.

Load-bearing invariant (first-print / ALFRED vintage discipline): Kalshi settlements contractually EXCLUDE post-expiration revisions, so the research layer serves as-released vintages, never the revised series. Vintage selection happens at read time via the vintages keyword.

The surface conforms to the cross-vertical source-identity contract (docs/source-identity.md, /31 v1.13/1.14): source= is always provenance (WHO produced the row), delivery= is always where the computation runs ("live" local | "hosted" reserved seam). Both validate loudly BEFORE any network call.

Public surface:

• series() — observation rows for an indicator across a date range (canonical read; source=/delivery= contract kwargs).
• snapshot() — the settlement-target state as-of a cutoff (the latest settlement-grade vintage knowable at as_of).
• releases() — the release calendar / schedule for an indicator.
• training_table() — a small, capped settlement-pair example.
• __version__ — the installed mostlyrightmd-economy distribution version (parity with the weather / markets siblings).

exception mostlyright.economy.IndicatorNotYetReleasedError(indicator, period, , expected_release=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

A requested economic release is EXPECTED but has not been published yet.

In the economy vertical, “not yet released” is a normal, branchable control state distinct from “unavailable” — the release calendar says a print is due, but vintage_time for that period does not exist yet. The economy surface (economy.history / economy.releases / economy.research_economy) raises this instead of returning [] / None so a caller can tell “the data is genuinely gone” (a DataAvailabilityError) apart from “come back after the 8:30 ET drop” (this error) and, when known, retry at expected_release.

Lives in the core hierarchy (not packages/economy) for the same reason EarningsError / NoCWOPDataError do: the exception taxonomy is centralized so MCP JSON-RPC serialization and the Python↔TS lockstep discipline apply uniformly. mostlyright.economy re-exports it.

• Parameters:
  • indicator (str)
  • period (str)
  • expected_release (datetime | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

indicator

The indicator id ("cpi", "nfp", "gdp", …).

period

The observation period requested ("2026-06", "2026Q2", an FOMC meeting date, …).

expected_release

The scheduled release wall-clock when known, else None (the payload never fabricates a timestamp).

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

error_code: str

expected_release: datetime | None

indicator: str

message: str

period: str

request_id: str | None

source: str | None

mostlyright.economy.releases(indicator)

Return the release calendar / schedule for indicator.

• Parameters: indicator (str) – An economy indicator id (schema.economy.observations.v1 vocabulary: "cpi" / "nfp" / "gdp" / "fed_funds" / "jobless_claims" / …).
• Return type: list[ReleaseEvent]
• Returns: The scheduled releases for the indicator as a list of ReleaseEvent, sorted by release_datetime ascending. Sourced from the curated v1 schedule table (a live agency-calendar fetch is a documented fast-follow).
• Raises:
  • TypeError – indicator is not a str.
  • ValueError – indicator has no known schedule (never returns []/None — an unschedulable indicator is an explicit error).

mostlyright.economy.series(indicator, from_date, to_date, , vintages=‘settlement’, source=None, delivery=‘live’)

Return economic-indicator observation rows for indicator (canonical).

series is the CANONICAL economy read function, conforming the surface to the cross-vertical source-identity kwarg contract (docs/source-identity.md). history() is a working alias returning byte-identical output — see its docstring for the deprecation note.

• Parameters:
  • indicator (str) – The indicator id ("cpi" / "nfp" / "gdp" / "ppi" / "jobless_claims" / …; the schema.economy.observations.v1 vocabulary).
  • from_date (date | datetime) – Inclusive start of the requested range.
  • to_date (date | datetime) – Inclusive end of the requested range.
  • vintages (str) – "settlement" (default) returns only the settlement-grade first-print rows (the value as-of the Kalshi expiration); "all" returns every vintage for feature engineering. settlement rows are always a subset of all rows (the clean-partition property).
  • source (str | None) – Provenance pin (contract §1). None (default) uses the per-indicator default routing (unchanged behavior). A pin names the authority ("fred" ALFRED vintage store, "bls", "bea", "dol", "fed"). An unknown source, OR a valid authority that cannot serve indicator (e.g. source="bea" for "cpi"), raises ValueError BEFORE any network call — never a silent fallback.
  • delivery (str) – Where the computation runs (contract §2). "live" (default) hits the public agency APIs locally; "hosted" is the reserved precomputed-API seam and raises SourceUnavailableError naming MOSTLYRIGHT_ECONOMY_HOSTED_URL + MOSTLYRIGHT_API_KEY. An unknown value raises ValueError pre-network.
• Return type: DataFrame
• Returns: A schema.economy.observations.v1 pandas.DataFrame (validated).
• Raises:
  • ValueError – vintages is not "settlement"/"all"; an invalid source/delivery (pre-network); or indicator has no dispatch entry (never a silent empty frame).
  • SourceUnavailableError – delivery="hosted" (the reserved seam).
  • DataAvailabilityError – reason="out_of_window" when from_date is below the indicator’s FEDS-2026-010 first-contract floor.
  • IndicatorNotYetReleasedError – the window has no relevant rows — a scheduled release has not landed yet. NEVER returns []/None.
  • ImportError – pandas (the [pandas] extra) is not installed.

Example

>>> df = series("cpi", "2024-01-01", "2024-06-30")
>>> df.columns[:2].tolist()
['indicator', 'period']

mostlyright.economy.snapshot(indicator, , as_of=None, source=None, delivery=‘live’)

Return the settlement-target state of indicator as knowable at as_of.

• Parameters:
  • indicator (str) – The indicator id ("cpi" / "nfp" / "gdp" / "ppi" / "jobless_claims" / …; the schema.economy.observations.v1 vocabulary).
  • as_of (datetime | None) – The knowledge-time cutoff. Only vintages whose vintage_time is at or before as_of are considered. Defaults to now (UTC-aware) — the current settlement-target state.
  • source (str | None) – Provenance pin (contract §1), forwarded to series(). None (default) uses the per-indicator default routing; an unknown source or a valid authority that cannot serve indicator raises ValueError pre-network.
  • delivery (str) – Where the computation runs (contract §2), forwarded to series. "live" (default) | "hosted" (reserved seam → SourceUnavailableError).
• Return type: DataFrame
• Returns: A schema.economy.observations.v1 pandas.DataFrame — one settlement-grade row per period knowable at as_of (the latest such vintage per period).
• Raises:
  • ValueError – an invalid source/delivery (pre-network) — see series.
  • SourceUnavailableError – delivery="hosted" (the reserved seam).
  • DataAvailabilityError – indicator is unknown (no FEDS floor).
  • IndicatorNotYetReleasedError – nothing is knowable at as_of — no settlement-grade vintage exists at or before the cutoff. NEVER returns []/None.
  • ImportError – pandas (the [pandas] extra) is not installed.

mostlyright.economy.training_table(entity, from_date, to_date, , as_of=None, source=None)

Built-in economy settlement-pair example for entity.

A thin, capped example over research_economy(): resolves the Kalshi/Polymarket economy contract (or series root) to its settlement-grade FIRST-PRINT agency vintage and returns training pairs that “behave the same in research and live”. Two positional dates, inclusive ends. Byte-identical to research_economy(entity, from_date, to_date, as_of=as_of, source=source) — this is a re-export of the shipped 1.16 join, NOT a new join.

• Parameters:
  • entity (str) – A Kalshi economy series root ("KXCPIYOY") or a concrete dated market ticker ("KXCPIYOY-26JUL"). Case-insensitive.
  • from_date (date | datetime) – Inclusive start of the requested range.
  • to_date (date | datetime) – Inclusive end of the requested range.
  • as_of (TimePoint | None) – Optional leakage cutoff (a TimePoint); any pair whose knowledge_time is after it raises LeakageError — a future revision can never leak into research.
  • source (str | None) – Provenance pin (source-identity contract §1), forwarded verbatim to the underlying join (None = per-indicator default routing).
• Return type: DataFrame
• Returns: The research_economy settlement-pairs pandas.DataFrame (identical columns and bytes).

:raises The same set as research_economy() — see its docstring: :raises (TypeError / ValueError / SourceUnavailableError /: :raises IndicatorNotYetReleasedError` / LeakageError / ImportError):

Notes

For the hosted delivery= seam or any surface beyond the capped quickstart, GRADUATE to research_economy() — the cap is never widened with a kwarg (the uniform domain-grammar rule).