kanboost 0.0.1__py3-none-any.whl

kanboost/__init__.py

@@ -0,0 +1,23 @@
+"""
+KANBoost: Gradient Boosting with Kolmogorov-Arnold Network learners.
+
+An interpretable alternative to tree-based gradient boosting (XGBoost,
+LightGBM, CatBoost), using shallow KAN networks as weak learners instead
+of decision trees.
+"""
+
+from .classifier import KANBoostClassifier
+from .regressor import KANBoostRegressor
+from .metrics import classification_report_dict, print_classification_report
+
+__version__ = "0.0.1"
+__all__ = [
+    "KANBoostClassifier",
+    "KANBoostRegressor",
+    "classification_report_dict",
+    "print_classification_report",
+]
+
+# Hyperparameter tuning lives in the separate `kantun` package, so that
+# kanboost's core dependency footprint stays minimal and kantun can be
+# used to tune other model types too. Install with: pip install kantun

kanboost/_base.py

@@ -0,0 +1,198 @@
+"""
+kanboost._base -- shared machinery for KANBoostClassifier / KANBoostRegressor.
+
+Contains:
+- input validation
+- the shared boosting loop skeleton
+- sklearn-compatible get_params / set_params (so KANBoost estimators work
+  inside sklearn Pipelines, GridSearchCV, and kantun without adapters)
+- feature importances (shared by both estimators)
+- suppression of pykan's noisy checkpoint logging
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+
+import numpy as np
+import pandas as pd
+import torch
+import torch.nn as nn
+from kan import KAN
+from sklearn.base import BaseEstimator
+
+from .encoders import TabularPreprocessor
+
+
+@contextlib.contextmanager
+def _suppress_pykan_noise():
+    """pykan prints checkpoint messages to stdout and tqdm progress bars
+    to stderr on every instantiation/fit; silence both."""
+    out, err = io.StringIO(), io.StringIO()
+    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+        yield
+
+
+def _validate_Xy(X, y):
+    """Validate and normalize training inputs. Returns (X_df, y_arr)."""
+    if not isinstance(X, pd.DataFrame):
+        X = pd.DataFrame(np.asarray(X))
+        X.columns = [f"f{i}" for i in range(X.shape[1])]
+
+    y = np.asarray(y, dtype=float).ravel()
+
+    if len(X) != len(y):
+        raise ValueError(
+            f"X and y have inconsistent lengths: {len(X)} vs {len(y)}"
+        )
+    if len(X) == 0:
+        raise ValueError("X is empty.")
+    if np.isnan(y).any():
+        raise ValueError(
+            "y contains NaN values. Remove or impute them before fitting."
+        )
+    return X, y
+
+
+class _BaseKANBoost(BaseEstimator):
+    """Shared base for the boosting estimators. Not part of the public API.
+
+    Inherits sklearn's BaseEstimator, which provides get_params/set_params,
+    __sklearn_tags__, and full compatibility with sklearn Pipelines,
+    GridSearchCV, cross_val_score, and clone().
+    """
+
+    def __init__(
+        self,
+        n_estimators: int = 100,
+        learning_rate: float = 0.1,
+        kan_hidden: int = 3,
+        kan_grid: int = 2,
+        kan_k: int = 3,
+        kan_steps: int = 20,
+        kan_lr: float = 0.02,
+        early_stopping_rounds: int | None = 10,
+        categorical_cols=None,
+        random_state: int = 42,
+        verbose: bool = False,
+    ):
+        self.n_estimators = n_estimators
+        self.learning_rate = learning_rate
+        self.kan_hidden = kan_hidden
+        self.kan_grid = kan_grid
+        self.kan_k = kan_k
+        self.kan_steps = kan_steps
+        self.kan_lr = kan_lr
+        self.early_stopping_rounds = early_stopping_rounds
+        self.categorical_cols = categorical_cols
+        self.random_state = random_state
+        self.verbose = verbose
+
+        # fitted state
+        self.preprocessor_ = None
+        self.learners_ = []
+        self.init_pred_ = None
+        self.best_iteration_ = None
+        self.feature_names_in_ = None
+
+    # ------------------------------------------------------------------
+    # NOTE: get_params/set_params/__sklearn_tags__ come from BaseEstimator.
+    # ------------------------------------------------------------------
+
+    # ------------------------------------------------------------------
+    # shared internals
+    # ------------------------------------------------------------------
+    def _validate_hyperparams(self):
+        if self.n_estimators < 1:
+            raise ValueError("n_estimators must be >= 1")
+        if not (0 < self.learning_rate <= 1):
+            raise ValueError("learning_rate must be in (0, 1]")
+        if self.kan_hidden < 1 or self.kan_grid < 1 or self.kan_steps < 1:
+            raise ValueError("kan_hidden, kan_grid, kan_steps must be >= 1")
+
+    def _prepare_fit(self, X, y):
+        """Common preamble: seeds, validation, preprocessing."""
+        self._validate_hyperparams()
+        torch.manual_seed(self.random_state)
+        np.random.seed(self.random_state)
+
+        X, y = _validate_Xy(X, y)
+        self.feature_names_in_ = list(X.columns)
+
+        self.preprocessor_ = TabularPreprocessor(
+            categorical_cols=self.categorical_cols or []
+        )
+        X_arr = self.preprocessor_.fit_transform(X, y)
+
+        if np.isnan(X_arr).any():
+            raise ValueError(
+                "Preprocessed X contains NaN values. KANBoost does not yet "
+                "handle missing values natively -- impute before fitting."
+            )
+        return X, y, X_arr
+
+    def _new_learner(self, n_features: int, seed_offset: int) -> KAN:
+        with _suppress_pykan_noise():
+            return KAN(
+                width=[n_features, self.kan_hidden, 1],
+                grid=self.kan_grid,
+                k=self.kan_k,
+                seed=self.random_state + seed_offset,
+            )
+
+    def _fit_learner(self, learner: KAN, X_t: torch.Tensor, residual: np.ndarray):
+        r_t = torch.tensor(residual, dtype=torch.float32).unsqueeze(1)
+        dataset = {
+            "train_input": X_t, "train_label": r_t,
+            "test_input": X_t, "test_label": r_t,
+        }
+        with _suppress_pykan_noise():
+            learner.fit(
+                dataset, opt="Adam", steps=self.kan_steps, lr=self.kan_lr,
+                loss_fn=nn.MSELoss(),
+            )
+        with torch.no_grad():
+            return learner(X_t).numpy().flatten()
+
+    def _check_fitted(self):
+        if not self.learners_:
+            raise RuntimeError(
+                f"This {type(self).__name__} instance is not fitted yet. "
+                "Call fit() before predicting."
+            )
+
+    def _transform_X(self, X) -> torch.Tensor:
+        self._check_fitted()
+        if not isinstance(X, pd.DataFrame):
+            X = pd.DataFrame(np.asarray(X), columns=self.feature_names_in_)
+        X_arr = self.preprocessor_.transform(X)
+        return torch.tensor(X_arr, dtype=torch.float32)
+
+    # ------------------------------------------------------------------
+    def feature_importances(self) -> np.ndarray:
+        """
+        Approximate per-feature importance: L2 norm of each learner's
+        first-layer spline coefficients per input dimension, summed over
+        the ensemble and normalized to 1. A rough analogue of GBDT
+        'gain' importance.
+        """
+        self._check_fitted()
+        n_features = self.learners_[0].width[0][0]
+        importances = np.zeros(n_features)
+        for learner in self.learners_[: self.best_iteration_]:
+            coef = learner.act_fun[0].coef.detach().numpy()
+            importances += np.linalg.norm(coef, axis=(1, 2))
+        total = importances.sum()
+        return importances / total if total > 0 else importances
+
+    def feature_importances_dict(self) -> dict:
+        """Feature importances keyed by input column name, sorted desc."""
+        imps = self.feature_importances()
+        # preprocessor may reorder: numeric cols first, then categorical
+        ordered_names = (
+            list(self.preprocessor_.numeric_cols_)
+            + list(self.preprocessor_.categorical_cols)
+        )
+        pairs = sorted(zip(ordered_names, imps), key=lambda kv: -kv[1])
+        return {name: float(v) for name, v in pairs}

kanboost/classifier.py

@@ -0,0 +1,169 @@
+"""
+KANBoostClassifier: binary classification via gradient boosting with
+shallow KAN networks as weak learners.
+
+Follows the classic Friedman (2001) gradient boosting recipe:
+
+    F_0(x)      = log-odds of the base rate
+    for t = 1..T:
+        r_t     = pseudo-residuals = y - sigmoid(F_{t-1}(x))     (logloss)
+        f_t     = a small KAN fit to (X, r_t)
+        F_t(x)  = F_{t-1}(x) + learning_rate * f_t(x)
+    prediction  = sigmoid(F_T(x))
+
+Each weak learner is a small, shallow KAN so it plays the same structural
+role a shallow decision tree plays in XGBoost/CatBoost: a cheap,
+high-bias/low-variance component that is only useful in aggregate.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import torch
+
+from sklearn.base import ClassifierMixin
+
+from ._base import _BaseKANBoost, _validate_Xy
+
+
+def _sigmoid(z: np.ndarray) -> np.ndarray:
+    return 1.0 / (1.0 + np.exp(-np.clip(z, -30, 30)))
+
+
+class KANBoostClassifier(ClassifierMixin, _BaseKANBoost):
+    """Gradient-boosted KAN ensemble for binary classification.
+
+    Parameters
+    ----------
+    n_estimators : int, default=100
+        Maximum number of boosting iterations (weak learners).
+    learning_rate : float, default=0.1
+        Shrinkage applied to each learner's contribution.
+    kan_hidden : int, default=3
+        Hidden-layer width of each weak KAN learner.
+    kan_grid : int, default=2
+        Number of B-spline grid intervals per edge function.
+    kan_k : int, default=3
+        B-spline polynomial degree.
+    kan_steps : int, default=20
+        Optimizer steps used to fit each weak learner.
+    kan_lr : float, default=0.02
+        Learning rate of each weak learner's inner optimizer.
+    early_stopping_rounds : int or None, default=10
+        Stop if validation logloss hasn't improved for this many rounds.
+        Requires eval_set in fit(). None disables early stopping.
+    categorical_cols : list of str, optional
+        Column names to target-mean encode automatically.
+    random_state : int, default=42
+    verbose : bool, default=False
+    """
+
+
+    def fit(self, X, y, eval_set: tuple | None = None):
+        """Fit the boosted ensemble.
+
+        Parameters
+        ----------
+        X : DataFrame or array of shape (n_samples, n_features)
+        y : array of shape (n_samples,) with values in {0, 1}
+        eval_set : (X_val, y_val) tuple, optional
+            Validation data for early stopping.
+        """
+        X, y, X_arr = self._prepare_fit(X, y)
+
+        classes = np.unique(y)
+        if not np.array_equal(classes, [0, 1]) and not np.array_equal(classes, [0]) \
+                and not np.array_equal(classes, [1]):
+            raise ValueError(
+                f"KANBoostClassifier supports binary targets in {{0, 1}}; "
+                f"got classes {classes}. Multiclass is on the roadmap."
+            )
+        self.classes_ = np.array([0, 1])
+
+        X_t = torch.tensor(X_arr, dtype=torch.float32)
+        n_features = X_arr.shape[1]
+
+        p = float(np.clip(y.mean(), 1e-6, 1 - 1e-6))
+        self.init_pred_ = float(np.log(p / (1 - p)))
+        F = np.full(len(y), self.init_pred_)
+
+        X_val_t = y_val = F_val = None
+        if eval_set is not None:
+            X_val_df, y_val = eval_set
+            X_val_df, y_val = _validate_Xy(X_val_df, y_val)
+            X_val_arr = self.preprocessor_.transform(X_val_df)
+            X_val_t = torch.tensor(X_val_arr, dtype=torch.float32)
+            F_val = np.full(len(y_val), self.init_pred_)
+
+        best_val_loss = np.inf
+        rounds_since_best = 0
+        self.learners_ = []
+        self.best_iteration_ = None
+
+        for t in range(self.n_estimators):
+            residual = y - _sigmoid(F)
+
+            learner = self._new_learner(n_features, seed_offset=t)
+            update = self._fit_learner(learner, X_t, residual)
+            F += self.learning_rate * update
+            self.learners_.append(learner)
+
+            if X_val_t is not None:
+                with torch.no_grad():
+                    F_val += self.learning_rate * learner(X_val_t).numpy().flatten()
+                val_prob = np.clip(_sigmoid(F_val), 1e-7, 1 - 1e-7)
+                val_loss = -float(np.mean(
+                    y_val * np.log(val_prob) + (1 - y_val) * np.log(1 - val_prob)
+                ))
+
+                if self.verbose:
+                    print(f"[{t + 1}/{self.n_estimators}] val_logloss={val_loss:.5f}")
+
+                if val_loss < best_val_loss - 1e-5:
+                    best_val_loss = val_loss
+                    rounds_since_best = 0
+                    self.best_iteration_ = t + 1
+                else:
+                    rounds_since_best += 1
+                    if (self.early_stopping_rounds is not None
+                            and rounds_since_best >= self.early_stopping_rounds):
+                        if self.verbose:
+                            print(f"Early stopping at iteration {t + 1}")
+                        break
+            elif self.verbose and (t + 1) % max(1, self.n_estimators // 10) == 0:
+                print(f"[{t + 1}/{self.n_estimators}] "
+                      f"train residual std={residual.std():.4f}")
+
+        if self.best_iteration_ is None:
+            self.best_iteration_ = len(self.learners_)
+        return self
+
+    # ------------------------------------------------------------------
+    def _raw_score(self, X) -> np.ndarray:
+        X_t = self._transform_X(X)
+        F = np.full(X_t.shape[0], self.init_pred_)
+        for learner in self.learners_[: self.best_iteration_]:
+            with torch.no_grad():
+                F += self.learning_rate * learner(X_t).numpy().flatten()
+        return F
+
+    def predict_proba(self, X) -> np.ndarray:
+        """Return array of shape (n_samples, 2): P(class 0), P(class 1)."""
+        prob_pos = _sigmoid(self._raw_score(X))
+        return np.vstack([1 - prob_pos, prob_pos]).T
+
+    def predict(self, X, threshold: float = 0.5) -> np.ndarray:
+        """Return hard 0/1 predictions at the given probability threshold."""
+        return (self.predict_proba(X)[:, 1] >= threshold).astype(int)
+
+    def evaluate(self, X, y, threshold: float = 0.5, verbose: bool = True) -> dict:
+        """Predict on X and report confusion matrix, accuracy, precision,
+        recall, F1, and ROC-AUC against y. Returns the metrics dict."""
+        from .metrics import classification_report_dict, print_classification_report
+
+        y_prob = self.predict_proba(X)[:, 1]
+        y_pred = (y_prob >= threshold).astype(int)
+        report = classification_report_dict(y, y_pred, y_prob)
+        if verbose:
+            print_classification_report(report)
+        return report

kanboost/encoders.py

@@ -0,0 +1,81 @@
+"""
+Preprocessing utilities for KANBoost.
+
+KAN is sensitive to input scale (splines are defined on a bounded grid),
+so numeric features must be scaled/clipped, and categorical features
+must be encoded to numbers before reaching the model. This module
+automates both steps so the end user can pass a raw-ish DataFrame,
+similar to how CatBoost handles categorical columns internally.
+"""
+
+import numpy as np
+import pandas as pd
+from sklearn.preprocessing import RobustScaler
+
+
+class TabularPreprocessor:
+    """
+    Automatic preprocessing for mixed numeric/categorical tabular data.
+
+    - Numeric columns: outlier clipping (1st/99th percentile) + RobustScaler
+      + final clip to [-1, 1] (KAN's default spline grid range).
+    - Categorical columns: target-mean encoding (smoothed), computed on
+      the training fold only, to avoid leakage -- similar in spirit to
+      CatBoost's ordered target statistics (simplified, non-ordered version).
+    """
+
+    def __init__(self, categorical_cols=None, smoothing: float = 10.0):
+        self.categorical_cols = categorical_cols or []
+        self.smoothing = smoothing
+        self.numeric_cols_ = None
+        self.scaler_ = None
+        self.clip_low_ = None
+        self.clip_high_ = None
+        self.cat_maps_ = {}
+        self.global_mean_ = None
+
+    def fit(self, X: pd.DataFrame, y: np.ndarray):
+        self.numeric_cols_ = [c for c in X.columns if c not in self.categorical_cols]
+        self.global_mean_ = float(np.mean(y))
+
+        # --- numeric ---
+        if self.numeric_cols_:
+            X_num = X[self.numeric_cols_].to_numpy(dtype=float)
+            self.clip_low_ = np.nanpercentile(X_num, 1, axis=0)
+            self.clip_high_ = np.nanpercentile(X_num, 99, axis=0)
+            X_num = np.clip(X_num, self.clip_low_, self.clip_high_)
+            self.scaler_ = RobustScaler()
+            self.scaler_.fit(X_num)
+
+        # --- categorical: smoothed target-mean encoding ---
+        for col in self.categorical_cols:
+            stats = (
+                pd.DataFrame({col: X[col].astype(str), "y": y})
+                .groupby(col)["y"]
+                .agg(["mean", "count"])
+            )
+            smoothed = (
+                stats["mean"] * stats["count"] + self.global_mean_ * self.smoothing
+            ) / (stats["count"] + self.smoothing)
+            self.cat_maps_[col] = smoothed.to_dict()
+
+        return self
+
+    def transform(self, X: pd.DataFrame) -> np.ndarray:
+        parts = []
+        if self.numeric_cols_:
+            X_num = X[self.numeric_cols_].to_numpy(dtype=float)
+            X_num = np.clip(X_num, self.clip_low_, self.clip_high_)
+            X_num = self.scaler_.transform(X_num)
+            X_num = np.clip(X_num, -1, 1)
+            parts.append(X_num)
+
+        for col in self.categorical_cols:
+            mapping = self.cat_maps_[col]
+            encoded = X[col].astype(str).map(mapping).fillna(self.global_mean_)
+            parts.append(encoded.to_numpy(dtype=float).reshape(-1, 1))
+
+        return np.hstack(parts) if parts else np.empty((len(X), 0))
+
+    def fit_transform(self, X: pd.DataFrame, y: np.ndarray) -> np.ndarray:
+        return self.fit(X, y).transform(X)

kanboost/metrics.py

@@ -0,0 +1,59 @@
+"""
+Evaluation utilities for KANBoost models.
+
+Kept as plain functions (not baked only into the classifier) so they can
+also be reused by the tuning module and by users who just want metrics
+on any set of predictions.
+"""
+
+import numpy as np
+from sklearn.metrics import (
+    confusion_matrix,
+    f1_score,
+    precision_score,
+    recall_score,
+    accuracy_score,
+    roc_auc_score,
+)
+
+
+def classification_report_dict(y_true, y_pred, y_prob=None) -> dict:
+    """
+    Returns a dict with confusion matrix + standard classification
+    metrics. If y_prob (probability of the positive class) is given,
+    also includes ROC-AUC.
+    """
+    y_true = np.asarray(y_true)
+    y_pred = np.asarray(y_pred)
+
+    cm = confusion_matrix(y_true, y_pred)
+    report = {
+        "confusion_matrix": cm.tolist(),
+        "confusion_matrix_labels": ["true_negative_row0", "true_positive_row1"],
+        "accuracy": float(accuracy_score(y_true, y_pred)),
+        "precision": float(precision_score(y_true, y_pred, zero_division=0)),
+        "recall": float(recall_score(y_true, y_pred, zero_division=0)),
+        "f1": float(f1_score(y_true, y_pred, zero_division=0)),
+    }
+    if y_prob is not None:
+        try:
+            report["auc"] = float(roc_auc_score(y_true, y_prob))
+        except ValueError:
+            report["auc"] = None
+    return report
+
+
+def print_classification_report(report: dict, class_names=("0", "1")) -> None:
+    """Pretty-print a report dict returned by classification_report_dict."""
+    cm = np.array(report["confusion_matrix"])
+    print("Confusion Matrix:")
+    print(f"                 predicted {class_names[0]}   predicted {class_names[1]}")
+    print(f"    actual {class_names[0]:>3}      {cm[0, 0]:>10d}      {cm[0, 1]:>10d}")
+    print(f"    actual {class_names[1]:>3}      {cm[1, 0]:>10d}      {cm[1, 1]:>10d}")
+    print()
+    print(f"Accuracy : {report['accuracy']:.4f}")
+    print(f"Precision: {report['precision']:.4f}")
+    print(f"Recall   : {report['recall']:.4f}")
+    print(f"F1 score : {report['f1']:.4f}")
+    if report.get("auc") is not None:
+        print(f"ROC-AUC  : {report['auc']:.4f}")

kanboost/regressor.py

@@ -0,0 +1,113 @@
+"""
+KANBoostRegressor: regression via gradient boosting with shallow KAN
+learners, minimizing squared error (residual = y - F(x) directly).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import torch
+
+from sklearn.base import RegressorMixin
+
+from ._base import _BaseKANBoost, _validate_Xy
+
+
+class KANBoostRegressor(RegressorMixin, _BaseKANBoost):
+    """Gradient-boosted KAN ensemble for regression (squared-error loss).
+
+    Parameters are identical to KANBoostClassifier; see its docstring.
+    """
+
+
+    def fit(self, X, y, eval_set: tuple | None = None):
+        """Fit the boosted ensemble.
+
+        Parameters
+        ----------
+        X : DataFrame or array of shape (n_samples, n_features)
+        y : array of shape (n_samples,), continuous target
+        eval_set : (X_val, y_val) tuple, optional
+            Validation data for early stopping on MSE.
+        """
+        X, y, X_arr = self._prepare_fit(X, y)
+
+        X_t = torch.tensor(X_arr, dtype=torch.float32)
+        n_features = X_arr.shape[1]
+
+        self.init_pred_ = float(y.mean())
+        F = np.full(len(y), self.init_pred_)
+
+        X_val_t = y_val = F_val = None
+        if eval_set is not None:
+            X_val_df, y_val = eval_set
+            X_val_df, y_val = _validate_Xy(X_val_df, y_val)
+            X_val_arr = self.preprocessor_.transform(X_val_df)
+            X_val_t = torch.tensor(X_val_arr, dtype=torch.float32)
+            F_val = np.full(len(y_val), self.init_pred_)
+
+        best_val_loss = np.inf
+        rounds_since_best = 0
+        self.learners_ = []
+        self.best_iteration_ = None
+
+        for t in range(self.n_estimators):
+            residual = y - F
+
+            learner = self._new_learner(n_features, seed_offset=t)
+            update = self._fit_learner(learner, X_t, residual)
+            F += self.learning_rate * update
+            self.learners_.append(learner)
+
+            if X_val_t is not None:
+                with torch.no_grad():
+                    F_val += self.learning_rate * learner(X_val_t).numpy().flatten()
+                val_loss = float(np.mean((y_val - F_val) ** 2))
+
+                if self.verbose:
+                    print(f"[{t + 1}/{self.n_estimators}] val_mse={val_loss:.5f}")
+
+                if val_loss < best_val_loss - 1e-6:
+                    best_val_loss = val_loss
+                    rounds_since_best = 0
+                    self.best_iteration_ = t + 1
+                else:
+                    rounds_since_best += 1
+                    if (self.early_stopping_rounds is not None
+                            and rounds_since_best >= self.early_stopping_rounds):
+                        if self.verbose:
+                            print(f"Early stopping at iteration {t + 1}")
+                        break
+
+        if self.best_iteration_ is None:
+            self.best_iteration_ = len(self.learners_)
+        return self
+
+    def predict(self, X) -> np.ndarray:
+        """Return continuous predictions of shape (n_samples,)."""
+        X_t = self._transform_X(X)
+        F = np.full(X_t.shape[0], self.init_pred_)
+        for learner in self.learners_[: self.best_iteration_]:
+            with torch.no_grad():
+                F += self.learning_rate * learner(X_t).numpy().flatten()
+        return F
+
+    def evaluate(self, X, y, verbose: bool = True) -> dict:
+        """Predict on X and report MSE, RMSE, MAE, and R^2 against y."""
+        from sklearn.metrics import (
+            mean_squared_error, mean_absolute_error, r2_score,
+        )
+
+        y = np.asarray(y, dtype=float).ravel()
+        y_pred = self.predict(X)
+        mse = float(mean_squared_error(y, y_pred))
+        report = {
+            "mse": mse,
+            "rmse": float(np.sqrt(mse)),
+            "mae": float(mean_absolute_error(y, y_pred)),
+            "r2": float(r2_score(y, y_pred)),
+        }
+        if verbose:
+            for k, v in report.items():
+                print(f"{k.upper():5s}: {v:.5f}")
+        return report

kanboost-0.0.1.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: kanboost
+Version: 0.0.1
+Summary: Gradient boosting with Kolmogorov-Arnold Network (KAN) learners -- an interpretable alternative to tree-based boosting (XGBoost/LightGBM/CatBoost).
+Author: Tuama M Hamzah
+License: MIT License
+        
+        Copyright (c) 2026 Tuama M Hamzah
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/tuamah/kanboost
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pykan>=0.2.5
+Requires-Dist: torch>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=1.5
+Requires-Dist: scikit-learn>=1.3
+Dynamic: license-file
+
+# KANBoost
+
+**Gradient boosting with Kolmogorov-Arnold Network (KAN) learners** — an
+interpretable, from-scratch alternative to tree-based boosting frameworks
+(XGBoost, LightGBM, CatBoost).
+
+Instead of decision trees as weak learners, KANBoost fits a sequence of
+small, shallow [KAN](https://arxiv.org/abs/2404.19756) networks to the
+pseudo-residuals of the previous stage, following the classic Friedman
+(2001) gradient boosting recipe. Because each KAN edge is a learnable
+univariate spline rather than an opaque weight, the resulting ensemble
+exposes per-feature shape functions that are directly inspectable —
+closer to a Generalized Additive Model than a black box.
+
+> **Status: early-stage research project.** This is *not* a drop-in
+> replacement for CatBoost/XGBoost in production. See
+> [Benchmarks](#benchmarks) and [Honest limitations](#honest-limitations)
+> below before using this for anything important.
+
+## Why this exists
+
+As of mid-2026, there is no widely-used, pip-installable library that
+combines KAN with gradient boosting. A closely related idea was
+published as **GB-KAN** (ICAART 2026), but no public code accompanies
+that paper. KANBoost is an independent, from-scratch open-source
+implementation of the same general idea, plus:
+
+- automatic handling of categorical features (smoothed target-mean
+  encoding, done fold-safe), instead of requiring manual one-hot encoding
+- built-in early stopping on a validation set
+- approximate feature importances derived from learned spline coefficients
+
+## Install
+
+```bash
+git clone https://github.com/tuamah/kanboost.git
+cd kanboost
+pip install -r requirements.txt
+pip install -e .
+```
+
+## Quickstart
+
+```python
+import pandas as pd
+from sklearn.model_selection import train_test_split
+from kanboost import KANBoostClassifier
+
+df = pd.read_csv("your_data.csv")
+X = df.drop(columns=["target"])
+y = df["target"].values
+
+X_train, X_val, y_train, y_val = train_test_split(X, y, test_size=0.2)
+
+model = KANBoostClassifier(
+    n_estimators=100,
+    learning_rate=0.2,
+    kan_hidden=4,
+    kan_grid=3,
+    categorical_cols=["region", "plan_type"],  # optional
+    early_stopping_rounds=10,
+)
+model.fit(X_train, y_train, eval_set=(X_val, y_val))
+
+probs = model.predict_proba(X_val)[:, 1]
+importances = model.feature_importances()
+```
+
+## Benchmarks
+
+Preliminary results on a real-world telecom churn dataset (100K rows,
+10 numeric features used, 8K-row sample for the KANBoost run due to
+current training-speed limits):
+
+| Model | Test AUC | Notes |
+|---|---|---|
+| CatBoost (tuned, full data, ~100 columns) | **0.6992** | production baseline |
+| KANBoostClassifier (this repo, 10 features, 8K sample) | 0.64 | early prototype, untuned |
+| Plain KAN (no boosting) | 0.65 | single model, same features |
+| Plain MLP | 0.59–0.62 | same features |
+
+**Read this table honestly**: KANBoost does not yet beat CatBoost on
+this dataset. The goal of this repo, at this stage, is to establish a
+working, extensible implementation and an honest baseline — not to claim
+state-of-the-art results.
+
+## Honest limitations
+
+- **Speed**: each weak learner is a full KAN forward/backward pass in
+  pure PyTorch. This is currently far slower per-iteration than a
+  histogram-based tree split in XGBoost/CatBoost/LightGBM.
+- **Tuning**: hyperparameters (`kan_grid`, `kan_hidden`, `kan_steps`,
+  `learning_rate`) interact in ways that are not yet well understood;
+  expect to need real tuning for your dataset.
+- **Categorical encoding** is a simple smoothed target-mean encoder, not
+  CatBoost's ordered boosting scheme — it can leak on small folds if not
+  used carefully.
+- **Missing values** are not yet handled natively; impute before fitting.
+
+## Roadmap
+
+See [`ROADMAP.md`](./ROADMAP.md) for the full project plan, including
+planned speed optimizations (FastKAN-style RBF basis, `torch.compile`),
+symbolic-formula extraction for the full ensemble, and benchmark
+expansion to standard UCI datasets.
+
+## Contributing
+
+Issues and PRs welcome, especially:
+- speed optimizations for the per-iteration KAN fit
+- better categorical encoding
+- benchmark results on additional public datasets
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).
+
+## Citation / related work
+
+If you use this, please also cite the KAN paper and, where relevant,
+the GB-KAN paper this project is conceptually closest to:
+
+```
+Liu, Z., Wang, Y., Vaidya, S., et al. (2024). KAN: Kolmogorov-Arnold
+Networks. arXiv:2404.19756.
+
+[GB-KAN authors] (2026). Gradient Boosting with Interpretable
+Kolmogorov-Arnold Networks. ICAART 2026.
+```

kanboost-0.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+kanboost/__init__.py,sha256=bLGvCFaiCYC3ik9N1ScWH38UI5WJZfbvGnbL3wThhaY,775
+kanboost/_base.py,sha256=Vmxzg1p2R3EdlIB8vUXIcNXNtLDbniHi1_Z7l7zku6o,7142
+kanboost/classifier.py,sha256=6Vqv-xQIgusAnyee-Uk6kqIzg2PFpeEU04jzSDcL3Lw,6662
+kanboost/encoders.py,sha256=FU_CFkGNQwoY7DJU_7b4bgvcYNcAien13Wm_kFie9Sc,3182
+kanboost/metrics.py,sha256=YpgMHR1VpM1KMfMmNJOB6-W3cqVdg8pDa7EM_oXQH4c,2132
+kanboost/regressor.py,sha256=uQjNrMzd4lHf6MqIrtP-i9e5fAkXGxAhJ__4buXlMDw,3981
+kanboost-0.0.1.dist-info/licenses/LICENSE,sha256=TibUcjm19hWQsu8odGoBCn5xJmN3FV7n8cKriciimJ8,1071
+kanboost-0.0.1.dist-info/METADATA,sha256=au9AODbHCp2W0EfLxGUVNpMsl9YpzWhHz1bYrZT7mg4,6729
+kanboost-0.0.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+kanboost-0.0.1.dist-info/top_level.txt,sha256=Smj79RKLj6B69IA60ZJUtsYUQb5eYdZwOMIrwYVEHcg,9
+kanboost-0.0.1.dist-info/RECORD,,

kanboost-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kanboost-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tuama M Hamzah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kanboost-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+kanboost