hnbm 0.1.0__tar.gz

hnbm-0.1.0/Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt setup.py setup.cfg MANIFEST.in README.md LICENSE ./
+COPY hnbm/ hnbm/
+
+RUN pip install --no-cache-dir --upgrade pip \
+ && pip install --no-cache-dir .
+
+CMD ["python", "-c", "from hnbm import HNBM; print('HNBM ready')"]

hnbm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qiancapital-dev
+
+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.

hnbm-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include requirements.txt
+include Dockerfile

hnbm-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: hnbm
+Version: 0.1.0
+Summary: Heterogeneous Newton Boosting Machine
+Home-page: https://github.com/qiancapital-dev/hnbm
+Author: Qian Capital
+Author-email: Qian Capital <samson.qian@qiancapital.com>
+License: MIT
+Project-URL: Homepage, https://github.com/qiancapital-dev/hnbm
+Keywords: boosting,gradient-boosting,hnbm,heterogeneous-newton
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: tqdm>=4.50
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# HNBM
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![scikit-learn](https://img.shields.io/badge/scikit--learn-compatible-blue.svg)](https://scikit-learn.org/)
+
+**Heterogeneous Newton Boosting Machine (HNBM)** — a scikit-learn-compatible gradient boosting framework that stochastically mixes heterogeneous base learners at each iteration.
+
+Unlike standard gradient boosting libraries that use a single learner type (typically decision trees), HNBM lets you define a pool of base learners with selection probabilities. At each boosting round, a learner is drawn from that pool and fit to the Newton step (gradient divided by Hessian, weighted by the Hessian).
+
+This is the core framework behind [SnapBoost](https://github.com/qiancapital/snapboost), inspired by [SnapBoost: A Heterogeneous Boosting Machine](https://arxiv.org/abs/2006.09745) (Parnell et al., NeurIPS 2020).
+
+---
+
+## Installation
+
+**From source** (recommended until PyPI release):
+
+```bash
+git clone https://github.com/qiancapital-dev/hnbm.git
+cd hnbm
+pip install .
+```
+
+**Requirements**: Python ≥ 3.8, NumPy, scikit-learn, tqdm.
+
+---
+
+## Quick Start
+
+Subclass `HNBM` and configure your base learner pool before training:
+
+```python
+from sklearn.datasets import load_breast_cancer
+from sklearn.model_selection import train_test_split
+from sklearn.tree import DecisionTreeRegressor
+from hnbm import HNBM
+
+X, y = load_breast_cancer(return_X_y=True)
+X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=42)
+
+
+class TreeBoost(HNBM):
+    def __init__(self, max_depth=5, **kwargs):
+        super().__init__(**kwargs)
+        self.base_learners_ = [DecisionTreeRegressor(max_depth=max_depth)]
+        self.probabilities_ = [1.0]
+
+
+model = TreeBoost(
+    num_iterations=100,
+    learning_rate=0.1,
+    mode="classification",
+    random_state=42,
+)
+model.fit(X_train, y_train)
+
+print("Accuracy:", model.score(X_test, y_test))
+model.evaluate(X_test, y_test)
+```
+
+---
+
+## API Reference
+
+### `HNBM`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `num_iterations` | `int` | `100` | Number of boosting rounds |
+| `learning_rate` | `float` | `0.1` | Shrinkage per learner |
+| `mode` | `str` | `"classification"` | `"classification"` or `"regression"` |
+| `random_state` | `int` or `None` | `None` | Seed for learner selection |
+| `verbose` | `bool` | `True` | Show tqdm progress bar |
+
+**Methods**
+
+| Method | Mode | Description |
+|--------|------|-------------|
+| `fit(X, y)` | both | Train the ensemble |
+| `predict(X)` | both | Class labels (0/1) or continuous values |
+| `predict_proba(X)` | classification | Probabilities, shape `(n_samples, 2)` |
+| `decision_function(X)` | classification | Raw logits |
+| `score(X, y)` | both | Accuracy or R² |
+| `evaluate(X, y)` | both | Prints and returns log loss or RMSE |
+
+**Subclass contract**: set `base_learners_` (list of unfitted sklearn regressors) and `probabilities_` (list summing to 1) before calling `fit`.
+
+### Loss functions
+
+`hnbm.losses` provides `Logistic` (classification) and `MeanSquaredError` (regression), each with a `compute_derivatives(y, f)` method returning gradient and Hessian vectors.
+
+---
+
+## Docker
+
+```bash
+docker build -t hnbm .
+docker run --rm hnbm
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/qiancapital-dev/hnbm.git
+cd hnbm
+pip install -r requirements.txt
+pip install -e .
+```
+
+---
+
+## Related projects
+
+- **[snapboost](https://github.com/QianCapital/snapboost)** — a concrete HNBM using decision trees and kernel ridge regressors
+
+---
+
+## License
+
+MIT — See [LICENSE](LICENSE) for full text.

hnbm-0.1.0/README.md

@@ -0,0 +1,122 @@
+# HNBM
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![scikit-learn](https://img.shields.io/badge/scikit--learn-compatible-blue.svg)](https://scikit-learn.org/)
+
+**Heterogeneous Newton Boosting Machine (HNBM)** — a scikit-learn-compatible gradient boosting framework that stochastically mixes heterogeneous base learners at each iteration.
+
+Unlike standard gradient boosting libraries that use a single learner type (typically decision trees), HNBM lets you define a pool of base learners with selection probabilities. At each boosting round, a learner is drawn from that pool and fit to the Newton step (gradient divided by Hessian, weighted by the Hessian).
+
+This is the core framework behind [SnapBoost](https://github.com/qiancapital/snapboost), inspired by [SnapBoost: A Heterogeneous Boosting Machine](https://arxiv.org/abs/2006.09745) (Parnell et al., NeurIPS 2020).
+
+---
+
+## Installation
+
+**From source** (recommended until PyPI release):
+
+```bash
+git clone https://github.com/qiancapital-dev/hnbm.git
+cd hnbm
+pip install .
+```
+
+**Requirements**: Python ≥ 3.8, NumPy, scikit-learn, tqdm.
+
+---
+
+## Quick Start
+
+Subclass `HNBM` and configure your base learner pool before training:
+
+```python
+from sklearn.datasets import load_breast_cancer
+from sklearn.model_selection import train_test_split
+from sklearn.tree import DecisionTreeRegressor
+from hnbm import HNBM
+
+X, y = load_breast_cancer(return_X_y=True)
+X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=42)
+
+
+class TreeBoost(HNBM):
+    def __init__(self, max_depth=5, **kwargs):
+        super().__init__(**kwargs)
+        self.base_learners_ = [DecisionTreeRegressor(max_depth=max_depth)]
+        self.probabilities_ = [1.0]
+
+
+model = TreeBoost(
+    num_iterations=100,
+    learning_rate=0.1,
+    mode="classification",
+    random_state=42,
+)
+model.fit(X_train, y_train)
+
+print("Accuracy:", model.score(X_test, y_test))
+model.evaluate(X_test, y_test)
+```
+
+---
+
+## API Reference
+
+### `HNBM`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `num_iterations` | `int` | `100` | Number of boosting rounds |
+| `learning_rate` | `float` | `0.1` | Shrinkage per learner |
+| `mode` | `str` | `"classification"` | `"classification"` or `"regression"` |
+| `random_state` | `int` or `None` | `None` | Seed for learner selection |
+| `verbose` | `bool` | `True` | Show tqdm progress bar |
+
+**Methods**
+
+| Method | Mode | Description |
+|--------|------|-------------|
+| `fit(X, y)` | both | Train the ensemble |
+| `predict(X)` | both | Class labels (0/1) or continuous values |
+| `predict_proba(X)` | classification | Probabilities, shape `(n_samples, 2)` |
+| `decision_function(X)` | classification | Raw logits |
+| `score(X, y)` | both | Accuracy or R² |
+| `evaluate(X, y)` | both | Prints and returns log loss or RMSE |
+
+**Subclass contract**: set `base_learners_` (list of unfitted sklearn regressors) and `probabilities_` (list summing to 1) before calling `fit`.
+
+### Loss functions
+
+`hnbm.losses` provides `Logistic` (classification) and `MeanSquaredError` (regression), each with a `compute_derivatives(y, f)` method returning gradient and Hessian vectors.
+
+---
+
+## Docker
+
+```bash
+docker build -t hnbm .
+docker run --rm hnbm
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/qiancapital-dev/hnbm.git
+cd hnbm
+pip install -r requirements.txt
+pip install -e .
+```
+
+---
+
+## Related projects
+
+- **[snapboost](https://github.com/QianCapital/snapboost)** — a concrete HNBM using decision trees and kernel ridge regressors
+
+---
+
+## License
+
+MIT — See [LICENSE](LICENSE) for full text.

hnbm-0.1.0/hnbm/__init__.py

@@ -0,0 +1,5 @@
+from .estimator import HNBM
+from .losses import Logistic, MeanSquaredError
+
+__all__ = ["HNBM", "Logistic", "MeanSquaredError"]
+__version__ = "0.1.0"

hnbm-0.1.0/hnbm/estimator.py

@@ -0,0 +1,276 @@
+import numpy as np
+from tqdm import tqdm
+from sklearn.base import BaseEstimator, clone
+from sklearn.exceptions import NotFittedError
+from sklearn.metrics import accuracy_score, mean_squared_error, log_loss, r2_score
+from sklearn.utils.validation import check_is_fitted
+
+from .losses import Logistic, MeanSquaredError
+
+
+def _normalize_classification_labels(y):
+    """Convert 0/1 labels to -1/+1 for logistic loss."""
+    y = np.asarray(y, dtype=float).ravel()
+    if np.any(np.isnan(y)):
+        raise ValueError("Classification labels must not contain NaN values.")
+    unique = np.unique(y)
+    if np.array_equal(unique, [-1.0, 1.0]) or np.array_equal(unique, [-1.0]) or np.array_equal(unique, [1.0]):
+        return y
+    if np.all(np.isin(unique, [0.0, 1.0])):
+        return np.where(y == 0, -1.0, 1.0)
+    raise ValueError("Classification labels must be 0/1 or -1/+1.")
+
+
+def _labels_for_log_loss(y):
+    """Convert labels to 0/1 for sklearn's log_loss."""
+    y = np.asarray(y, dtype=float).ravel()
+    if np.any(np.isnan(y)):
+        raise ValueError("Classification labels must not contain NaN values.")
+    unique = np.unique(y)
+    if np.all(np.isin(unique, [0.0, 1.0])):
+        return y
+    if np.all(np.isin(unique, [-1.0, 1.0])):
+        return np.where(y == -1, 0.0, 1.0)
+    raise ValueError("Classification labels must be 0/1 or -1/+1.")
+
+
+def _validate_X(X):
+    """Validate and reshape feature matrix."""
+    X = np.asarray(X)
+    if X.ndim == 1:
+        X = X.reshape(1, -1)
+    elif X.ndim != 2:
+        raise ValueError(f"X must be a 2D array, got shape {X.shape}.")
+    if X.shape[0] == 0:
+        raise ValueError("X must contain at least one sample.")
+    return X
+
+
+def _validate_X_y(X, y):
+    """Validate feature matrix and label vector shapes."""
+    X = _validate_X(X)
+    y = np.asarray(y)
+    if y.ndim == 2 and y.shape[1] == 1:
+        y = y.ravel()
+    elif y.ndim != 1:
+        raise ValueError(f"y must be a 1D array, got shape {y.shape}.")
+    if y.shape[0] == 0:
+        raise ValueError("y must contain at least one label.")
+    if X.shape[0] != y.shape[0]:
+        raise ValueError(
+            f"X and y have inconsistent lengths: {X.shape[0]} vs {y.shape[0]}."
+        )
+    return X, y
+
+
+class HNBM(BaseEstimator):
+    """
+    Heterogeneous Newton Boosting Machine.
+
+    A gradient boosting framework that stochastically selects base learners
+    from a heterogeneous pool at each iteration. Subclass HNBM and configure
+    ``base_learners_`` and ``probabilities_`` before calling ``fit``.
+
+    Parameters
+    ----------
+    num_iterations : int, default=100
+        Number of boosting iterations.
+    learning_rate : float, default=0.1
+        Shrinkage applied to each learner's contribution.
+    mode : {'classification', 'regression'}, default='classification'
+        Training objective.
+    random_state : int or None, default=None
+        Random seed for base learner selection.
+    verbose : bool, default=True
+        Whether to show a progress bar during training.
+
+    Attributes
+    ----------
+    ensemble_ : list
+        Fitted base learners after training.
+    base_learners_ : list
+        Candidate base learners (must be set before ``fit``).
+    probabilities_ : list
+        Selection probabilities for each base learner (must be set before ``fit``).
+    """
+
+    def __init__(
+        self,
+        num_iterations=100,
+        learning_rate=0.1,
+        mode="classification",
+        random_state=None,
+        verbose=True,
+    ):
+        if mode not in ("classification", "regression"):
+            raise ValueError("Invalid mode: specify 'classification' or 'regression'.")
+        if num_iterations < 1:
+            raise ValueError(f"num_iterations must be >= 1, got {num_iterations}.")
+        if learning_rate <= 0:
+            raise ValueError(f"learning_rate must be > 0, got {learning_rate}.")
+
+        self.num_iterations = num_iterations
+        self.learning_rate = learning_rate
+        self.mode = mode
+        self.random_state = random_state
+        self.verbose = verbose
+        self.base_learners_ = []
+        self.probabilities_ = []
+        self.ensemble_ = []
+
+    def __sklearn_tags__(self):
+        tags = super().__sklearn_tags__()
+        tags.estimator_type = (
+            "classifier" if self.mode == "classification" else "regressor"
+        )
+        return tags
+
+    def _check_fitted(self):
+        check_is_fitted(self, "ensemble_")
+        if not self.ensemble_:
+            raise NotFittedError(
+                "This HNBM instance is not fitted yet. Call 'fit' with appropriate arguments."
+            )
+
+    def set_params(self, **params):
+        result = super().set_params(**params)
+        if params:
+            if "num_iterations" in params and self.num_iterations < 1:
+                raise ValueError(
+                    f"num_iterations must be >= 1, got {self.num_iterations}."
+                )
+            if "learning_rate" in params and self.learning_rate <= 0:
+                raise ValueError(
+                    f"learning_rate must be > 0, got {self.learning_rate}."
+                )
+            if "mode" in params and self.mode not in ("classification", "regression"):
+                raise ValueError(
+                    "Invalid mode: specify 'classification' or 'regression'."
+                )
+            self.ensemble_ = []
+        return result
+
+    def fit(self, X, y):
+        """
+        Train the model.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Feature matrix.
+        y : array-like of shape (n_samples,)
+            Target values.
+
+        Returns
+        -------
+        self
+        """
+        if not self.base_learners_:
+            raise ValueError(
+                "No base learners configured. Subclass HNBM and set base_learners_ "
+                "and probabilities_ before calling fit."
+            )
+
+        X, y = _validate_X_y(X, y)
+        if self.mode == "classification":
+            y = _normalize_classification_labels(y)
+            self.classes_ = np.array([0, 1])
+        else:
+            y = np.asarray(y, dtype=float).ravel()
+
+        rng = np.random.default_rng(self.random_state)
+        z = np.zeros(X.shape[0])
+        self.ensemble_ = []
+        iterations = range(self.num_iterations)
+        if self.verbose:
+            iterations = tqdm(iterations, desc="Training")
+
+        for _ in iterations:
+            g, h = self.loss_.compute_derivatives(y, z)
+            idx = rng.choice(len(self.base_learners_), p=self.probabilities_)
+            base_learner = clone(self.base_learners_[idx])
+            base_learner.fit(X, -np.divide(g, h), sample_weight=h)
+            z += base_learner.predict(X) * self.learning_rate
+            self.ensemble_.append(base_learner)
+
+        return self
+
+    @property
+    def loss_(self):
+        return Logistic if self.mode == "classification" else MeanSquaredError
+
+    @property
+    def num_iterations_(self):
+        return self.num_iterations
+
+    @property
+    def learning_rate_(self):
+        return self.learning_rate
+
+    def _raw_predict(self, X):
+        """Return raw model output (logits for classification, values for regression)."""
+        self._check_fitted()
+        X = _validate_X(X)
+        preds = np.zeros(X.shape[0])
+        for learner in self.ensemble_:
+            preds += self.learning_rate * learner.predict(X)
+        return preds
+
+    def decision_function(self, X):
+        """Return classification logits."""
+        if self.mode != "classification":
+            raise ValueError("decision_function is only available in classification mode.")
+        return self._raw_predict(X)
+
+    def predict(self, X):
+        """
+        Predict using the model.
+
+        Classification returns 0/1 labels; regression returns continuous values.
+        """
+        if self.mode == "classification":
+            logits = self.decision_function(X)
+            return (logits >= 0).astype(int)
+        return self._raw_predict(X)
+
+    def predict_proba(self, X):
+        """
+        Predict class probabilities (classification mode only).
+
+        Returns
+        -------
+        ndarray of shape (n_samples, 2)
+            Probabilities ``[P(y=0), P(y=1)]``.
+        """
+        if self.mode != "classification":
+            raise ValueError("predict_proba is only available in classification mode.")
+        logits = self.decision_function(X)
+        prob_pos = 1.0 / (1.0 + np.exp(-logits))
+        return np.column_stack([1.0 - prob_pos, prob_pos])
+
+    def score(self, X, y):
+        """Return accuracy (classification) or R² (regression)."""
+        self._check_fitted()
+        _, y = _validate_X_y(X, y)
+        if self.mode == "classification":
+            y = _labels_for_log_loss(y)
+            return accuracy_score(y, self.predict(X))
+        y = np.asarray(y, dtype=float).ravel()
+        return r2_score(y, self.predict(X))
+
+    def evaluate(self, X, y):
+        """Print and return log loss (classification) or RMSE (regression)."""
+        self._check_fitted()
+        if self.mode == "classification":
+            _, y = _validate_X_y(X, y)
+            y = _labels_for_log_loss(y)
+            prob_pos = self.predict_proba(X)[:, 1]
+            loss = log_loss(y, prob_pos, labels=[0, 1])
+            print("Log Loss: %.4f" % loss)
+        else:
+            _, y = _validate_X_y(X, y)
+            y = np.asarray(y, dtype=float).ravel()
+            preds = self._raw_predict(X)
+            loss = np.sqrt(mean_squared_error(y, preds))
+            print("RMSE: %.4f" % loss)
+        return loss

hnbm-0.1.0/hnbm/losses.py

@@ -0,0 +1,23 @@
+import numpy as np
+
+
+class MeanSquaredError:
+    """Mean Squared Error loss for regression."""
+
+    @staticmethod
+    def compute_derivatives(y, f):
+        g = 2 * (f - y)
+        h = 2.0 * np.ones(y.shape[0])
+        return g, h
+
+
+class Logistic:
+    """Logistic loss for binary classification."""
+
+    @staticmethod
+    def compute_derivatives(y, f):
+        tmp = np.exp(-np.multiply(y, f))
+        tmp2 = np.divide(tmp, 1 + tmp)
+        g = -np.multiply(y, tmp2)
+        h = np.multiply(tmp2, 1.0 - tmp2)
+        return g, h

hnbm-0.1.0/hnbm.egg-info/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: hnbm
+Version: 0.1.0
+Summary: Heterogeneous Newton Boosting Machine
+Home-page: https://github.com/qiancapital-dev/hnbm
+Author: Qian Capital
+Author-email: Qian Capital <samson.qian@qiancapital.com>
+License: MIT
+Project-URL: Homepage, https://github.com/qiancapital-dev/hnbm
+Keywords: boosting,gradient-boosting,hnbm,heterogeneous-newton
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: tqdm>=4.50
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# HNBM
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![scikit-learn](https://img.shields.io/badge/scikit--learn-compatible-blue.svg)](https://scikit-learn.org/)
+
+**Heterogeneous Newton Boosting Machine (HNBM)** — a scikit-learn-compatible gradient boosting framework that stochastically mixes heterogeneous base learners at each iteration.
+
+Unlike standard gradient boosting libraries that use a single learner type (typically decision trees), HNBM lets you define a pool of base learners with selection probabilities. At each boosting round, a learner is drawn from that pool and fit to the Newton step (gradient divided by Hessian, weighted by the Hessian).
+
+This is the core framework behind [SnapBoost](https://github.com/qiancapital/snapboost), inspired by [SnapBoost: A Heterogeneous Boosting Machine](https://arxiv.org/abs/2006.09745) (Parnell et al., NeurIPS 2020).
+
+---
+
+## Installation
+
+**From source** (recommended until PyPI release):
+
+```bash
+git clone https://github.com/qiancapital-dev/hnbm.git
+cd hnbm
+pip install .
+```
+
+**Requirements**: Python ≥ 3.8, NumPy, scikit-learn, tqdm.
+
+---
+
+## Quick Start
+
+Subclass `HNBM` and configure your base learner pool before training:
+
+```python
+from sklearn.datasets import load_breast_cancer
+from sklearn.model_selection import train_test_split
+from sklearn.tree import DecisionTreeRegressor
+from hnbm import HNBM
+
+X, y = load_breast_cancer(return_X_y=True)
+X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=42)
+
+
+class TreeBoost(HNBM):
+    def __init__(self, max_depth=5, **kwargs):
+        super().__init__(**kwargs)
+        self.base_learners_ = [DecisionTreeRegressor(max_depth=max_depth)]
+        self.probabilities_ = [1.0]
+
+
+model = TreeBoost(
+    num_iterations=100,
+    learning_rate=0.1,
+    mode="classification",
+    random_state=42,
+)
+model.fit(X_train, y_train)
+
+print("Accuracy:", model.score(X_test, y_test))
+model.evaluate(X_test, y_test)
+```
+
+---
+
+## API Reference
+
+### `HNBM`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `num_iterations` | `int` | `100` | Number of boosting rounds |
+| `learning_rate` | `float` | `0.1` | Shrinkage per learner |
+| `mode` | `str` | `"classification"` | `"classification"` or `"regression"` |
+| `random_state` | `int` or `None` | `None` | Seed for learner selection |
+| `verbose` | `bool` | `True` | Show tqdm progress bar |
+
+**Methods**
+
+| Method | Mode | Description |
+|--------|------|-------------|
+| `fit(X, y)` | both | Train the ensemble |
+| `predict(X)` | both | Class labels (0/1) or continuous values |
+| `predict_proba(X)` | classification | Probabilities, shape `(n_samples, 2)` |
+| `decision_function(X)` | classification | Raw logits |
+| `score(X, y)` | both | Accuracy or R² |
+| `evaluate(X, y)` | both | Prints and returns log loss or RMSE |
+
+**Subclass contract**: set `base_learners_` (list of unfitted sklearn regressors) and `probabilities_` (list summing to 1) before calling `fit`.
+
+### Loss functions
+
+`hnbm.losses` provides `Logistic` (classification) and `MeanSquaredError` (regression), each with a `compute_derivatives(y, f)` method returning gradient and Hessian vectors.
+
+---
+
+## Docker
+
+```bash
+docker build -t hnbm .
+docker run --rm hnbm
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/qiancapital-dev/hnbm.git
+cd hnbm
+pip install -r requirements.txt
+pip install -e .
+```
+
+---
+
+## Related projects
+
+- **[snapboost](https://github.com/QianCapital/snapboost)** — a concrete HNBM using decision trees and kernel ridge regressors
+
+---
+
+## License
+
+MIT — See [LICENSE](LICENSE) for full text.

hnbm-0.1.0/hnbm.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+Dockerfile
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+requirements.txt
+setup.cfg
+setup.py
+hnbm/__init__.py
+hnbm/estimator.py
+hnbm/losses.py
+hnbm.egg-info/PKG-INFO
+hnbm.egg-info/SOURCES.txt
+hnbm.egg-info/dependency_links.txt
+hnbm.egg-info/requires.txt
+hnbm.egg-info/top_level.txt

hnbm-0.1.0/hnbm.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hnbm-0.1.0/hnbm.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy>=1.20
+scikit-learn>=1.0
+tqdm>=4.50

hnbm-0.1.0/hnbm.egg-info/top_level.txt

@@ -0,0 +1 @@
+hnbm

hnbm-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hnbm"
+version = "0.1.0"
+description = "Heterogeneous Newton Boosting Machine"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [{name = "Qian Capital", email = "samson.qian@qiancapital.com"}]
+keywords = ["boosting", "gradient-boosting", "hnbm", "heterogeneous-newton"]
+dependencies = [
+    "numpy>=1.20",
+    "scikit-learn>=1.0",
+    "tqdm>=4.50",
+]
+
+[project.urls]
+Homepage = "https://github.com/qiancapital-dev/hnbm"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["hnbm*"]

hnbm-0.1.0/requirements.txt

@@ -0,0 +1,3 @@
+numpy>=1.20
+scikit-learn>=1.0
+tqdm>=4.50

hnbm-0.1.0/setup.cfg

@@ -0,0 +1,9 @@
+[metadata]
+description_file = README.md
+requirements-file = requirements.txt
+docker-file = Dockerfile
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

hnbm-0.1.0/setup.py

@@ -0,0 +1,36 @@
+from setuptools import setup
+import pathlib
+
+HERE = pathlib.Path(__file__).parent
+README = (HERE / "README.md").read_text()
+
+
+def _parse_requirements(file_path):
+    with open(file_path) as f:
+        lines = f.read().splitlines()
+    reqs = []
+    for line in lines:
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("pip") or line.startswith("setuptools"):
+            continue
+        reqs.append(line)
+    return reqs
+
+
+setup(
+    name="hnbm",
+    version="0.1.0",
+    author="Qian Capital",
+    author_email="samson.qian@qiancapital.com",
+    packages=["hnbm"],
+    url="https://github.com/qiancapital-dev/hnbm",
+    license="MIT",
+    description="Heterogeneous Newton Boosting Machine",
+    long_description=README,
+    long_description_content_type="text/markdown",
+    install_requires=_parse_requirements("requirements.txt"),
+    python_requires=">=3.8",
+    keywords="boosting gradient-boosting hnbm heterogeneous-newton",
+)