README.md

---
tags:
  - numerai
  - tabular-regression
  - finance
  - lightgbm
  - catboost
  - weekly-model
pipeline_tag: tabular-regression
---

# Numerai Weekly Champion v4

This repository publishes the exact model bundle currently used by Noptus' validated Numerai submission pipeline. It is intended as a reproducible research artifact and a starting point for ensemble-diversity work—not as investment advice or a promise of tournament performance.

## Current release

- Release: `v4-20260801-180455`
- Verified live round: `1333`
- Data schema: Numerai `v5.2`
- Inputs: 780 `medium` features plus 8 public benchmark-model columns
- Components: two benchmark-aware LightGBM models, six multi-target LightGBM models, one residual LightGBM model, and one CatBoost model
- Bundle size: approximately 142 MiB
- SHA-256: `79db5f41f3506e8e10a8b96c60a927f6a9ca202e49e03304ceaa9d304116b8d9`

The bundle was promoted over the previous local champion on a 57-era untouched holdout:

| Metric | v4 | previous champion |
|---|---:|---:|
| Mean Numerai CORR | 0.010453 | 0.001821 |
| Sharpe | 0.7712 | 0.1499 |
| Positive-era consistency | 75.44% | 52.63% |
| Maximum drawdown proxy | -0.01360 | -0.02329 |

These are historical offline measurements, not live-performance guarantees. The model remains experimental, can decay under regime change, and should not be used to make financial decisions.

## Load and predict

Install the pinned runtime dependencies:

```bash
pip install -r requirements.txt
```

Download the files and run inference on the public Numerai live and benchmark-model frames:

```python
from huggingface_hub import hf_hub_download
import joblib
import pandas as pd

from inference import predict_ranked

repo_id = "Noptus/numerai-weekly-v4"
model_path = hf_hub_download(repo_id, "ensemble_v4.pkl")
bundle = joblib.load(model_path)

live = pd.read_parquet("live.parquet")
benchmarks = pd.read_parquet("live_benchmark_models.parquet")
benchmark_columns = [c for c in benchmarks.columns if c != "era"]
live = live.join(benchmarks[benchmark_columns], how="left")

submission = pd.DataFrame(
    {"prediction": predict_ranked(live, bundle)},
    index=live.index,
)
submission.index.name = "id"
submission.to_csv("predictions.csv")
```

The included command-line entry point performs the same base inference:

```bash
python inference.py \
  --model ensemble_v4.pkl \
  --live live.parquet \
  --benchmarks live_benchmark_models.parquet \
  --output predictions.csv
```

The production system derives several slot-specific submissions by applying different feature and benchmark neutralization settings after this base ensemble. Those operational credentials and live submissions are intentionally excluded.

## Reproducibility and safety

`manifest.json` records the source revision, metric split, dependency versions, and hashes. Numerai datasets, target labels, live predictions, API credentials, and staking information are not included.

The checkpoint uses Python pickle serialization because it contains native LightGBM and CatBoost estimators. Pickle can execute code while loading: verify the SHA-256 and load only artifacts you trust. Reconstructing the component estimators in native, non-pickle formats is planned for a later release.

## Research context

Three subsequent frozen-prediction experiments did not displace this champion:

- extra tree families were highly redundant with the core (pairwise prediction correlations 0.81–0.94);
- equal and shrinkage weighting lost to purged walk-forward coordinate ascent;
- a raw-magnitude residual stack lost to the existing rank blend.

Negative results are retained because they narrow the useful next step: seek genuinely different input signal—currently the official v5.3 feature families—rather than adding more tree implementations over the same v5.2 inputs.

## License and use

No explicit model or software license has been selected for this first release. Numerai data and benchmark-model files are governed by their own terms and are not redistributed here. Verify the applicable terms before reuse or redistribution.