gboostrs 0.1.0__tar.gz

gboostrs-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,137 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      testpypi:
+        description: "Upload to TestPyPI instead of PyPI"
+        type: choice
+        options: ["false", "true"]
+        default: "false"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { label: linux-x86_64,   runner: ubuntu-latest,    python: "3.11" }
+          - { label: linux-x86_64,   runner: ubuntu-latest,    python: "3.12" }
+          - { label: linux-x86_64,   runner: ubuntu-latest,    python: "3.13" }
+          - { label: linux-aarch64,  runner: ubuntu-24.04-arm, python: "3.11" }
+          - { label: linux-aarch64,  runner: ubuntu-24.04-arm, python: "3.12" }
+          - { label: linux-aarch64,  runner: ubuntu-24.04-arm, python: "3.13" }
+          - { label: macos-arm64,    runner: macos-latest,     python: "3.11" }
+          - { label: macos-arm64,    runner: macos-latest,     python: "3.12" }
+          - { label: macos-arm64,    runner: macos-latest,     python: "3.13" }
+          - { label: windows-x86_64, runner: windows-latest,   python: "3.11" }
+          - { label: windows-x86_64, runner: windows-latest,   python: "3.12" }
+          - { label: windows-x86_64, runner: windows-latest,   python: "3.13" }
+    runs-on: ${{ matrix.runner }}
+    env:
+      CARGO_TERM_COLOR: always
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo
+        uses: actions/cache@v6
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-${{ matrix.label }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ matrix.label }}-cargo-
+
+      - name: Install maturin
+        run: python -m pip install -U pip maturin
+
+      - name: Build wheel
+        shell: bash
+        run: |
+          maturin build --release --manifest-path py-gboost/Cargo.toml -o wheels
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.label }}-py${{ matrix.python }}
+          path: wheels/*.whl
+          if-no-files-found: error
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Install maturin
+        run: python3 -m pip install -U pip maturin
+
+      - name: Build sdist
+        run: maturin sdist --manifest-path py-gboost/Cargo.toml --out dist
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    needs: [build, sdist]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: "wheels-*"
+          path: dist
+          merge-multiple: true
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: sdist
+          path: dist
+          merge-multiple: true
+
+      - name: List artifacts
+        run: ls -la dist
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Install twine
+        run: python -m pip install -U pip twine
+
+      - name: Check with twine
+        run: twine check dist/*
+
+      - name: Upload to TestPyPI
+        if: inputs.testpypi == 'true'
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
+        run: twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+
+      - name: Upload to PyPI
+        if: inputs.testpypi != 'true'
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

gboostrs-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+Cargo.lock
+target
+.venv
+__pycache__

gboostrs-0.1.0/Cargo.toml

@@ -0,0 +1,34 @@
+[package]
+name = "gboost"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.85"
+description = "Gradient boosting library in Rust"
+license = "MIT"
+repository = "https://github.com/rseko/gboost"
+keywords = ["gradient-boosting", "machine-learning", "decision-tree"]
+categories = ["algorithms", "science"]
+readme = "README.md"
+
+[features]
+large-index = []
+
+[dependencies]
+anyhow = "1.0"
+itertools = "0.15"
+num-traits = "0.2"
+rand = "0.10"
+rayon = "1.12"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = { version = "1.0", features = ["preserve_order"] }
+thiserror = "2.0"
+zerocopy = { version = "0.8", features = ["std"] }
+
+[dev-dependencies]
+criterion = "0.8"
+half = { version = "2.7", features = ["num-traits"] }
+tempfile = "3"
+
+[[bench]]
+name = "benchmark"
+harness = false

gboostrs-0.1.0/LICENSE

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

gboostrs-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: gboostrs
+Version: 0.1.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: numpy
+Summary: Python bindings for the gboost gradient boosting library
+Keywords: gradient-boosting,machine-learning,decision-tree
+Author: rseko
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Repository, https://github.com/rseko/gboost
+
+# py-gboost
+
+Python bindings for the [`gboost`](../README.md) gradient-boosting library.
+
+It exposes a single `GradientBooster` class backed by the Rust core, with a
+sklearn-like `fit(x, y)` / `predict(x)` API over NumPy `float32` arrays. All
+training work (histogram binning, split search, per-batch update) runs in Rust;
+`fit` and `fit_next` release the GIL while the booster grows.
+
+## Installation
+
+`py-gboost` is a [maturin](https://www.maturin.rs) package; it builds the Rust
+extension and installs it as the importable module `gboostrs`.
+
+```bash
+# From a release build
+pip install .
+
+# Or, for in-place development
+pip install maturin
+maturin develop
+```
+
+Requires Python 3.9+. The import name is `gboostrs`:
+
+```python
+import gboostrs
+gboostrs.__version__
+```
+
+## Quick start
+
+```python
+import numpy as np
+from gboostrs import GradientBooster
+
+rng = np.random.default_rng(1)
+x = rng.standard_normal((100, 5)).astype(np.float32)  # (rows, cols)
+y = rng.standard_normal(100).astype(np.float32)        # one value per row
+
+# Regression
+gb = GradientBooster(objective="squaredloss", iterations=100)
+gb.fit(x, y)
+scores = gb.predict(x)      # np.ndarray of float32, one score per row
+gb.loss()                   # mean loss of the current predictions vs. the labels
+
+# Binary classification (labels in {0, 1})
+y = rng.integers(0, 2, 100).astype(np.float32)
+gb = GradientBooster(objective="logloss", iterations=100)
+gb.fit(x, y)
+```
+
+### Growing round by round
+
+`fit(x, y)` trains up to `iterations` rounds and replaces any previously
+trained model. `fit_next()` grows one additional round on the existing model
+and returns `False` when a round produced no tree (no gain) — the natural
+early-stopping signal.
+
+```python
+gb = GradientBooster(objective="squaredloss", iterations=0)
+gb.fit(x, y)                # fit(0) builds the booster without growing trees
+
+while gb.fit_next():
+    print(gb.loss())
+```
+
+## `GradientBooster`
+
+All parameters are keyword-only and have defaults, so `GradientBooster()` is a
+valid, fully-configured instance.
+
+| Parameter            | Default       | Description                                                                     |
+| -------------------- | :-----------: | ------------------------------------------------------------------------------- |
+| `iterations`         |     `100`     | Maximum boosting rounds run by `fit`.                                           |
+| `objective`          | `"squaredloss"` | Loss to minimize: `"squaredloss"` (regression) or `"logloss"` (classification). |
+| `base_score`         |     `0.0`     | Initial constant prediction before any tree is added.                            |
+| `max_bins`           |     `255`     | Maximum number of quantization bins per column.                                  |
+| `persist_path`       |   `None`      | Directory for on-disk artifacts, if persistence is used.                         |
+| `parallel`           |   `True`      | Enable the parallel (Rayon) execution paths.                                     |
+| `seed`               |      `0`      | Seed for reproducible random draws (subsampling).                                |
+| `learning_rate`      |     `0.3`     | Per-tree update step size.                                                       |
+| `subsample`          |     `1.0`     | Row subsampling fraction per tree.                                               |
+| `colsample_bytree`   |     `1.0`     | Per-tree feature subsampling fraction.                                           |
+| `colsample_bylevel`  |     `1.0`     | Per-level feature subsampling fraction.                                          |
+| `colsample_bynode`   |     `1.0`     | Per-node feature subsampling fraction.                                           |
+| `max_depth`          |      `6`      | Maximum tree depth (`0` = no limit).                                             |
+| `max_leaves`         |      `0`      | Maximum number of leaves (`0` = no limit).                                       |
+| `grow_policy`        | `"depthwise"` | Tree growth policy: `"depthwise"` or `"lossguide"`.                              |
+| `reg_alpha`          |     `0.0`     | L1 regularizer on leaf weights.                                                  |
+| `reg_lambda`         |     `1.0`     | L2 regularizer on leaf weights.                                                  |
+| `min_split_gain`     |     `0.0`     | Minimum gain required to take a split.                                           |
+| `min_child_weight`   |     `1.0`     | Minimum hessian sum allowed in a leaf.                                           |
+| `allow_missing_splits` |  `False`   | Whether missing values may drive their own split.                                |
+| `onehot_columns`     |     `[]`      | Indices of columns to treat as one-hot categoricals (exact-bin splits).         |
+
+### Methods
+
+- **`fit(x, y) -> None`** — Train the booster. `x` is a 2-D `float32` matrix
+  of shape `(rows, cols)`; `y` is a 1-D `float32` target of length `rows`.
+  Replaces any previously trained model.
+- **`fit_next() -> bool`** — Grow one additional round on the trained model.
+  Returns `False` when the round produced no tree (no gain).
+- **`predict(x) -> np.ndarray`** — Score `x` (shape `(rows, cols)`, same
+  column count as training) with the trained model; returns one `float32`
+  score per row.
+- **`loss() -> float | None`** — Mean loss of the current predictions against
+  the training labels, or `None` before `fit`.
+- **`get_params() -> dict`** — Return the constructor kwargs as a dict of
+  `name -> value`; `GradientBooster(**gb.get_params())` reconstructs an
+  equivalent instance.
+
+## Notes
+
+- **Zero-copy inputs.** The Rust core works on column-major (Fortran-order)
+  arrays. Pass `x` as `np.asfortranarray(x)` to avoid a copy; row-major or
+  strided inputs are transposed into column-major internally.
+- **Error types.** I/O failures (e.g. an invalid `persist_path`) raise
+  `IOError`; other problems (an untrained model, a `NaN` in the target, a
+  column-count mismatch in `predict`, an invalid `objective`/`grow_policy`)
+  raise `ValueError`.
+- **`onehot_columns`.** Columns listed here are split on an exact bin (`==`)
+  rather than an ordered threshold (`<=`), so high-cardinality categoricals
+  are first-class. Other columns are treated as linear (ordered) features.
+- **Determinism.** With a fixed `seed` and `subsample`, a run is reproducible.
+
+## Tests
+
+The test suite exercises the binding end-to-end (regression, classification,
+`fit_next`, and error paths):
+
+```bash
+pip install pytest
+pytest tests/
+```
+

gboostrs-0.1.0/README.md

@@ -0,0 +1,224 @@
+# gboost
+
+A gradient-boosting library in Rust.
+
+The distinguishing feature of `gboost` is out-of-core learning: the dataset is
+staged to disk and each boosting round streams it through the gradient/hessian
+computation, keeping only a subsample of rows in RAM — not the whole table.
+You can train on tens of billions of rows on a machine that could never hold
+the full columnar data at once.
+
+It also works in-memory (fully columnar, histogram-binned, optionally parallel
+via `rayon`) for datasets that do fit in RAM, behind the same object-safe
+[`Booster`] trait.
+
+`gboost` follows the XGBoost model: the same histogram-based boosting
+algorithm, the same gradient/hessian leaf-value math, and training parameters
+that mirror XGBoost's names (`learning_rate`, `subsample`, `colsample_bytree`,
+`max_depth`, `min_split_gain`, `reg_alpha` / `reg_lambda`, …). If you know
+XGBoost, the options will feel familiar — the main differences are the Rust
+columnar API, a couple of gboost-specific options, and the out-of-core path.
+
+## Features
+
+- **Out-of-core training** — stage columns to disk, then grow trees by
+  streaming the dataset with only a subsample of rows held in RAM, so memory
+  stays bounded regardless of dataset size. See [`ModelInit`] and
+  `BoostModel::init_large`.
+- **One-hot (categorical) features** — a column can split on an exact bin
+  (`==`) rather than an ordered threshold (`<=`), so high-cardinality
+  categoricals are a first-class feature kind, not just `Linear` splits.
+- **Half-precision floats** — the feature type `F` is generic over any
+  `QuantFloat`, so `f16` and `bf16` (from the `half` crate) are accepted in
+  addition to `f32` input type.
+- **Histogram binning** — values are quantized into a bounded number of bins
+  (`max_bins` up to 65535), so split search scales with the bin count, not the
+  raw data.
+- **Parallel training** — split search, histogram building and the per-batch
+  update pass run across threads via `rayon` (toggle with `set_parallel`).
+- **Deterministic** — a single `seed` drives all random draws (subsampling),
+  so runs are reproducible.
+
+## Installation
+
+```toml
+[dependencies]
+gboost = "0.1"
+```
+
+MIT-licensed. Edition 2024 requires Rust 1.85+.
+
+### Crate features
+
+| Feature       | Default | Description                                                        |
+| ------------- | :-----: | ------------------------------------------------------------------ |
+| `large-index` |   no    | Allow training targets with more than `u32::MAX` rows (`u64` row indices). |
+
+## Training on data that doesn't fit in RAM
+
+This is the primary use case. The flow is:
+
+1. **Stage** the dataset to a persistence directory: for each feature column,
+   fit its quantizer and write the bin indices to `feature.<name>`; write the
+   target to `target`; the feature headers are appended to `model.txt`.
+2. **Build** a booster over that on-disk dataset with `BoostModel::init_large`.
+   Rows are *not* loaded wholesale — only a subsample of rows is kept in RAM,
+   and the first pass streams the full dataset to seed the per-row
+   gradient/hessian index.
+3. **Fit** one or more rounds. Each `fit_next` round takes the streaming
+   `update_large` path: it walks the on-disk batches, folds the new tree's
+   leaf values into the running predictions, and recomputes the derivatives.
+
+The persistence path is mandatory on this route — set it with
+`Options::set_persist_path`.
+
+```rust
+use gboost::boost_model::{BoostModel, ModelInit};
+use gboost::dataset::{SquaredLoss, FeatureKind};
+use gboost::options::Options;
+use std::path::PathBuf;
+
+let persist_path = PathBuf::from("/tmp/gboost");
+let options = Options::default()
+    .set_persist_path(Some(persist_path.clone()))
+    .set_max_bins(255)
+    .set_subsample(0.5)
+    .set_seed(42)
+    .set_parallel(true);
+
+// 1. Stage columns to disk. Each column is fit, quantized, and written.
+let mut init = ModelInit::new(persist_path.clone(), 255)?;
+for (name, column) in [
+    ("age", &[/* one f32 per row */]),
+    ("income", &[/* ... */]),
+] {
+    init.write_feature::<u8, _>(name, FeatureKind::Linear, column)?;
+}
+init.write_target(&target)?;          // one f32 per row
+let _features = init.finish();        // get bin thresholds data
+
+// 2. Build the booster over the on-disk dataset.
+let mut model = BoostModel::<u8, u32, SquaredLoss>::init_large(options)?;
+
+// 3. Grow rounds; each streams batches from disk.
+model.fit_next()?;
+model.fit_next()?;
+```
+
+> **Very wide datasets.** If the row count exceeds `u32::MAX`, enable the
+> `large-index` cargo feature and instantiate with a `u64` index
+> (`BoostModel::<u8, u64, SquaredLoss>`).
+>
+> **Many columns on multi-core machines.** In the parallel update path, each
+> rayon worker holds one open file handle per feature column (plus the target
+> and prediction files). With `T` threads and `C` columns this is roughly
+> `T × (C + 2)` open descriptors at once, so a wide dataset on a many-core
+> system can exhaust the process or system file-descriptor limit
+> (`EMFILE`/`ENFILE`). Raise `ulimit -n`, or cap the worker count
+> (e.g. via `RAYON_NUM_THREADS`) if you hit this.
+
+## Training in-memory
+
+For data that fits in RAM, use the `Booster` trait: build a boxed, object-safe
+booster over in-memory feature columns, grow it, and predict. `inputs` holds
+one column per feature, in feature order; `target` has one value per row.
+
+```rust
+use gboost::boost_api::{new_booster, Booster};
+use gboost::options::{ObjectiveKind, Options};
+
+let inputs: Vec<Vec<f32>> = vec![/* one column: one f32 per row */; /* n_features */];
+let cols = inputs.iter().map(|c| c.as_slice()).collect::<Vec<_>>();
+let target: Vec<f32> = vec![/* per-row */];
+
+let options = Options::default()
+    .set_objective(ObjectiveKind::SquaredLoss)
+    .set_learning_rate(0.1);
+
+let mut booster = new_booster::<f32>(options, &cols, &target)?;
+
+// Grow up to 50 rounds; stops early if a round adds no tree.
+booster.fit(50)?;
+
+let predictions = booster.predict(&cols)?;
+let per_row_loss = booster.loss();
+```
+
+### Growing round by round
+
+`fit` is a convenience wrapper over `fit_next`. Each call to `fit_next`
+grows one tree and folds it into the ensemble. To control the stopping
+condition yourself, loop until it reports no gain:
+
+```rust
+use gboost::boost_api::Booster;
+
+while booster.fit_next()? {
+    // keep boosting
+}
+```
+
+`fit_next` returns `Ok(false)` when a round produced no tree (no gain), which
+is the natural early-stopping signal.
+
+### Explicit feature descriptors
+
+`new_booster` synthesizes `linear` features named by position. To supply your
+own names and kinds, use `new_with_features`; bin boundaries are still refit
+from the inputs. Each column is either `linear` (ordered threshold splits) or
+`onehot` (exact-bin splits for categoricals).
+
+```rust
+use gboost::boost_api::{new_with_features, Booster};
+use gboost::dataset::Feature;
+use gboost::options::Options;
+
+let inputs: Vec<Vec<f32>> = vec![/* one column per feature */];
+let cols = inputs.iter().map(|c| c.as_slice()).collect::<Vec<_>>();
+let target: Vec<f32> = vec![/* per-row */];
+
+let options = Options::default().set_learning_rate(0.1);
+
+let features = vec![
+    Feature::linear("age", None),      // ordered threshold
+    Feature::onehot("country", None),  // exact-bin categorical
+];
+let mut booster = new_with_features::<f32>(options, &cols, &target, features)?;
+booster.fit(50)?;
+```
+
+## Options
+
+`Options` aggregates booster-, tree-, and node-level settings. Parameter names
+and defaults mirror XGBoost, plus a couple of gboost-specific options. Every
+field is reachable through self-consuming `set_*` methods, so a fully
+configured value is built in one chain from `Options::default()`:
+
+```rust
+let options = Options::default()
+    .set_objective(ObjectiveKind::LogLoss)   // classification
+    .set_base_score(0.5)
+    .set_learning_rate(0.1)
+    .set_max_depth(10)                       // 0 = no limit
+    .set_max_leaves(100)                     // 0 = no limit
+    .set_allow_missing_splits(true);
+```
+
+Options round-trip to a portable JSON config:
+
+```rust
+let json = options.to_json();          // defaults and `persist_path` are pruned
+let restored = Options::from_json(json)?;
+```
+
+`persist_path` is machine-local and is never serialized; re-supply it via
+`set_persist_path` after `from_json`.
+
+## Python bindings
+
+A Python package is provided under [`py-gboost/`](py-gboost/). See that
+directory for its own setup and tests.
+
+## License
+
+MIT — see [LICENSE](LICENSE).