kumoai 2.13.0.dev202511191731__cp310-cp310-macosx_11_0_arm64.whl → 2.14.0.dev202512271732__cp310-cp310-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.dev202511191731'
+__version__ = '2.14.0.dev202512271732'

kumoai/client/client.py

@@ -13,6 +13,7 @@ if TYPE_CHECKING:
         ArtifactExportJobAPI,
         BaselineJobAPI,
         BatchPredictionJobAPI,
+        DistillationJobAPI,
         GeneratePredictionTableJobAPI,
         GenerateTrainTableJobAPI,
         LLMJobAPI,
@@ -132,6 +133,11 @@ class KumoClient:
         from kumoai.client.jobs import TrainingJobAPI
         return TrainingJobAPI(self)
 
+    @property
+    def distillation_job_api(self) -> 'DistillationJobAPI':
+        from kumoai.client.jobs import DistillationJobAPI
+        return DistillationJobAPI(self)
+
     @property
     def batch_prediction_job_api(self) -> 'BatchPredictionJobAPI':
         from kumoai.client.jobs import BatchPredictionJobAPI

kumoai/client/jobs.py

@@ -22,6 +22,8 @@ from kumoapi.jobs import (
     BatchPredictionRequest,
     CancelBatchPredictionJobResponse,
     CancelTrainingJobResponse,
+    DistillationJobRequest,
+    DistillationJobResource,
     ErrorDetails,
     GeneratePredictionTableJobResource,
     GeneratePredictionTableRequest,
@@ -171,6 +173,28 @@ class TrainingJobAPI(CommonJobAPI[TrainingJobRequest, TrainingJobResource]):
         return resource.config
 
 
+class DistillationJobAPI(CommonJobAPI[DistillationJobRequest,
+                                      DistillationJobResource]):
+    r"""Typed API definition for the distillation job resource."""
+    def __init__(self, client: KumoClient) -> None:
+        super().__init__(client, '/training_jobs/distilled_training_job',
+                         DistillationJobResource)
+
+    def get_config(self, job_id: str) -> DistillationJobRequest:
+        raise NotImplementedError(
+            "Getting the configuration for a distillation job is "
+            "not implemented yet.")
+
+    def get_progress(self, id: str) -> AutoTrainerProgress:
+        raise NotImplementedError(
+            "Getting the progress for a distillation job is not "
+            "implemented yet.")
+
+    def cancel(self, id: str) -> CancelTrainingJobResponse:
+        raise NotImplementedError(
+            "Cancelling a distillation job is not implemented yet.")
+
+
 class BatchPredictionJobAPI(CommonJobAPI[BatchPredictionRequest,
                                          BatchPredictionJobResource]):
     r"""Typed API definition for the prediction job resource."""

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/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 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 kumoai.spcs import _get_active_session
+
 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')
 
@@ -77,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
@@ -101,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.
@@ -149,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:
@@ -164,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")
 
@@ -197,12 +194,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/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/__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,14 +1,12 @@
-import warnings
-from typing import Dict, List, Optional, Tuple, Union
+from typing import TYPE_CHECKING
 
 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.utils import InteractiveProgressLogger, ProgressLogger
+from kumoai.experimental.rfm.backend.local import LocalTable
+from kumoai.experimental.rfm.base import Table
+from kumoai.utils import ProgressLogger
 
 try:
     import torch
@@ -16,43 +14,40 @@ 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,
-        verbose: Union[bool, ProgressLogger] = True,
+        graph: 'Graph',
+        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, preprocess)
-            self.stype_dict = self.get_stype_dict(graph)
+            self.df_dict, self.mask_dict = self.sanitize(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")
 
@@ -62,14 +57,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.
 
@@ -105,9 +92,8 @@ class LocalGraphStore:
 
     def sanitize(
         self,
-        graph: LocalGraph,
-        preprocess: bool = False,
-    ) -> Tuple[Dict[str, pd.DataFrame], Dict[str, np.ndarray]]:
+        graph: 'Graph',
+    ) -> tuple[dict[str, pd.DataFrame], dict[str, np.ndarray]]:
         r"""Sanitizes raw data according to table schema definition:
 
         In particular, it:
@@ -115,42 +101,25 @@ 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_dict[table_name] = Table._sanitize(
+                df=table._data.copy(deep=False).reset_index(drop=True),
+                dtype_dict={
+                    column.name: column.dtype
+                    for column in table.columns
+                },
+                stype_dict={
+                    column.name: column.stype
+                    for column in table.columns
+                },
+            )
 
-        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:
-                    ser = df_dict[table.name][col.name]
-                    if not pd.api.types.is_datetime64_any_dtype(ser):
-                        with warnings.catch_warnings():
-                            warnings.filterwarnings(
-                                'ignore',
-                                message='Could not infer format',
-                            )
-                            ser = pd.to_datetime(ser, errors='coerce')
-                        df_dict[table.name][col.name] = ser
-                    if isinstance(ser.dtype, pd.DatetimeTZDtype):
-                        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
+            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()
@@ -165,34 +134,16 @@ class LocalGraphStore:
 
         return df_dict, mask_dict
 
-    def get_stype_dict(self, graph: LocalGraph) -> 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: LocalGraph,
-    ) -> Tuple[
-            Dict[str, str],
-            Dict[str, pd.DataFrame],
-    ]:
-        pkey_name_dict: Dict[str, str] = {}
-        pkey_map_dict: Dict[str, pd.DataFrame] = {}
+        graph: 'Graph',
+    ) -> 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))),
@@ -214,61 +165,48 @@ 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: LocalGraph,
-    ) -> Tuple[
-            Dict[str, str],
-            Dict[str, str],
-            Dict[str, np.ndarray],
-            pd.Timestamp,
-            pd.Timestamp,
+        graph: 'Graph',
+    ) -> 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
 
             time = self.df_dict[table.name][table._time_column]
-            time_dict[table.name] = time.astype('datetime64[ns]').astype(
-                int).to_numpy() // 1000**3
-            time_column_dict[table.name] = table._time_column
+            time_dict[table.name] = time.astype(int).to_numpy() // 1000**3
 
             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: LocalGraph,
-    ) -> Tuple[
-            Dict[Tuple[str, str, str], np.ndarray],
-            Dict[Tuple[str, str, str], np.ndarray],
+        graph: 'Graph',
+    ) -> 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]
@@ -277,8 +215,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]
@@ -340,7 +278,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: