mostlyright.contracts

mr.contracts — spine + source contract shapes / validators (demoted).

The demoted surface: the bitemporal SourceContract, the labeled-target SpineContract, the shared contract/frame validators (validate_source_contract(), validate_source_frame(), validate_spine_frame()), and a re-export of the TimePoint temporal primitive the whole contract layer is seeded from.

This surface is author-facing (met via error messages, not researcher autocomplete) — hence demoted out of the root namespace per the cut rule.

The schema-description verb describe() and the reproducibility token DataVersion live here as byte-stable re-exports of the private _discovery implementation (identity-stable, no logic change). Both are contracts-shaped author-facing machinery.

class mostlyright.contracts.DataVersion(sdk_version, schema_ids, sources, code_sha, data_sha, token)

Bases: object

Reproducibility token stamping a research() call.

Carries enough metadata to re-run the same query against the same code + same data and get byte-identical output. token is a deterministic SHA-256 hash; components keeps the inputs for debugging.

• Parameters:
  • sdk_version (str)
  • schema_ids (tuple [str , … ])
  • sources (tuple [str , … ])
  • code_sha (str)
  • data_sha (str)
  • token (str)

code_sha: str

data_sha: str

classmethod for_research(, station, from_date, to_date, sdk_version=None)

Build a DataVersion for a research() call.

Hashes the current SDK version + the (station, from_date, to_date) triple + a deterministic data-cache fingerprint so two callers running the same query against the same cache get the same token.

Note: the sources tuple is the SDK’s source-priority contract, not the per-call subset that actually returned rows. v0.1.0 has no source-filter kwarg, so the contract matches reality; v0.2 with explicit source toggles should narrow this to the actually- consulted set.

• Return type: DataVersion
• Parameters:
  • station (str)
  • from_date (str)
  • to_date (str)
  • sdk_version (str | None)

classmethod from_components(, sdk_version, schema_ids, sources, code_sha, data_sha)

• Return type: DataVersion
• Parameters:
  • sdk_version (str)
  • schema_ids (tuple [str , … ])
  • sources (tuple [str , … ])
  • code_sha (str)
  • data_sha (str)

schema_ids: tuple[str, ...]

sdk_version: str

sources: tuple[str, ...]

token: str

class mostlyright.contracts.SourceContract(id, prefix, event_time_col=”, knowledge_time_col=”, entity_key=(‘station’, ), revision_order=(), revision_tiebreak=‘first_seen’, point_in_time_fidelity=‘reconstructed’, units=, license=‘unknown’, valid_from=, native_frequency=‘daily’, availability=(‘python’, ), schema_id=”, schema_version=1, columns=())

Bases: object

Immutable bitemporal contract for one source frame.

• Parameters:
  • id (str)
  • prefix (str)
  • event_time_col (str)
  • knowledge_time_col (str)
  • entity_key (tuple [str , … ])
  • revision_order (tuple [tuple [str , str ] , … ])
  • revision_tiebreak (str)
  • point_in_time_fidelity (Literal [ ‘exact’ , ‘reconstructed’ , ‘latest_only’ ])
  • units (MappingProxyType)
  • license (str)
  • valid_from (MappingProxyType)
  • native_frequency (str)
  • availability (tuple [Literal [ ‘python’ , ‘typescript’ ] , … ])
  • schema_id (str)
  • schema_version (int)
  • columns (tuple [str , … ])

id

Short source identity (e.g. "weather.climate.cli"). Named in every error the source’s rows trigger (leakage attribution, R-22).

prefix

Column namespace this source owns; MUST end with "_" so a collision check is an unambiguous string-prefix test. A bad prefix raises ContractError at construction.

event_time_col

The column holding the row’s event/observation time. When the spine already carries this column, align uses a materialized equality join (the reconstructed-label path); otherwise it uses a backward as-of on knowledge_time_col.

knowledge_time_col

The column holding when the row became KNOWN. The leakage guard compares this against the spine’s decision_time.

entity_key

The per-entity key tuple joins group by (by= in merge_asof); default ("station",).

revision_order

Tuple of (column, "asc"|"desc") authority pairs. The collapse stage sorts by this order then keeps the top row per (entity_key, event_time_col) group. Empty → collapse is identity.

revision_tiebreak

Tie-break at equal authority; "first_seen" (STRICT > semantics — the second equal row never overwrites the first).

point_in_time_fidelity

"exact" (true point-in-time, leakage-audited), "reconstructed" (highest-authority-available, knowingly NOT PIT → audit-exempt, e.g. the CLI settlement label), or "latest_only" (align refuses / loudly warns — Plan 03).

units

Per-column unit strings (frozen).

license

Redistribution/resale-rights flag; default "unknown".

valid_from

Per-entity coverage left-edge (frozen).

native_frequency

Declared native cadence; default "daily".

availability

Runtime availability — a tuple of full language names (("python",) / ("typescript",) / ("python", "typescript")); discover() surfaces it as a list (never the legacy "py,ts" string).

schema_id

Registered schema.*.v1 id (may be empty for a spike spec).

schema_version

Schema version integer.

columns

The declared feature columns this source emits.

availability: tuple[Literal['python', 'typescript'], ...]

columns: tuple[str, ...]

entity_key: tuple[str, ...]

event_time_col: str

id: str

knowledge_time_col: str

license: str

native_frequency: str

point_in_time_fidelity: Literal['exact', 'reconstructed', 'latest_only']

prefix: str

revision_order: tuple[tuple[str, str], ...]

revision_tiebreak: str

schema_id: str

schema_version: int

units: mappingproxy[str, str]

valid_from: mappingproxy[str, str]

class mostlyright.contracts.SpineContract(y_columns, label_source_id, entity_key=(‘station’,), decision_time_col=‘decision_time_utc’, label_available_time_col=‘label_available_time_utc’, label_version=1)

Bases: object

Immutable contract for the labeled-target (y) axis of align.

• Parameters:
  • y_columns (tuple [str , … ])
  • label_source_id (str)
  • entity_key (tuple [str , … ])
  • decision_time_col (str)
  • label_available_time_col (str)
  • label_version (int)

y_columns

The target column(s) the spine carries (e.g. ("y_high_f", "y_low_f")). A spine with no target is meaningless — an empty tuple raises ContractError at construction.

label_source_id

The source identity of the label (e.g. "weather.label.cli") — named in leakage / mismatch errors.

entity_key

The per-entity key tuple the spine groups by; default ("station",).

decision_time_col

The column holding the per-row decision cutoff (the “as of” a model would have acted); default "decision_time_utc".

label_available_time_col

The column holding when the label became KNOWN (published); default "label_available_time_utc".

label_version

Monotonic label-recipe version; default 1. A bump signals the settlement label’s computation changed.

decision_time_col: str

entity_key: tuple[str, ...]

label_available_time_col: str

label_source_id: str

label_version: int

y_columns: tuple[str, ...]

class mostlyright.contracts.TimePoint(value)

Bases: object

A UTC-aware timestamp normalized to UTC for storage.

Construction accepts:

• datetime.datetime with tzinfo set (converted to UTC)
• pandas.Timestamp with tz set (converted to UTC)
• ISO 8601 string with a timezone (parsed and converted to UTC)

Rejects:

• naive datetime / pd.Timestamp (tzinfo / tz is None)
• date-only ISO strings (no time component, e.g. "YYYY-MM-DD")

Storage is a datetime with tzinfo=timezone.utc and microsecond precision preserved.

• Parameters: value (TimePointInput)

as_zone(tz)

Convert to a different IANA zone via zoneinfo.ZoneInfo.

Display helper only — the canonical storage stays UTC. Raises zoneinfo.ZoneInfoNotFoundError if tz is not a known IANA timezone.

• Return type: datetime
• Parameters: tz (str)

classmethod from_pandas(ts)

Construct from a tz-aware pandas.Timestamp.

Explicit alternative to passing a Timestamp to TimePoint(...) — useful when the caller wants the pandas-specific dispatch path to be unambiguous.

Raises ValueError if ts is pd.NaT (missing-data sentinel).

• Return type: TimePoint
• Parameters: ts (Timestamp)

iso()

Return an ISO 8601 UTC string.

Includes microseconds only when non-zero, matching standard datetime.isoformat() behavior (e.g. "2026-05-21T14:30:00+00:00" or "2026-05-21T14:30:00.123456+00:00").

• Return type: str

classmethod now()

Return a TimePoint for the current UTC time.

• Return type: TimePoint

to_utc()

Return the underlying UTC datetime (microseconds preserved).

• Return type: datetime

mostlyright.contracts.describe(schema_id)

Return a human-readable description of a registered schema.

• Return type: str
• Parameters: schema_id (str)

mostlyright.contracts.validate_source_contract(spec)

Validate a SourceContract spec (bitemporal + point_in_time_fidelity + prefix).

Raised as a ContractError naming the offending field. Reused by mr.registry.source() / mr.registry.label() so a nonconforming spec is rejected at registration time (the prefix end-"_" rule is already enforced in SourceContract.__post_init__(); re-checked here for the direct-validation path).

• Return type: None
• Parameters: spec (SourceContract)

mostlyright.contracts.validate_source_frame(df, contract)

Validate that a source DataFrame carries its contract’s declared columns.

Checks the bitemporal timestamp columns (event_time_col / knowledge_time_col), the entity_key, and the declared feature columns. Also sanity-checks the contract’s point_in_time_fidelity is a known value. Raises ContractError naming the first missing column.

• Return type: None
• Parameters:
  • df (DataFrame)
  • contract (SourceContract)

mostlyright.contracts.validate_spine_frame(df, contract)

Validate that a spine DataFrame carries its contract’s declared columns.

Checks the entity_key, decision_time_col, label_available_time_col, and every y_columns entry. Raises ContractError naming the first missing column.

• Return type: None
• Parameters:
  • df (DataFrame)
  • contract (SpineContract)