mostlyright

mostlyright — SDK for prediction-market weather settlement research.

import mostlyright exposes exactly ten names — the product map, nothing else:

• mr.weather / mr.markets / mr.economy / mr.finance — the data domains (each advertised only when its distribution is installed).
• mr.discover(query?, **filters) — cross-domain catalog search.
• mr.MostlyrightError / mr.LeakageError / mr.ContractError / mr.NoDataError — the collapsed error taxonomy, one import deep (except mr.LeakageError:); they resolve without any domain installed.
• mr.__version__ — bug reports.

__all__, dir(), from mostlyright import *, and attribute access all agree: on a partial install the domain names present are exactly the installed members of the fixed four-domain allowlist — a missing domain never masquerades as a working attribute.

The composition functions (spine / align + the deferred-source builders) are imported from mostlyright.experimental, their supported home. They are not bound at the root: mr.spine / mr.align attribute access raises AttributeError on a fresh import mostlyright. The source modules mostlyright.spine / mostlyright.align remain importable directly but are undocumented. Author-facing machinery (registry / contracts / provenance) stays importable at the root without warning but is absent from __all__ and dir().

Namespace note: mostlyright is a split-distribution namespace package. Core owns this __init__.py; sibling distributions mostlyrightmd-weather, mostlyrightmd-markets, mostlyrightmd-economy, and mostlyrightmd-finance ship subdirectories (mostlyright/weather/, mostlyright/markets/, mostlyright/economy/, mostlyright/finance/) 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.

exception mostlyright.ContractError(message=”, , field=None, expected=None, actual=None, location=None, doc_url=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

A frame or source spec violates its declared contract.

Modelled on SchemaValidationError but for the two-axis align(spine, *sources) world: raised when a SourceContract is malformed (e.g. a prefix that does not end with "_") or when a source/spine frame does not conform at compose time. field names the offending contract field so the copy (built via mostlyright._errmsg.contract_message()) points the user at the exact thing to change.

• Parameters:
  • message (str)
  • field (str | None)
  • expected (str | None)
  • actual (str | None)
  • location (str | None)
  • doc_url (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.LeakageError(message=”, , as_of, violating_count, sample_violations=None, column=None, boundary=None, decision_time=None, doc_url=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

Temporal leakage detected — at least one row has knowledge_time greater than the asserted as_of cutoff. Carries the count and a small sample of violating rows for actionable surfacing.

• Parameters:
  • message (str)
  • as_of (str)
  • violating_count (int)
  • sample_violations (list [dict [str , Any ] ] | None)
  • column (str | None)
  • boundary (str | None)
  • decision_time (str | None)
  • doc_url (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.MostlyrightError(message=”, , error_code=None, source=None, request_id=None)

Bases: Exception

Base class for all mostlyright structured errors.

error_code is a stable enum (e.g. "SOURCE_UNAVAILABLE") used by callers / agents to branch on without parsing message text. source is the source ID involved ("iem.archive" etc.) when applicable, and request_id correlates an MCP JSON-RPC request when applicable.

• Parameters:
  • message (str)
  • error_code (str | None)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

to_dict()

Return a JSON-safe dict suitable for MCP error.data.

• Return type: dict[str, Any]

exception mostlyright.NoDataError(message=”, , cause=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

No usable data was produced for the requested entity/window.

The base class for “I asked and got nothing” across domains; NoLiveDataError and NoCWOPDataError live under it, so align and contract code can catch one stable name. The optional cause names which fact failed (empty window, unknown entity, source gap), so a valid zero-row result is distinguishable from a broken feed.

• Parameters:
  • message (str)
  • cause (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

mostlyright.discover(query=None, , domain=None, kind=None, availability=None, license=None, point_in_time_fidelity=None, live=False, **_extra)

Search the registration-metadata catalog across domains.

Example

>>> import mostlyright as mr
>>> hits = mr.discover(query="nyc")
>>> hits["kind"].iloc[0]
'station'

• Parameters:
  • query (str | None) – Optional free-text query. Known station aliases in the query (e.g. "nyc") resolve to the settlement stations (kind "station" rows, carrying the cross-venue note); the remaining tokens score the registered data sources (kind "source" rows). City lookups go here: discover(query="nyc").
  • domain (str | None) – Structured filter — the domain slug ("weather" …).
  • kind (Literal['station', 'source', 'market'] | None) – Structured filter — "station", "source", or "market" (the row discriminant). "market" rows need live=True.
  • availability (Literal['python', 'typescript'] | list[Literal['python', 'typescript']] | None) – Structured filter — "python" / "typescript" (or a list).
  • license (str | None) – Structured filter — the source license string.
  • point_in_time_fidelity (str | None) – Structured filter — the PIT fidelity value.
  • live (bool) – Also search the prediction-market venues and return their matches as kind="market" rows. Off by default: the default path makes no network call, and this is the explicit opt-in that does. Needs a query — a live search with nothing to search for would sweep both venues’ full universes, so it raises instead. The venues are called directly (no venue account; their addresses resolve through the keyed manifest catalog), narrowed, and nothing is cached. The read is bounded per venue (page and row ceilings), and the frame says so: df.attrs["live_search_bounded"] is True, df.attrs["venues_truncated"] names any venue whose ceiling bound, and df.attrs["degraded_venues"] names any venue that could not be read at all.
  • _extra (Any)
• Return type: DataFrame
• Returns: One pd.DataFrame. Every row carries a kind discriminant ("station" | "source" | "market") as the first column, then the shared id/name/domain identity, then the kind-specific nullable columns — station geo (country/latitude/longitude/timezone from the bundled catalog) and source metadata (point_in_time_fidelity/ availability) — plus note/usage/score. No option changes the return type. Deterministically ordered (score desc, then id asc). Zero-arg discover() lists the registered sources. A guaranteed-miss free-text query returns an empty-but-shaped frame whose df.attrs["message"] guides back.
• Raises:
  • ContractError – an invalid kind / availability selector (carries a difflib did-you-mean).
  • EntityNotFoundError – an alias in query could not be resolved (carries a deterministic nearest-match suggestion).
  • SourceUnavailableError – pandas is not installed, or live=True was passed without the markets distribution installed (the message names the pip install).
  • TypeError – the removed city= selector (or another unknown filter) was passed — use query= instead.

Modules

Module	Description
align	mr.align(spine, *sources) — the composition operator.
contracts	mr.contracts — spine and source contract shapes plus their validators.
core	Internal SDK plumbing for temporal safety, schemas, and formats.
discover([query, domain, kind, …])	Search the registration-metadata catalog across domains.
experimental	mostlyright.experimental — public-experimental, semver-exempt surfaces.
registry	mr.registry — the author-facing catalog writer.
spine	mr.spine() — bring your own target frame into the leakage-guarded join.
finance	mostlyright.finance — finance data for prediction-market research.
economy	mostlyright.economy — economic-indicator data for prediction-market settlement.
markets	mostlyright.markets — prediction-market data (Kalshi, Polymarket).
weather	Weather observations, forecasts, daily settlement summaries, and satellite data.