kumoai 2.13.0.dev202512081731__cp313-cp313-macosx_11_0_arm64.whl → 2.14.0.dev202512211732__cp313-cp313-macosx_11_0_arm64.whl

kumoai/_version.py

@@ -1 +1 @@
-__version__ = '2.13.0.dev202512081731'
+__version__ = '2.14.0.dev202512211732'

kumoai/client/pquery.py

@@ -176,8 +176,12 @@ def filter_model_plan(
                     # Undefined
                     pass
 
-            new_opt_fields.append((field.name, _type, default))
-            new_opts.append(getattr(section, field.name))
+            # Forward compatibility - Remove any newly introduced arguments not
+            # returned yet by the backend:
+            value = getattr(section, field.name)
+            if value != MissingType.VALUE:
+                new_opt_fields.append((field.name, _type, default))
+                new_opts.append(value)
 
         Section = dataclass(
             config=dict(validate_assignment=True),

kumoai/experimental/rfm/__init__.py

@@ -6,11 +6,11 @@ import socket
 import threading
 from dataclasses import dataclass
 from enum import Enum
-from typing import Dict, Optional, Tuple
 from urllib.parse import urlparse
 
 import kumoai
 from kumoai.client.client import KumoClient
+from kumoai.spcs import _get_active_session
 
 from .authenticate import authenticate
 from .sagemaker import (
@@ -49,7 +49,8 @@ class InferenceBackend(str, Enum):
 
 
 def _detect_backend(
-        url: str) -> Tuple[InferenceBackend, Optional[str], Optional[str]]:
+        url: str,  #
+) -> tuple[InferenceBackend, str | None, str | None]:
     parsed = urlparse(url)
 
     # Remote SageMaker
@@ -73,12 +74,27 @@ def _detect_backend(
     return InferenceBackend.REST, None, None
 
 
+def _get_snowflake_url(snowflake_application: str) -> str:
+    snowpark_session = _get_active_session()
+    if not snowpark_session:
+        raise ValueError(
+            "Client creation failed: snowflake_application is specified "
+            "without an active snowpark session. If running outside "
+            "a snowflake notebook, specify a URL and credentials.")
+    with snowpark_session.connection.cursor() as cur:
+        cur.execute(
+            f"DESCRIBE SERVICE {snowflake_application}.user_schema.rfm_service"
+            f" ->> SELECT \"dns_name\" from $1")
+        dns_name: str = cur.fetchone()[0]
+    return f"http://{dns_name}:8000/api"
+
+
 @dataclass
 class RfmGlobalState:
     _url: str = '__url_not_provided__'
     _backend: InferenceBackend = InferenceBackend.UNKNOWN
-    _region: Optional[str] = None
-    _endpoint_name: Optional[str] = None
+    _region: str | None = None
+    _endpoint_name: str | None = None
     _thread_local = threading.local()
 
     # Thread-safe init-once.
@@ -121,10 +137,10 @@ global_state = RfmGlobalState()
 
 
 def init(
-    url: Optional[str] = None,
-    api_key: Optional[str] = None,
-    snowflake_credentials: Optional[Dict[str, str]] = None,
-    snowflake_application: Optional[str] = None,
+    url: str | None = None,
+    api_key: str | None = None,
+    snowflake_credentials: dict[str, str] | None = None,
+    snowflake_application: str | None = None,
     log_level: str = "INFO",
 ) -> None:
     with global_state._lock:
@@ -136,6 +152,15 @@ def init(
                     "supported.")
             return
 
+        if snowflake_application:
+            if url is not None:
+                raise ValueError(
+                    "Client creation failed: both snowflake_application and "
+                    "url are specified. If running from a snowflake notebook, "
+                    "specify only snowflake_application.")
+            url = _get_snowflake_url(snowflake_application)
+            api_key = "test:DISABLED"
+
         if url is None:
             url = os.getenv("RFM_API_URL", "https://kumorfm.ai/api")
 

kumoai/experimental/rfm/authenticate.py

@@ -2,12 +2,11 @@ import logging
 import os
 import platform
 from datetime import datetime
-from typing import Optional
 
 from kumoai import in_notebook
 
 
-def authenticate(api_url: Optional[str] = None) -> None:
+def authenticate(api_url: str | None = None) -> None:
     """Authenticates the user and sets the Kumo API key for the SDK.
 
     This function detects the current environment and launches the appropriate
@@ -65,11 +64,11 @@ def _authenticate_local(api_url: str, redirect_port: int = 8765) -> None:
     import webbrowser
     from getpass import getpass
     from socketserver import TCPServer
-    from typing import Any, Dict
+    from typing import Any
 
     logger = logging.getLogger('kumoai')
 
-    token_status: Dict[str, Any] = {
+    token_status: dict[str, Any] = {
         'token': None,
         'token_name': None,
         'failed': False

kumoai/experimental/rfm/backend/local/graph_store.py

@@ -1,5 +1,5 @@
 import warnings
-from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, Union
+from typing import TYPE_CHECKING
 
 import numpy as np
 import pandas as pd
@@ -7,7 +7,7 @@ from kumoapi.rfm.context import Subgraph
 from kumoapi.typing import Stype
 
 from kumoai.experimental.rfm.backend.local import LocalTable
-from kumoai.utils import InteractiveProgressLogger, ProgressLogger
+from kumoai.utils import ProgressLogger
 
 try:
     import torch
@@ -23,37 +23,32 @@ class LocalGraphStore:
     def __init__(
         self,
         graph: 'Graph',
-        verbose: Union[bool, ProgressLogger] = True,
+        verbose: bool | ProgressLogger = True,
     ) -> None:
 
         if not isinstance(verbose, ProgressLogger):
-            verbose = InteractiveProgressLogger(
-                "Materializing graph",
+            verbose = ProgressLogger.default(
+                msg="Materializing graph",
                 verbose=verbose,
             )
 
         with verbose as logger:
             self.df_dict, self.mask_dict = self.sanitize(graph)
-            self.stype_dict = self.get_stype_dict(graph)
             logger.log("Sanitized input data")
 
-            self.pkey_name_dict, self.pkey_map_dict = self.get_pkey_data(graph)
+            self.pkey_map_dict = self.get_pkey_map_dict(graph)
             num_pkeys = sum(t.has_primary_key() for t in graph.tables.values())
             if num_pkeys > 1:
                 logger.log(f"Collected primary keys from {num_pkeys} tables")
             else:
                 logger.log(f"Collected primary key from {num_pkeys} table")
 
-            (
-                self.time_column_dict,
-                self.end_time_column_dict,
-                self.time_dict,
-                self.min_time,
-                self.max_time,
-            ) = self.get_time_data(graph)
-            if self.max_time != pd.Timestamp.min:
+            self.time_dict, self.min_max_time_dict = self.get_time_data(graph)
+            if len(self.min_max_time_dict) > 0:
+                min_time = min(t for t, _ in self.min_max_time_dict.values())
+                max_time = max(t for _, t in self.min_max_time_dict.values())
                 logger.log(f"Identified temporal graph from "
-                           f"{self.min_time.date()} to {self.max_time.date()}")
+                           f"{min_time.date()} to {max_time.date()}")
             else:
                 logger.log("Identified static graph without timestamps")
 
@@ -63,14 +58,6 @@ class LocalGraphStore:
             logger.log(f"Created graph with {num_nodes:,} nodes and "
                        f"{num_edges:,} edges")
 
-    @property
-    def node_types(self) -> List[str]:
-        return list(self.df_dict.keys())
-
-    @property
-    def edge_types(self) -> List[Tuple[str, str, str]]:
-        return list(self.row_dict.keys())
-
     def get_node_id(self, table_name: str, pkey: pd.Series) -> np.ndarray:
         r"""Returns the node ID given primary keys.
 
@@ -107,7 +94,7 @@ class LocalGraphStore:
     def sanitize(
         self,
         graph: 'Graph',
-    ) -> Tuple[Dict[str, pd.DataFrame], Dict[str, np.ndarray]]:
+    ) -> tuple[dict[str, pd.DataFrame], dict[str, np.ndarray]]:
         r"""Sanitizes raw data according to table schema definition:
 
         In particular, it:
@@ -116,13 +103,13 @@ class LocalGraphStore:
         * drops duplicate primary keys
         * removes rows with missing primary keys or time values
         """
-        df_dict: Dict[str, pd.DataFrame] = {}
+        df_dict: dict[str, pd.DataFrame] = {}
         for table_name, table in graph.tables.items():
             assert isinstance(table, LocalTable)
             df = table._data
             df_dict[table_name] = df.copy(deep=False).reset_index(drop=True)
 
-        mask_dict: Dict[str, np.ndarray] = {}
+        mask_dict: dict[str, np.ndarray] = {}
         for table in graph.tables.values():
             for col in table.columns:
                 if col.stype == Stype.timestamp:
@@ -139,7 +126,7 @@ class LocalGraphStore:
                         ser = ser.dt.tz_localize(None)
                         df_dict[table.name][col.name] = ser
 
-            mask: Optional[np.ndarray] = None
+            mask: np.ndarray | None = None
             if table._time_column is not None:
                 ser = df_dict[table.name][table._time_column]
                 mask = ser.notna().to_numpy()
@@ -154,34 +141,16 @@ class LocalGraphStore:
 
         return df_dict, mask_dict
 
-    def get_stype_dict(self, graph: 'Graph') -> Dict[str, Dict[str, Stype]]:
-        stype_dict: Dict[str, Dict[str, Stype]] = {}
-        foreign_keys = {(edge.src_table, edge.fkey) for edge in graph.edges}
-        for table in graph.tables.values():
-            stype_dict[table.name] = {}
-            for column in table.columns:
-                if column == table.primary_key:
-                    continue
-                if (table.name, column.name) in foreign_keys:
-                    continue
-                stype_dict[table.name][column.name] = column.stype
-        return stype_dict
-
-    def get_pkey_data(
+    def get_pkey_map_dict(
         self,
         graph: 'Graph',
-    ) -> Tuple[
-            Dict[str, str],
-            Dict[str, pd.DataFrame],
-    ]:
-        pkey_name_dict: Dict[str, str] = {}
-        pkey_map_dict: Dict[str, pd.DataFrame] = {}
+    ) -> dict[str, pd.DataFrame]:
+        pkey_map_dict: dict[str, pd.DataFrame] = {}
 
         for table in graph.tables.values():
             if table._primary_key is None:
                 continue
 
-            pkey_name_dict[table.name] = table._primary_key
             pkey = self.df_dict[table.name][table._primary_key]
             pkey_map = pd.DataFrame(
                 dict(arange=range(len(pkey))),
@@ -203,27 +172,18 @@ class LocalGraphStore:
 
             pkey_map_dict[table.name] = pkey_map
 
-        return pkey_name_dict, pkey_map_dict
+        return pkey_map_dict
 
     def get_time_data(
         self,
         graph: 'Graph',
-    ) -> Tuple[
-            Dict[str, str],
-            Dict[str, str],
-            Dict[str, np.ndarray],
-            pd.Timestamp,
-            pd.Timestamp,
+    ) -> tuple[
+            dict[str, np.ndarray],
+            dict[str, tuple[pd.Timestamp, pd.Timestamp]],
     ]:
-        time_column_dict: Dict[str, str] = {}
-        end_time_column_dict: Dict[str, str] = {}
-        time_dict: Dict[str, np.ndarray] = {}
-        min_time = pd.Timestamp.max
-        max_time = pd.Timestamp.min
+        time_dict: dict[str, np.ndarray] = {}
+        min_max_time_dict: dict[str, tuple[pd.Timestamp, pd.Timestamp]] = {}
         for table in graph.tables.values():
-            if table._end_time_column is not None:
-                end_time_column_dict[table.name] = table._end_time_column
-
             if table._time_column is None:
                 continue
 
@@ -231,34 +191,31 @@ class LocalGraphStore:
             if time.dtype != 'datetime64[ns]':
                 time = time.astype('datetime64[ns]')
             time_dict[table.name] = time.astype(int).to_numpy() // 1000**3
-            time_column_dict[table.name] = table._time_column
 
             if table.name in self.mask_dict.keys():
                 time = time[self.mask_dict[table.name]]
             if len(time) > 0:
-                min_time = min(min_time, time.min())
-                max_time = max(max_time, time.max())
+                min_max_time_dict[table.name] = (time.min(), time.max())
+            else:
+                min_max_time_dict[table.name] = (
+                    pd.Timestamp.max,
+                    pd.Timestamp.min,
+                )
 
-        return (
-            time_column_dict,
-            end_time_column_dict,
-            time_dict,
-            min_time,
-            max_time,
-        )
+        return time_dict, min_max_time_dict
 
     def get_csc(
         self,
         graph: 'Graph',
-    ) -> Tuple[
-            Dict[Tuple[str, str, str], np.ndarray],
-            Dict[Tuple[str, str, str], np.ndarray],
+    ) -> tuple[
+            dict[tuple[str, str, str], np.ndarray],
+            dict[tuple[str, str, str], np.ndarray],
     ]:
         # A mapping from raw primary keys to node indices (0 to N-1):
-        map_dict: Dict[str, pd.CategoricalDtype] = {}
+        map_dict: dict[str, pd.CategoricalDtype] = {}
         # A dictionary to manage offsets of node indices for invalid rows:
-        offset_dict: Dict[str, np.ndarray] = {}
-        for table_name in set(edge.dst_table for edge in graph.edges):
+        offset_dict: dict[str, np.ndarray] = {}
+        for table_name in {edge.dst_table for edge in graph.edges}:
             ser = self.df_dict[table_name][graph[table_name]._primary_key]
             if table_name in self.mask_dict.keys():
                 mask = self.mask_dict[table_name]
@@ -267,8 +224,8 @@ class LocalGraphStore:
             map_dict[table_name] = pd.CategoricalDtype(ser, ordered=True)
 
         # Build CSC graph representation:
-        row_dict: Dict[Tuple[str, str, str], np.ndarray] = {}
-        colptr_dict: Dict[Tuple[str, str, str], np.ndarray] = {}
+        row_dict: dict[tuple[str, str, str], np.ndarray] = {}
+        colptr_dict: dict[tuple[str, str, str], np.ndarray] = {}
         for src_table, fkey, dst_table in graph.edges:
             src_df = self.df_dict[src_table]
             dst_df = self.df_dict[dst_table]
@@ -330,7 +287,7 @@ def _argsort(input: np.ndarray) -> np.ndarray:
     return torch.from_numpy(input).argsort().numpy()
 
 
-def _lexsort(inputs: List[np.ndarray]) -> np.ndarray:
+def _lexsort(inputs: list[np.ndarray]) -> np.ndarray:
     assert len(inputs) >= 1
 
     if not WITH_TORCH:

kumoai/experimental/rfm/backend/local/sampler.py

@@ -1,10 +1,12 @@
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
 
 import numpy as np
 import pandas as pd
+from kumoapi.pquery import ValidatedPredictiveQuery
 
 from kumoai.experimental.rfm.backend.local import LocalGraphStore
-from kumoai.experimental.rfm.base import BackwardSamplerOutput, Sampler
+from kumoai.experimental.rfm.base import Sampler, SamplerOutput
+from kumoai.experimental.rfm.pquery import PQueryPandasExecutor
 from kumoai.utils import ProgressLogger
 
 if TYPE_CHECKING:
@@ -17,7 +19,7 @@ class LocalSampler(Sampler):
         graph: 'Graph',
         verbose: bool | ProgressLogger = True,
     ) -> None:
-        super().__init__(graph=graph)
+        super().__init__(graph=graph, verbose=verbose)
 
         import kumoai.kumolib as kumolib
 
@@ -36,19 +38,32 @@ class LocalSampler(Sampler):
             self._graph_store.time_dict,
         )
 
-    def _sample_backward(
+    def _get_min_max_time_dict(
+        self,
+        table_names: list[str],
+    ) -> dict[str, tuple[pd.Timestamp, pd.Timestamp]]:
+        return {
+            key: value
+            for key, value in self._graph_store.min_max_time_dict.items()
+            if key in table_names
+        }
+
+    def _sample_subgraph(
         self,
         entity_table_name: str,
         entity_pkey: pd.Series,
-        anchor_time: pd.Series,
+        anchor_time: pd.Series | Literal['entity'],
         columns_dict: dict[str, set[str]],
         num_neighbors: list[int],
-    ) -> BackwardSamplerOutput:
+    ) -> SamplerOutput:
 
-        num_neighbors_dict: dict[str, list[int]] = {
-            '__'.join(edge_type): num_neighbors
-            for edge_type in self.edge_types
-        }
+        index = self._graph_store.get_node_id(entity_table_name, entity_pkey)
+
+        if isinstance(anchor_time, pd.Series):
+            time = anchor_time.astype(int).to_numpy() // 1000**3  # to seconds
+        else:
+            assert anchor_time == 'entity'
+            time = self._graph_store.time_dict[entity_table_name][index]
 
         (
             row_dict,
@@ -58,11 +73,14 @@ class LocalSampler(Sampler):
             num_sampled_nodes_dict,
             num_sampled_edges_dict,
         ) = self._graph_sampler.sample(
-            num_neighbors_dict,
+            {
+                '__'.join(edge_type): num_neighbors
+                for edge_type in self.edge_types
+            },
             {},
             entity_table_name,
-            self._graph_store.get_node_id(entity_table_name, entity_pkey),
-            anchor_time.astype(int).to_numpy() // 1000**3,  # to seconds
+            index,
+            time,
         )
 
         df_dict: dict[str, pd.DataFrame] = {}
@@ -105,7 +123,8 @@ class LocalSampler(Sampler):
             for edge_type in self.edge_types
         }
 
-        return BackwardSamplerOutput(
+        return SamplerOutput(
+            anchor_time=time * 1000**3,  # to nanoseconds
             df_dict=df_dict,
             inverse_dict=inverse_dict,
             batch_dict=batch_dict,
@@ -114,3 +133,183 @@ class LocalSampler(Sampler):
             col_dict=col_dict,
             num_sampled_edges_dict=num_sampled_edges_dict,
         )
+
+    def _sample_entity_table(
+        self,
+        table_name: str,
+        columns: set[str],
+        num_rows: int,
+        random_seed: int | None = None,
+    ) -> pd.DataFrame:
+        pkey_map = self._graph_store.pkey_map_dict[table_name]
+        if len(pkey_map) > num_rows:
+            pkey_map = pkey_map.sample(
+                n=num_rows,
+                random_state=random_seed,
+                ignore_index=True,
+            )
+        df = self._graph_store.df_dict[table_name]
+        df = df.iloc[pkey_map['arange']][list(columns)]
+        return df
+
+    def _sample_target(
+        self,
+        query: ValidatedPredictiveQuery,
+        entity_df: pd.DataFrame,
+        train_index: np.ndarray,
+        train_time: pd.Series,
+        num_train_examples: int,
+        test_index: np.ndarray,
+        test_time: pd.Series,
+        num_test_examples: int,
+        columns_dict: dict[str, set[str]],
+        time_offset_dict: dict[
+            tuple[str, str, str],
+            tuple[pd.DateOffset | None, pd.DateOffset],
+        ],
+    ) -> tuple[pd.Series, np.ndarray, pd.Series, np.ndarray]:
+
+        train_y, train_mask = self._sample_target_set(
+            query=query,
+            pkey=entity_df[self.primary_key_dict[query.entity_table]],
+            index=train_index,
+            anchor_time=train_time,
+            num_examples=num_train_examples,
+            columns_dict=columns_dict,
+            time_offset_dict=time_offset_dict,
+        )
+
+        test_y, test_mask = self._sample_target_set(
+            query=query,
+            pkey=entity_df[self.primary_key_dict[query.entity_table]],
+            index=test_index,
+            anchor_time=test_time,
+            num_examples=num_test_examples,
+            columns_dict=columns_dict,
+            time_offset_dict=time_offset_dict,
+        )
+
+        return train_y, train_mask, test_y, test_mask
+
+    # Helper Methods ##########################################################
+
+    def _sample_target_set(
+        self,
+        query: ValidatedPredictiveQuery,
+        pkey: pd.Series,
+        index: np.ndarray,
+        anchor_time: pd.Series,
+        num_examples: int,
+        columns_dict: dict[str, set[str]],
+        time_offset_dict: dict[
+            tuple[str, str, str],
+            tuple[pd.DateOffset | None, pd.DateOffset],
+        ],
+        batch_size: int = 10_000,
+    ) -> tuple[pd.Series, np.ndarray]:
+
+        num_hops = 1 if len(time_offset_dict) > 0 else 0
+        num_neighbors_dict: dict[str, list[int]] = {}
+        unix_time_offset_dict: dict[str, list[list[int | None]]] = {}
+        for edge_type, (start, end) in time_offset_dict.items():
+            unix_time_offset_dict['__'.join(edge_type)] = [[
+                date_offset_to_seconds(start) if start is not None else None,
+                date_offset_to_seconds(end),
+            ]]
+        for edge_type in set(self.edge_types) - set(time_offset_dict.keys()):
+            num_neighbors_dict['__'.join(edge_type)] = [0] * num_hops
+
+        if anchor_time.dtype != 'datetime64[ns]':
+            anchor_time = anchor_time.astype('datetime64')
+
+        count = 0
+        ys: list[pd.Series] = []
+        mask = np.full(len(index), False, dtype=bool)
+        for start in range(0, len(index), batch_size):
+            subset = pkey.iloc[index[start:start + batch_size]]
+            time = anchor_time.iloc[start:start + batch_size]
+
+            _, _, node_dict, batch_dict, _, _ = self._graph_sampler.sample(
+                num_neighbors_dict,
+                unix_time_offset_dict,
+                query.entity_table,
+                self._graph_store.get_node_id(query.entity_table, subset),
+                time.astype(int).to_numpy() // 1000**3,  # to seconds
+            )
+
+            feat_dict: dict[str, pd.DataFrame] = {}
+            time_dict: dict[str, pd.Series] = {}
+            for table_name, columns in columns_dict.items():
+                df = self._graph_store.df_dict[table_name]
+                df = df.iloc[node_dict[table_name]].reset_index(drop=True)
+                df = df[list(columns)]
+                feat_dict[table_name] = df
+
+                time_column = self.time_column_dict.get(table_name)
+                if time_column in columns:
+                    time_dict[table_name] = df[time_column]
+
+            y, _mask = PQueryPandasExecutor().execute(
+                query=query,
+                feat_dict=feat_dict,
+                time_dict=time_dict,
+                batch_dict=batch_dict,
+                anchor_time=time,
+                num_forecasts=query.num_forecasts,
+            )
+            ys.append(y)
+            mask[start:start + batch_size] = _mask
+
+            count += len(y)
+            if count >= num_examples:
+                break
+
+        if len(ys) == 0:
+            y = pd.Series([], dtype=float)
+        elif len(ys) == 1:
+            y = ys[0]
+        else:
+            y = pd.concat(ys, axis=0, ignore_index=True)
+
+        return y, mask
+
+
+# Helper Functions ############################################################
+
+
+def date_offset_to_seconds(offset: pd.DateOffset) -> int:
+    r"""Convert a :class:`pandas.DateOffset` into a number of seconds.
+
+    .. note::
+        We are conservative and take months and years as their maximum value.
+        Additional values are then dropped in label computation where we know
+        the actual dates.
+    """
+    MAX_DAYS_IN_MONTH = 31
+    MAX_DAYS_IN_YEAR = 366
+
+    SECONDS_IN_MINUTE = 60
+    SECONDS_IN_HOUR = 60 * SECONDS_IN_MINUTE
+    SECONDS_IN_DAY = 24 * SECONDS_IN_HOUR
+
+    total_sec = 0
+    multiplier = getattr(offset, 'n', 1)  # The multiplier (if present).
+
+    for attr, value in offset.__dict__.items():
+        if value is None or value == 0:
+            continue
+        scaled_value = value * multiplier
+        if attr == 'years':
+            total_sec += scaled_value * MAX_DAYS_IN_YEAR * SECONDS_IN_DAY
+        elif attr == 'months':
+            total_sec += scaled_value * MAX_DAYS_IN_MONTH * SECONDS_IN_DAY
+        elif attr == 'days':
+            total_sec += scaled_value * SECONDS_IN_DAY
+        elif attr == 'hours':
+            total_sec += scaled_value * SECONDS_IN_HOUR
+        elif attr == 'minutes':
+            total_sec += scaled_value * SECONDS_IN_MINUTE
+        elif attr == 'seconds':
+            total_sec += scaled_value
+
+    return total_sec