kumoai 2.12.0.dev202510231830__cp311-cp311-win_amd64.whl → 2.14.0.dev202512311733__cp311-cp311-win_amd64.whl

kumoai/experimental/rfm/rfm.py

@@ -2,35 +2,38 @@ import json
 import time
 import warnings
 from collections import defaultdict
-from collections.abc import Generator
+from collections.abc import Generator, Iterator
 from contextlib import contextmanager
 from dataclasses import dataclass, replace
-from typing import Iterator, List, Literal, Optional, Union, overload
+from typing import Any, Literal, overload
 
 import numpy as np
 import pandas as pd
 from kumoapi.model_plan import RunMode
-from kumoapi.pquery import QueryType
+from kumoapi.pquery import QueryType, ValidatedPredictiveQuery
+from kumoapi.pquery.AST import (
+    Aggregation,
+    Column,
+    Condition,
+    Join,
+    LogicalOperation,
+)
 from kumoapi.rfm import Context
 from kumoapi.rfm import Explanation as ExplanationConfig
 from kumoapi.rfm import (
-    PQueryDefinition,
     RFMEvaluateRequest,
+    RFMParseQueryRequest,
     RFMPredictRequest,
-    RFMValidateQueryRequest,
 )
 from kumoapi.task import TaskType
+from kumoapi.typing import AggregationType, Stype
 
-from kumoai import global_state
+from kumoai.client.rfm import RFMAPI
 from kumoai.exceptions import HTTPException
-from kumoai.experimental.rfm import LocalGraph
-from kumoai.experimental.rfm.local_graph_sampler import LocalGraphSampler
-from kumoai.experimental.rfm.local_graph_store import LocalGraphStore
-from kumoai.experimental.rfm.local_pquery_driver import (
-    LocalPQueryDriver,
-    date_offset_to_seconds,
-)
-from kumoai.utils import InteractiveProgressLogger, ProgressLogger
+from kumoai.experimental.rfm import Graph
+from kumoai.experimental.rfm.base import DataBackend, Sampler
+from kumoai.mixin import CastMixin
+from kumoai.utils import ProgressLogger, display
 
 _RANDOM_SEED = 42
 
@@ -60,6 +63,17 @@ _SIZE_LIMIT_MSG = ("Context size exceeds the 30MB limit. {stats}\nPlease "
                    "beyond this for your use-case.")
 
 
+@dataclass(repr=False)
+class ExplainConfig(CastMixin):
+    """Configuration for explainability.
+
+    Args:
+        skip_summary: Whether to skip generating a human-readable summary of
+            the explanation.
+    """
+    skip_summary: bool = False
+
+
 @dataclass(repr=False)
 class Explanation:
     prediction: pd.DataFrame
@@ -74,19 +88,27 @@ class Explanation:
     def __getitem__(self, index: Literal[1]) -> str:
         pass
 
-    def __getitem__(self, index: int) -> Union[pd.DataFrame, str]:
+    def __getitem__(self, index: int) -> pd.DataFrame | str:
         if index == 0:
             return self.prediction
         if index == 1:
             return self.summary
         raise IndexError("Index out of range")
 
-    def __iter__(self) -> Iterator[Union[pd.DataFrame, str]]:
+    def __iter__(self) -> Iterator[pd.DataFrame | str]:
         return iter((self.prediction, self.summary))
 
     def __repr__(self) -> str:
         return str((self.prediction, self.summary))
 
+    def print(self) -> None:
+        r"""Prints the explanation."""
+        display.dataframe(self.prediction)
+        display.message(self.summary)
+
+    def _ipython_display_(self) -> None:
+        self.print()
+
 
 class KumoRFM:
     r"""The Kumo Relational Foundation model (RFM) from the `KumoRFM: A
@@ -96,17 +118,17 @@ class KumoRFM:
     :class:`KumoRFM` is a foundation model to generate predictions for any
     relational dataset without training.
     The model is pre-trained and the class provides an interface to query the
-    model from a :class:`LocalGraph` object.
+    model from a :class:`Graph` object.
 
     .. code-block:: python
 
-        from kumoai.experimental.rfm import LocalGraph, KumoRFM
+        from kumoai.experimental.rfm import Graph, KumoRFM
 
         df_users = pd.DataFrame(...)
         df_items = pd.DataFrame(...)
         df_orders = pd.DataFrame(...)
 
-        graph = LocalGraph.from_data({
+        graph = Graph.from_data({
             'users': df_users,
             'items': df_items,
             'orders': df_orders,
@@ -114,47 +136,63 @@ class KumoRFM:
 
         rfm = KumoRFM(graph)
 
-        query = ("PREDICT COUNT(transactions.*, 0, 30, days)>0 "
-                 "FOR users.user_id=0")
-        result = rfm.query(query)
+        query = ("PREDICT COUNT(orders.*, 0, 30, days)>0 "
+                 "FOR users.user_id=1")
+        result = rfm.predict(query)
 
         print(result)  # user_id  COUNT(transactions.*, 0, 30, days) > 0
                        # 1        0.85
 
     Args:
         graph: The graph.
-        preprocess: Whether to pre-process the data in advance during graph
-            materialization.
-            This is a runtime trade-off between graph materialization and model
-            processing speed.
-            It can be benefical to preprocess your data once and then run many
-            queries on top to achieve maximum model speed.
-            However, if activiated, graph materialization can take potentially
-            much longer, especially on graphs with many large text columns.
-            Best to tune this option manually.
         verbose: Whether to print verbose output.
+        optimize: If set to ``True``, will optimize the underlying data backend
+            for optimal querying. For example, for transactional database
+            backends, will create any missing indices. Requires write-access to
+            the data backend.
     """
     def __init__(
         self,
-        graph: LocalGraph,
-        preprocess: bool = False,
-        verbose: Union[bool, ProgressLogger] = True,
+        graph: Graph,
+        verbose: bool | ProgressLogger = True,
+        optimize: bool = False,
     ) -> None:
         graph = graph.validate()
         self._graph_def = graph._to_api_graph_definition()
-        self._graph_store = LocalGraphStore(graph, preprocess, verbose)
-        self._graph_sampler = LocalGraphSampler(self._graph_store)
 
-        self._batch_size: Optional[int | Literal['max']] = None
+        if graph.backend == DataBackend.LOCAL:
+            from kumoai.experimental.rfm.backend.local import LocalSampler
+            self._sampler: Sampler = LocalSampler(graph, verbose)
+        elif graph.backend == DataBackend.SQLITE:
+            from kumoai.experimental.rfm.backend.sqlite import SQLiteSampler
+            self._sampler = SQLiteSampler(graph, verbose, optimize)
+        elif graph.backend == DataBackend.SNOWFLAKE:
+            from kumoai.experimental.rfm.backend.snow import SnowSampler
+            self._sampler = SnowSampler(graph, verbose)
+        else:
+            raise NotImplementedError
+
+        self._client: RFMAPI | None = None
+
+        self._batch_size: int | Literal['max'] | None = None
         self.num_retries: int = 0
 
+    @property
+    def _api_client(self) -> RFMAPI:
+        if self._client is not None:
+            return self._client
+
+        from kumoai.experimental.rfm import global_state
+        self._client = RFMAPI(global_state.client)
+        return self._client
+
     def __repr__(self) -> str:
         return f'{self.__class__.__name__}()'
 
     @contextmanager
     def batch_mode(
         self,
-        batch_size: Union[int, Literal['max']] = 'max',
+        batch_size: int | Literal['max'] = 'max',
         num_retries: int = 1,
     ) -> Generator[None, None, None]:
         """Context manager to predict in batches.
@@ -188,17 +226,17 @@ class KumoRFM:
     def predict(
         self,
         query: str,
-        indices: Union[List[str], List[float], List[int], None] = None,
+        indices: list[str] | list[float] | list[int] | None = None,
         *,
         explain: Literal[False] = False,
-        anchor_time: Union[pd.Timestamp, Literal['entity'], None] = None,
-        context_anchor_time: Union[pd.Timestamp, None] = None,
-        run_mode: Union[RunMode, str] = RunMode.FAST,
-        num_neighbors: Optional[List[int]] = None,
+        anchor_time: pd.Timestamp | Literal['entity'] | None = None,
+        context_anchor_time: pd.Timestamp | None = None,
+        run_mode: RunMode | str = RunMode.FAST,
+        num_neighbors: list[int] | None = None,
         num_hops: int = 2,
-        max_pq_iterations: int = 20,
-        random_seed: Optional[int] = _RANDOM_SEED,
-        verbose: Union[bool, ProgressLogger] = True,
+        max_pq_iterations: int = 10,
+        random_seed: int | None = _RANDOM_SEED,
+        verbose: bool | ProgressLogger = True,
         use_prediction_time: bool = False,
     ) -> pd.DataFrame:
         pass
@@ -207,17 +245,17 @@ class KumoRFM:
     def predict(
         self,
         query: str,
-        indices: Union[List[str], List[float], List[int], None] = None,
+        indices: list[str] | list[float] | list[int] | None = None,
         *,
-        explain: Literal[True],
-        anchor_time: Union[pd.Timestamp, Literal['entity'], None] = None,
-        context_anchor_time: Union[pd.Timestamp, None] = None,
-        run_mode: Union[RunMode, str] = RunMode.FAST,
-        num_neighbors: Optional[List[int]] = None,
+        explain: Literal[True] | ExplainConfig | dict[str, Any],
+        anchor_time: pd.Timestamp | Literal['entity'] | None = None,
+        context_anchor_time: pd.Timestamp | None = None,
+        run_mode: RunMode | str = RunMode.FAST,
+        num_neighbors: list[int] | None = None,
         num_hops: int = 2,
-        max_pq_iterations: int = 20,
-        random_seed: Optional[int] = _RANDOM_SEED,
-        verbose: Union[bool, ProgressLogger] = True,
+        max_pq_iterations: int = 10,
+        random_seed: int | None = _RANDOM_SEED,
+        verbose: bool | ProgressLogger = True,
         use_prediction_time: bool = False,
     ) -> Explanation:
         pass
@@ -225,19 +263,19 @@ class KumoRFM:
     def predict(
         self,
         query: str,
-        indices: Union[List[str], List[float], List[int], None] = None,
+        indices: list[str] | list[float] | list[int] | None = None,
         *,
-        explain: bool = False,
-        anchor_time: Union[pd.Timestamp, Literal['entity'], None] = None,
-        context_anchor_time: Union[pd.Timestamp, None] = None,
-        run_mode: Union[RunMode, str] = RunMode.FAST,
-        num_neighbors: Optional[List[int]] = None,
+        explain: bool | ExplainConfig | dict[str, Any] = False,
+        anchor_time: pd.Timestamp | Literal['entity'] | None = None,
+        context_anchor_time: pd.Timestamp | None = None,
+        run_mode: RunMode | str = RunMode.FAST,
+        num_neighbors: list[int] | None = None,
         num_hops: int = 2,
-        max_pq_iterations: int = 20,
-        random_seed: Optional[int] = _RANDOM_SEED,
-        verbose: Union[bool, ProgressLogger] = True,
+        max_pq_iterations: int = 10,
+        random_seed: int | None = _RANDOM_SEED,
+        verbose: bool | ProgressLogger = True,
         use_prediction_time: bool = False,
-    ) -> Union[pd.DataFrame, Explanation]:
+    ) -> pd.DataFrame | Explanation:
         """Returns predictions for a predictive query.
 
         Args:
@@ -247,9 +285,12 @@ class KumoRFM:
                 be generated for all indices, independent of whether they
                 fulfill entity filter constraints. To pre-filter entities, use
                 :meth:`~KumoRFM.is_valid_entity`.
-            explain: If set to ``True``, will additionally explain the
-                prediction. Explainability is currently only supported for
-                single entity predictions with ``run_mode="FAST"``.
+            explain: Configuration for explainability.
+                If set to ``True``, will additionally explain the prediction.
+                Passing in an :class:`ExplainConfig` instance provides control
+                over which parts of explanation are generated.
+                Explainability is currently only supported for single entity
+                predictions with ``run_mode="FAST"``.
             anchor_time: The anchor timestamp for the prediction. If set to
                 ``None``, will use the maximum timestamp in the data.
                 If set to ``"entity"``, will use the timestamp of the entity.
@@ -273,56 +314,62 @@ class KumoRFM:
 
         Returns:
             The predictions as a :class:`pandas.DataFrame`.
-            If ``explain=True``, additionally returns a textual summary that
-            explains the prediction.
+            If ``explain`` is provided, returns an :class:`Explanation` object
+            containing the prediction, summary, and details.
         """
+        explain_config: ExplainConfig | None = None
+        if explain is True:
+            explain_config = ExplainConfig()
+        elif explain is not False:
+            explain_config = ExplainConfig._cast(explain)
+
         query_def = self._parse_query(query)
+        query_str = query_def.to_string()
 
         if num_hops != 2 and num_neighbors is not None:
             warnings.warn(f"Received custom 'num_neighbors' option; ignoring "
                           f"custom 'num_hops={num_hops}' option")
 
-        if explain and run_mode in {RunMode.NORMAL, RunMode.BEST}:
+        if explain_config is not None and run_mode in {
+                RunMode.NORMAL, RunMode.BEST
+        }:
             warnings.warn(f"Explainability is currently only supported for "
                           f"run mode 'FAST' (got '{run_mode}'). Provided run "
                           f"mode has been reset. Please lower the run mode to "
                           f"suppress this warning.")
 
         if indices is None:
-            if query_def.entity.ids is None:
+            if query_def.rfm_entity_ids is None:
                 raise ValueError("Cannot find entities to predict for. Please "
                                  "pass them via `predict(query, indices=...)`")
-            indices = query_def.entity.ids.value
+            indices = query_def.get_rfm_entity_id_list()
         else:
-            query_def = replace(
-                query_def,
-                entity=replace(query_def.entity, ids=None),
-            )
+            query_def = replace(query_def, rfm_entity_ids=None)
 
         if len(indices) == 0:
             raise ValueError("At least one entity is required")
 
-        if explain and len(indices) > 1:
+        if explain_config is not None and len(indices) > 1:
             raise ValueError(
                 f"Cannot explain predictions for more than a single entity "
                 f"(got {len(indices)})")
 
         query_repr = query_def.to_string(rich=True, exclude_predict=True)
-        if explain:
+        if explain_config is not None:
             msg = f'[bold]EXPLAIN[/bold] {query_repr}'
         else:
             msg = f'[bold]PREDICT[/bold] {query_repr}'
 
         if not isinstance(verbose, ProgressLogger):
-            verbose = InteractiveProgressLogger(msg, verbose=verbose)
+            verbose = ProgressLogger.default(msg=msg, verbose=verbose)
 
         with verbose as logger:
 
-            batch_size: Optional[int] = None
+            batch_size: int | None = None
             if self._batch_size == 'max':
-                task_type = query_def.get_task_type(
-                    stypes=self._graph_store.stype_dict,
-                    edge_types=self._graph_store.edge_types,
+                task_type = self._get_task_type(
+                    query=query_def,
+                    edge_types=self._sampler.edge_types,
                 )
                 batch_size = _MAX_PRED_SIZE[task_type]
             else:
@@ -338,9 +385,9 @@ class KumoRFM:
                 logger.log(f"Splitting {len(indices):,} entities into "
                            f"{len(batches):,} batches of size {batch_size:,}")
 
-            predictions: List[pd.DataFrame] = []
-            summary: Optional[str] = None
-            details: Optional[Explanation] = None
+            predictions: list[pd.DataFrame] = []
+            summary: str | None = None
+            details: Explanation | None = None
             for i, batch in enumerate(batches):
                 # TODO Re-use the context for subsequent predictions.
                 context = self._get_context(
@@ -359,6 +406,7 @@ class KumoRFM:
                 request = RFMPredictRequest(
                     context=context,
                     run_mode=RunMode(run_mode),
+                    query=query_str,
                     use_prediction_time=use_prediction_time,
                 )
                 with warnings.catch_warnings():
@@ -373,8 +421,7 @@ class KumoRFM:
                     stats = Context.get_memory_stats(request_msg.context)
                     raise ValueError(_SIZE_LIMIT_MSG.format(stats=stats))
 
-                if (isinstance(verbose, InteractiveProgressLogger) and i == 0
-                        and len(batches) > 1):
+                if i == 0 and len(batches) > 1:
                     verbose.init_progress(
                         total=len(batches),
                         description='Predicting',
@@ -382,20 +429,23 @@ class KumoRFM:
 
                 for attempt in range(self.num_retries + 1):
                     try:
-                        if explain:
-                            resp = global_state.client.rfm_api.explain(_bytes)
+                        if explain_config is not None:
+                            resp = self._api_client.explain(
+                                request=_bytes,
+                                skip_summary=explain_config.skip_summary,
+                            )
                             summary = resp.summary
                             details = resp.details
                         else:
-                            resp = global_state.client.rfm_api.predict(_bytes)
+                            resp = self._api_client.predict(_bytes)
                         df = pd.DataFrame(**resp.prediction)
 
                         # Cast 'ENTITY' to correct data type:
                         if 'ENTITY' in df:
-                            entity = query_def.entity.pkey.table_name
-                            pkey_map = self._graph_store.pkey_map_dict[entity]
-                            df['ENTITY'] = df['ENTITY'].astype(
-                                type(pkey_map.index[0]))
+                            table_dict = context.subgraph.table_dict
+                            table = table_dict[query_def.entity_table]
+                            ser = table.df[table.primary_key]
+                            df['ENTITY'] = df['ENTITY'].astype(ser.dtype)
 
                         # Cast 'ANCHOR_TIMESTAMP' to correct data type:
                         if 'ANCHOR_TIMESTAMP' in df:
@@ -410,8 +460,7 @@ class KumoRFM:
 
                         predictions.append(df)
 
-                        if (isinstance(verbose, InteractiveProgressLogger)
-                                and len(batches) > 1):
+                        if len(batches) > 1:
                             verbose.step()
 
                         break
@@ -434,7 +483,7 @@ class KumoRFM:
         else:
             prediction = pd.concat(predictions, ignore_index=True)
 
-        if explain:
+        if explain_config is not None:
             assert len(predictions) == 1
             assert summary is not None
             assert details is not None
@@ -449,9 +498,9 @@ class KumoRFM:
     def is_valid_entity(
         self,
         query: str,
-        indices: Union[List[str], List[float], List[int], None] = None,
+        indices: list[str] | list[float] | list[int] | None = None,
         *,
-        anchor_time: Union[pd.Timestamp, Literal['entity'], None] = None,
+        anchor_time: pd.Timestamp | Literal['entity'] | None = None,
     ) -> np.ndarray:
         r"""Returns a mask that denotes which entities are valid for the
         given predictive query, *i.e.*, which entities fulfill (temporal)
@@ -468,48 +517,42 @@ class KumoRFM:
         query_def = self._parse_query(query)
 
         if indices is None:
-            if query_def.entity.ids is None:
+            if query_def.rfm_entity_ids is None:
                 raise ValueError("Cannot find entities to predict for. Please "
                                  "pass them via "
                                  "`is_valid_entity(query, indices=...)`")
-            indices = query_def.entity.ids.value
+            indices = query_def.get_rfm_entity_id_list()
 
         if len(indices) == 0:
             raise ValueError("At least one entity is required")
 
         if anchor_time is None:
-            anchor_time = self._graph_store.max_time
+            anchor_time = self._get_default_anchor_time(query_def)
 
         if isinstance(anchor_time, pd.Timestamp):
             self._validate_time(query_def, anchor_time, None, False)
         else:
             assert anchor_time == 'entity'
-            if (query_def.entity.pkey.table_name
-                    not in self._graph_store.time_dict):
+            if query_def.entity_table not in self._sampler.time_column_dict:
                 raise ValueError(f"Anchor time 'entity' requires the entity "
-                                 f"table '{query_def.entity.pkey.table_name}' "
-                                 f"to have a time column")
+                                 f"table '{query_def.entity_table}' "
+                                 f"to have a time column.")
 
-        node = self._graph_store.get_node_id(
-            table_name=query_def.entity.pkey.table_name,
-            pkey=pd.Series(indices),
-        )
-        query_driver = LocalPQueryDriver(self._graph_store, query_def)
-        return query_driver.is_valid(node, anchor_time)
+        raise NotImplementedError
 
     def evaluate(
         self,
         query: str,
         *,
-        metrics: Optional[List[str]] = None,
-        anchor_time: Union[pd.Timestamp, Literal['entity'], None] = None,
-        context_anchor_time: Union[pd.Timestamp, None] = None,
-        run_mode: Union[RunMode, str] = RunMode.FAST,
-        num_neighbors: Optional[List[int]] = None,
+        metrics: list[str] | None = None,
+        anchor_time: pd.Timestamp | Literal['entity'] | None = None,
+        context_anchor_time: pd.Timestamp | None = None,
+        run_mode: RunMode | str = RunMode.FAST,
+        num_neighbors: list[int] | None = None,
         num_hops: int = 2,
-        max_pq_iterations: int = 20,
-        random_seed: Optional[int] = _RANDOM_SEED,
-        verbose: Union[bool, ProgressLogger] = True,
+        max_pq_iterations: int = 10,
+        random_seed: int | None = _RANDOM_SEED,
+        verbose: bool | ProgressLogger = True,
         use_prediction_time: bool = False,
     ) -> pd.DataFrame:
         """Evaluates a predictive query.
@@ -547,17 +590,17 @@ class KumoRFM:
             warnings.warn(f"Received custom 'num_neighbors' option; ignoring "
                           f"custom 'num_hops={num_hops}' option")
 
-        if query_def.entity.ids is not None:
+        if query_def.rfm_entity_ids is not None:
             query_def = replace(
                 query_def,
-                entity=replace(query_def.entity, ids=None),
+                rfm_entity_ids=None,
             )
 
         query_repr = query_def.to_string(rich=True, exclude_predict=True)
         msg = f'[bold]EVALUATE[/bold] {query_repr}'
 
         if not isinstance(verbose, ProgressLogger):
-            verbose = InteractiveProgressLogger(msg, verbose=verbose)
+            verbose = ProgressLogger.default(msg=msg, verbose=verbose)
 
         with verbose as logger:
             context = self._get_context(
@@ -591,10 +634,10 @@ class KumoRFM:
 
             if len(request_bytes) > _MAX_SIZE:
                 stats_msg = Context.get_memory_stats(request_msg.context)
-                raise ValueError(_SIZE_LIMIT_MSG.format(stats_msg=stats_msg))
+                raise ValueError(_SIZE_LIMIT_MSG.format(stats=stats_msg))
 
             try:
-                resp = global_state.client.rfm_api.evaluate(request_bytes)
+                resp = self._api_client.evaluate(request_bytes)
             except HTTPException as e:
                 try:
                     msg = json.loads(e.detail)['detail']
@@ -616,9 +659,9 @@ class KumoRFM:
         query: str,
         size: int,
         *,
-        anchor_time: Union[pd.Timestamp, Literal['entity'], None] = None,
-        random_seed: Optional[int] = _RANDOM_SEED,
-        max_iterations: int = 20,
+        anchor_time: pd.Timestamp | Literal['entity'] | None = None,
+        random_seed: int | None = _RANDOM_SEED,
+        max_iterations: int = 10,
     ) -> pd.DataFrame:
         """Returns the labels of a predictive query for a specified anchor
         time.
@@ -638,45 +681,43 @@ class KumoRFM:
         query_def = self._parse_query(query)
 
         if anchor_time is None:
-            anchor_time = self._graph_store.max_time
-            anchor_time = anchor_time - (query_def.target.end_offset *
-                                         query_def.num_forecasts)
+            anchor_time = self._get_default_anchor_time(query_def)
+            if query_def.target_ast.date_offset_range is not None:
+                offset = query_def.target_ast.date_offset_range.end_date_offset
+                offset *= query_def.num_forecasts
+                anchor_time -= offset
 
         assert anchor_time is not None
         if isinstance(anchor_time, pd.Timestamp):
             self._validate_time(query_def, anchor_time, None, evaluate=True)
         else:
             assert anchor_time == 'entity'
-            if (query_def.entity.pkey.table_name
-                    not in self._graph_store.time_dict):
+            if query_def.entity_table not in self._sampler.time_column_dict:
                 raise ValueError(f"Anchor time 'entity' requires the entity "
-                                 f"table '{query_def.entity.pkey.table_name}' "
+                                 f"table '{query_def.entity_table}' "
                                  f"to have a time column")
 
-        query_driver = LocalPQueryDriver(self._graph_store, query_def,
-                                         random_seed)
-
-        node, time, y = query_driver.collect_test(
-            size=size,
-            anchor_time=anchor_time,
-            batch_size=min(10_000, size),
-            max_iterations=max_iterations,
-            guarantee_train_examples=False,
+        train, test = self._sampler.sample_target(
+            query=query_def,
+            num_train_examples=0,
+            train_anchor_time=anchor_time,
+            num_train_trials=0,
+            num_test_examples=size,
+            test_anchor_time=anchor_time,
+            num_test_trials=max_iterations * size,
+            random_seed=random_seed,
         )
 
-        entity = self._graph_store.pkey_map_dict[
-            query_def.entity.pkey.table_name].index[node]
-
         return pd.DataFrame({
-            'ENTITY': entity,
-            'ANCHOR_TIMESTAMP': time,
-            'TARGET': y,
+            'ENTITY': test.entity_pkey,
+            'ANCHOR_TIMESTAMP': test.anchor_time,
+            'TARGET': test.target,
         })
 
     # Helpers #################################################################
 
-    def _parse_query(self, query: str) -> PQueryDefinition:
-        if isinstance(query, PQueryDefinition):
+    def _parse_query(self, query: str) -> ValidatedPredictiveQuery:
+        if isinstance(query, ValidatedPredictiveQuery):
             return query
 
         if isinstance(query, str) and query.strip()[:9].lower() == 'evaluate ':
@@ -686,13 +727,12 @@ class KumoRFM:
                              "predictions or evaluations.")
 
         try:
-            request = RFMValidateQueryRequest(
+            request = RFMParseQueryRequest(
                 query=query,
                 graph_definition=self._graph_def,
             )
 
-            resp = global_state.client.rfm_api.validate_query(request)
-            # TODO Expose validation warnings.
+            resp = self._api_client.parse_query(request)
 
             if len(resp.validation_response.warnings) > 0:
                 msg = '\n'.join([
@@ -702,7 +742,7 @@ class KumoRFM:
                 warnings.warn(f"Encountered the following warnings during "
                               f"parsing:\n{msg}")
 
-            return resp.query_definition
+            return resp.query
         except HTTPException as e:
             try:
                 msg = json.loads(e.detail)['detail']
@@ -711,30 +751,91 @@ class KumoRFM:
             raise ValueError(f"Failed to parse query '{query}'. "
                              f"{msg}") from None
 
+    @staticmethod
+    def _get_task_type(
+        query: ValidatedPredictiveQuery,
+        edge_types: list[tuple[str, str, str]],
+    ) -> TaskType:
+        if isinstance(query.target_ast, (Condition, LogicalOperation)):
+            return TaskType.BINARY_CLASSIFICATION
+
+        target = query.target_ast
+        if isinstance(target, Join):
+            target = target.rhs_target
+        if isinstance(target, Aggregation):
+            if target.aggr == AggregationType.LIST_DISTINCT:
+                table_name, col_name = target._get_target_column_name().split(
+                    '.')
+                target_edge_types = [
+                    edge_type for edge_type in edge_types
+                    if edge_type[0] == table_name and edge_type[1] == col_name
+                ]
+                if len(target_edge_types) != 1:
+                    raise NotImplementedError(
+                        f"Multilabel-classification queries based on "
+                        f"'LIST_DISTINCT' are not supported yet. If you "
+                        f"planned to write a link prediction query instead, "
+                        f"make sure to register '{col_name}' as a "
+                        f"foreign key.")
+                return TaskType.TEMPORAL_LINK_PREDICTION
+
+            return TaskType.REGRESSION
+
+        assert isinstance(target, Column)
+
+        if target.stype in {Stype.ID, Stype.categorical}:
+            return TaskType.MULTICLASS_CLASSIFICATION
+
+        if target.stype in {Stype.numerical}:
+            return TaskType.REGRESSION
+
+        raise NotImplementedError("Task type not yet supported")
+
+    def _get_default_anchor_time(
+        self,
+        query: ValidatedPredictiveQuery,
+    ) -> pd.Timestamp:
+        if query.query_type == QueryType.TEMPORAL:
+            aggr_table_names = [
+                aggr._get_target_column_name().split('.')[0]
+                for aggr in query.get_all_target_aggregations()
+            ]
+            return self._sampler.get_max_time(aggr_table_names)
+
+        assert query.query_type == QueryType.STATIC
+        return self._sampler.get_max_time()
+
     def _validate_time(
         self,
-        query: PQueryDefinition,
+        query: ValidatedPredictiveQuery,
         anchor_time: pd.Timestamp,
-        context_anchor_time: Union[pd.Timestamp, None],
+        context_anchor_time: pd.Timestamp | None,
         evaluate: bool,
     ) -> None:
 
-        if self._graph_store.min_time == pd.Timestamp.max:
+        if len(self._sampler.time_column_dict) == 0:
             return  # Graph without timestamps
 
-        if anchor_time < self._graph_store.min_time:
+        min_time = self._sampler.get_min_time()
+        max_time = self._sampler.get_max_time()
+
+        if anchor_time < min_time:
             raise ValueError(f"Anchor timestamp '{anchor_time}' is before "
-                             f"the earliest timestamp "
-                             f"'{self._graph_store.min_time}' in the data.")
+                             f"the earliest timestamp '{min_time}' in the "
+                             f"data.")
 
-        if (context_anchor_time is not None
-                and context_anchor_time < self._graph_store.min_time):
+        if context_anchor_time is not None and context_anchor_time < min_time:
             raise ValueError(f"Context anchor timestamp is too early or "
                              f"aggregation time range is too large. To make "
                              f"this prediction, we would need data back to "
                              f"'{context_anchor_time}', however, your data "
-                             f"only contains data back to "
-                             f"'{self._graph_store.min_time}'.")
+                             f"only contains data back to '{min_time}'.")
+
+        if query.target_ast.date_offset_range is not None:
+            end_offset = query.target_ast.date_offset_range.end_date_offset
+        else:
+            end_offset = pd.DateOffset(0)
+        end_offset = end_offset * query.num_forecasts
 
         if (context_anchor_time is not None
                 and context_anchor_time > anchor_time):
@@ -744,51 +845,46 @@ class KumoRFM:
                           f"(got '{anchor_time}'). Please make sure this is "
                           f"intended.")
         elif (query.query_type == QueryType.TEMPORAL
-              and context_anchor_time is not None and context_anchor_time +
-              query.target.end_offset * query.num_forecasts > anchor_time):
+              and context_anchor_time is not None
+              and context_anchor_time + end_offset > anchor_time):
             warnings.warn(f"Aggregation for context examples at timestamp "
                           f"'{context_anchor_time}' will leak information "
                           f"from the prediction anchor timestamp "
                           f"'{anchor_time}'. Please make sure this is "
                           f"intended.")
 
-        elif (context_anchor_time is not None and context_anchor_time -
-              query.target.end_offset * query.num_forecasts
-              < self._graph_store.min_time):
-            _time = context_anchor_time - (query.target.end_offset *
-                                           query.num_forecasts)
+        elif (context_anchor_time is not None
+              and context_anchor_time - end_offset < min_time):
+            _time = context_anchor_time - end_offset
             warnings.warn(f"Context anchor timestamp is too early or "
                           f"aggregation time range is too large. To form "
                           f"proper input data, we would need data back to "
                           f"'{_time}', however, your data only contains "
-                          f"data back to '{self._graph_store.min_time}'.")
+                          f"data back to '{min_time}'.")
 
-        if (not evaluate and anchor_time
-                > self._graph_store.max_time + pd.DateOffset(days=1)):
+        if not evaluate and anchor_time > max_time + pd.DateOffset(days=1):
             warnings.warn(f"Anchor timestamp '{anchor_time}' is after the "
-                          f"latest timestamp '{self._graph_store.max_time}' "
-                          f"in the data. Please make sure this is intended.")
+                          f"latest timestamp '{max_time}' in the data. Please "
+                          f"make sure this is intended.")
 
-        max_eval_time = (self._graph_store.max_time -
-                         query.target.end_offset * query.num_forecasts)
-        if evaluate and anchor_time > max_eval_time:
+        if evaluate and anchor_time > max_time - end_offset:
             raise ValueError(
                 f"Anchor timestamp for evaluation is after the latest "
-                f"supported timestamp '{max_eval_time}'.")
+                f"supported timestamp '{max_time - end_offset}'.")
 
     def _get_context(
         self,
-        query: PQueryDefinition,
-        indices: Union[List[str], List[float], List[int], None],
-        anchor_time: Union[pd.Timestamp, Literal['entity'], None],
-        context_anchor_time: Union[pd.Timestamp, None],
+        query: ValidatedPredictiveQuery,
+        indices: list[str] | list[float] | list[int] | None,
+        anchor_time: pd.Timestamp | Literal['entity'] | None,
+        context_anchor_time: pd.Timestamp | None,
         run_mode: RunMode,
-        num_neighbors: Optional[List[int]],
+        num_neighbors: list[int] | None,
         num_hops: int,
         max_pq_iterations: int,
         evaluate: bool,
-        random_seed: Optional[int] = _RANDOM_SEED,
-        logger: Optional[ProgressLogger] = None,
+        random_seed: int | None = _RANDOM_SEED,
+        logger: ProgressLogger | None = None,
     ) -> Context:
 
         if num_neighbors is not None:
@@ -805,10 +901,9 @@ class KumoRFM:
                              f"'https://github.com/kumo-ai/kumo-rfm' if you "
                              f"must go beyond this for your use-case.")
 
-        query_driver = LocalPQueryDriver(self._graph_store, query, random_seed)
-        task_type = query.get_task_type(
-            stypes=self._graph_store.stype_dict,
-            edge_types=self._graph_store.edge_types,
+        task_type = self._get_task_type(
+            query=query,
+            edge_types=self._sampler.edge_types,
         )
 
         if logger is not None:
@@ -839,11 +934,18 @@ class KumoRFM:
             else:
                 num_neighbors = [64, 64, 8, 8, 4, 4][:num_hops]
 
+        if query.target_ast.date_offset_range is None:
+            step_offset = pd.DateOffset(0)
+        else:
+            step_offset = query.target_ast.date_offset_range.end_date_offset
+        end_offset = step_offset * query.num_forecasts
+
         if anchor_time is None:
-            anchor_time = self._graph_store.max_time
+            anchor_time = self._get_default_anchor_time(query)
+
             if evaluate:
-                anchor_time = anchor_time - (query.target.end_offset *
-                                             query.num_forecasts)
+                anchor_time = anchor_time - end_offset
+
             if logger is not None:
                 assert isinstance(anchor_time, pd.Timestamp)
                 if anchor_time == pd.Timestamp.min:
@@ -857,58 +959,71 @@ class KumoRFM:
 
         assert anchor_time is not None
         if isinstance(anchor_time, pd.Timestamp):
+            if context_anchor_time == 'entity':
+                raise ValueError("Anchor time 'entity' needs to be shared "
+                                 "for context and prediction examples")
             if context_anchor_time is None:
-                context_anchor_time = anchor_time - (query.target.end_offset *
-                                                     query.num_forecasts)
+                context_anchor_time = anchor_time - end_offset
             self._validate_time(query, anchor_time, context_anchor_time,
                                 evaluate)
         else:
             assert anchor_time == 'entity'
-            if query.entity.pkey.table_name not in self._graph_store.time_dict:
+            if query.query_type != QueryType.STATIC:
+                raise ValueError("Anchor time 'entity' is only valid for "
+                                 "static predictive queries")
+            if query.entity_table not in self._sampler.time_column_dict:
                 raise ValueError(f"Anchor time 'entity' requires the entity "
-                                 f"table '{query.entity.pkey.table_name}' to "
+                                 f"table '{query.entity_table}' to "
                                  f"have a time column")
-            if context_anchor_time is not None:
-                warnings.warn("Ignoring option 'context_anchor_time' for "
-                              "`anchor_time='entity'`")
-            context_anchor_time = None
+            if isinstance(context_anchor_time, pd.Timestamp):
+                raise ValueError("Anchor time 'entity' needs to be shared "
+                                 "for context and prediction examples")
+            context_anchor_time = 'entity'
 
-        y_test: Optional[pd.Series] = None
+        num_train_examples = _MAX_CONTEXT_SIZE[run_mode]
         if evaluate:
-            max_test_size = _MAX_TEST_SIZE[run_mode]
+            num_test_examples = _MAX_TEST_SIZE[run_mode]
             if task_type.is_link_pred:
-                max_test_size = max_test_size // 5
+                num_test_examples = num_test_examples // 5
+        else:
+            num_test_examples = 0
+
+        train, test = self._sampler.sample_target(
+            query=query,
+            num_train_examples=num_train_examples,
+            train_anchor_time=context_anchor_time,
+            num_train_trials=max_pq_iterations * num_train_examples,
+            num_test_examples=num_test_examples,
+            test_anchor_time=anchor_time,
+            num_test_trials=max_pq_iterations * num_test_examples,
+            random_seed=random_seed,
+        )
+        train_pkey, train_time, y_train = train
+        test_pkey, test_time, y_test = test
 
-            test_node, test_time, y_test = query_driver.collect_test(
-                size=max_test_size,
-                anchor_time=anchor_time,
-                max_iterations=max_pq_iterations,
-                guarantee_train_examples=True,
-            )
-            if logger is not None:
-                if task_type == TaskType.BINARY_CLASSIFICATION:
-                    pos = 100 * int((y_test > 0).sum()) / len(y_test)
-                    msg = (f"Collected {len(y_test):,} test examples with "
-                           f"{pos:.2f}% positive cases")
-                elif task_type == TaskType.MULTICLASS_CLASSIFICATION:
-                    msg = (f"Collected {len(y_test):,} test examples "
-                           f"holding {y_test.nunique()} classes")
-                elif task_type == TaskType.REGRESSION:
-                    _min, _max = float(y_test.min()), float(y_test.max())
-                    msg = (f"Collected {len(y_test):,} test examples with "
-                           f"targets between {format_value(_min)} and "
-                           f"{format_value(_max)}")
-                elif task_type == TaskType.TEMPORAL_LINK_PREDICTION:
-                    num_rhs = y_test.explode().nunique()
-                    msg = (f"Collected {len(y_test):,} test examples with "
-                           f"{num_rhs:,} unique items")
-                else:
-                    raise NotImplementedError
-                logger.log(msg)
+        if evaluate and logger is not None:
+            if task_type == TaskType.BINARY_CLASSIFICATION:
+                pos = 100 * int((y_test > 0).sum()) / len(y_test)
+                msg = (f"Collected {len(y_test):,} test examples with "
+                       f"{pos:.2f}% positive cases")
+            elif task_type == TaskType.MULTICLASS_CLASSIFICATION:
+                msg = (f"Collected {len(y_test):,} test examples holding "
+                       f"{y_test.nunique()} classes")
+            elif task_type == TaskType.REGRESSION:
+                _min, _max = float(y_test.min()), float(y_test.max())
+                msg = (f"Collected {len(y_test):,} test examples with targets "
+                       f"between {format_value(_min)} and "
+                       f"{format_value(_max)}")
+            elif task_type == TaskType.TEMPORAL_LINK_PREDICTION:
+                num_rhs = y_test.explode().nunique()
+                msg = (f"Collected {len(y_test):,} test examples with "
+                       f"{num_rhs:,} unique items")
+            else:
+                raise NotImplementedError
+            logger.log(msg)
 
-        else:
+        if not evaluate:
             assert indices is not None
-
             if len(indices) > _MAX_PRED_SIZE[task_type]:
                 raise ValueError(f"Cannot predict for more than "
                                  f"{_MAX_PRED_SIZE[task_type]:,} entities at "
@@ -916,27 +1031,12 @@ class KumoRFM:
                                  f"`KumoRFM.batch_mode` to process entities "
                                  f"in batches")
 
-            test_node = self._graph_store.get_node_id(
-                table_name=query.entity.pkey.table_name,
-                pkey=pd.Series(indices),
-            )
-
+            test_pkey = pd.Series(indices, dtype=train_pkey.dtype)
             if isinstance(anchor_time, pd.Timestamp):
-                test_time = pd.Series(anchor_time).repeat(
-                    len(test_node)).reset_index(drop=True)
+                test_time = pd.Series([anchor_time]).repeat(
+                    len(indices)).reset_index(drop=True)
             else:
-                time = self._graph_store.time_dict[
-                    query.entity.pkey.table_name]
-                time = time[test_node] * 1000**3
-                test_time = pd.Series(time, dtype='datetime64[ns]')
-
-        train_node, train_time, y_train = query_driver.collect_train(
-            size=_MAX_CONTEXT_SIZE[run_mode],
-            anchor_time=context_anchor_time or 'entity',
-            exclude_node=test_node if (query.query_type == QueryType.STATIC
-                                       or anchor_time == 'entity') else None,
-            max_iterations=max_pq_iterations,
-        )
+                train_time = test_time = 'entity'
 
         if logger is not None:
             if task_type == TaskType.BINARY_CLASSIFICATION:
@@ -959,27 +1059,41 @@ class KumoRFM:
                 raise NotImplementedError
             logger.log(msg)
 
-        entity_table_names = query.get_entity_table_names(
-            self._graph_store.edge_types)
+        entity_table_names: tuple[str, ...]
+        if task_type.is_link_pred:
+            final_aggr = query.get_final_target_aggregation()
+            assert final_aggr is not None
+            edge_fkey = final_aggr._get_target_column_name()
+            for edge_type in self._sampler.edge_types:
+                if edge_fkey == f'{edge_type[0]}.{edge_type[1]}':
+                    entity_table_names = (
+                        query.entity_table,
+                        edge_type[2],
+                    )
+        else:
+            entity_table_names = (query.entity_table, )
 
         # Exclude the entity anchor time from the feature set to prevent
         # running out-of-distribution between in-context and test examples:
-        exclude_cols_dict = query.exclude_cols_dict
-        if anchor_time == 'entity':
+        exclude_cols_dict = query.get_exclude_cols_dict()
+        if entity_table_names[0] in self._sampler.time_column_dict:
             if entity_table_names[0] not in exclude_cols_dict:
                 exclude_cols_dict[entity_table_names[0]] = []
-            time_column_dict = self._graph_store.time_column_dict
-            time_column = time_column_dict[entity_table_names[0]]
+            time_column = self._sampler.time_column_dict[entity_table_names[0]]
             exclude_cols_dict[entity_table_names[0]].append(time_column)
 
-        subgraph = self._graph_sampler(
+        subgraph = self._sampler.sample_subgraph(
             entity_table_names=entity_table_names,
-            node=np.concatenate([train_node, test_node]),
-            time=np.concatenate([
-                train_time.astype('datetime64[ns]').astype(int).to_numpy(),
-                test_time.astype('datetime64[ns]').astype(int).to_numpy(),
-            ]),
-            run_mode=run_mode,
+            entity_pkey=pd.concat(
+                [train_pkey, test_pkey],
+                axis=0,
+                ignore_index=True,
+            ),
+            anchor_time=pd.concat(
+                [train_time, test_time],
+                axis=0,
+                ignore_index=True,
+            ) if isinstance(train_time, pd.Series) else 'entity',
             num_neighbors=num_neighbors,
             exclude_cols_dict=exclude_cols_dict,
         )
@@ -991,23 +1105,19 @@ class KumoRFM:
                              f"'https://github.com/kumo-ai/kumo-rfm' if you "
                              f"must go beyond this for your use-case.")
 
-        step_size: Optional[int] = None
-        if query.query_type == QueryType.TEMPORAL:
-            step_size = date_offset_to_seconds(query.target.end_offset)
-
         return Context(
             task_type=task_type,
             entity_table_names=entity_table_names,
             subgraph=subgraph,
             y_train=y_train,
-            y_test=y_test,
+            y_test=y_test if evaluate else None,
             top_k=query.top_k,
-            step_size=step_size,
+            step_size=None,
         )
 
     @staticmethod
     def _validate_metrics(
-        metrics: List[str],
+        metrics: list[str],
         task_type: TaskType,
     ) -> None:
 
@@ -1064,7 +1174,7 @@ class KumoRFM:
                                  f"'https://github.com/kumo-ai/kumo-rfm'.")
 
 
-def format_value(value: Union[int, float]) -> str:
+def format_value(value: int | float) -> str:
     if value == int(value):
         return f'{int(value):,}'
     if abs(value) >= 1000: