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

kumoai/client/jobs.py

@@ -344,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/snow/sampler.py

@@ -144,11 +144,11 @@ class SnowSampler(SQLSampler):
             query.entity_table: np.arange(len(entity_df)),
         }
         for edge_type, (min_offset, max_offset) in time_offset_dict.items():
-            table_name, fkey, _ = edge_type
+            table_name, foreign_key, _ = edge_type
             feat_dict[table_name], batch_dict[table_name] = self._by_time(
                 table_name=table_name,
-                fkey=fkey,
-                pkey=entity_df[self.primary_key_dict[query.entity_table]],
+                foreign_key=foreign_key,
+                index=entity_df[self.primary_key_dict[query.entity_table]],
                 anchor_time=time,
                 min_offset=min_offset,
                 max_offset=max_offset,
@@ -179,7 +179,7 @@ class SnowSampler(SQLSampler):
     def _by_pkey(
         self,
         table_name: str,
-        pkey: pd.Series,
+        index: pd.Series,
         columns: set[str],
     ) -> tuple[pd.DataFrame, np.ndarray]:
         key = self.primary_key_dict[table_name]
@@ -189,7 +189,7 @@ class SnowSampler(SQLSampler):
             for column in columns
         ]
 
-        payload = json.dumps(list(pkey))
+        payload = json.dumps(list(index))
 
         sql = ("WITH TMP as (\n"
                "  SELECT\n"
@@ -206,7 +206,7 @@ class SnowSampler(SQLSampler):
                 f"TMP.__KUMO_BATCH__ as __KUMO_BATCH__, "
                 f"{', '.join(projections)}\n"
                 f"FROM TMP\n"
-                f"JOIN {self.source_name_dict[table_name]} ENT\n"
+                f"JOIN {self.source_name_dict[table_name]}\n"
                 f"  ON {key_ref} = TMP.__KUMO_ID__")
 
         with paramstyle(self._connection), self._connection.cursor() as cursor:
@@ -228,13 +228,82 @@ class SnowSampler(SQLSampler):
             stype_dict=self.table_stype_dict[table_name],
         ), batch
 
+    def _by_fkey(
+        self,
+        table_name: str,
+        foreign_key: str,
+        index: pd.Series,
+        num_neighbors: int,
+        anchor_time: pd.Series | None,
+        columns: set[str],
+    ) -> tuple[pd.DataFrame, np.ndarray]:
+        time_column = self.time_column_dict.get(table_name)
+
+        if time_column is not None and anchor_time is not None:
+            anchor_time = anchor_time.dt.strftime("%Y-%m-%d %H:%M:%S")
+            payload = json.dumps(list(zip(index, anchor_time)))
+        else:
+            payload = json.dumps(list(zip(index)))
+
+        key_ref = self.table_column_ref_dict[table_name][foreign_key]
+        projections = [
+            self.table_column_proj_dict[table_name][column]
+            for column in columns
+        ]
+
+        sql = ("WITH TMP as (\n"
+               "  SELECT\n"
+               "    f.index as __KUMO_BATCH__,\n")
+        if self.table_dtype_dict[table_name][foreign_key].is_int():
+            sql += "    f.value[0]::NUMBER as __KUMO_ID__"
+        elif self.table_dtype_dict[table_name][foreign_key].is_float():
+            sql += "    f.value[0]::FLOAT as __KUMO_ID__"
+        else:
+            sql += "    f.value[0]::VARCHAR as __KUMO_ID__"
+        if time_column is not None and anchor_time is not None:
+            sql += (",\n"
+                    "    f.value[1]::TIMESTAMP_NTZ as __KUMO_TIME__")
+        sql += (f"\n"
+                f"  FROM TABLE(FLATTEN(INPUT => PARSE_JSON(?))) f\n"
+                f")\n"
+                f"SELECT "
+                f"TMP.__KUMO_BATCH__ as __KUMO_BATCH__, "
+                f"{', '.join(projections)}\n"
+                f"FROM TMP\n"
+                f"JOIN {self.source_name_dict[table_name]}\n"
+                f"  ON {key_ref} = TMP.__KUMO_ID__\n")
+        if time_column is not None and anchor_time is not None:
+            time_ref = self.table_column_ref_dict[table_name][time_column]
+            sql += f" AND {time_ref} <= TMP.__KUMO_TIME__\n"
+        sql += ("QUALIFY ROW_NUMBER() OVER (\n"
+                "  PARTITION BY TMP.__KUMO_BATCH__\n")
+        if time_column is not None:
+            sql += f"  ORDER BY {time_ref} DESC\n"
+        else:
+            sql += f"  ORDER BY {key_ref}\n"
+        sql += f") <= {num_neighbors}"
+
+        with paramstyle(self._connection), self._connection.cursor() as cursor:
+            cursor.execute(sql, (payload, ))
+            table = cursor.fetch_arrow_all()
+
+        batch = table['__KUMO_BATCH__'].cast(pa.int64()).to_numpy()
+        batch_index = table.schema.get_field_index('__KUMO_BATCH__')
+        table = table.remove_column(batch_index)
+
+        return Table._sanitize(
+            df=table.to_pandas(),
+            dtype_dict=self.table_dtype_dict[table_name],
+            stype_dict=self.table_stype_dict[table_name],
+        ), batch
+
     # Helper Methods ##########################################################
 
     def _by_time(
         self,
         table_name: str,
-        fkey: str,
-        pkey: pd.Series,
+        foreign_key: str,
+        index: pd.Series,
         anchor_time: pd.Series,
         min_offset: pd.DateOffset | None,
         max_offset: pd.DateOffset,
@@ -247,11 +316,11 @@ class SnowSampler(SQLSampler):
         if min_offset is not None:
             start_time = anchor_time + min_offset
             start_time = start_time.dt.strftime("%Y-%m-%d %H:%M:%S")
-            payload = json.dumps(list(zip(pkey, end_time, start_time)))
+            payload = json.dumps(list(zip(index, end_time, start_time)))
         else:
-            payload = json.dumps(list(zip(pkey, end_time)))
+            payload = json.dumps(list(zip(index, end_time)))
 
-        key_ref = self.table_column_ref_dict[table_name][fkey]
+        key_ref = self.table_column_ref_dict[table_name][foreign_key]
         time_ref = self.table_column_ref_dict[table_name][time_column]
         projections = [
             self.table_column_proj_dict[table_name][column]
@@ -260,9 +329,9 @@ class SnowSampler(SQLSampler):
         sql = ("WITH TMP as (\n"
                "  SELECT\n"
                "    f.index as __KUMO_BATCH__,\n")
-        if self.table_dtype_dict[table_name][fkey].is_int():
+        if self.table_dtype_dict[table_name][foreign_key].is_int():
             sql += "    f.value[0]::NUMBER as __KUMO_ID__,\n"
-        elif self.table_dtype_dict[table_name][fkey].is_float():
+        elif self.table_dtype_dict[table_name][foreign_key].is_float():
             sql += "    f.value[0]::FLOAT as __KUMO_ID__,\n"
         else:
             sql += "    f.value[0]::VARCHAR as __KUMO_ID__,\n"
@@ -276,7 +345,7 @@ class SnowSampler(SQLSampler):
                 f"TMP.__KUMO_BATCH__ as __KUMO_BATCH__, "
                 f"{', '.join(projections)}\n"
                 f"FROM TMP\n"
-                f"JOIN {self.source_name_dict[table_name]} FACT\n"
+                f"JOIN {self.source_name_dict[table_name]}\n"
                 f"  ON {key_ref} = TMP.__KUMO_ID__\n"
                 f" AND {time_ref} <= TMP.__KUMO_END_TIME__")
         if min_offset is not None:

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

@@ -226,7 +226,7 @@ class SQLiteSampler(SQLSampler):
     def _by_pkey(
         self,
         table_name: str,
-        pkey: pd.Series,
+        index: pd.Series,
         columns: set[str],
     ) -> tuple[pd.DataFrame, np.ndarray]:
         source_table = self.source_table_dict[table_name]
@@ -237,7 +237,7 @@ class SQLiteSampler(SQLSampler):
             for column in columns
         ]
 
-        tmp = pa.table([pa.array(pkey)], names=['__kumo_id__'])
+        tmp = pa.table([pa.array(index)], names=['__kumo_id__'])
         tmp_name = f'tmp_{table_name}_{key}_{id(tmp)}'
 
         sql = (f"SELECT "
@@ -245,7 +245,6 @@ class SQLiteSampler(SQLSampler):
                f"{', '.join(projections)}\n"
                f"FROM {quote_ident(tmp_name)} tmp\n"
                f"JOIN {self.source_name_dict[table_name]} ent\n")
-
         if key in source_table and source_table[key].is_unique_key:
             sql += (f"  ON {key_ref} = tmp.__kumo_id__")
         else:
@@ -271,13 +270,70 @@ class SQLiteSampler(SQLSampler):
             stype_dict=self.table_stype_dict[table_name],
         ), batch
 
+    def _by_fkey(
+        self,
+        table_name: str,
+        foreign_key: str,
+        index: pd.Series,
+        num_neighbors: int,
+        anchor_time: pd.Series | None,
+        columns: set[str],
+    ) -> tuple[pd.DataFrame, np.ndarray]:
+        time_column = self.time_column_dict.get(table_name)
+
+        # NOTE SQLite does not have a native datetime format. Currently, we
+        # assume timestamps are given as `TEXT` in `ISO-8601 UTC`:
+        tmp = pa.table([pa.array(index)], names=['__kumo_id__'])
+        if time_column is not None and anchor_time is not None:
+            anchor_time = anchor_time.dt.strftime("%Y-%m-%d %H:%M:%S")
+            tmp = tmp.append_column('__kumo_time__', pa.array(anchor_time))
+        tmp_name = f'tmp_{table_name}_{foreign_key}_{id(tmp)}'
+
+        key_ref = self.table_column_ref_dict[table_name][foreign_key]
+        projections = [
+            self.table_column_proj_dict[table_name][column]
+            for column in columns
+        ]
+        sql = (f"SELECT "
+               f"tmp.rowid - 1 as __kumo_batch__, "
+               f"{', '.join(projections)}\n"
+               f"FROM {quote_ident(tmp_name)} tmp\n"
+               f"JOIN {self.source_name_dict[table_name]} fact\n"
+               f"ON fact.rowid IN (\n"
+               f"  SELECT rowid\n"
+               f"  FROM {self.source_name_dict[table_name]}\n"
+               f"  WHERE {key_ref} = tmp.__kumo_id__\n")
+        if time_column is not None and anchor_time is not None:
+            time_ref = self.table_column_ref_dict[table_name][time_column]
+            sql += f"  AND {time_ref} <= tmp.__kumo_time__\n"
+        if time_column is not None:
+            time_ref = self.table_column_ref_dict[table_name][time_column]
+            sql += f"  ORDER BY {time_ref} DESC\n"
+        sql += (f"  LIMIT {num_neighbors}\n"
+                f")")
+
+        with self._connection.cursor() as cursor:
+            cursor.adbc_ingest(tmp_name, tmp, mode='replace')
+            cursor.execute(sql)
+            table = cursor.fetch_arrow_table()
+
+        batch = table['__kumo_batch__'].to_numpy()
+        batch_index = table.schema.get_field_index('__kumo_batch__')
+        table = table.remove_column(batch_index)
+
+        return Table._sanitize(
+            df=table.to_pandas(),
+            dtype_dict=self.table_dtype_dict[table_name],
+            stype_dict=self.table_stype_dict[table_name],
+        ), batch
+
     # Helper Methods ##########################################################
 
     def _by_time(
         self,
         table_name: str,
-        fkey: str,
-        pkey: pd.Series,
+        foreign_key: str,
+        index: pd.Series,
         anchor_time: pd.Series,
         min_offset: pd.DateOffset | None,
         max_offset: pd.DateOffset,
@@ -287,7 +343,7 @@ class SQLiteSampler(SQLSampler):
 
         # NOTE SQLite does not have a native datetime format. Currently, we
         # assume timestamps are given as `TEXT` in `ISO-8601 UTC`:
-        tmp = pa.table([pa.array(pkey)], names=['__kumo_id__'])
+        tmp = pa.table([pa.array(index)], names=['__kumo_id__'])
         end_time = anchor_time + max_offset
         end_time = end_time.dt.strftime("%Y-%m-%d %H:%M:%S")
         tmp = tmp.append_column('__kumo_end__', pa.array(end_time))
@@ -295,9 +351,9 @@ class SQLiteSampler(SQLSampler):
             start_time = anchor_time + min_offset
             start_time = start_time.dt.strftime("%Y-%m-%d %H:%M:%S")
             tmp = tmp.append_column('__kumo_start__', pa.array(start_time))
-        tmp_name = f'tmp_{table_name}_{fkey}_{id(tmp)}'
+        tmp_name = f'tmp_{table_name}_{foreign_key}_{id(tmp)}'
 
-        key_ref = self.table_column_ref_dict[table_name][fkey]
+        key_ref = self.table_column_ref_dict[table_name][foreign_key]
         time_ref = self.table_column_ref_dict[table_name][time_column]
         projections = [
             self.table_column_proj_dict[table_name][column]
@@ -307,7 +363,7 @@ class SQLiteSampler(SQLSampler):
                f"tmp.rowid - 1 as __kumo_batch__, "
                f"{', '.join(projections)}\n"
                f"FROM {quote_ident(tmp_name)} tmp\n"
-               f"JOIN {self.source_name_dict[table_name]} fact\n"
+               f"JOIN {self.source_name_dict[table_name]}\n"
                f"  ON {key_ref} = tmp.__kumo_id__\n"
                f" AND {time_ref} <= tmp.__kumo_end__")
         if min_offset is not None:
@@ -359,11 +415,11 @@ class SQLiteSampler(SQLSampler):
                 query.entity_table: np.arange(len(df)),
             }
             for edge_type, (_min, _max) in time_offset_dict.items():
-                table_name, fkey, _ = edge_type
+                table_name, foreign_key, _ = edge_type
                 feat_dict[table_name], batch_dict[table_name] = self._by_time(
                     table_name=table_name,
-                    fkey=fkey,
-                    pkey=df[self.primary_key_dict[query.entity_table]],
+                    foreign_key=foreign_key,
+                    index=df[self.primary_key_dict[query.entity_table]],
                     anchor_time=time,
                     min_offset=_min,
                     max_offset=_max,

kumoai/experimental/rfm/base/mapper.py

@@ -0,0 +1,67 @@
+import numpy as np
+import pandas as pd
+
+
+class Mapper:
+    r"""A mapper to map ``(pkey, batch)`` pairs to contiguous node IDs.
+
+    Args:
+        num_examples: The maximum number of examples to add/retrieve.
+    """
+    def __init__(self, num_examples: int):
+        self._pkey_dtype: pd.CategoricalDtype | None = None
+        self._indices: list[np.ndarray] = []
+        self._index_dtype: pd.CategoricalDtype | None = None
+        self._num_examples = num_examples
+
+    def add(self, pkey: pd.Series, batch: np.ndarray) -> None:
+        r"""Adds a set of ``(pkey, batch)`` pairs to the mapper.
+
+        Args:
+            pkey: The primary keys.
+            batch: The batch vector.
+        """
+        if self._pkey_dtype is not None:
+            category = np.concatenate([
+                self._pkey_dtype.categories.values,
+                pkey,
+            ], axis=0)
+            category = pd.unique(category)
+            self._pkey_dtype = pd.CategoricalDtype(category)
+        elif pd.api.types.is_string_dtype(pkey):
+            category = pd.unique(pkey)
+            self._pkey_dtype = pd.CategoricalDtype(category)
+
+        if self._pkey_dtype is not None:
+            index = pd.Categorical(pkey, dtype=self._pkey_dtype).codes
+        else:
+            index = pkey.to_numpy()
+        index = self._num_examples * index + batch
+        self._indices.append(index)
+        self._index_dtype = None
+
+    def get(self, pkey: pd.Series, batch: np.ndarray) -> np.ndarray:
+        r"""Retrieves the node IDs for a set of ``(pkey, batch)`` pairs.
+
+        Returns ``-1`` for any pair not registered in the mapping.
+
+        Args:
+            pkey: The primary keys.
+            batch: The batch vector.
+        """
+        if len(self._indices) == 0:
+            return np.full(len(pkey), -1, dtype=np.int64)
+
+        if self._index_dtype is None:  # Lazy build index:
+            category = pd.unique(np.concatenate(self._indices))
+            self._index_dtype = pd.CategoricalDtype(category)
+
+        if self._pkey_dtype is not None:
+            index = pd.Categorical(pkey, dtype=self._pkey_dtype).codes
+        else:
+            index = pkey.to_numpy()
+        index = self._num_examples * index + batch
+
+        out = pd.Categorical(index, dtype=self._index_dtype).codes
+        out = out.astype('int64')
+        return out