kumoai 2.13.0.dev202511231731__cp312-cp312-macosx_11_0_arm64.whl → 2.13.0.dev202512011731__cp312-cp312-macosx_11_0_arm64.whl

kumoai/_version.py

@@ -1 +1 @@
-__version__ = '2.13.0.dev202511231731'
+__version__ = '2.13.0.dev202512011731'

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,38 @@
+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
+
+__all__ = [
+    'LocalTable',
+]

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

@@ -0,0 +1,151 @@
+from typing import List, Optional
+
+import pandas as pd
+from kumoapi.typing import Dtype, Stype
+from typing_extensions import Self
+
+from kumoai.experimental.rfm import utils
+from kumoai.experimental.rfm.base import Column, Table
+
+
+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 must have at least one row")
+        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 infer_metadata(self, verbose: bool = True) -> Self:
+        r"""Infers metadata, *i.e.*, primary keys and time columns, in the
+        table.
+
+        Args:
+            verbose: Whether to print verbose output.
+        """
+        logs = []
+
+        # Try to detect primary key if not set:
+        if not self.has_primary_key():
+
+            def is_candidate(column: Column) -> bool:
+                if column.stype == Stype.ID:
+                    return True
+                if all(column.stype != Stype.ID for column in self.columns):
+                    if self.name == column.name:
+                        return True
+                    if (self.name.endswith('s')
+                            and self.name[:-1] == column.name):
+                        return True
+                return False
+
+            candidates = [
+                column.name for column in self.columns if is_candidate(column)
+            ]
+
+            if primary_key := utils.detect_primary_key(
+                    table_name=self.name,
+                    df=self._data,
+                    candidates=candidates,
+            ):
+                self.primary_key = primary_key
+                logs.append(f"primary key '{primary_key}'")
+
+        # Try to detect time column if not set:
+        if not self.has_time_column():
+            candidates = [
+                column.name for column in self.columns
+                if column.stype == Stype.timestamp
+                and column.name != self._end_time_column
+            ]
+            if time_column := utils.detect_time_column(self._data, candidates):
+                self.time_column = time_column
+                logs.append(f"time column '{time_column}'")
+
+        if verbose and len(logs) > 0:
+            print(f"Detected {' and '.join(logs)} in table '{self.name}'")
+
+        return self
+
+    def _has_source_column(self, name: str) -> bool:
+        return name in self._data.columns
+
+    def _get_source_dtype(self, name: str) -> Dtype:
+        return utils.to_dtype(self._data[name])
+
+    def _get_source_stype(self, name: str, dtype: Dtype) -> Stype:
+        return utils.infer_stype(self._data[name], name, dtype)
+
+    def _infer_primary_key(self, candidates: List[str]) -> Optional[str]:
+        return utils.detect_primary_key(
+            table_name=self.name,
+            df=self._data,
+            candidates=candidates,
+        )
+
+    def _infer_time_column(self, candidates: List[str]) -> Optional[str]:
+        return utils.detect_time_column(df=self._data, candidates=candidates)
+
+    def _num_rows(self) -> Optional[int]:
+        return len(self._data)

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

@@ -0,0 +1,23 @@
+from pathlib import Path
+from typing import Any, TypeAlias, Union
+
+try:
+    import adbc_driver_sqlite.dbapi as adbc
+except ImportError:
+    raise ImportError("No module named 'adbc_driver_sqlite'. Please install "
+                      "Kumo SDK with the 'sqlite' extension via "
+                      "`pip install kumoai[sqlite]`.")
+
+Connection: TypeAlias = adbc.AdbcSqliteConnection
+
+
+def connect(uri: Union[str, Path, None] = None, **kwargs: Any) -> Connection:
+    return adbc.connect(uri, **kwargs)
+
+
+from .table import SQLiteTable  # noqa: E402
+
+__all__ = [
+    'Connection',
+    'SQLiteTable',
+]

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

@@ -0,0 +1,117 @@
+import re
+from typing import Dict, List, Optional, Sequence
+
+import pyarrow as pa
+from kumoapi.typing import Dtype, Stype
+from typing_extensions import Self
+
+from kumoai.experimental.rfm import utils
+from kumoai.experimental.rfm.backend.sqlite import Connection
+from kumoai.experimental.rfm.base import Table
+
+
+class SQLiteTable(Table):
+    r"""A table backed by a :class:`sqlite` database.
+
+    Args:
+        connection: The connection to a :class:`sqlite` database.
+        name: The name of this table.
+        columns: The selected columns 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,
+        connection: Connection,
+        name: str,
+        columns: Optional[Sequence[str]] = None,
+        primary_key: Optional[str] = None,
+        time_column: Optional[str] = None,
+        end_time_column: Optional[str] = None,
+    ) -> None:
+
+        self._connection = connection
+        self._dtype_dict: Dict[str, Dtype] = {}
+
+        with connection.cursor() as cursor:
+            cursor.execute(f"PRAGMA table_info({name})")
+            for _, column, dtype, _, _, is_pkey in cursor.fetchall():
+                if bool(is_pkey):
+                    if primary_key is not None and primary_key != column:
+                        raise ValueError(f"Found duplicate primary key "
+                                         f"definition '{primary_key}' and "
+                                         f"'{column}' in table '{name}'")
+                    primary_key = column
+
+                # Determine colun affinity:
+                dtype = dtype.strip().upper()
+                if re.search('INT', dtype):
+                    self._dtype_dict[column] = Dtype.int
+                elif re.search('TEXT|CHAR|CLOB', dtype):
+                    self._dtype_dict[column] = Dtype.string
+                elif re.search('REAL|FLOA|DOUB', dtype):
+                    self._dtype_dict[column] = Dtype.float
+                else:  # NUMERIC affinity.
+                    self._dtype_dict[column] = Dtype.unsupported
+
+            if len(self._dtype_dict) > 0:
+                column_names = ', '.join(self._dtype_dict.keys())
+                cursor.execute(f"SELECT {column_names} FROM {name} "
+                               f"ORDER BY rowid LIMIT 1000")
+                self._sample = cursor.fetch_arrow_table()
+
+            for column_name in list(self._dtype_dict.keys()):
+                if self._dtype_dict[column_name] == Dtype.unsupported:
+                    dtype = self._sample[column_name].type
+                    if pa.types.is_integer(dtype):
+                        self._dtype_dict[column_name] = Dtype.int
+                    elif pa.types.is_floating(dtype):
+                        self._dtype_dict[column_name] = Dtype.float
+                    elif pa.types.is_decimal(dtype):
+                        self._dtype_dict[column_name] = Dtype.float
+                    elif pa.types.is_string(dtype):
+                        self._dtype_dict[column_name] = Dtype.string
+                    else:
+                        del self._dtype_dict[column_name]
+
+        if len(self._dtype_dict) == 0:
+            raise RuntimeError(f"Table '{name}' does not exist or does not "
+                               f"hold any column with a supported data type")
+
+        super().__init__(
+            name=name,
+            columns=columns or list(self._dtype_dict.keys()),
+            primary_key=primary_key,
+            time_column=time_column,
+            end_time_column=end_time_column,
+        )
+
+    def infer_metadata(self, verbose: bool = True) -> Self:
+        r"""Infers metadata, *i.e.*, primary keys and time columns, in the
+        table.
+
+        Args:
+            verbose: Whether to print verbose output.
+        """
+        return self
+
+    def _has_source_column(self, name: str) -> bool:
+        return name in self._dtype_dict
+
+    def _get_source_dtype(self, name: str) -> Dtype:
+        return self._dtype_dict[name]
+
+    def _get_source_stype(self, name: str, dtype: Dtype) -> Stype:
+        ser = self._sample[name].to_pandas()
+        return utils.infer_stype(ser, name, dtype)
+
+    def _infer_primary_key(self, candidates: List[str]) -> Optional[str]:
+        return None  # TODO
+
+    def _infer_time_column(self, candidates: List[str]) -> Optional[str]:
+        return None  # TODO
+
+    def _num_rows(self) -> Optional[int]:
+        return None

kumoai/experimental/rfm/base/__init__.py

@@ -0,0 +1,7 @@
+from .column import Column
+from .table import Table
+
+__all__ = [
+    'Column',
+    'Table',
+]

kumoai/experimental/rfm/base/column.py

@@ -0,0 +1,66 @@
+from dataclasses import dataclass
+from typing import Any
+
+from kumoapi.typing import Dtype, Stype
+
+
+@dataclass(init=False, repr=False, eq=False)
+class Column:
+    stype: Stype
+
+    def __init__(
+        self,
+        name: str,
+        dtype: Dtype,
+        stype: Stype,
+        is_primary_key: bool = False,
+        is_time_column: bool = False,
+        is_end_time_column: bool = False,
+    ) -> None:
+        self._name = name
+        self._dtype = Dtype(dtype)
+        self._is_primary_key = is_primary_key
+        self._is_time_column = is_time_column
+        self._is_end_time_column = is_end_time_column
+        self.stype = Stype(stype)
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def dtype(self) -> Dtype:
+        return self._dtype
+
+    def __setattr__(self, key: str, val: Any) -> None:
+        if key == 'stype':
+            if isinstance(val, str):
+                val = Stype(val)
+            assert isinstance(val, Stype)
+            if not val.supports_dtype(self.dtype):
+                raise ValueError(f"Column '{self.name}' received an "
+                                 f"incompatible semantic type (got "
+                                 f"dtype='{self.dtype}' and stype='{val}')")
+            if self._is_primary_key and val != Stype.ID:
+                raise ValueError(f"Primary key '{self.name}' must have 'ID' "
+                                 f"semantic type (got '{val}')")
+            if self._is_time_column and val != Stype.timestamp:
+                raise ValueError(f"Time column '{self.name}' must have "
+                                 f"'timestamp' semantic type (got '{val}')")
+            if self._is_end_time_column and val != Stype.timestamp:
+                raise ValueError(f"End time column '{self.name}' must have "
+                                 f"'timestamp' semantic type (got '{val}')")
+
+        super().__setattr__(key, val)
+
+    def __hash__(self) -> int:
+        return hash((self.name, self.stype, self.dtype))
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, Column):
+            return False
+        return hash(self) == hash(other)
+
+    def __repr__(self) -> str:
+        return (f'{self.__class__.__name__}(name={self.name}, '
+                f'stype={self.stype}, dtype={self.dtype})')