macboost 0.2.0__py3-none-any.whl

macboost/__init__.py

@@ -0,0 +1,360 @@
+"""macboost — gradient boosted trees on Apple-silicon GPUs (Metal).
+
+Scikit-learn-compatible estimators backed by the Swift/Metal core:
+
+    from macboost import MacBoostRegressor
+    model = MacBoostRegressor(n_estimators=200, max_depth=6)
+    model.fit(X_train, y_train, eval_set=(X_valid, y_valid),
+              early_stopping_rounds=50)
+    preds = model.predict(X_test)
+
+Parameter names follow the dialect LightGBM's and XGBoost's sklearn wrappers
+share; the well-known native spellings (num_iterations, eta, gamma,
+lambda_l2, ...) are accepted as aliases. get_params/set_params implement the
+scikit-learn estimator protocol, so clone, Pipeline, GridSearchCV and
+cross_val_score work.
+"""
+
+import numpy as np
+
+from . import _core
+from ._core import MacBoostError
+
+# scikit-learn is optional: when present, inheriting its base classes gives
+# full estimator-protocol compliance (__sklearn_tags__, clone, CV tooling).
+try:
+    from sklearn.base import BaseEstimator as _SkBase
+    from sklearn.base import ClassifierMixin as _SkClassifier
+    from sklearn.base import RegressorMixin as _SkRegressor
+except ImportError:
+    class _SkBase: pass
+    class _SkRegressor: pass
+    class _SkClassifier: pass
+
+__all__ = ["MacBoostRegressor", "MacBoostClassifier", "MacBoostError"]
+__version__ = "0.2.0"
+
+# Native LightGBM / XGBoost spellings -> canonical macboost names.
+_ALIASES = {
+    "num_trees": "n_estimators",
+    "num_iterations": "n_estimators",
+    "num_boost_round": "n_estimators",
+    "num_round": "n_estimators",
+    "eta": "learning_rate",
+    "shrinkage_rate": "learning_rate",
+    "lambda_l2": "reg_lambda",
+    "reg_lambda_l2": "reg_lambda",
+    "gamma": "min_split_gain",
+    "min_split_loss": "min_split_gain",
+    "min_gain_to_split": "min_split_gain",
+    "min_sum_hessian_in_leaf": "min_child_weight",
+    "max_bins": "max_bin",
+    "categorical_feature": "categorical_features",
+    "top_rate": "goss_top_rate",
+    "other_rate": "goss_other_rate",
+    "bagging_fraction": "subsample",
+    "feature_fraction": "colsample_bytree",
+    "colsample": "colsample_bytree",
+    "eval_metric": "metric",
+    "scale_pos_weight": "scale_pos_weight",
+    "monotone_constraints": "monotone_constraints",
+    "tweedie_variance_power": "tweedie_variance_power",
+}
+
+_PARAM_NAMES = (
+    "n_estimators", "max_depth", "learning_rate", "reg_lambda",
+    "min_child_weight", "min_split_gain", "max_bin", "categorical_features",
+    "cat_smooth", "early_stopping_rounds", "verbose",
+    "goss", "goss_top_rate", "goss_other_rate",
+    "objective", "alpha", "tweedie_variance_power", "scale_pos_weight",
+    "subsample", "colsample_bytree", "monotone_constraints", "metric",
+    "importance_type",
+)
+
+
+def _canonical(name):
+    return _ALIASES.get(name, name)
+
+
+class _BaseBooster:
+    _objective = "regression"
+
+    def __init__(self, n_estimators=100, max_depth=6, learning_rate=0.1,
+                 reg_lambda=1.0, min_child_weight=1.0, min_split_gain=0.0,
+                 max_bin=256, categorical_features=None, cat_smooth=10.0,
+                 early_stopping_rounds=0, verbose=False,
+                 goss=False, goss_top_rate=0.2, goss_other_rate=0.1,
+                 objective=None, alpha=0.9, tweedie_variance_power=1.5,
+                 scale_pos_weight=1.0, subsample=1.0, colsample_bytree=1.0,
+                 monotone_constraints=None, metric="auto",
+                 importance_type="gain", **aliases):
+        self.n_estimators = n_estimators
+        self.max_depth = max_depth
+        self.learning_rate = learning_rate
+        self.reg_lambda = reg_lambda
+        self.min_child_weight = min_child_weight
+        self.min_split_gain = min_split_gain
+        self.max_bin = max_bin
+        self.categorical_features = categorical_features
+        self.cat_smooth = cat_smooth
+        self.early_stopping_rounds = early_stopping_rounds
+        self.verbose = verbose
+        self.goss = goss
+        self.goss_top_rate = goss_top_rate
+        self.goss_other_rate = goss_other_rate
+        self.objective = objective
+        self.alpha = alpha
+        self.tweedie_variance_power = tweedie_variance_power
+        self.scale_pos_weight = scale_pos_weight
+        self.subsample = subsample
+        self.colsample_bytree = colsample_bytree
+        self.monotone_constraints = monotone_constraints
+        self.metric = metric
+        self.importance_type = importance_type
+        self._handle = None
+        self.classes_ = None
+        for key, value in aliases.items():
+            canon = _canonical(key)
+            if canon not in _PARAM_NAMES:
+                raise TypeError(f"unknown parameter '{key}'")
+            setattr(self, canon, value)
+
+    # -- scikit-learn estimator protocol ---------------------------------
+    def get_params(self, deep=True):
+        return {k: getattr(self, k) for k in _PARAM_NAMES}
+
+    def set_params(self, **params):
+        for key, value in params.items():
+            canon = _canonical(key)
+            if canon not in _PARAM_NAMES:
+                raise ValueError(f"unknown parameter '{key}' for {type(self).__name__}")
+            setattr(self, canon, value)
+        return self
+
+    # ---------------------------------------------------------------------
+    def _config(self, early_stopping_rounds, eval_every):
+        objective = self.objective or self._objective
+        cfg = {
+            "num_trees": self.n_estimators,
+            "max_depth": self.max_depth,
+            "learning_rate": self.learning_rate,
+            "lambda": self.reg_lambda,
+            "min_child_weight": self.min_child_weight,
+            "min_split_gain": self.min_split_gain,
+            "num_bins": self.max_bin,
+            "objective": objective,
+            "cat_smooth": self.cat_smooth,
+            "early_stopping_rounds": early_stopping_rounds,
+            "eval_every": eval_every,
+            "verbose": self.verbose,
+            "goss": self.goss,
+            "goss_top_rate": self.goss_top_rate,
+            "goss_other_rate": self.goss_other_rate,
+            "alpha": self.alpha,
+            "tweedie_variance_power": self.tweedie_variance_power,
+            "scale_pos_weight": self.scale_pos_weight,
+            "subsample": self.subsample,
+            "feature_fraction": self.colsample_bytree,
+        }
+        if self.metric and self.metric != "auto":
+            cfg["metric"] = self.metric
+        if self.monotone_constraints:
+            cfg["monotone_constraints"] = list(self.monotone_constraints)
+        if self.categorical_features:
+            cfg["categorical_features"] = list(self.categorical_features)
+        return cfg
+
+    def fit(self, X, y, eval_set=None, early_stopping_rounds=None, eval_every=0,
+            sample_weight=None, init_model=None):
+        if not _core.native_available():
+            raise MacBoostError(
+                "training requires the native Metal core (Apple silicon, "
+                "macOS 15+). This install supports inference only — use "
+                "load_model() to score models trained on a Mac.")
+        """Train. X: (n, f) array; NaN marks missing values. Columns listed
+        in categorical_features must hold integer category ids.
+
+        eval_set: (X_valid, y_valid) tuple, or [(X_valid, y_valid)] in the
+        LightGBM/XGBoost list style. early_stopping_rounds here overrides
+        the constructor value (both places accepted, like XGBoost)."""
+        if isinstance(eval_set, list):
+            if len(eval_set) != 1:
+                raise ValueError("only a single eval_set is supported")
+            eval_set = eval_set[0]
+        rounds = (self.early_stopping_rounds if early_stopping_rounds is None
+                  else early_stopping_rounds)
+        if rounds and eval_set is None:
+            raise ValueError("early stopping requires an eval_set")
+        cfg = self._config(rounds, eval_every)
+        y = self._encode_labels(y)
+        if eval_set is not None and self.classes_ is not None and len(self.classes_) > 0:
+            ev = eval_set if not isinstance(eval_set, list) else eval_set[0]
+            eval_set = (ev[0], self._transform_labels(ev[1]))
+        if self.classes_ is not None and len(self.classes_) > 2:
+            cfg["objective"] = "multiclass"
+            cfg["num_class"] = len(self.classes_)
+        import tempfile as _tmp
+        init_path = None
+        if init_model is not None:
+            if isinstance(init_model, (str, bytes)) or hasattr(init_model, "__fspath__"):
+                cfg["init_model"] = str(init_model)
+            else:
+                fd = _tmp.NamedTemporaryFile(suffix=".json", delete=False)
+                init_path = fd.name
+                fd.close()
+                init_model.save_model(init_path)
+                cfg["init_model"] = init_path
+        try:
+            self._handle = _core.train(cfg, X, y, eval_set, sample_weight)
+        finally:
+            if init_path:
+                import os as _os
+                _os.unlink(init_path)
+        import warnings as _warnings
+        for w in _core.warnings_of(self._handle):
+            _warnings.warn(w, UserWarning, stacklevel=2)
+        return self
+
+    def _raw_predict(self, X):
+        if getattr(self, "_pymodel", None) is not None:
+            return self._pymodel.predict_raw(np.asarray(X, dtype=np.float32))
+        if self._handle is None:
+            raise MacBoostError("model is not fitted; call fit() or load_model()")
+        return _core.predict(self._handle, X)
+
+    def _encode_labels(self, y):
+        return np.asarray(y, dtype=np.float32).ravel()
+
+    def _transform_labels(self, y):
+        return y
+
+    def feature_importance(self, importance_type=None):
+        if getattr(self, "_pymodel", None) is not None:
+            return self._pymodel.feature_importance(
+                importance_type or self.importance_type)
+        if self._handle is None:
+            raise MacBoostError("model is not fitted")
+        return _core.feature_importance(
+            self._handle, importance_type or self.importance_type)
+
+    @property
+    def feature_importances_(self):
+        return self.feature_importance()
+
+    def predict_contrib(self, X):
+        """SHAP contributions, rows x (n_features + 1); the last column is
+        the expected value. Rows sum to the raw prediction."""
+        if getattr(self, "_pymodel", None) is not None:
+            raise MacBoostError(
+                "predict_contrib requires the native core; export the model "
+                "or score contributions on a Mac")
+        if self._handle is None:
+            raise MacBoostError("model is not fitted")
+        return _core.predict_contrib(self._handle, X)
+
+    def save_xgboost(self, path):
+        """Export as an XGBoost JSON model for deployment anywhere xgboost
+        runs (identical predictions; categorical splits are expanded into
+        equivalent numeric chains)."""
+        from . import export
+        export.save_xgboost(self, path)
+
+    def save_onnx(self, path):
+        """Export as an ONNX model (ai.onnx.ml TreeEnsemble) scoreable by
+        onnxruntime on any platform. Requires the `onnx` package."""
+        from . import export
+        export.save_onnx(self, path)
+
+    def save_model(self, path):
+        if getattr(self, "_pymodel", None) is not None:
+            return self._pymodel.save(path)
+        if self._handle is None:
+            raise MacBoostError("model is not fitted")
+        _core.save(self._handle, path)
+
+    @classmethod
+    def load_model(cls, path):
+        model = cls()
+        if _core.native_available():
+            model._handle = _core.load(path)
+        else:
+            # Pure-Python inference backend: works on any platform.
+            from ._pyinfer import PyModel
+            model._pymodel = PyModel(path)
+        return model
+
+    @property
+    def n_trees_(self):
+        if getattr(self, "_pymodel", None) is not None:
+            return self._pymodel.num_trees
+        return _core.num_trees(self._handle) if self._handle else 0
+
+    @property
+    def n_features_in_(self):
+        if getattr(self, "_pymodel", None) is not None:
+            return self._pymodel.num_features
+        return _core.num_features(self._handle) if self._handle else 0
+
+    # Back-compat spelling.
+    n_features_ = n_features_in_
+
+    @property
+    def best_iteration_(self):
+        best = _core.best_iteration(self._handle) if self._handle else 0
+        return best or None
+
+
+class MacBoostRegressor(_SkRegressor, _BaseBooster, _SkBase):
+    _objective = "regression"
+    _estimator_type = "regressor"
+
+    def predict(self, X):
+        if getattr(self, "_pymodel", None) is not None:
+            return self._pymodel.predict(np.asarray(X, dtype=np.float32))
+        return self._raw_predict(X)
+
+    def score(self, X, y):
+        """R^2, per the scikit-learn regressor contract."""
+        y = np.asarray(y, dtype=np.float64).ravel()
+        pred = self.predict(X).astype(np.float64)
+        ss_res = float(np.sum((y - pred) ** 2))
+        ss_tot = float(np.sum((y - y.mean()) ** 2))
+        return 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
+
+
+class MacBoostClassifier(_SkClassifier, _BaseBooster, _SkBase):
+    _objective = "binary"
+    _estimator_type = "classifier"
+
+    def _encode_labels(self, y):
+        y = np.asarray(y).ravel()
+        self.classes_ = np.unique(y)
+        if len(self.classes_) < 2:
+            raise ValueError("classifier needs at least 2 classes")
+        if len(self.classes_) > 128:
+            raise ValueError(
+                f"y has {len(self.classes_)} distinct values — is it continuous? "
+                "Use MacBoostRegressor for regression targets")
+        return self._transform_labels(y)
+
+    def _transform_labels(self, y):
+        y = np.asarray(y).ravel()
+        lookup = {c: i for i, c in enumerate(self.classes_)}
+        return np.asarray([lookup[v] for v in y], dtype=np.float32)
+
+    def predict_proba(self, X):
+        raw = self._raw_predict(X).astype(np.float64)
+        if raw.ndim == 2:                       # multiclass softmax
+            e = np.exp(raw - raw.max(axis=1, keepdims=True))
+            return e / e.sum(axis=1, keepdims=True)
+        p = 1.0 / (1.0 + np.exp(-raw))
+        return np.column_stack([1 - p, p])
+
+    def predict(self, X):
+        idx = np.argmax(self.predict_proba(X), axis=1)
+        classes = self.classes_ if self.classes_ is not None else np.array([0, 1])
+        return classes[idx]
+
+    def score(self, X, y):
+        """Accuracy, per the scikit-learn classifier contract."""
+        return float(np.mean(self.predict(X) == np.asarray(y).ravel()))

macboost/_core.py

@@ -0,0 +1,226 @@
+"""ctypes bridge to libmacboostc.dylib (the Swift core's C ABI)."""
+
+import ctypes
+import json
+import os
+from pathlib import Path
+
+import numpy as np
+
+
+def _find_library() -> str:
+    candidates = []
+    if env := os.environ.get("MACBOOST_LIB"):
+        candidates.append(Path(env))
+    pkg_dir = Path(__file__).resolve().parent
+    candidates.append(pkg_dir / "libmacboostc.dylib")
+    # Running from a source checkout: ../../.build/release relative to python/macboost.
+    repo = pkg_dir.parent.parent
+    candidates.append(repo / ".build" / "release" / "libmacboostc.dylib")
+    for c in candidates:
+        if c.is_file():
+            return str(c)
+    raise OSError(
+        "libmacboostc.dylib not found. Build it with `swift build -c release` "
+        "(or scripts/build_python.sh to bundle it), or set MACBOOST_LIB."
+    )
+
+
+_c_char_pp = ctypes.POINTER(ctypes.c_char_p)
+_f32_p = ctypes.POINTER(ctypes.c_float)
+
+_lib_instance = None
+
+
+class _LazyLib:
+    """Defers dylib loading so `import macboost` works on any platform;
+    only training/native inference require the Metal core."""
+
+    def __getattr__(self, name):
+        global _lib_instance
+        if _lib_instance is None:
+            if os.environ.get("MACBOOST_FORCE_PYTHON"):
+                raise OSError("MACBOOST_FORCE_PYTHON is set")
+            _lib_instance = ctypes.CDLL(_find_library())
+            _configure(_lib_instance)
+        return getattr(_lib_instance, name)
+
+
+def native_available() -> bool:
+    try:
+        _lib.macboost_num_trees   # noqa: B018 — probe the load
+        return True
+    except OSError:
+        return False
+
+
+_lib = _LazyLib()
+
+def _configure(_lib):
+    _lib.macboost_train.restype = ctypes.c_void_p
+    _lib.macboost_train.argtypes = [
+        ctypes.c_char_p, _f32_p, ctypes.c_int64, ctypes.c_int64, _f32_p, _f32_p,
+        _f32_p, ctypes.c_int64, _f32_p, _c_char_pp,
+    ]
+    _lib.macboost_predict_contrib.restype = ctypes.c_int32
+    _lib.macboost_predict_contrib.argtypes = [
+        ctypes.c_void_p, _f32_p, ctypes.c_int64, ctypes.c_int64, _f32_p, _c_char_pp,
+    ]
+    _lib.macboost_feature_importance.restype = ctypes.c_int32
+    _lib.macboost_feature_importance.argtypes = [ctypes.c_void_p, ctypes.c_int32, _f32_p]
+    _lib.macboost_predict.restype = ctypes.c_int32
+    _lib.macboost_predict.argtypes = [
+        ctypes.c_void_p, _f32_p, ctypes.c_int64, ctypes.c_int64, _f32_p, _c_char_pp,
+    ]
+    _lib.macboost_save.restype = ctypes.c_int32
+    _lib.macboost_save.argtypes = [ctypes.c_void_p, ctypes.c_char_p, _c_char_pp]
+    _lib.macboost_load.restype = ctypes.c_void_p
+    _lib.macboost_load.argtypes = [ctypes.c_char_p, _c_char_pp]
+    for name in ("macboost_num_trees", "macboost_num_features", "macboost_best_iteration",
+                 "macboost_num_classes"):
+        fn = getattr(_lib, name)
+        fn.restype = ctypes.c_int64
+        fn.argtypes = [ctypes.c_void_p]
+    _lib.macboost_warnings.restype = ctypes.c_void_p   # char* we must free ourselves
+    _lib.macboost_warnings.argtypes = [ctypes.c_void_p]
+    _lib.macboost_free.restype = None
+    _lib.macboost_free.argtypes = [ctypes.c_void_p]
+    _lib.macboost_free_string.restype = None
+    _lib.macboost_free_string.argtypes = [ctypes.c_char_p]
+
+
+class MacBoostError(RuntimeError):
+    pass
+
+
+def _take_error(err: ctypes.c_char_p) -> str:
+    msg = err.value.decode() if err.value else "unknown error"
+    # err.value copies the bytes; free the C string.
+    _lib.macboost_free_string(err)
+    return msg
+
+
+def _feature_major(X) -> tuple[np.ndarray, int, int]:
+    """(n, f) array-like -> contiguous feature-major float32 + (rows, cols)."""
+    a = np.asarray(X, dtype=np.float32)
+    if a.ndim != 2:
+        raise ValueError(f"X must be 2-dimensional, got shape {a.shape}")
+    rows, cols = a.shape
+    return np.ascontiguousarray(a.T), rows, cols
+
+
+def _f32(a: np.ndarray) -> "ctypes._Pointer":
+    return a.ctypes.data_as(_f32_p)
+
+
+class _Handle:
+    """Owns a booster handle and frees it on GC."""
+
+    def __init__(self, ptr: int):
+        self.ptr = ptr
+
+    def __del__(self):
+        if getattr(self, "ptr", None):
+            _lib.macboost_free(self.ptr)
+            self.ptr = None
+
+
+def train(config: dict, X, y, eval_set=None, sample_weight=None) -> _Handle:
+    Xf, rows, cols = _feature_major(X)
+    ya = np.ascontiguousarray(np.asarray(y, dtype=np.float32).ravel())
+    if ya.shape[0] != rows:
+        raise ValueError(f"y has {ya.shape[0]} rows, X has {rows}")
+    w_ptr = None
+    if sample_weight is not None:
+        wa = np.ascontiguousarray(np.asarray(sample_weight, dtype=np.float32).ravel())
+        if wa.shape[0] != rows:
+            raise ValueError(f"sample_weight has {wa.shape[0]} rows, X has {rows}")
+        w_ptr = _f32(wa)
+
+    xv_ptr, yv_ptr, vrows = None, None, 0
+    if eval_set is not None:
+        Xv, yv = eval_set
+        Xvf, vrows, vcols = _feature_major(Xv)
+        if vcols != cols:
+            raise ValueError("eval_set feature count differs from X")
+        yva = np.ascontiguousarray(np.asarray(yv, dtype=np.float32).ravel())
+        if yva.shape[0] != vrows:
+            raise ValueError("eval_set X/y row mismatch")
+        xv_ptr, yv_ptr = _f32(Xvf), _f32(yva)
+
+    err = ctypes.c_char_p()
+    ptr = _lib.macboost_train(
+        json.dumps(config).encode(), _f32(Xf), rows, cols, _f32(ya), w_ptr,
+        xv_ptr, vrows, yv_ptr, ctypes.byref(err),
+    )
+    if not ptr:
+        raise MacBoostError(_take_error(err))
+    return _Handle(ptr)
+
+
+def predict(handle: _Handle, X) -> np.ndarray:
+    Xf, rows, cols = _feature_major(X)
+    k = _lib.macboost_num_classes(handle.ptr)
+    out = np.empty(rows * k, dtype=np.float32)
+    err = ctypes.c_char_p()
+    rc = _lib.macboost_predict(handle.ptr, _f32(Xf), rows, cols, _f32(out),
+                               ctypes.byref(err))
+    if rc != 0:
+        raise MacBoostError(_take_error(err))
+    return out.reshape(rows, k) if k > 1 else out
+
+
+def predict_contrib(handle: _Handle, X) -> np.ndarray:
+    Xf, rows, cols = _feature_major(X)
+    k = _lib.macboost_num_classes(handle.ptr)
+    out = np.empty(rows * k * (cols + 1), dtype=np.float32)
+    err = ctypes.c_char_p()
+    rc = _lib.macboost_predict_contrib(handle.ptr, _f32(Xf), rows, cols,
+                                       _f32(out), ctypes.byref(err))
+    if rc != 0:
+        raise MacBoostError(_take_error(err))
+    return out.reshape(rows, k * (cols + 1))
+
+
+def feature_importance(handle: _Handle, importance_type: str) -> np.ndarray:
+    n = _lib.macboost_num_features(handle.ptr)
+    out = np.empty(n, dtype=np.float32)
+    t = 1 if importance_type == "split" else 0
+    if _lib.macboost_feature_importance(handle.ptr, t, _f32(out)) != 0:
+        raise MacBoostError("feature_importance failed")
+    return out
+
+
+def save(handle: _Handle, path: str) -> None:
+    err = ctypes.c_char_p()
+    if _lib.macboost_save(handle.ptr, str(path).encode(), ctypes.byref(err)) != 0:
+        raise MacBoostError(_take_error(err))
+
+
+def load(path: str) -> _Handle:
+    err = ctypes.c_char_p()
+    ptr = _lib.macboost_load(str(path).encode(), ctypes.byref(err))
+    if not ptr:
+        raise MacBoostError(_take_error(err))
+    return _Handle(ptr)
+
+
+def warnings_of(handle: _Handle) -> list[str]:
+    ptr = _lib.macboost_warnings(handle.ptr)
+    if not ptr:
+        return []
+    text = ctypes.string_at(ptr).decode()
+    _lib.macboost_free_string(ctypes.cast(ptr, ctypes.c_char_p))
+    return text.splitlines()
+
+
+def num_trees(handle: _Handle) -> int:
+    return _lib.macboost_num_trees(handle.ptr)
+
+
+def num_features(handle: _Handle) -> int:
+    return _lib.macboost_num_features(handle.ptr)
+
+
+def best_iteration(handle: _Handle) -> int:
+    return _lib.macboost_best_iteration(handle.ptr)

macboost/_pyinfer.py

@@ -0,0 +1,112 @@
+"""Pure-Python (numpy) inference over MacBoost model.json files.
+
+Training requires the Metal core (Apple silicon), but a trained model is
+just trees — this backend scores them anywhere Python runs, so models
+trained on a Mac deploy to Linux with nothing but `pip install macboost`.
+Semantics match the native predictor exactly: `x <= threshold` goes left,
+NaN follows the learned default direction, categorical splits test bitmask
+membership (unseen/out-of-range categories route like missing), and
+poisson/tweedie outputs are exp-transformed.
+"""
+
+import json
+
+import numpy as np
+
+_LOG_LINK_OBJECTIVES = {5, 6}          # poisson, tweedie
+
+
+class PyModel:
+    """Reads the JSON written by MacBooster.save / save_model."""
+
+    def __init__(self, path):
+        with open(path) as fh:
+            m = json.load(fh)
+        if m.get("version") != 1:
+            raise ValueError("unsupported model file version")
+        self.objective = int(m["objective"])
+        self.num_bins = int(m["numBins"])
+        self.base_score = np.float32(m["baseScore"])
+        self.num_features = int(m["numFeatures"])
+        self.num_classes = int(m.get("numClasses") or 1)
+        self.base_scores = np.asarray(
+            m.get("baseScores") or [m["baseScore"]], dtype=np.float32)
+        self.feature_names = m.get("featureNames")
+        self._raw = m
+        self.trees = []
+        for t in m["trees"]:
+            tree = {
+                "feature": np.asarray(t["feature"], dtype=np.int64),
+                "threshold": np.asarray(t["threshold"], dtype=np.float32),
+                "leaf": np.asarray(t["leaf"], dtype=np.float32),
+                "flags": np.asarray(t["flags"], dtype=np.uint8),
+                "gain": np.asarray(t.get("gain") or [], dtype=np.float32),
+            }
+            mask = np.asarray(t.get("catMask") or [], dtype=np.uint64)
+            tree["catMask"] = mask.reshape(-1, 8) if mask.size else None
+            self.trees.append(tree)
+
+    @property
+    def num_trees(self):
+        return len(self.trees)
+
+    def predict_raw(self, X):
+        X = np.asarray(X, dtype=np.float32)
+        if X.ndim != 2 or X.shape[1] != self.num_features:
+            raise ValueError(
+                f"X must be (n, {self.num_features}), got {X.shape}")
+        n = X.shape[0]
+        K = self.num_classes
+        out = np.tile(self.base_scores, (n, 1)).astype(np.float32)   # (n, K)
+        for t, tree in enumerate(self.trees):
+            node = np.zeros(n, dtype=np.int64)
+            active = tree["feature"][node] >= 0
+            while active.any():
+                idx = np.nonzero(active)[0]
+                cur = node[idx]
+                v = X[idx, tree["feature"][cur]]
+                left = self._goes_left_at(tree, cur, v)
+                node[idx] = 2 * cur + 1 + (~left).astype(np.int64)
+                active[idx] = tree["feature"][node[idx]] >= 0
+            out[:, t % K] += tree["leaf"][node]
+        return out[:, 0] if K == 1 else out
+
+    def _goes_left_at(self, tree, node, v):
+        thr = tree["threshold"][node]
+        flags = tree["flags"][node]
+        left = v <= thr
+        nan = np.isnan(v)
+        if nan.any():
+            left = np.where(nan, (flags & 1) != 0, left)
+        cat_nodes = (flags & 2) != 0
+        if tree["catMask"] is not None and cat_nodes.any():
+            data_bins = self.num_bins - 1
+            cat = np.where(np.isfinite(v), np.rint(v), -1).astype(np.int64)
+            bad = (cat < 0) | (cat >= data_bins)
+            cat = np.where(bad, data_bins, cat)
+            words = tree["catMask"][node, cat >> 5]
+            member = ((words >> (cat & 31).astype(np.uint64)) & 1).astype(bool)
+            left = np.where(cat_nodes, member, left)
+        return left
+
+    def predict(self, X):
+        out = self.predict_raw(X)
+        if self.objective in _LOG_LINK_OBJECTIVES:
+            out = np.exp(out)
+        return out
+
+    def feature_importance(self, importance_type="gain"):
+        imp = np.zeros(self.num_features, dtype=np.float32)
+        for tree in self.trees:
+            splits = tree["feature"] >= 0
+            feats = tree["feature"][splits]
+            if importance_type == "split":
+                np.add.at(imp, feats, 1)
+            else:
+                np.add.at(imp, feats, tree["gain"][splits]
+                          if tree["gain"].size else 0)
+        return imp
+
+    def save(self, path):
+        with open(path, "w") as fh:
+            json.dump(self._raw, fh)

macboost/export.py

@@ -0,0 +1,334 @@
+"""Export MacBoost models for deployment on non-Apple platforms.
+
+- save_xgboost(model, path): writes an XGBoost JSON model that standard
+  `xgboost` loads and scores anywhere (Linux servers, containers, ...).
+- to_onnx(model): builds an ONNX graph using the ai.onnx.ml TreeEnsemble
+  operators for onnxruntime everywhere (requires the `onnx` package).
+
+Semantics notes:
+- MacBoost splits are `x <= t` (left); XGBoost/ONNX-LEQ conventions are
+  matched exactly (thresholds nudged by one float32 ulp where needed).
+- Categorical subset splits have no direct equivalent in either target, so
+  they are rewritten into chains of numeric interval tests routing to
+  duplicated subtrees — identical predictions, larger trees. Unseen or
+  out-of-range categories route like missing values, as in MacBoost.
+- Raw-score regression objectives (l2/mae/huber/quantile) export as plain
+  regression; logistic/poisson/tweedie/multiclass map to the target's
+  equivalent transform. Base scores are folded into the first tree's
+  leaves so no cross-library base-score semantics are involved.
+"""
+
+import json
+import tempfile
+
+import numpy as np
+
+_FLAG_DEFAULT_LEFT = 1
+_FLAG_CATEGORICAL = 2
+
+
+def _model_dict(model):
+    """Model JSON dict from an estimator or a PyModel."""
+    pymodel = getattr(model, "_pymodel", None)
+    if pymodel is not None:
+        return pymodel._raw
+    with tempfile.NamedTemporaryFile(suffix=".json") as fh:
+        model.save_model(fh.name)
+        with open(fh.name) as f:
+            return json.load(f)
+
+
+class _Node:
+    __slots__ = ("feature", "threshold", "default_left", "left", "right", "value")
+
+    def __init__(self, feature=-1, threshold=0.0, default_left=False,
+                 left=-1, right=-1, value=0.0):
+        self.feature = feature          # -1 => leaf
+        self.threshold = threshold      # "x <= threshold" goes left
+        self.default_left = default_left
+        self.left = left
+        self.right = right
+        self.value = value
+
+
+def _explicit_tree(tree, num_bins):
+    """Heap-layout tree -> explicit numeric-only node list (categorical
+    splits expanded into interval chains with duplicated subtrees)."""
+    feature = tree["feature"]
+    threshold = tree["threshold"]
+    leaf = tree["leaf"]
+    flags = tree["flags"]
+    cat_mask = tree.get("catMask") or []
+    data_bins = num_bins - 1
+    nodes = []
+
+    def add(node):
+        nodes.append(node)
+        return len(nodes) - 1
+
+    def member(heap_idx, cat):
+        word = cat_mask[heap_idx * 8 + (cat >> 5)]
+        return (word >> (cat & 31)) & 1 == 1
+
+    def build(h):
+        f = int(feature[h])
+        if f < 0:
+            return add(_Node(value=float(leaf[h])))
+        fl = int(flags[h])
+        if fl & _FLAG_CATEGORICAL == 0:
+            n = add(_Node(feature=f, threshold=float(threshold[h]),
+                          default_left=bool(fl & _FLAG_DEFAULT_LEFT)))
+            nodes[n].left = build(2 * h + 1)
+            nodes[n].right = build(2 * h + 2)
+            return n
+
+        # Categorical: membership of ints 0..data_bins-1 (missing bin =
+        # data_bins participates too). Compress into runs of equal side,
+        # then a right-deep chain of `x <= run_end + 0.5` tests. NaN and
+        # out-of-range categories route to the missing bin's side.
+        sides = [member(h, c) for c in range(data_bins)]     # True => left
+        missing_left = member(h, data_bins)
+        runs = []                                            # (end_cat, side)
+        for c in range(data_bins):
+            if runs and runs[-1][1] == sides[c]:
+                runs[-1] = (c, sides[c])
+            else:
+                runs.append((c, sides[c]))
+
+        def side_subtree(left_side):
+            return build(2 * h + 1) if left_side else build(2 * h + 2)
+
+        # Trailing destination for x > last category: missing side.
+        chain = side_subtree(missing_left)
+        for end, side in reversed(runs):
+            n = add(_Node(feature=f, threshold=end + 0.5,
+                          default_left=(side == missing_left)))
+            nodes[n].left = side_subtree(side)
+            nodes[n].right = chain
+            chain = n
+        # Leading guard: x < 0 (invalid category) -> missing side.
+        n = add(_Node(feature=f, threshold=-0.5, default_left=missing_left))
+        nodes[n].left = side_subtree(missing_left)
+        nodes[n].right = chain
+        return n
+
+    root = build(0)
+    # BFS relabel: XGBoost allocates parents before children and its JSON
+    # loader relies on that ordering, so match it (root at index 0).
+    order = [root]
+    for i in order:
+        if nodes[i].feature >= 0:
+            order.append(nodes[i].left)
+            order.append(nodes[i].right)
+    remap = {old: new for new, old in enumerate(order)}
+    reordered = [nodes[old] for old in order]
+    for node in reordered:
+        if node.feature >= 0:
+            node.left = remap[node.left]
+            node.right = remap[node.right]
+    return reordered
+
+
+_NEUTRAL_BASE = {          # base_score whose margin is 0, per objective
+    "reg:squarederror": "0", "binary:logistic": "0.5",
+    "count:poisson": "1", "reg:tweedie": "1", "multi:softprob": "0.5",
+}
+
+
+def _xgb_objective(m):
+    obj = int(m["objective"])
+    if obj == 1:
+        return "binary:logistic", {"reg_loss_param": {"scale_pos_weight": "1"}}
+    if obj == 5:
+        return "count:poisson", {"poisson_regression_param": {"max_delta_step": "0.7"}}
+    if obj == 6:
+        return "reg:tweedie", {"tweedie_regression_param": {"tweedie_variance_power": "1.5"}}
+    if obj == 7:
+        k = str(int(m.get("numClasses") or 1))
+        return "multi:softprob", {"softmax_multiclass_param": {"num_class": k}}
+    # l2 / mae / huber / quantile: raw scores, plain regression at inference.
+    return "reg:squarederror", {"reg_loss_param": {"scale_pos_weight": "1"}}
+
+
+def to_xgboost_dict(model):
+    m = _model_dict(model)
+    num_features = int(m["numFeatures"])
+    num_bins = int(m["numBins"])
+    k = int(m.get("numClasses") or 1)
+    base_scores = m.get("baseScores") or [m["baseScore"]]
+    obj_name, obj_param = _xgb_objective(m)
+
+    trees_json = []
+    for t, tree in enumerate(m["trees"]):
+        nodes = _explicit_tree(tree, num_bins)
+        n = len(nodes)
+        left = [node.left for node in nodes]
+        right = [node.right for node in nodes]
+        parents = [2147483647] * n
+        for i, node in enumerate(nodes):
+            if node.feature >= 0:
+                parents[node.left] = i
+                parents[node.right] = i
+        conditions, indices, defaults, weights = [], [], [], []
+        for node in nodes:
+            if node.feature >= 0:
+                # xgb: x < condition goes left; ours: x <= t. Nudge up 1 ulp.
+                thr = float(np.nextafter(np.float32(node.threshold),
+                                         np.float32(np.inf)))
+                conditions.append(thr)
+                indices.append(node.feature)
+                defaults.append(1 if node.default_left else 0)
+                weights.append(0.0)
+            else:
+                value = node.value
+                # Fold per-class base scores into the first tree of each class.
+                if t < k:
+                    value += float(base_scores[t % k])
+                conditions.append(value)
+                indices.append(0)
+                defaults.append(0)
+                weights.append(value)
+        trees_json.append({
+            "base_weights": weights,
+            "categories": [], "categories_nodes": [],
+            "categories_segments": [], "categories_sizes": [],
+            "default_left": defaults,
+            "id": t,
+            "left_children": left,
+            "loss_changes": [0.0] * n,
+            "parents": parents,
+            "right_children": right,
+            "split_conditions": conditions,
+            "split_indices": indices,
+            "split_type": [0] * n,
+            "sum_hessian": [1.0] * n,
+            "tree_param": {
+                "num_deleted": "0",
+                "num_feature": str(num_features),
+                "num_nodes": str(n),
+                "size_leaf_vector": "1",
+            },
+        })
+
+    num_trees = len(trees_json)
+    rounds = num_trees // k if k else num_trees
+    return {
+        "learner": {
+            "attributes": {},
+            "feature_names": [],
+            "feature_types": [],
+            "gradient_booster": {
+                "model": {
+                    "gbtree_model_param": {
+                        "num_parallel_tree": "1",
+                        "num_trees": str(num_trees),
+                    },
+                    "iteration_indptr": [i * k for i in range(rounds + 1)],
+                    "tree_info": [t % k for t in range(num_trees)],
+                    "trees": trees_json,
+                },
+                "name": "gbtree",
+            },
+            "learner_model_param": {
+                "base_score": _NEUTRAL_BASE[obj_name],
+                "boost_from_average": "1",
+                "num_class": str(k if k > 1 else 0),
+                "num_feature": str(num_features),
+                "num_target": "1",
+            },
+            "objective": {"name": obj_name, **obj_param},
+        },
+        "version": [2, 1, 0],
+    }
+
+
+def save_xgboost(model, path):
+    """Write an XGBoost-format JSON model loadable by xgb.Booster()."""
+    with open(path, "w") as fh:
+        json.dump(to_xgboost_dict(model), fh)
+
+
+def to_onnx(model):
+    """Build an ONNX ModelProto (ai.onnx.ml TreeEnsembleRegressor).
+
+    The graph takes float input `(n, num_features)` and produces
+    `prediction`: raw scores for regression objectives, probabilities for
+    logistic (n, 1) / multiclass (n, K), and exp-transformed means for
+    poisson/tweedie. Requires the `onnx` package.
+    """
+    try:
+        from onnx import TensorProto, helper
+    except ImportError as e:
+        raise ImportError(
+            "ONNX export requires the `onnx` package: pip install onnx") from e
+
+    m = _model_dict(model)
+    num_features = int(m["numFeatures"])
+    num_bins = int(m["numBins"])
+    k = int(m.get("numClasses") or 1)
+    obj = int(m["objective"])
+    base_scores = [float(b) for b in (m.get("baseScores") or [m["baseScore"]])]
+
+    attrs = {
+        "nodes_treeids": [], "nodes_nodeids": [], "nodes_featureids": [],
+        "nodes_modes": [], "nodes_values": [], "nodes_truenodeids": [],
+        "nodes_falsenodeids": [], "nodes_missing_value_tracks_true": [],
+        "target_treeids": [], "target_nodeids": [], "target_ids": [],
+        "target_weights": [],
+    }
+    for t, tree in enumerate(m["trees"]):
+        for i, node in enumerate(_explicit_tree(tree, num_bins)):
+            attrs["nodes_treeids"].append(t)
+            attrs["nodes_nodeids"].append(i)
+            if node.feature >= 0:
+                attrs["nodes_featureids"].append(node.feature)
+                attrs["nodes_modes"].append("BRANCH_LEQ")   # v <= t: exact match
+                attrs["nodes_values"].append(node.threshold)
+                attrs["nodes_truenodeids"].append(node.left)
+                attrs["nodes_falsenodeids"].append(node.right)
+                attrs["nodes_missing_value_tracks_true"].append(
+                    1 if node.default_left else 0)
+            else:
+                attrs["nodes_featureids"].append(0)
+                attrs["nodes_modes"].append("LEAF")
+                attrs["nodes_values"].append(0.0)
+                attrs["nodes_truenodeids"].append(0)
+                attrs["nodes_falsenodeids"].append(0)
+                attrs["nodes_missing_value_tracks_true"].append(0)
+                attrs["target_treeids"].append(t)
+                attrs["target_nodeids"].append(i)
+                attrs["target_ids"].append(t % k)
+                attrs["target_weights"].append(node.value)
+
+    ensemble = helper.make_node(
+        "TreeEnsembleRegressor", ["input"], ["margin"],
+        domain="ai.onnx.ml", n_targets=k, base_values=base_scores,
+        post_transform="NONE", **attrs)
+    nodes = [ensemble]
+    if obj == 1:                                    # logistic -> probability
+        nodes.append(helper.make_node("Sigmoid", ["margin"], ["prediction"]))
+    elif obj == 7:                                  # multiclass -> probabilities
+        nodes.append(helper.make_node("Softmax", ["margin"], ["prediction"], axis=1))
+    elif obj in (5, 6):                             # poisson/tweedie -> mean
+        nodes.append(helper.make_node("Exp", ["margin"], ["prediction"]))
+    else:
+        nodes.append(helper.make_node("Identity", ["margin"], ["prediction"]))
+
+    graph = helper.make_graph(
+        nodes, "macboost",
+        [helper.make_tensor_value_info("input", TensorProto.FLOAT,
+                                       [None, num_features])],
+        [helper.make_tensor_value_info("prediction", TensorProto.FLOAT,
+                                       [None, k])],
+    )
+    onnx_model = helper.make_model(
+        graph, opset_imports=[helper.make_opsetid("ai.onnx.ml", 1),
+                              helper.make_opsetid("", 13)],
+        producer_name="macboost", ir_version=7)
+    return onnx_model
+
+
+def save_onnx(model, path):
+    """Write an ONNX model scoreable by onnxruntime on any platform."""
+    with open(path, "wb") as fh:
+        fh.write(to_onnx(model).SerializeToString())

macboost-0.2.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: macboost
+Version: 0.2.0
+Summary: Gradient boosted trees on Apple-silicon GPUs (Metal), sklearn-style API
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+
+# macboost (Python)
+
+Python bindings for [MacBoost](../README.md) — gradient boosted trees on
+Apple-silicon GPUs, with a scikit-learn-style API (`MacBoostRegressor`,
+`MacBoostClassifier`).
+
+Build the native core first, then install:
+
+```bash
+swift build -c release && ../scripts/build_python.sh   # bundles the dylib
+pip install .
+```
+
+See the repository README for usage and benchmarks.

macboost-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+macboost/__init__.py,sha256=GQZ_VjEvKduYMYCQsuTw8uJWV57yx3wRk5U2CVQXvkg,14586
+macboost/_core.py,sha256=aOKoUK_4hizN1Yx8AcTwwJPtxPUDF-ey1g6JW1fiSOA,7729
+macboost/_pyinfer.py,sha256=YBC5h77m2tMFadUghVlZduFBZOYbYsI8XpWSZcx0k8s,4470
+macboost/export.py,sha256=Ua7DxFw6n4GakECdYm3-SH4wlaZlmtBYI_qfzFunE6w,13346
+macboost/libmacboostc.dylib,sha256=wdnlEXR44vxqTnUW3QrjRxNO92S3QEJ9tMLassrHdPw,456288
+macboost-0.2.0.dist-info/METADATA,sha256=15VZhkSRh2_yRpvumTr9NBVR3vBis2i_b81TvkIUFIA,628
+macboost-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+macboost-0.2.0.dist-info/top_level.txt,sha256=7ER5jA9JUzdGk8Z9DkYnkCsbwLCQNH0PXCDmT1yKc2s,9
+macboost-0.2.0.dist-info/RECORD,,

macboost-0.2.0.dist-info/WHEEL

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

macboost-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+macboost