kumoai 2.13.0.dev202512011731__cp312-cp312-macosx_11_0_arm64.whl → 2.14.0.dev202512181731__cp312-cp312-macosx_11_0_arm64.whl

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

@@ -0,0 +1,315 @@
+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 Sampler, SamplerOutput
+from kumoai.experimental.rfm.pquery import PQueryPandasExecutor
+from kumoai.utils import ProgressLogger
+
+if TYPE_CHECKING:
+    from kumoai.experimental.rfm import Graph
+
+
+class LocalSampler(Sampler):
+    def __init__(
+        self,
+        graph: 'Graph',
+        verbose: bool | ProgressLogger = True,
+    ) -> None:
+        super().__init__(graph=graph, verbose=verbose)
+
+        import kumoai.kumolib as kumolib
+
+        self._graph_store = LocalGraphStore(graph, verbose)
+        self._graph_sampler = kumolib.NeighborSampler(
+            list(self.table_stype_dict.keys()),
+            self.edge_types,
+            {
+                '__'.join(edge_type): colptr
+                for edge_type, colptr in self._graph_store.colptr_dict.items()
+            },
+            {
+                '__'.join(edge_type): row
+                for edge_type, row in self._graph_store.row_dict.items()
+            },
+            self._graph_store.time_dict,
+        )
+
+    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 | Literal['entity'],
+        columns_dict: dict[str, set[str]],
+        num_neighbors: list[int],
+    ) -> SamplerOutput:
+
+        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,
+            col_dict,
+            node_dict,
+            batch_dict,
+            num_sampled_nodes_dict,
+            num_sampled_edges_dict,
+        ) = self._graph_sampler.sample(
+            {
+                '__'.join(edge_type): num_neighbors
+                for edge_type in self.edge_types
+            },
+            {},
+            entity_table_name,
+            index,
+            time,
+        )
+
+        df_dict: dict[str, pd.DataFrame] = {}
+        inverse_dict: dict[str, np.ndarray] = {}
+        for table_name, node in node_dict.items():
+            df = self._graph_store.df_dict[table_name]
+            columns = columns_dict[table_name]
+            if self.end_time_column_dict.get(table_name, None) in columns:
+                df = df.iloc[node]
+            elif len(columns) == 0:
+                df = df.iloc[node]
+            else:
+                # Only store unique rows in `df` above a certain threshold:
+                unique_node, inverse = np.unique(node, return_inverse=True)
+                if len(node) > 1.05 * len(unique_node):
+                    df = df.iloc[unique_node]
+                    inverse_dict[table_name] = inverse
+                else:
+                    df = df.iloc[node]
+            df = df.reset_index(drop=True)
+            df = df[list(columns)]
+            df_dict[table_name] = df
+
+        num_sampled_nodes_dict = {
+            table_name: num_sampled_nodes.tolist()
+            for table_name, num_sampled_nodes in
+            num_sampled_nodes_dict.items()
+        }
+
+        row_dict = {
+            edge_type: row_dict['__'.join(edge_type)]
+            for edge_type in self.edge_types
+        }
+        col_dict = {
+            edge_type: col_dict['__'.join(edge_type)]
+            for edge_type in self.edge_types
+        }
+        num_sampled_edges_dict = {
+            edge_type: num_sampled_edges_dict['__'.join(edge_type)].tolist()
+            for edge_type in self.edge_types
+        }
+
+        return SamplerOutput(
+            anchor_time=time * 1000**3,  # to nanoseconds
+            df_dict=df_dict,
+            inverse_dict=inverse_dict,
+            batch_dict=batch_dict,
+            num_sampled_nodes_dict=num_sampled_nodes_dict,
+            row_dict=row_dict,
+            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

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

@@ -1,11 +1,11 @@
-from typing import List, Optional
+import warnings
+from typing import cast
 
 import pandas as pd
-from kumoapi.typing import Dtype, Stype
-from typing_extensions import Self
+from kumoapi.model_plan import MissingType
 
-from kumoai.experimental.rfm import utils
-from kumoai.experimental.rfm.base import Column, Table
+from kumoai.experimental.rfm.base import DataBackend, SourceColumn, Table
+from kumoai.experimental.rfm.infer import infer_dtype
 
 
 class LocalTable(Table):
@@ -53,13 +53,13 @@ class LocalTable(Table):
         self,
         df: pd.DataFrame,
         name: str,
-        primary_key: Optional[str] = None,
-        time_column: Optional[str] = None,
-        end_time_column: Optional[str] = None,
+        primary_key: MissingType | str | None = MissingType.VALUE,
+        time_column: str | None = None,
+        end_time_column: str | None = None,
     ) -> None:
 
         if df.empty:
-            raise ValueError("Data frame must have at least one row")
+            raise ValueError("Data frame is empty")
         if isinstance(df.columns, pd.MultiIndex):
             raise ValueError("Data frame must not have a multi-index")
         if not df.columns.is_unique:
@@ -77,75 +77,36 @@ class LocalTable(Table):
             end_time_column=end_time_column,
         )
 
-    def infer_metadata(self, verbose: bool = True) -> Self:
-        r"""Infers metadata, *i.e.*, primary keys and time columns, in the
-        table.
-
-        Args:
-            verbose: Whether to print verbose output.
-        """
-        logs = []
-
-        # Try to detect primary key if not set:
-        if not self.has_primary_key():
-
-            def is_candidate(column: Column) -> bool:
-                if column.stype == Stype.ID:
-                    return True
-                if all(column.stype != Stype.ID for column in self.columns):
-                    if self.name == column.name:
-                        return True
-                    if (self.name.endswith('s')
-                            and self.name[:-1] == column.name):
-                        return True
-                return False
-
-            candidates = [
-                column.name for column in self.columns if is_candidate(column)
-            ]
-
-            if primary_key := utils.detect_primary_key(
-                    table_name=self.name,
-                    df=self._data,
-                    candidates=candidates,
-            ):
-                self.primary_key = primary_key
-                logs.append(f"primary key '{primary_key}'")
-
-        # Try to detect time column if not set:
-        if not self.has_time_column():
-            candidates = [
-                column.name for column in self.columns
-                if column.stype == Stype.timestamp
-                and column.name != self._end_time_column
-            ]
-            if time_column := utils.detect_time_column(self._data, candidates):
-                self.time_column = time_column
-                logs.append(f"time column '{time_column}'")
-
-        if verbose and len(logs) > 0:
-            print(f"Detected {' and '.join(logs)} in table '{self.name}'")
-
-        return self
-
-    def _has_source_column(self, name: str) -> bool:
-        return name in self._data.columns
-
-    def _get_source_dtype(self, name: str) -> Dtype:
-        return utils.to_dtype(self._data[name])
-
-    def _get_source_stype(self, name: str, dtype: Dtype) -> Stype:
-        return utils.infer_stype(self._data[name], name, dtype)
-
-    def _infer_primary_key(self, candidates: List[str]) -> Optional[str]:
-        return utils.detect_primary_key(
-            table_name=self.name,
-            df=self._data,
-            candidates=candidates,
-        )
-
-    def _infer_time_column(self, candidates: List[str]) -> Optional[str]:
-        return utils.detect_time_column(df=self._data, candidates=candidates)
-
-    def _num_rows(self) -> Optional[int]:
+    @property
+    def backend(self) -> DataBackend:
+        return cast(DataBackend, DataBackend.LOCAL)
+
+    def _get_source_columns(self) -> list[SourceColumn]:
+        source_columns: list[SourceColumn] = []
+        for column in self._data.columns:
+            ser = self._data[column]
+            try:
+                dtype = infer_dtype(ser)
+            except Exception:
+                warnings.warn(f"Data type inference for column '{column}' in "
+                              f"table '{self.name}' failed. Consider changing "
+                              f"the data type of the column to use it within "
+                              f"this table.")
+                continue
+
+            source_column = SourceColumn(
+                name=column,
+                dtype=dtype,
+                is_primary_key=False,
+                is_unique_key=False,
+                is_nullable=True,
+            )
+            source_columns.append(source_column)
+
+        return source_columns
+
+    def _get_sample_df(self) -> pd.DataFrame:
+        return self._data
+
+    def _get_num_rows(self) -> int | None:
         return len(self._data)

kumoai/experimental/rfm/backend/snow/__init__.py

@@ -0,0 +1,37 @@
+from typing import Any, TypeAlias
+
+try:
+    import snowflake.connector
+except ImportError:
+    raise ImportError("No module named 'snowflake'. Please install Kumo SDK "
+                      "with the 'snowflake' extension via "
+                      "`pip install kumoai[snowflake]`.")
+
+Connection: TypeAlias = snowflake.connector.SnowflakeConnection
+
+
+def connect(**kwargs: Any) -> Connection:
+    r"""Opens a connection to a :class:`snowflake` database.
+
+    If available, will return a connection to the active session.
+
+    kwargs: Connection arguments, following the :class:`snowflake` protocol.
+    """
+    try:
+        from snowflake.snowpark.context import get_active_session
+        return get_active_session().connection
+    except Exception:
+        pass
+
+    return snowflake.connector.connect(**kwargs)
+
+
+from .table import SnowTable  # noqa: E402
+from .sampler import SnowSampler  # noqa: E402
+
+__all__ = [
+    'connect',
+    'Connection',
+    'SnowTable',
+    'SnowSampler',
+]