alloygbm 0.1.0__tar.gz

alloygbm-0.1.0/Cargo.lock

@@ -0,0 +1,284 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "alloygbm-backend-cpu"
+version = "0.1.0"
+dependencies = [
+ "alloygbm-core",
+ "alloygbm-engine",
+ "rayon",
+]
+
+[[package]]
+name = "alloygbm-categorical"
+version = "0.1.0"
+dependencies = [
+ "alloygbm-core",
+]
+
+[[package]]
+name = "alloygbm-core"
+version = "0.1.0"
+
+[[package]]
+name = "alloygbm-engine"
+version = "0.1.0"
+dependencies = [
+ "alloygbm-categorical",
+ "alloygbm-core",
+]
+
+[[package]]
+name = "alloygbm-predictor"
+version = "0.1.0"
+dependencies = [
+ "alloygbm-backend-cpu",
+ "alloygbm-core",
+ "alloygbm-engine",
+ "rayon",
+]
+
+[[package]]
+name = "alloygbm-python"
+version = "0.1.0"
+dependencies = [
+ "alloygbm-backend-cpu",
+ "alloygbm-categorical",
+ "alloygbm-core",
+ "alloygbm-engine",
+ "alloygbm-predictor",
+ "alloygbm-shap",
+ "pyo3",
+]
+
+[[package]]
+name = "alloygbm-shap"
+version = "0.1.0"
+dependencies = [
+ "alloygbm-core",
+ "alloygbm-engine",
+ "alloygbm-predictor",
+]
+
+[[package]]
+name = "autocfg"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dd111b7b7f7d55b72c0a6ae361660ee5853c9af73f70c3c2ef6858b950e2e51"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.183"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5b646652bf6661599e1da8901b3b9522896f01e736bad5f723fe7a3a27f899d"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7778bffd85cf38175ac1f545509665d0b9b92a198ca7941f131f85f7a4f9a872"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94f6cbe86ef3bf18998d9df6e0f3fc1050a8c5efa409bf712e661a4366e010fb"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e9f1b4c431c0bb1c8fb0a338709859eed0d030ff6daa34368d3b152a63dfdd8d"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fbc2201328f63c4710f68abdf653c89d8dbc2858b88c5d88b0ff38a75288a9da"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fca6726ad0f3da9c9de093d6f116a93c1a38e417ed73bf138472cf4064f72028"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rayon"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "368f01d005bf8fd9b1206fb6fa653e6c4a81ceb1466406b81792d87c5677a58f"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"

alloygbm-0.1.0/Cargo.toml

@@ -0,0 +1,15 @@
+[workspace]
+members = ["crates/core", "crates/engine", "crates/backend_cpu", "crates/predictor", "crates/shap", "crates/categorical", "bindings/python"]
+resolver = "2"
+
+[workspace.package]
+version = "0.1.0"
+edition = "2024"
+license = "MIT"
+rust-version = "1.92.0"
+homepage = "https://github.com/LGA-Personal/AlloyGBM"
+repository = "https://github.com/LGA-Personal/AlloyGBM"
+documentation = "https://alloygbm.readthedocs.io/en/latest/"
+
+[workspace.lints.rust]
+unsafe_code = "forbid"

alloygbm-0.1.0/LICENSE

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

alloygbm-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: alloygbm
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+License-File: LICENSE
+Summary: Rust-first gradient boosting for structured regression with time-aware validation utilities and Python bindings
+Keywords: gradient boosting,gbdt,machine learning,tabular,time series,finance
+Home-Page: https://github.com/LGA-Personal/AlloyGBM
+Author-email: Logan Ashby <ashbylogan12@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Benchmarks, https://github.com/LGA-Personal/AlloyGBM/tree/main/benchmarks
+Project-URL: Documentation, https://alloygbm.readthedocs.io/en/latest/
+Project-URL: Homepage, https://github.com/LGA-Personal/AlloyGBM
+Project-URL: Issues, https://github.com/LGA-Personal/AlloyGBM/issues
+Project-URL: Repository, https://github.com/LGA-Personal/AlloyGBM
+
+# AlloyGBM
+
+AlloyGBM is a Rust-first gradient boosting library for structured regression, with a Python API focused on fast native execution, deterministic training, and time-aware tabular workflows.
+
+It is currently strongest on panel and finance-style regression problems where leakage-aware validation and practical iteration speed matter. It also includes native artifact prediction, SHAP explanations, and purged time-series split helpers in the Python package.
+
+## When To Use AlloyGBM
+
+AlloyGBM is a good fit when you want:
+
+- a native-backed gradient boosting regressor with a small Python API surface
+- deterministic CPU training and inference
+- time-aware validation helpers for forecasting or panel-style workflows
+- native prediction from serialized artifacts
+- SHAP-based local explanations and global feature importances
+
+If you need the broadest possible objective support, classification, ranking, multiple categorical columns, or the strongest out-of-the-box results on generic tabular benchmarks, you should still expect XGBoost, LightGBM, or CatBoost to be stronger today.
+
+## Installation
+
+PyPI:
+
+```bash
+pip install alloygbm
+```
+
+From source:
+
+```bash
+python -m pip install --upgrade maturin
+maturin develop --manifest-path bindings/python/Cargo.toml --release
+```
+
+AlloyGBM currently targets Python `3.10+` and uses a native Rust extension module.
+
+Initial `0.1.0` packaging policy:
+
+- tested directly on macOS Apple Silicon
+- planned wheel targets: macOS `arm64` and Linux `x86_64`
+- Windows support is deferred until after `0.1.0`
+- source distribution remains the fallback for unsupported environments
+
+## Minimal Example
+
+```python
+from alloygbm import GBMRegressor, rmse
+
+X_train = [
+    [0.0, 1.0],
+    [1.0, 0.0],
+    [2.0, 1.0],
+    [3.0, 0.0],
+]
+y_train = [0.2, 0.9, 1.8, 2.7]
+
+X_test = [
+    [1.5, 1.0],
+    [2.5, 0.0],
+]
+y_test = [1.3, 2.3]
+
+model = GBMRegressor(
+    learning_rate=0.05,
+    max_depth=6,
+    n_estimators=1200,
+    training_policy="auto",
+    deterministic=True,
+    seed=7,
+)
+model.fit(X_train, y_train)
+
+predictions = model.predict(X_test)
+print(predictions)
+print(rmse(y_test, predictions))
+```
+
+## Time-Aware Validation Example
+
+```python
+from alloygbm import GBMRegressor, purged_time_series_splits, rmse
+
+rows = [
+    [0.1, 1.0],
+    [0.2, 1.1],
+    [0.4, 0.9],
+    [0.6, 1.2],
+    [0.8, 1.3],
+    [1.0, 1.4],
+]
+targets = [0.0, 0.1, 0.2, 0.5, 0.8, 1.0]
+time_index = [0, 0, 1, 1, 2, 2]
+
+splits = purged_time_series_splits(
+    time_index,
+    n_splits=3,
+    purge_gap=0,
+    embargo=0,
+)
+
+fold_scores = []
+for train_idx, test_idx in splits:
+    model = GBMRegressor(
+        learning_rate=0.05,
+        max_depth=6,
+        n_estimators=400,
+        deterministic=True,
+        seed=7,
+    )
+    X_train = [rows[i] for i in train_idx]
+    y_train = [targets[i] for i in train_idx]
+    X_test = [rows[i] for i in test_idx]
+    y_test = [targets[i] for i in test_idx]
+
+    model.fit(X_train, y_train)
+    fold_scores.append(rmse(y_test, model.predict(X_test)))
+
+print(fold_scores)
+```
+
+For panel data, use `purged_panel_splits(...)`.
+
+## Feature Summary
+
+- Native Rust-backed training and prediction from Python
+- `GBMRegressor` with deterministic training controls and dataset-aware `training_policy`
+- Continuous-feature binning strategies: `linear`, `rank`, `quantile`
+- Optional single-column categorical encoding path
+- Artifact-backed prediction via `predict_from_artifact(...)`
+- SHAP row explanations via `shap_values(...)`
+- SHAP global feature importance via `feature_importances(...)`
+- Time-aware validation helpers:
+  - `purged_time_series_splits(...)`
+  - `purged_panel_splits(...)`
+- Metric helpers:
+  - `rmse`, `mae`, `r2_score`
+  - `pearson_correlation`, `rank_ic`, `hit_rate`, `icir`
+
+## Benchmark Snapshot
+
+The current public benchmark suite compares AlloyGBM against XGBoost, LightGBM, and CatBoost on synthetic and real regression datasets.
+
+Current headline results from the expanded suite:
+
+- AlloyGBM is best on the `panel_time_series` benchmark across the tested profiles.
+- AlloyGBM is strong on `dow_jones_financial`, with its best showing under the deeper low-learning-rate profile.
+- AlloyGBM is competitive on `dense_numeric`, but still trails XGBoost and CatBoost on RMSE.
+- AlloyGBM currently lags all three libraries on `california_housing` and `bike_sharing`.
+- LightGBM is usually the fastest trainer in the comparison set.
+
+The honest short version is:
+
+- strong on `panel_time_series`
+- strong on `dow_jones_financial`
+- weaker on `california_housing` and `bike_sharing`
+
+Benchmark tooling and methodology live in [benchmarks/README.md](benchmarks/README.md).
+
+## Current Limitations
+
+- Regression-only. Classification and ranking are not implemented yet.
+- CPU-only runtime today.
+- Single categorical feature support only.
+- Best performance is still concentrated in time-aware and finance-style structured regression, not broad tabular dominance.
+- The API is intentionally small and still evolving toward a more complete `0.x` user-facing surface.
+
+## Documentation
+
+- Docs index: [docs/README.md](docs/README.md)
+- Benchmark guide: [benchmarks/README.md](benchmarks/README.md)
+- Current roadmap: [docs/roadmap/current.md](docs/roadmap/current.md)
+- Archive: [docs/archive/README.md](docs/archive/README.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+

alloygbm-0.1.0/README.md

@@ -0,0 +1,175 @@
+# AlloyGBM
+
+AlloyGBM is a Rust-first gradient boosting library for structured regression, with a Python API focused on fast native execution, deterministic training, and time-aware tabular workflows.
+
+It is currently strongest on panel and finance-style regression problems where leakage-aware validation and practical iteration speed matter. It also includes native artifact prediction, SHAP explanations, and purged time-series split helpers in the Python package.
+
+## When To Use AlloyGBM
+
+AlloyGBM is a good fit when you want:
+
+- a native-backed gradient boosting regressor with a small Python API surface
+- deterministic CPU training and inference
+- time-aware validation helpers for forecasting or panel-style workflows
+- native prediction from serialized artifacts
+- SHAP-based local explanations and global feature importances
+
+If you need the broadest possible objective support, classification, ranking, multiple categorical columns, or the strongest out-of-the-box results on generic tabular benchmarks, you should still expect XGBoost, LightGBM, or CatBoost to be stronger today.
+
+## Installation
+
+PyPI:
+
+```bash
+pip install alloygbm
+```
+
+From source:
+
+```bash
+python -m pip install --upgrade maturin
+maturin develop --manifest-path bindings/python/Cargo.toml --release
+```
+
+AlloyGBM currently targets Python `3.10+` and uses a native Rust extension module.
+
+Initial `0.1.0` packaging policy:
+
+- tested directly on macOS Apple Silicon
+- planned wheel targets: macOS `arm64` and Linux `x86_64`
+- Windows support is deferred until after `0.1.0`
+- source distribution remains the fallback for unsupported environments
+
+## Minimal Example
+
+```python
+from alloygbm import GBMRegressor, rmse
+
+X_train = [
+    [0.0, 1.0],
+    [1.0, 0.0],
+    [2.0, 1.0],
+    [3.0, 0.0],
+]
+y_train = [0.2, 0.9, 1.8, 2.7]
+
+X_test = [
+    [1.5, 1.0],
+    [2.5, 0.0],
+]
+y_test = [1.3, 2.3]
+
+model = GBMRegressor(
+    learning_rate=0.05,
+    max_depth=6,
+    n_estimators=1200,
+    training_policy="auto",
+    deterministic=True,
+    seed=7,
+)
+model.fit(X_train, y_train)
+
+predictions = model.predict(X_test)
+print(predictions)
+print(rmse(y_test, predictions))
+```
+
+## Time-Aware Validation Example
+
+```python
+from alloygbm import GBMRegressor, purged_time_series_splits, rmse
+
+rows = [
+    [0.1, 1.0],
+    [0.2, 1.1],
+    [0.4, 0.9],
+    [0.6, 1.2],
+    [0.8, 1.3],
+    [1.0, 1.4],
+]
+targets = [0.0, 0.1, 0.2, 0.5, 0.8, 1.0]
+time_index = [0, 0, 1, 1, 2, 2]
+
+splits = purged_time_series_splits(
+    time_index,
+    n_splits=3,
+    purge_gap=0,
+    embargo=0,
+)
+
+fold_scores = []
+for train_idx, test_idx in splits:
+    model = GBMRegressor(
+        learning_rate=0.05,
+        max_depth=6,
+        n_estimators=400,
+        deterministic=True,
+        seed=7,
+    )
+    X_train = [rows[i] for i in train_idx]
+    y_train = [targets[i] for i in train_idx]
+    X_test = [rows[i] for i in test_idx]
+    y_test = [targets[i] for i in test_idx]
+
+    model.fit(X_train, y_train)
+    fold_scores.append(rmse(y_test, model.predict(X_test)))
+
+print(fold_scores)
+```
+
+For panel data, use `purged_panel_splits(...)`.
+
+## Feature Summary
+
+- Native Rust-backed training and prediction from Python
+- `GBMRegressor` with deterministic training controls and dataset-aware `training_policy`
+- Continuous-feature binning strategies: `linear`, `rank`, `quantile`
+- Optional single-column categorical encoding path
+- Artifact-backed prediction via `predict_from_artifact(...)`
+- SHAP row explanations via `shap_values(...)`
+- SHAP global feature importance via `feature_importances(...)`
+- Time-aware validation helpers:
+  - `purged_time_series_splits(...)`
+  - `purged_panel_splits(...)`
+- Metric helpers:
+  - `rmse`, `mae`, `r2_score`
+  - `pearson_correlation`, `rank_ic`, `hit_rate`, `icir`
+
+## Benchmark Snapshot
+
+The current public benchmark suite compares AlloyGBM against XGBoost, LightGBM, and CatBoost on synthetic and real regression datasets.
+
+Current headline results from the expanded suite:
+
+- AlloyGBM is best on the `panel_time_series` benchmark across the tested profiles.
+- AlloyGBM is strong on `dow_jones_financial`, with its best showing under the deeper low-learning-rate profile.
+- AlloyGBM is competitive on `dense_numeric`, but still trails XGBoost and CatBoost on RMSE.
+- AlloyGBM currently lags all three libraries on `california_housing` and `bike_sharing`.
+- LightGBM is usually the fastest trainer in the comparison set.
+
+The honest short version is:
+
+- strong on `panel_time_series`
+- strong on `dow_jones_financial`
+- weaker on `california_housing` and `bike_sharing`
+
+Benchmark tooling and methodology live in [benchmarks/README.md](benchmarks/README.md).
+
+## Current Limitations
+
+- Regression-only. Classification and ranking are not implemented yet.
+- CPU-only runtime today.
+- Single categorical feature support only.
+- Best performance is still concentrated in time-aware and finance-style structured regression, not broad tabular dominance.
+- The API is intentionally small and still evolving toward a more complete `0.x` user-facing surface.
+
+## Documentation
+
+- Docs index: [docs/README.md](docs/README.md)
+- Benchmark guide: [benchmarks/README.md](benchmarks/README.md)
+- Current roadmap: [docs/roadmap/current.md](docs/roadmap/current.md)
+- Archive: [docs/archive/README.md](docs/archive/README.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).