mostlyright.experimental

mostlyright.experimental

mostlyright.experimental — public-experimental, semver-exempt surfaces.

Phase 32 32-01 (D-24). Everything re-exported here is EXPERIMENTAL: its API, semantics, and existence may change in ANY minor release until 2.0. Pin your mostlyright version if you depend on it.

The pattern mirrors pandas’ pandas.api.extensions namespace — a documented, importable home for plugin surfaces that are stable enough to build on but not yet frozen under the semver contract.

Current surface:

• contributor() — register a dataset() contributor. A contributor is one function contribute(entity, window, grain) -> {key: {prefixed_col: value}} plus declared metadata (prefix namespace, archive_class, injection_point, and the columns it emits). Registered contributors compose into dataset() via the features=[...] selector without any core change. The FIRST third-party registration emits an ExperimentalFeatureWarning. The labels-only firewall is UNCONDITIONAL — a contributor can NEVER emit or override a label / obs_* / cli_* column.

  A third-party contributor MUST declare columns= (its prefixed column set) so that a contribute() which RAISES or covers zero days still yields an all-NaN prefix block instead of silently dropping the columns. The returned mapping may be keyed by a plain settlement-date string OR by the declared key tuple (entity, settlement_date); both bucket to the settlement day.

Example:

from mostlyright.experimental import contributor

@contributor(
    "era5_ssrd",
    "ssrd_",
    "refetchable",
    injection_point="post_join",
    columns=("ssrd_mean",),
)
def era5_ssrd(entity, window, grain, *, tz_override=None):
    from_date, to_date = window
    # ... fetch + aggregate to one row per LST settlement day ...
    # keyed by the documented (station, settlement_date) tuple:
    return {(entity, "2025-01-06"): {"ssrd_mean": 12.3}, ...}

df = mostlyright.dataset("KNYC", "2025-01-06", "2025-01-08",
                         features=["era5_ssrd"])
# df now carries an additive ssrd_mean column; label columns untouched.

class mostlyright.experimental.ContributorSpec(name, prefix, archive_class, injection_point, fn, key=(‘station’, ‘settlement_date’), native_grain=‘daily’, columns=(), builtin=False)

Bases: object

An immutable registry entry describing one contributor.

• Parameters:
  • name (str)
  • prefix (str)
  • archive_class (Literal [ ‘refetchable’ , ‘ledger’ ])
  • injection_point (Literal [ ‘pre_aggregation’ , ‘post_join’ ])
  • fn (Callable [ [ … ] , dict [str , dict [str , Any ] ] ])
  • key (tuple [str , str ])
  • native_grain (Literal [ ‘daily’ , ‘observation’ ])
  • columns (tuple [str , … ])
  • builtin (bool)

name

Unique registry key (also the value used in features=[...]).

prefix

Column namespace this contributor owns (e.g. "sat_"). Every column it emits MUST start with this prefix; the prefix must be non-empty and end with "_".

archive_class

"refetchable" | "ledger" (source-identity §5).

injection_point

"pre_aggregation" | "post_join" — where the columns land in the dataset() pipeline.

fn

The contribute(entity, window, grain, **kw) callable.

key

The key tuple the returned frame is keyed by. Default ("station", "settlement_date") (v1 weather vertical); the earnings vertical will register with e.g. ("ticker", "call_date").

native_grain

RESERVED. v1 contributors are "daily"; a future contributor may declare "observation" to supply per-report rows.

columns

The declared prefixed column set this contributor emits. REQUIRED for third-party contributors (so a contribute() that RAISES or covers zero days still yields an all-NaN prefix block instead of vanishing — the failure-semantics contract). Built-ins derive it lazily (their columns are the D-16 helper output), so it may be empty for them; when empty the aligner falls back to the first-seen-across-days universe.

builtin

True for the four migrated built-ins (exempt from the ExperimentalFeatureWarning + third-party-prefix guard).

archive_class : Literal['refetchable', 'ledger']

builtin : bool = False

columns : tuple[str, ...] = ()

fn : Callable[..., dict[str, dict[str, Any]]]

injection_point : Literal['pre_aggregation', 'post_join']

key : tuple[str, str] = (‘station’, ‘settlement_date’)

name : str

native_grain : Literal['daily', 'observation'] = ‘daily’

prefix : str

mostlyright.experimental.contributor(name, prefix, archive_class, , injection_point, fn=None, key=(‘station’, ‘settlement_date’), native_grain=‘daily’, columns=None, _builtin=False)

Register a contributor. Usable as a decorator or a direct call.

EXPERIMENTAL / semver-exempt until 2.0 (D-24). The public entry point is mostlyright.experimental.contributor(). The registry is module-level and shared by dataset/markets/reconcile; the returned spec is also the decorated function (so @contributor(...) leaves the original callable bound in the caller’s namespace).

Decorator form:

@contributor("era5_ssrd", "ssrd_", "refetchable", injection_point="post_join")
def era5_ssrd(entity, window, grain, *, tz_override=None):
    ...
    return {("KNYC", "2025-01-06"): {"ssrd_mean": 12.3}, ...}

Direct form (used by the built-in migrations):

contributor("satellite", "sat_", "refetchable",
            injection_point="post_join", fn=_sat_contribute, _builtin=True)

• Parameters:
  • name (str) – Unique registry key + features=[...] token.
  • prefix (str) – Column namespace (non-empty, ends with "_", not a label prefix). Third-party contributors may not claim a built-in prefix.
  • archive_class (Literal['refetchable', 'ledger']) – "refetchable" | "ledger" (source-identity §5).
  • injection_point (Literal['pre_aggregation', 'post_join']) – "pre_aggregation" | "post_join".
  • fn (Callable[..., dict[str, dict[str, Any]]] | None) – The contribute callable. Omitted in decorator form (the decorated function becomes fn).
  • key (tuple[str, str]) – Returned-frame key tuple (default the v1 weather key). The contribute() return mapping may be keyed by a plain settlement-date string OR by this tuple (entity, settlement_date); both bucket to the settlement day (the tuple’s last element).
  • native_grain (Literal['daily', 'observation']) – RESERVED grain declaration (v1 = "daily").
  • columns (tuple[str, ...] | list[str] | None) – The prefixed column set the contributor emits. REQUIRED for third-party contributors (each column must carry prefix) so a failed / empty contribute() still yields an all-NaN prefix block instead of silently dropping the columns. Built-ins may omit it (they derive their columns from the D-16 helper output).
  • _builtin (bool) – Internal — set by the four built-in migrations to bypass the ExperimentalFeatureWarning + third-party-prefix guard.
• Raises: ValueError – duplicate name, malformed / label-colliding prefix, a third-party contributor claiming a reserved built-in prefix, or a third-party contributor that omits columns / declares a column outside its prefix namespace.
• Return type: Any
• Returns: The registered ContributorSpec (direct form) or a decorator that registers then returns the decorated function (decorator form).

mostlyright.experimental.list_contributors()

Return the sorted registered contributor names.

• Return type: list[str]

mostlyright.experimental.registered_contributors()

Return a shallow copy of the registry (name → spec).

• Return type: dict[str, ContributorSpec]