Skip to content
Mostly Right

mostlyright

mostlyright — local-first 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 layer (spine / align + the deferred-source builders) lives behind mostlyright.experimental — the single blessed import. It is 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 until a later phase relocates them. Author-facing machinery (registry / contracts / provenance) stays importable at the root without warning but is OFF __all__ / dir() (reference-tier).

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)

Section titled “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

Section titled “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)

Section titled “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

Section titled “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)

Section titled “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

Section titled “default_error_code: str”

Subclass override — the stable string enum surfaced via error_code.

to_dict()

Section titled “to_dict()”

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

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

Section titled “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 taxonomy base for “I asked and got nothing” across domains. NoLiveDataError / NoCWOPDataError are re-parented under this class so align/contract code can build on a stable name. The optional cause names WHICH fact failed (window empty vs entity unknown vs source gap) so a valid zero-row result is distinguishable from a broken feed (MACH-02 / DX-H5).

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

default_error_code: str

Section titled “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, **_extra)

Section titled “mostlyright.discover(query=None, , domain=None, kind=None, availability=None, license=None, point_in_time_fidelity=None, **_extra)”

Search the registration-metadata catalog across domains.

Example

Section titled “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 (Optional[Literal['station', 'source']]) – Structured filter — "station" or "source" (the row discriminant).
    • availability (Union[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.
    • _extra (Any)
  • Return type: DataFrame
  • Returns: ONE discriminated pd.DataFrame. Every row carries a kind discriminant ("station" | "source") as the LEADING 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.
    • TypeError – the removed city= selector (or another unknown filter) was passed — use query= instead.

Modules

Section titled “Modules”
alignmr.align(spine, *sources) — the frozen composition operator (01).
contractsmr.contracts — spine + source contract shapes / validators (demoted).
coremostlyright.core — internal SDK plumbing (temporal safety + schema + formats).
discover([query, domain, kind, …])Search the registration-metadata catalog across domains.
experimentalmostlyright.experimental — public-experimental, semver-exempt surfaces.
registrymr.registry — the demoted, author-facing catalog writer (02).
spinemr.spine() — the BYO bridge into the guarded align world (04).
financemostlyright.finance — the finance data domain (4th vertical).
economymostlyright.economy — economic-indicator data for prediction-market settlement.
marketsmostlyright.markets — prediction-market data (Kalshi, Polymarket).
weathermostlyright.weather — direct public-API access for AWC, IEM, GHCNh, NWS CLI.