perpetual 1.0.40__cp311-cp311-macosx_10_12_x86_64.whl

perpetual/data.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass
+from typing import Any, Iterable, Optional, Union
+
+
+@dataclass
+class Node:
+    """Dataclass representation of a node, this represents all of the fields present in a tree node."""
+
+    num: int
+    weight_value: float
+    hessian_sum: float
+    depth: int = 0
+    split_value: float = 0.0
+    split_feature: Union[str, int] = ""
+    split_gain: float = 0.0
+    missing_node: int = 0
+    left_child: int = 0
+    right_child: int = 0
+    is_leaf: bool = False
+    node_type: str = "split"
+    parent_node: int = 0
+    generalization: Optional[float] = None
+    left_cats: Optional[Iterable] = None
+    right_cats: Optional[Iterable] = None
+    count: int = 0
+    weights: Optional[Iterable[float]] = None
+    stats: Optional[Any] = None

perpetual/serialize.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from ast import literal_eval
+from dataclasses import dataclass
+from typing import Dict, Generic, List, Tuple, TypeVar, Union
+
+import numpy as np
+import numpy.typing as npt
+
+T = TypeVar("T")
+
+
+class BaseSerializer(ABC, Generic[T]):
+    @abstractmethod
+    def serialize(self, obj: T) -> str:
+        """serialize method - should take an object and return a string"""
+
+    @abstractmethod
+    def deserialize(self, obj_repr: str) -> T:
+        """deserialize method - should take a string and return original object"""
+
+
+Scaler = Union[int, float, str]
+
+
+class ScalerSerializer(BaseSerializer[Scaler]):
+    def serialize(self, obj: Scaler) -> str:
+        if isinstance(obj, str):
+            obj_ = f"'{obj}'"
+        else:
+            obj_ = str(obj)
+        return obj_
+
+    def deserialize(self, obj_repr: str) -> Scaler:
+        return literal_eval(node_or_string=obj_repr)
+
+
+ObjectItem = Union[
+    List[Scaler],
+    Dict[str, Scaler],
+    Scaler,
+]
+
+
+class ObjectSerializer(BaseSerializer[ObjectItem]):
+    def serialize(self, obj: ObjectItem) -> str:
+        return json.dumps(obj)
+
+    def deserialize(self, obj_repr: str) -> ObjectItem:
+        return json.loads(obj_repr)
+
+
+@dataclass
+class NumpyData:
+    array: Union[List[float], List[int]]
+    dtype: str
+    shape: Tuple[int, ...]
+
+
+class NumpySerializer(BaseSerializer[npt.NDArray]):
+    def serialize(self, obj: npt.NDArray) -> str:
+        return json.dumps(
+            {"array": obj.tolist(), "dtype": str(obj.dtype), "shape": obj.shape}
+        )
+
+    def deserialize(self, obj_repr: str) -> npt.NDArray:
+        data = NumpyData(**json.loads(obj_repr))
+        a = np.array(data.array, dtype=data.dtype)  # type: ignore
+        if len(data.shape) == 1:
+            return a
+        else:
+            return a.reshape(data.shape)

perpetual/sklearn.py

@@ -0,0 +1,194 @@
+import warnings
+from types import FunctionType
+from typing import Any, Dict, Optional, Tuple, Union
+
+from sklearn.base import ClassifierMixin, RegressorMixin
+from sklearn.metrics import accuracy_score, r2_score
+from typing_extensions import Self
+
+from perpetual.booster import PerpetualBooster
+
+
+class PerpetualClassifier(PerpetualBooster, ClassifierMixin):
+    """
+    A scikit-learn compatible classifier based on PerpetualBooster.
+    Uses 'LogLoss' as the default objective.
+    """
+
+    # Expose the objective explicitly in the __init__ signature to allow
+    # scikit-learn to correctly discover and set it via set_params.
+    def __init__(
+        self,
+        *,
+        objective: Union[
+            str, Tuple[FunctionType, FunctionType, FunctionType]
+        ] = "LogLoss",
+        budget: float = 0.5,
+        num_threads: Optional[int] = None,
+        monotone_constraints: Union[Dict[Any, int], None] = None,
+        # ... other parameters ...
+        max_bin: int = 256,
+        max_cat: int = 1000,
+        # Capture all parameters in a way that BaseEstimator can handle
+        **kwargs,
+    ):
+        # Ensure the objective is one of the valid classification objectives
+        valid_objectives = {
+            "LogLoss"
+        }  # Assuming only LogLoss for classification for simplicity
+        if isinstance(objective, str) and objective not in valid_objectives:
+            # Custom objectives are allowed via the tuple form
+            pass
+
+        super().__init__(
+            objective=objective,
+            budget=budget,
+            num_threads=num_threads,
+            monotone_constraints=monotone_constraints,
+            # ... pass all other parameters ...
+            max_bin=max_bin,
+            max_cat=max_cat,
+            **kwargs,  # Catch-all for any other parameters passed by user or set_params
+        )
+
+    # fit, predict, predict_proba, and predict_log_proba are inherited
+    # and properly adapted in PerpetualBooster.
+
+    def score(self, X, y, sample_weight=None):
+        """Returns the mean accuracy on the given test data and labels."""
+        preds = self.predict(X)
+        return accuracy_score(y, preds, sample_weight=sample_weight)
+
+    def fit(self, X, y, sample_weight=None, **fit_params) -> Self:
+        """A wrapper for the base fit method."""
+        # Check if objective is appropriate for classification if it's a string
+        if isinstance(self.objective, str) and self.objective not in ["LogLoss"]:
+            warnings.warn(
+                f"Objective '{self.objective}' is typically for regression/ranking but used in PerpetualClassifier. Consider 'LogLoss'."
+            )
+
+        # In classification, the labels (classes_) are set in the base fit.
+        return super().fit(X, y, sample_weight=sample_weight, **fit_params)
+
+
+class PerpetualRegressor(PerpetualBooster, RegressorMixin):
+    """
+    A scikit-learn compatible regressor based on PerpetualBooster.
+    Uses 'SquaredLoss' as the default objective.
+    """
+
+    def __init__(
+        self,
+        *,
+        objective: Union[
+            str, Tuple[FunctionType, FunctionType, FunctionType]
+        ] = "SquaredLoss",
+        budget: float = 0.5,
+        num_threads: Optional[int] = None,
+        monotone_constraints: Union[Dict[Any, int], None] = None,
+        # ... other parameters ...
+        max_bin: int = 256,
+        max_cat: int = 1000,
+        **kwargs,
+    ):
+        # Enforce or warn about regression objectives
+        valid_objectives = {
+            "SquaredLoss",
+            "QuantileLoss",
+            "HuberLoss",
+            "AdaptiveHuberLoss",
+        }
+        if isinstance(objective, str) and objective not in valid_objectives:
+            pass  # Allow for custom string or tuple objective
+
+        super().__init__(
+            objective=objective,
+            budget=budget,
+            num_threads=num_threads,
+            monotone_constraints=monotone_constraints,
+            # ... pass all other parameters ...
+            max_bin=max_bin,
+            max_cat=max_cat,
+            **kwargs,
+        )
+
+    def fit(self, X, y, sample_weight=None, **fit_params) -> Self:
+        """A wrapper for the base fit method."""
+        # For regression, we typically enforce len(self.classes_) == 0 after fit
+        if isinstance(self.objective, str) and self.objective not in [
+            "SquaredLoss",
+            "QuantileLoss",
+            "HuberLoss",
+            "AdaptiveHuberLoss",
+        ]:
+            warnings.warn(
+                f"Objective '{self.objective}' may not be suitable for PerpetualRegressor. Consider 'SquaredLoss' or a quantile/huber loss."
+            )
+
+        return super().fit(X, y, sample_weight=sample_weight, **fit_params)
+
+    def score(self, X, y, sample_weight=None):
+        """Returns the coefficient of determination ($R^2$) of the prediction."""
+        preds = self.predict(X)
+        return r2_score(y, preds, sample_weight=sample_weight)
+
+
+class PerpetualRanker(
+    PerpetualBooster, RegressorMixin
+):  # Ranking models sometimes inherit from RegressorMixin for compatibility
+    """
+    A scikit-learn compatible ranker based on PerpetualBooster.
+    Uses 'ListNetLoss' as the default objective.
+    Requires the 'group' parameter to be passed to fit.
+    """
+
+    def __init__(
+        self,
+        *,
+        objective: Union[
+            str, Tuple[FunctionType, FunctionType, FunctionType]
+        ] = "ListNetLoss",
+        budget: float = 0.5,
+        num_threads: Optional[int] = None,
+        monotone_constraints: Union[Dict[Any, int], None] = None,
+        # ... other parameters ...
+        max_bin: int = 256,
+        max_cat: int = 1000,
+        **kwargs,
+    ):
+        if isinstance(objective, str) and objective not in {"ListNetLoss"}:
+            warnings.warn(
+                f"Objective '{objective}' may not be suitable for PerpetualRanker. Consider 'ListNetLoss'."
+            )
+
+        super().__init__(
+            objective=objective,
+            budget=budget,
+            num_threads=num_threads,
+            monotone_constraints=monotone_constraints,
+            # ... pass all other parameters ...
+            max_bin=max_bin,
+            max_cat=max_cat,
+            **kwargs,
+        )
+
+    def fit(self, X, y, group=None, sample_weight=None, **fit_params) -> Self:
+        """
+        Fit the ranker. Requires the 'group' parameter.
+
+        Args:
+            X: Training data.
+            y: Target relevance scores.
+            group: Group lengths to use for a ranking objective. (Required for ListNetLoss).
+            sample_weight: Instance weights.
+        """
+        if (
+            group is None
+            and isinstance(self.objective, str)
+            and self.objective == "ListNetLoss"
+        ):
+            raise ValueError(
+                "The 'group' parameter must be provided when using the 'ListNetLoss' objective for ranking."
+            )
+
+        return super().fit(X, y, sample_weight=sample_weight, group=group, **fit_params)

perpetual/types.py

@@ -0,0 +1,151 @@
+from typing import Any, Dict, Iterable, Protocol, Set
+
+import numpy as np
+from typing_extensions import Self
+
+
+class BoosterType(Protocol):
+    monotone_constraints: Dict[int, int]
+    terminate_missing_features: Set[int]
+    number_of_trees: int
+    base_score: float
+
+    def fit(
+        self,
+        flat_data: np.ndarray,
+        rows: int,
+        cols: int,
+        y: np.ndarray,
+        budget: float,
+        sample_weight: np.ndarray,
+        parallel: bool = False,
+    ):
+        """Fit method"""
+
+    def predict(
+        self,
+        flat_data: np.ndarray,
+        rows: int,
+        cols: int,
+        parallel: bool = True,
+    ) -> np.ndarray:
+        """predict method"""
+
+    def predict_proba(
+        self,
+        flat_data: np.ndarray,
+        rows: int,
+        cols: int,
+        parallel: bool = True,
+    ) -> np.ndarray:
+        """predict probabilities method"""
+
+    def predict_contributions(
+        self,
+        flat_data: np.ndarray,
+        rows: int,
+        cols: int,
+        method: str,
+        parallel: bool = True,
+    ) -> np.ndarray:
+        """method"""
+
+    def value_partial_dependence(
+        self,
+        feature: int,
+        value: float,
+    ) -> float:
+        """pass"""
+
+    def calculate_feature_importance(
+        self,
+        method: str,
+        normalize: bool,
+    ) -> Dict[int, float]:
+        """pass"""
+
+    def text_dump(self) -> Iterable[str]:
+        """pass"""
+
+    @classmethod
+    def load_booster(cls, path: str) -> Self:
+        """pass"""
+
+    def save_booster(self, path: str):
+        """pass"""
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Self:
+        """pass"""
+
+    def json_dump(self) -> str:
+        """pass"""
+
+    def get_params(self) -> Dict[str, Any]:
+        """pass"""
+
+    def insert_metadata(self, key: str, value: str) -> None:
+        """pass"""
+
+    def get_metadata(self, key: str) -> str:
+        """pass"""
+
+
+class MultiOutputBoosterType(Protocol):
+    monotone_constraints: Dict[int, int]
+    terminate_missing_features: Set[int]
+    number_of_trees: Iterable[int]
+    base_score: Iterable[float]
+
+    def fit(
+        self,
+        flat_data: np.ndarray,
+        rows: int,
+        cols: int,
+        y: np.ndarray,
+        budget: float,
+        sample_weight: np.ndarray,
+        parallel: bool = False,
+    ):
+        """Fit method"""
+
+    def predict(
+        self,
+        flat_data: np.ndarray,
+        rows: int,
+        cols: int,
+        parallel: bool = True,
+    ) -> np.ndarray:
+        """predict method"""
+
+    def predict_proba(
+        self,
+        flat_data: np.ndarray,
+        rows: int,
+        cols: int,
+        parallel: bool = True,
+    ) -> np.ndarray:
+        """predict probabilities method"""
+
+    @classmethod
+    def load_booster(cls, path: str) -> Self:
+        """pass"""
+
+    def save_booster(self, path: str):
+        """pass"""
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Self:
+        """pass"""
+
+    def json_dump(self) -> str:
+        """pass"""
+
+    def get_params(self) -> Dict[str, Any]:
+        """pass"""
+
+    def insert_metadata(self, key: str, value: str) -> None:
+        """pass"""
+
+    def get_metadata(self, key: str) -> str:
+        """pass"""