Metadata-Version: 2.4
Name: wlearn-rf
Version: 0.4.1
Summary: Random Forest and ExtraTrees backed by the wlearn C11 core
License-Expression: Apache-2.0
Project-URL: Homepage, https://wlearn.org
Project-URL: Repository, https://github.com/wlearn-org/rf
Project-URL: Issues, https://github.com/wlearn-org/rf/issues
Keywords: random-forest,extra-trees,machine-learning,wlearn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.22
Requires-Dist: wlearn<0.4,>=0.3.0
Dynamic: license-file

# wlearn-rf Python

Python estimator wrapper for the wlearn C11 random forest core.

## Install

```bash
pip install wlearn-rf
```

## Example

```python
from wlearn_rf import RFModel

model = RFModel({"n_estimators": 100, "seed": 42})
model.fit(X, y)
pred = model.predict(X_test)
proba = model.predict_proba(X_test)

model.save("rf.wlrn")
restored = RFModel.load("rf.wlrn")
```

## API

- `RFModel(params=None)`.
- `fit(X, y)` trains a classifier by default; set `task: "regression"` for regression.
- `predict(X)`, `predict_proba(X)`, `score(X, y)`.
- `predict_quantile(X, quantile)` and `predict_interval(X, alpha)` for regression forests.
- `feature_importances()`, `permutation_importance(...)`, `proximity(X)`,
  `oob_score()` inspect fitted forests.
- `save(path=None)` returns WLRN bytes and writes them when given a `str` or `Path`.
- `RFModel.load(bytes_or_path)` accepts WLRN bytes, `str`, or `Path`.
- `get_params()` / `set_params(...)` support estimator cloning/search.
- `default_search_space(task=None)` returns the AutoML search-space IR.
- `dispose()` releases native memory early in long-running processes.

Properties: `n_features`, `n_classes`, `n_trees`, `is_fitted`, `capabilities`.

Common params: `n_estimators`, `max_depth`, `min_samples_split`,
`min_samples_leaf`, `max_features`, `bootstrap`, `compute_oob`, `extra_trees`,
`seed`, `task`, `criterion`, `sample_weight`, `class_weight`, `sample_rate`,
`histogram_binning`, `max_bins`, `monotonic_cst`.

`save()` returns a WLRN bundle. RF01 native bytes are an internal artifact inside
the bundle, matching JavaScript `@wlearn/rf`.

## Development

The canonical native source is repository root `src/`; `py/csrc/` is generated
for Python builds. Use `WLEARN_PYTHON=/path/to/python make test-py` from the
repository root to force a specific Python environment.

Classification accepts int32 labels, including negative and nonconsecutive values.
The `classes` property gives the probability-column order. Artifacts with a
nonidentity label mapping use `wlearn.rf.classifier@2`; ordinal classifiers and
regressors retain their existing `@1` format. Both formats load in this release.
