Metadata-Version: 2.4
Name: idun-numerai
Version: 0.1.0
Summary: Numerai on top of idun: the data, walk-forward refits, labels, scoring and presets.
Keywords: Numerai,tabular,gradient boosting,TabM,RealMLP
Author: Anton Shaniuk
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: cloudpickle>=3.1,<4
Requires-Dist: idun==0.1.0
Requires-Dist: numerapi>=3.1.1,<4
Requires-Dist: pyarrow>=25,<27
Requires-Dist: scipy>=1.18,<2
Requires-Python: >=3.12, <3.15
Description-Content-Type: text/markdown

# idun-numerai

Numerai on top of [idun](https://pypi.org/project/idun/)'s public interface: Numerai's data in idun's packed format,
the walk-forward refits, the labels, Numerai's scores in NumPy, fixed presets for each learner, and model uploads.

```bash
pip install idun-numerai    # Python 3.12–3.14; idun's Metal backend needs Apple silicon with macOS 15 or later
```

## Train and score

```python
from idun import gbm
from idun.data import PackedDataset
from idun_numerai import presets
from idun_numerai.data import build_cache
from idun_numerai.download import download
from idun_numerai.score import corr, per_era

download("v6")  # Numerai's v6 training and validation files and the feature list (public data, no credentials)
build_cache("v6", "cache", seed=0)  # streamed into a memory-mapped packed dataset; never the whole panel in memory

data = PackedDataset.open("cache", binning="r2")  # the last walk-forward window's binning
window = data.refits[2]
model = gbm.train(presets.GBM_C, data, rows=slice(0, window.train_hi), backend="metal")
rows = slice(window.pred_lo, window.pred_hi)
scores = per_era(corr, data.era[rows], model.predict(data, rows=rows, backend="metal"), data.target[rows])
```

- `idun_numerai.download`, `idun_numerai.data.build_cache`: the data, checked and packed (4-bit codes, the named
  factors binned per window, the country as a categorical column).
- `idun_numerai.refits`: the walk-forward windows (training rows, a purge, the predicted rows).
- `idun_numerai.inputs`: the labels: classes `rint(4 · y)` for the networks' classification, per-era z for regression.
- `idun_numerai.presets`: fixed configurations of idun_gbm (`GBM_C` and its seed bag), TabM and RealMLP.
- `idun_numerai.score`: NCORR and CORR per era in NumPy and SciPy, as `numerai-tools` defines them (checked against it
  per era in the tests; `numerai-tools` is not a dependency).

## Model uploads

Numerai's model uploads run a pickled `predict(live_features, live_benchmark_models)` on its servers, where idun is not
installed. `idun_numerai.upload` carries trained models as arrays and predicts with NumPy alone:

```python
from idun_numerai import upload

predict = upload.predictor([model, [tabm_s0, tabm_s1], realmlp], data, weights=[2, 1, 1])
upload.save(predict, "model.pkl")  # run under Python 3.12, the runtime's
```

idun_gbm's upload predictions equal `Booster.predict`'s bit for bit; TabM's and RealMLP's are their float64 reference
backend's. A list is a bag (its mean); several entries are blended by rank.

## Licence

Apache-2.0.
