mostlyright.core.temporal.knowledge_view

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).

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 | MostlyRightResult)
  • 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