kumoai 2.14.0.dev202512191731__cp311-cp311-macosx_11_0_arm64.whl → 2.15.0.dev202601141731__cp311-cp311-macosx_11_0_arm64.whl

kumoai/__init__.py

@@ -1,3 +1,4 @@
+import warnings
 import os
 import sys
 import threading
@@ -68,9 +69,8 @@ class GlobalState(metaclass=Singleton):
         if self._url is None or (self._api_key is None
                                  and self._spcs_token is None
                                  and self._snowpark_session is None):
-            raise ValueError(
-                "Client creation or authentication failed; please re-create "
-                "your client before proceeding.")
+            raise ValueError("Client creation or authentication failed. "
+                             "Please re-create your client before proceeding.")
 
         if hasattr(self.thread_local, '_client'):
             # Set the spcs token in the client to ensure it has the latest.
@@ -123,10 +123,9 @@ def init(
     """  # noqa
     # Avoid mutations to the global state after it is set:
     if global_state.initialized:
-        print(
-            "Client has already been created. To re-initialize Kumo, please "
-            "start a new interpreter. No changes will be made to the current "
-            "session.")
+        warnings.warn("Kumo SDK already initialized. To re-initialize the "
+                      "SDK, please start a new interpreter. No changes will "
+                      "be made to the current session.")
         return
 
     set_log_level(os.getenv(_ENV_KUMO_LOG, log_level))
@@ -138,15 +137,15 @@ def init(
     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.")
+                "Kumo SDK initialization failed. Both 'snowflake_application' "
+                "and 'url' are specified. If running from a Snowflake "
+                "notebook, specify only 'snowflake_application'.")
         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.")
+                "Kumo SDK initialization failed. 'snowflake_application' is "
+                "specified without an active Snowpark session. If running "
+                "outside a Snowflake notebook, specify a URL and credentials.")
         description = snowpark_session.sql(
             f"DESCRIBE SERVICE {snowflake_application}."
             "USER_SCHEMA.KUMO_SERVICE").collect()[0]
@@ -155,14 +154,14 @@ def init(
     if api_key is None and not snowflake_application:
         if snowflake_credentials is None:
             raise ValueError(
-                "Client creation failed: Neither API key nor snowflake "
-                "credentials provided. Please either set the 'KUMO_API_KEY' "
-                "or explicitly call `kumoai.init(...)`.")
+                "Kumo SDK initialization failed. Neither an API key nor "
+                "Snowflake credentials provided. Please either set the "
+                "'KUMO_API_KEY' or explicitly call `kumoai.init(...)`.")
         if (set(snowflake_credentials.keys())
                 != {'user', 'password', 'account'}):
             raise ValueError(
-                f"Provided credentials should be a dictionary with keys "
-                f"'user', 'password', and 'account'. Only "
+                f"Provided Snowflake credentials should be a dictionary with "
+                f"keys 'user', 'password', and 'account'. Only "
                 f"{set(snowflake_credentials.keys())} were provided.")
 
     # Get or infer URL:
@@ -173,10 +172,10 @@ def init(
     except KeyError:
         pass
     if url is None:
-        raise ValueError(
-            "Client creation failed: endpoint URL not provided. Please "
-            "either set the 'KUMO_API_ENDPOINT' environment variable or "
-            "explicitly call `kumoai.init(...)`.")
+        raise ValueError("Kumo SDK initialization failed since no endpoint "
+                         "URL was provided. Please either set the "
+                         "'KUMO_API_ENDPOINT' environment variable or "
+                         "explicitly call `kumoai.init(...)`.")
 
     # Assign global state after verification that client can be created and
     # authenticated successfully:
@@ -198,10 +197,8 @@ def init(
     logger = logging.getLogger('kumoai')
     log_level = logging.getLevelName(logger.getEffectiveLevel())
 
-    logger.info(
-        f"Successfully initialized the Kumo SDK (version {__version__}) "
-        f"against deployment {url}, with "
-        f"log level {log_level}.")
+    logger.info(f"Initialized Kumo SDK v{__version__} against deployment "
+                f"'{url}'")
 
 
 def set_log_level(level: str) -> None:

kumoai/_version.py

@@ -1 +1 @@
-__version__ = '2.14.0.dev202512191731'
+__version__ = '2.15.0.dev202601141731'

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."""
@@ -320,12 +344,14 @@ class GenerateTrainTableJobAPI(CommonJobAPI[GenerateTrainTableRequest,
         id: str,
         source_table_type: SourceTableType,
         train_table_mod: TrainingTableSpec,
+        extensive_validation: bool,
     ) -> ValidationResponse:
         response = self._client._post(
             f'{self._base_endpoint}/{id}/validate_custom_train_table',
             json=to_json_dict({
                 'custom_table': source_table_type,
                 'train_table_mod': train_table_mod,
+                'extensive_validation': extensive_validation,
             }),
         )
         return parse_response(ValidationResponse, response)

kumoai/connector/utils.py

@@ -1,10 +1,10 @@
 import asyncio
 import csv
-import gc
 import io
 import math
 import os
 import re
+import sys
 import tempfile
 import threading
 import time
@@ -920,7 +920,10 @@ def _read_remote_file_with_progress(
     if capture_first_line and not seen_nl:
         header_line = bytes(header_acc)
 
-    mv = buf.getbuffer()  # zero-copy view of BytesIO internal buffer
+    if sys.version_info >= (3, 13):
+        mv = memoryview(buf.getvalue())
+    else:
+        mv = buf.getbuffer()  # zero-copy view of BytesIO internal buffer
     return buf, mv, header_line
 
 
@@ -999,7 +1002,10 @@ def _iter_mv_chunks(mv: memoryview,
     n = mv.nbytes
     while pos < n:
         nxt = min(n, pos + part_size)
-        yield mv[pos:nxt]  # zero-copy slice
+        if sys.version_info >= (3, 13):
+            yield mv[pos:nxt].tobytes()
+        else:
+            yield mv[pos:nxt]  # zero-copy slice
         pos = nxt
 
 
@@ -1473,13 +1479,17 @@ def _remote_upload_file(name: str, fs: Filesystem, url: str, info: dict,
     if renamed_cols_msg:
         logger.info(renamed_cols_msg)
 
+    try:
+        if isinstance(data_mv, memoryview):
+            data_mv.release()
+    except Exception:
+        pass
+
     try:
         if buf:
             buf.close()
     except Exception:
         pass
-    del buf, data_mv, header_line
-    gc.collect()
 
     logger.info("Upload complete. Validated table %s.", name)
 
@@ -1719,13 +1729,17 @@ def _remote_upload_directory(
                     else:
                         break
 
+                try:
+                    if isinstance(data_mv, memoryview):
+                        data_mv.release()
+                except Exception:
+                    pass
+
                 try:
                     if buf:
                         buf.close()
                 except Exception:
                     pass
-                del buf, data_mv, header_line
-                gc.collect()
 
                 _safe_bar_update(file_bar, 1)
                 _merge_status_update(fpath)

kumoai/experimental/rfm/__init__.py

@@ -20,6 +20,7 @@ from .sagemaker import (
 from .base import Table
 from .backend.local import LocalTable
 from .graph import Graph
+from .task_table import TaskTable
 from .rfm import ExplainConfig, Explanation, KumoRFM
 
 logger = logging.getLogger('kumoai_rfm')
@@ -78,9 +79,9 @@ 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.")
+            "KumoRFM initialization 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"
@@ -103,6 +104,9 @@ class RfmGlobalState:
 
     @property
     def client(self) -> KumoClient:
+        if self._backend == InferenceBackend.UNKNOWN:
+            raise RuntimeError("KumoRFM is not yet initialized")
+
         if self._backend == InferenceBackend.REST:
             return kumoai.global_state.client
 
@@ -146,18 +150,19 @@ def init(
     with global_state._lock:
         if global_state._initialized:
             if url != global_state._url:
-                raise ValueError(
-                    "Kumo RFM has already been initialized with a different "
-                    "URL. Re-initialization with a different URL is not "
+                raise RuntimeError(
+                    "KumoRFM has already been initialized with a different "
+                    "API URL. Re-initialization with a different URL is not "
                     "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.")
+                    "KumoRFM initialization 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"
 
@@ -166,32 +171,28 @@ def init(
 
         backend, region, endpoint_name = _detect_backend(url)
         if backend == InferenceBackend.REST:
-            # Initialize kumoai.global_state
-            if (kumoai.global_state.initialized
-                    and kumoai.global_state._url != url):
-                raise ValueError(
-                    "Kumo AI SDK has already been initialized with different "
-                    "API URL. Please restart Python interpreter and "
-                    "initialize via kumoai.rfm.init()")
-            kumoai.init(url=url, api_key=api_key,
-                        snowflake_credentials=snowflake_credentials,
-                        snowflake_application=snowflake_application,
-                        log_level=log_level)
+            kumoai.init(
+                url=url,
+                api_key=api_key,
+                snowflake_credentials=snowflake_credentials,
+                snowflake_application=snowflake_application,
+                log_level=log_level,
+            )
         elif backend == InferenceBackend.AWS_SAGEMAKER:
             assert region
             assert endpoint_name
             KumoClient_SageMakerAdapter(region, endpoint_name).authenticate()
+            logger.info("KumoRFM initialized in AWS SageMaker")
         else:
             assert backend == InferenceBackend.LOCAL_SAGEMAKER
             KumoClient_SageMakerProxy_Local(url).authenticate()
+            logger.info(f"KumoRFM initialized in local SageMaker at '{url}'")
 
         global_state._url = url
         global_state._backend = backend
         global_state._region = region
         global_state._endpoint_name = endpoint_name
         global_state._initialized = True
-        logger.info("Kumo RFM initialized with backend: %s, url: %s", backend,
-                    url)
 
 
 LocalGraph = Graph  # NOTE Backward compatibility - do not use anymore.
@@ -202,6 +203,7 @@ __all__ = [
     'Table',
     'LocalTable',
     'Graph',
+    'TaskTable',
     'KumoRFM',
     'ExplainConfig',
     'Explanation',

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

@@ -1,12 +1,11 @@
-import warnings
 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.backend.local import LocalTable
+from kumoai.experimental.rfm.base import Table
 from kumoai.utils import ProgressLogger
 
 try:
@@ -106,26 +105,20 @@ class LocalGraphStore:
         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)
+            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] = {}
         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
-
             mask: np.ndarray | None = None
             if table._time_column is not None:
                 ser = df_dict[table.name][table._time_column]
@@ -188,8 +181,6 @@ class LocalGraphStore:
                 continue
 
             time = self.df_dict[table.name][table._time_column]
-            if time.dtype != 'datetime64[ns]':
-                time = time.astype('datetime64[ns]')
             time_dict[table.name] = time.astype(int).to_numpy() // 1000**3
 
             if table.name in self.mask_dict.keys():

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

@@ -219,9 +219,6 @@ class LocalSampler(Sampler):
         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)

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

@@ -1,11 +1,15 @@
-import warnings
-from typing import cast
+from typing import Sequence, cast
 
 import pandas as pd
 from kumoapi.model_plan import MissingType
 
-from kumoai.experimental.rfm.base import DataBackend, SourceColumn, Table
-from kumoai.experimental.rfm.infer import infer_dtype
+from kumoai.experimental.rfm.base import (
+    ColumnSpec,
+    DataBackend,
+    SourceColumn,
+    SourceForeignKey,
+    Table,
+)
 
 
 class LocalTable(Table):
@@ -71,7 +75,6 @@ class LocalTable(Table):
 
         super().__init__(
             name=name,
-            columns=list(df.columns),
             primary_key=primary_key,
             time_column=time_column,
             end_time_column=end_time_column,
@@ -82,33 +85,29 @@ class LocalTable(Table):
         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"Encountered unsupported data type "
-                              f"'{ser.dtype}' for column '{column}' in table "
-                              f"'{self.name}'. Please change the data type of "
-                              f"the column in the `pandas.DataFrame` to use "
-                              f"it within this table, or remove it to "
-                              f"suppress this warning.")
-                continue
-
-            source_column = SourceColumn(
-                name=column,
-                dtype=dtype,
+        return [
+            SourceColumn(
+                name=column_name,
+                dtype=None,
                 is_primary_key=False,
                 is_unique_key=False,
                 is_nullable=True,
-            )
-            source_columns.append(source_column)
+            ) for column_name in self._data.columns
+        ]
 
-        return source_columns
+    def _get_source_foreign_keys(self) -> list[SourceForeignKey]:
+        return []
 
     def _get_source_sample_df(self) -> pd.DataFrame:
         return self._data
 
+    def _get_expr_sample_df(
+        self,
+        columns: Sequence[ColumnSpec],
+    ) -> pd.DataFrame:
+        raise RuntimeError(f"Column expressions are not supported in "
+                           f"'{self.__class__.__name__}'. Please apply your "
+                           f"expressions on the `pd.DataFrame` directly.")
+
     def _get_num_rows(self) -> int | None:
         return len(self._data)