kumoai 2.13.0.dev202511261731__cp313-cp313-macosx_11_0_arm64.whl → 2.13.0.dev202512061731__cp313-cp313-macosx_11_0_arm64.whl

kumoai/__init__.py

@@ -280,7 +280,19 @@ __all__ = [
 ]
 
 
+def in_snowflake_notebook() -> bool:
+    try:
+        from snowflake.snowpark.context import get_active_session
+        import streamlit  # noqa: F401
+        get_active_session()
+        return True
+    except Exception:
+        return False
+
+
 def in_notebook() -> bool:
+    if in_snowflake_notebook():
+        return True
     try:
         from IPython import get_ipython
         shell = get_ipython()

kumoai/_version.py

@@ -1 +1 @@
-__version__ = '2.13.0.dev202511261731'
+__version__ = '2.13.0.dev202512061731'

kumoai/connector/utils.py

@@ -381,8 +381,29 @@ def _handle_duplicate_names(names: List[str]) -> List[str]:
 
 
 def _sanitize_columns(names: List[str]) -> Tuple[List[str], bool]:
-    _SAN_RE = re.compile(r"[^0-9A-Za-z]+")
+    """Normalize column names in a CSV or Parquet file.
+
+    Rules:
+      - Replace any non-alphanumeric character with "_"
+      - Strip leading/trailing underscores
+      - Ensure uniqueness by appending suffixes: _1, _2, ...
+      - Auto-name empty columns as auto_named_<n>
+
+    Returns:
+        (new_column_names, changed)
+    """
+    _SAN_RE = re.compile(r"[^0-9A-Za-z,\t]")
+    # 1) Replace non-alphanumeric sequences with underscore
     new = [_SAN_RE.sub("_", n).strip("_") for n in names]
+
+    # 2) Auto-name any empty column names to match UI behavior
+    unnamed_counter = 0
+    for i, n in enumerate(new):
+        if not n:
+            new[i] = f"auto_named_{unnamed_counter}"
+            unnamed_counter += 1
+
+    # 3) Ensure uniqueness (append suffixes where needed)
     new = _handle_duplicate_names(new)
     return new, new != names
 
@@ -1168,7 +1189,7 @@ def _detect_and_validate_csv(head_bytes: bytes) -> str:
     - Re-serializes those rows and validates with pandas (small nrows) to catch
       malformed inputs.
     - Raises ValueError on empty input or if parsing fails with the chosen
-    delimiter.
+      delimiter.
     """
     if not head_bytes:
         raise ValueError("Could not auto-detect a delimiter: file is empty.")

kumoai/experimental/rfm/__init__.py

@@ -1,54 +1,26 @@
-try:
-    import kumoai.kumolib  # noqa: F401
-except Exception as e:
-    import platform
-
-    _msg = f"""RFM is not supported in your environment.
-
-💻 Your Environment:
-Python version: {platform.python_version()}
-Operating system: {platform.system()}
-CPU architecture: {platform.machine()}
-glibc version: {platform.libc_ver()[1]}
-
-✅ Supported Environments:
-* Python versions: 3.10, 3.11, 3.12, 3.13
-* Operating systems and CPU architectures:
-  * Linux (x86_64)
-  * macOS (arm64)
-  * Windows (x86_64)
-* glibc versions: >=2.28
-
-❌ Unsupported Environments:
-* Python versions: 3.8, 3.9, 3.14
-* Operating systems and CPU architectures:
-  * Linux (arm64)
-  * macOS (x86_64)
-  * Windows (arm64)
-* glibc versions: <2.28
-
-Please create a feature request at 'https://github.com/kumo-ai/kumo-rfm'."""
-
-    raise RuntimeError(_msg) from e
-
-from dataclasses import dataclass
-from enum import Enum
 import ipaddress
 import logging
+import os
 import re
 import socket
 import threading
-from typing import Optional, Dict, Tuple
-import os
+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 .sagemaker import (KumoClient_SageMakerAdapter,
-                        KumoClient_SageMakerProxy_Local)
-from .local_table import LocalTable
-from .local_graph import LocalGraph
-from .rfm import ExplainConfig, Explanation, KumoRFM
+
 from .authenticate import authenticate
+from .sagemaker import (
+    KumoClient_SageMakerAdapter,
+    KumoClient_SageMakerProxy_Local,
+)
+from .base import Table
+from .backend.local import LocalTable
+from .graph import Graph
+from .rfm import ExplainConfig, Explanation, KumoRFM
 
 logger = logging.getLogger('kumoai_rfm')
 
@@ -197,12 +169,15 @@ def init(
                     url)
 
 
+LocalGraph = Graph  # NOTE Backward compatibility - do not use anymore.
+
 __all__ = [
+    'authenticate',
+    'init',
+    'Table',
     'LocalTable',
-    'LocalGraph',
+    'Graph',
     'KumoRFM',
     'ExplainConfig',
     'Explanation',
-    'authenticate',
-    'init',
 ]

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

@@ -0,0 +1,42 @@
+try:
+    import kumoai.kumolib  # noqa: F401
+except Exception as e:
+    import platform
+
+    _msg = f"""RFM is not supported in your environment.
+
+💻 Your Environment:
+Python version: {platform.python_version()}
+Operating system: {platform.system()}
+CPU architecture: {platform.machine()}
+glibc version: {platform.libc_ver()[1]}
+
+✅ Supported Environments:
+* Python versions: 3.10, 3.11, 3.12, 3.13
+* Operating systems and CPU architectures:
+  * Linux (x86_64)
+  * macOS (arm64)
+  * Windows (x86_64)
+* glibc versions: >=2.28
+
+❌ Unsupported Environments:
+* Python versions: 3.8, 3.9, 3.14
+* Operating systems and CPU architectures:
+  * Linux (arm64)
+  * macOS (x86_64)
+  * Windows (arm64)
+* glibc versions: <2.28
+
+Please create a feature request at 'https://github.com/kumo-ai/kumo-rfm'."""
+
+    raise RuntimeError(_msg) from e
+
+from .table import LocalTable
+from .graph_store import LocalGraphStore
+from .sampler import LocalSampler
+
+__all__ = [
+    'LocalTable',
+    'LocalGraphStore',
+    'LocalSampler',
+]

kumoai/experimental/rfm/{local_graph_store.py → backend/local/graph_store.py}

@@ -1,13 +1,12 @@
 import warnings
-from typing import Dict, List, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, Union
 
 import numpy as np
 import pandas as pd
 from kumoapi.rfm.context import Subgraph
 from kumoapi.typing import Stype
 
-from kumoai.experimental.rfm import LocalGraph
-from kumoai.experimental.rfm.utils import normalize_text
+from kumoai.experimental.rfm.backend.local import LocalTable
 from kumoai.utils import InteractiveProgressLogger, ProgressLogger
 
 try:
@@ -16,12 +15,14 @@ try:
 except ImportError:
     WITH_TORCH = False
 
+if TYPE_CHECKING:
+    from kumoai.experimental.rfm import Graph
+
 
 class LocalGraphStore:
     def __init__(
         self,
-        graph: LocalGraph,
-        preprocess: bool = False,
+        graph: 'Graph',
         verbose: Union[bool, ProgressLogger] = True,
     ) -> None:
 
@@ -32,7 +33,7 @@ class LocalGraphStore:
             )
 
         with verbose as logger:
-            self.df_dict, self.mask_dict = self.sanitize(graph, preprocess)
+            self.df_dict, self.mask_dict = self.sanitize(graph)
             self.stype_dict = self.get_stype_dict(graph)
             logger.log("Sanitized input data")
 
@@ -105,8 +106,7 @@ class LocalGraphStore:
 
     def sanitize(
         self,
-        graph: LocalGraph,
-        preprocess: bool = False,
+        graph: 'Graph',
     ) -> Tuple[Dict[str, pd.DataFrame], Dict[str, np.ndarray]]:
         r"""Sanitizes raw data according to table schema definition:
 
@@ -115,17 +115,12 @@ class LocalGraphStore:
         * drops timezone information from timestamps
         * drops duplicate primary keys
         * removes rows with missing primary keys or time values
-
-        If ``preprocess`` is set to ``True``, it will additionally pre-process
-        data for faster model processing. In particular, it:
-        * tokenizes any text column that is not a foreign key
         """
-        df_dict: Dict[str, pd.DataFrame] = {
-            table_name: table._data.copy(deep=False).reset_index(drop=True)
-            for table_name, table in graph.tables.items()
-        }
-
-        foreign_keys = {(edge.src_table, edge.fkey) for edge in graph.edges}
+        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] = {}
         for table in graph.tables.values():
@@ -144,12 +139,6 @@ class LocalGraphStore:
                         ser = ser.dt.tz_localize(None)
                         df_dict[table.name][col.name] = ser
 
-                # Normalize text in advance (but exclude foreign keys):
-                if (preprocess and col.stype == Stype.text
-                        and (table.name, col.name) not in foreign_keys):
-                    ser = df_dict[table.name][col.name]
-                    df_dict[table.name][col.name] = normalize_text(ser)
-
             mask: Optional[np.ndarray] = None
             if table._time_column is not None:
                 ser = df_dict[table.name][table._time_column]
@@ -165,7 +154,7 @@ class LocalGraphStore:
 
         return df_dict, mask_dict
 
-    def get_stype_dict(self, graph: LocalGraph) -> Dict[str, Dict[str, Stype]]:
+    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():
@@ -180,7 +169,7 @@ class LocalGraphStore:
 
     def get_pkey_data(
         self,
-        graph: LocalGraph,
+        graph: 'Graph',
     ) -> Tuple[
             Dict[str, str],
             Dict[str, pd.DataFrame],
@@ -218,7 +207,7 @@ class LocalGraphStore:
 
     def get_time_data(
         self,
-        graph: LocalGraph,
+        graph: 'Graph',
     ) -> Tuple[
             Dict[str, str],
             Dict[str, str],
@@ -239,8 +228,9 @@ class LocalGraphStore:
                 continue
 
             time = self.df_dict[table.name][table._time_column]
-            time_dict[table.name] = time.astype('datetime64[ns]').astype(
-                int).to_numpy() // 1000**3
+            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():
@@ -259,7 +249,7 @@ class LocalGraphStore:
 
     def get_csc(
         self,
-        graph: LocalGraph,
+        graph: 'Graph',
     ) -> Tuple[
             Dict[Tuple[str, str, str], np.ndarray],
             Dict[Tuple[str, str, str], np.ndarray],

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

@@ -0,0 +1,131 @@
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+
+from kumoai.experimental.rfm.backend.local import LocalGraphStore
+from kumoai.experimental.rfm.base import EdgeSpec, Sampler, SamplerOutput
+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)
+
+        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 sample(
+        self,
+        entity_table_name: str,
+        entity_pkey: pd.Series,
+        anchor_time: pd.Series,
+        column_spec_dict: dict[str, list[str]],
+        edge_spec_dict: dict[tuple[str, str, str], list[EdgeSpec]],
+        drop_duplicates: bool = False,
+        return_edges: bool = False,
+    ) -> SamplerOutput:
+
+        if anchor_time.dtype != 'datetime64[ns]':
+            anchor_time = anchor_time.astype('datetime64[ns]')
+
+        num_hops = max([len(specs) for specs in edge_spec_dict.values()] + [0])
+        num_neighbors_dict: dict[str, list[int]] = {}
+
+        for edge_type, specs in edge_spec_dict.items():
+            edge_type_str = '__'.join(edge_type)
+            num_neighbors_dict[edge_type_str] = [0] * num_hops
+            for hop, spec in enumerate(specs):
+                # TODO Add support for time-based sampling.
+                assert spec.num_neighbors is not None
+                num_neighbors_dict[edge_type_str][hop] = spec.num_neighbors
+
+        (
+            row_dict,
+            col_dict,
+            node_dict,
+            batch_dict,
+            num_sampled_nodes_dict,
+            num_sampled_edges_dict,
+        ) = self._graph_sampler.sample(
+            num_neighbors_dict,
+            {},
+            entity_table_name,
+            self._graph_store.get_node_id(entity_table_name, entity_pkey),
+            anchor_time.astype(int).to_numpy() // 1000**3,  # to seconds
+        )
+
+        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 = column_spec_dict[table_name]
+            if self.end_time_column_dict.get(table_name, None) in columns:
+                df = df.iloc[node]
+            elif len(columns) > 0 and drop_duplicates:
+                # 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]
+            else:
+                df = df.iloc[node]
+            df = df.reset_index(drop=True)
+            df = df[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()
+        }
+
+        if return_edges:
+            row_dict = {
+                edge_type: row_dict['__'.join(edge_type)]
+                for edge_type in edge_spec_dict.keys()
+            }
+            col_dict = {
+                edge_type: col_dict['__'.join(edge_type)]
+                for edge_type in edge_spec_dict.keys()
+            }
+            num_sampled_edges_dict = {
+                edge_type:
+                num_sampled_edges_dict['__'.join(edge_type)].tolist()
+                for edge_type in edge_spec_dict.keys()
+            }
+        else:
+            row_dict = col_dict = num_sampled_edges_dict = None
+
+        return SamplerOutput(
+            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,
+        )

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

@@ -0,0 +1,109 @@
+import warnings
+from typing import List, Optional
+
+import pandas as pd
+
+from kumoai.experimental.rfm.base import SourceColumn, SourceForeignKey, Table
+from kumoai.experimental.rfm.infer import infer_dtype
+
+
+class LocalTable(Table):
+    r"""A table backed by a :class:`pandas.DataFrame`.
+
+    A :class:`LocalTable` fully specifies the relevant metadata, *i.e.*
+    selected columns, column semantic types, primary keys and time columns.
+    :class:`LocalTable` is used to create a :class:`Graph`.
+
+    .. code-block:: python
+
+        import pandas as pd
+        import kumoai.experimental.rfm as rfm
+
+        # Load data from a CSV file:
+        df = pd.read_csv("data.csv")
+
+        # Create a table from a `pandas.DataFrame` and infer its metadata ...
+        table = rfm.LocalTable(df, name="my_table").infer_metadata()
+
+        # ... or create a table explicitly:
+        table = rfm.LocalTable(
+            df=df,
+            name="my_table",
+            primary_key="id",
+            time_column="time",
+            end_time_column=None,
+        )
+
+        # Verify metadata:
+        table.print_metadata()
+
+        # Change the semantic type of a column:
+        table[column].stype = "text"
+
+    Args:
+        df: The data frame to create this table from.
+        name: The name of this table.
+        primary_key: The name of the primary key of this table, if it exists.
+        time_column: The name of the time column of this table, if it exists.
+        end_time_column: The name of the end time column of this table, if it
+            exists.
+    """
+    def __init__(
+        self,
+        df: pd.DataFrame,
+        name: str,
+        primary_key: Optional[str] = None,
+        time_column: Optional[str] = None,
+        end_time_column: Optional[str] = None,
+    ) -> None:
+
+        if df.empty:
+            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:
+            raise ValueError("Data frame must have unique column names")
+        if any(col == '' for col in df.columns):
+            raise ValueError("Data frame must have non-empty column names")
+
+        self._data = df.copy(deep=False)
+
+        super().__init__(
+            name=name,
+            columns=list(df.columns),
+            primary_key=primary_key,
+            time_column=time_column,
+            end_time_column=end_time_column,
+        )
+
+    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,
+            )
+            source_columns.append(source_column)
+
+        return source_columns
+
+    def _get_source_foreign_keys(self) -> List[SourceForeignKey]:
+        return []
+
+    def _get_sample_df(self) -> pd.DataFrame:
+        return self._data
+
+    def _get_num_rows(self) -> Optional[int]:
+        return len(self._data)

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

@@ -0,0 +1,35 @@
+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
+
+__all__ = [
+    'connect',
+    'Connection',
+    'SnowTable',
+]