mostlyright.core.temporal.knowledge_view

KnowledgeView — temporal filtering by knowledge_time.

A plain wrapper class (not a pandas accessor, not a DataFrame subclass) that exposes a dataframe() view filtered by knowledge_time <= as_of. This is the structural temporal-safety primitive the mostlyright research() Mode 2 dispatch uses to render leakage-free training tables — any row whose knowledge_time is later than the asserted as-of cutoff is silently dropped from the view (and would be loud via LeakageDetector).

Design constraints (CORE-07):

• Uses __slots__ for memory predictability.
• Does NOT register a pandas accessor (verified by acceptance test).
• Validates input shape eagerly — raises SchemaValidationError if knowledge_time is missing or not tz-aware UTC.

See docs/design.md §M (KnowledgeView semantics).

Functions

knowable_at(df, knowledge_time_cols)	The UTC instant each row became computable (MACH-05).

Classes

KnowledgeView(df, as_of)	A filtered, knowledge-time-bounded view over a DataFrame.

class mostlyright.core.temporal.knowledge_view.KnowledgeView(df, as_of)

Bases: object

A filtered, knowledge-time-bounded view over a DataFrame.

Construction validates the shape of the input DataFrame. After construction, dataframe() returns a defensive copy of the rows where knowledge_time <= as_of.

Examples

Build a 3-row DataFrame with a tz-aware UTC knowledge_time column and view only the rows knowable as of 2025-01-02T12:00:00Z:

>>> import pandas as pd
>>> from mostlyright.core import KnowledgeView, TimePoint
>>> df = pd.DataFrame({
...     "knowledge_time": pd.to_datetime([
...         "2025-01-01T00:00:00Z",
...         "2025-01-02T00:00:00Z",
...         "2025-01-03T00:00:00Z",
...     ], utc=True),
...     "value": [10, 20, 30],
... })
>>> view = KnowledgeView(df, TimePoint("2025-01-02T12:00:00Z"))
>>> len(view.dataframe())
2

• Parameters:
  • df (pd.DataFrame | ProvenancedFrame)
  • as_of (TimePoint)

property as_of : TimePoint

The as-of cutoff supplied at construction.

dataframe()

Return a defensive copy of the rows where knowledge_time <= as_of.

• Return type: DataFrame

mostlyright.core.temporal.knowledge_view.knowable_at(df, knowledge_time_cols)

The UTC instant each row became computable (MACH-05).

Returns the row-wise MAX across the given knowledge-time columns — the latest moment any of the row’s bitemporal inputs became known, i.e. the earliest wall-clock instant at which the whole row could have been computed live. This is the knowable_at_utc column training_table() exposes peer to the event-time columns, so a researcher can filter to exactly the rows a live model would have had in hand.

• Parameters:
  • df (DataFrame) – The composed frame carrying the knowledge-time columns.
  • knowledge_time_cols (list[str]) – The bitemporal knowledge columns to reduce over (e.g. the spine decision_time_utc + label_available_time_utc).
• Return type: Series
• Returns: A Series of tz-aware UTC timestamps aligned to df’s index.