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. It is the temporal-safety primitive the 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 dropped from the view silently. Use LeakageDetector when such a row should raise instead.

The class:

• uses __slots__ for memory predictability;
• does not register a pandas accessor;
• validates input shape eagerly, raising SchemaValidationError if knowledge_time is missing or not tz-aware UTC.

Functions

Function	Description
knowable_at(df, knowledge_time_cols)	The UTC instant each row became computable.

Classes

Class	Description
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.

Returns the row-wise maximum across the given knowledge-time columns — the latest moment any of the row’s bitemporal inputs became known, which is the earliest wall-clock instant at which the whole row could have been computed live. This is the knowable_at_utc column training_table() returns alongside 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.